OpenClaw + Hermes Support

README.md

@@ -34,6 +34,7 @@ One Go binary, a full terminal UI, and it runs against whatever models you alrea
 <tr><td><b>A real terminal UI</b></td><td>Multiline editing, slash commands with autocomplete, streaming tool output, interrupt and redirect mid-turn, themes, and a live context meter.</td></tr>
 <tr><td><b>Plans before it builds</b></td><td><code>/plan</code> researches with parallel scouts, drafts, gets a cross-model review, and turns the approved plan into a binding contract for execution.</td></tr>
 <tr><td><b>Delegates and parallelizes</b></td><td>Spawn read-only explorers or full sub-agents, run detached background jobs, and manage them with <code>/jobs</code>, <code>/tail</code>, <code>/kill</code>.</td></tr>
+<tr><td><b>Runs where you chat</b></td><td>The same binary runs as a self-hosted <a href="docs/gateway/README.md">gateway</a>: Telegram, Discord, Slack, GitHub, and WhatsApp messages become agent jobs in your repo. Durable idempotent dispatch, per-channel allow-lists, and one-command import from OpenClaw. Coding is one use of the loop, not what it is built around.</td></tr>
 <tr><td><b>Table stakes, done properly</b></td><td>MCP client, Agent Skills, hooks (<a href="HOOKS.md">HOOKS.md</a>), resident LSP for diagnostics and navigation, a sandboxed shell with a real command classifier, vision and PDF input, prompt caching, and context compaction that respects the model's actual window (<a href="COMPACTION.md">COMPACTION.md</a>).</td></tr>
 <tr><td><b>Self-updating</b></td><td>Stages updates in the background and applies them on the next launch. <code>MEMCODE_AUTO_UPDATE=off</code> keeps it manual.</td></tr>
 </table>

cmd/agent.go

@@ -105,7 +105,7 @@ for local gateway development. Never store keys in .memcode.`,
 				mode = permissions.ModeAuto // a backgrounded job can't answer prompts
 				fmt.Println("note: background jobs run in --auto (can't prompt); pass --allow-all to widen")
 			}
-			job, err := jobs.Spawn(cfg.Root, task, string(mode), "", chrome, false)
+			job, err := jobs.Spawn(cfg.Root, task, string(mode), "", chrome, false, "")
 			if err != nil {
 				return err
 			}
@@ -136,6 +136,29 @@ for local gateway development. Never store keys in .memcode.`,
 			case "strong":
 				sess.SetForceEscalate(true) // strong-tier background agent → strong vendor's balanced tier
 			}
+			// --session: a gateway conversation job. Pin the id and resume the prior
+			// transcript if it exists, so follow-up messages continue the same session.
+			// Uses the chat seams (which load + save the transcript) instead of Run.
+			if sessionID, _ := cmd.Flags().GetString("session"); sessionID != "" {
+				sess.SetSessionID(sessionID)
+				if _, err := runtime.ResolveSession(cfg.Root, sessionID); err == nil {
+					sess.SetResume(sessionID)
+				}
+				fmt.Printf("memcode job %s · model %s · mode %s · session %s\n", jobID, model, mode, sessionID)
+				chat := sess.StartChat(ctx)
+				sess.Submit(ctx, chat, task)
+				sess.EndChat(ctx)
+				code := 0
+				if sess.LastError() != nil {
+					code = 1
+				}
+				result := ""
+				if rb, _ := cmd.Flags().GetBool("report-back"); rb {
+					result = sess.LastText()
+				}
+				_ = jobs.Finish(cfg.Root, jobID, code, result)
+				return sess.LastError()
+			}
 			fmt.Printf("memcode job %s · model %s · mode %s\n", jobID, model, mode)
 			_, runErr := sess.Run(ctx, task)
 			code := 0
@@ -233,5 +256,6 @@ func init() {
 	agentCmd.Flags().String("protocol", "", "machine control protocol: stream-json (newline-delimited JSON on stdio, for SDK wrappers)")
 	agentCmd.Flags().BoolP("continue", "c", false, "resume the most recent session with its full conversation")
 	agentCmd.Flags().String("resume", "", "resume a session by id or prefix (see `memcode session recent`)")
+	agentCmd.Flags().String("session", "", "run a --job in this session id, resuming it if it exists (gateway conversation continuity)")
 	rootCmd.AddCommand(agentCmd)
 }

cmd/gateway.go

@@ -0,0 +1,174 @@
+package cmd
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"golang.org/x/term"
+
+	"github.com/memcode-ai/memcode/internal/authflow"
+	gwconfig "github.com/memcode-ai/memcode/internal/gateway/config"
+	gwserver "github.com/memcode-ai/memcode/internal/gateway/server"
+	"github.com/memcode-ai/memcode/internal/provider"
+)
+
+// gatewayCmd runs memcode as a long-lived gateway: the same binary that runs the
+// interactive agent also hosts channel adapters (Telegram/Discord/Slack/GitHub/
+// WhatsApp) that turn inbound messages into agent work and post the results back.
+// Self-hosted, configured once with `memcode gateway setup` — bot tokens land in
+// the global .env, non-secret settings in ~/.config/memcode/gateway.yaml.
+var gatewayCmd = &cobra.Command{
+	Use:   "gateway",
+	Short: "Run memcode as a self-hosted gateway (chat channels → agent → reply)",
+	Long: `Run memcode as a long-lived gateway.
+
+Channels are configured once with 'memcode gateway setup'. Bot tokens are stored
+in the global .env; non-secret settings in ~/.config/memcode/gateway.yaml. Each
+inbound message runs as a detached agent job in the current project and the
+result is posted back to the channel it came from. Runs until interrupted.`,
+	RunE: func(cmd *cobra.Command, args []string) error {
+		ctx := cmd.Context()
+		provider.LoadDotEnv() // pull bot tokens from the global .env into the environment
+		settings, err := gwconfig.Load()
+		if err != nil {
+			return err
+		}
+		if len(gwconfig.EnabledChannels()) == 0 {
+			return fmt.Errorf("no channels configured — run `memcode gateway setup` first")
+		}
+		st, cfg, err := openProject(ctx)
+		if err != nil {
+			return err
+		}
+		defer st.Close()
+
+		cmd.Printf("memcode gateway — %s (channels: %s)\n", cfg.Root, strings.Join(gwconfig.EnabledChannels(), ", "))
+		return gwserver.Run(ctx, cfg.Root, st, settings, cmd.OutOrStdout())
+	},
+}
+
+// gatewaySetupCmd is the interactive wizard that replaces hand-setting a pile of
+// environment variables. It routes each answer the way memcode (and Hermes)
+// split config: bot tokens go to the global .env, non-secret knobs to
+// gateway.yaml.
+var gatewaySetupCmd = &cobra.Command{
+	Use:   "setup",
+	Short: "Configure gateway channels (Telegram/Discord/Slack/GitHub/WhatsApp)",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		provider.LoadDotEnv()
+		settings, err := gwconfig.Load()
+		if err != nil {
+			return err
+		}
+		in := bufio.NewReader(os.Stdin)
+
+		for {
+			if enabled := gwconfig.EnabledChannels(); len(enabled) == 0 {
+				cmd.Println("No channels configured yet.")
+			} else {
+				cmd.Printf("Configured: %s\n", strings.Join(enabled, ", "))
+			}
+			choice := strings.ToLower(strings.TrimSpace(prompt(in, cmd, "Channel to add/update [telegram/discord/slack/github/whatsapp] (blank to finish): ")))
+
+			secrets := map[string]string{}
+			if settings.Channels == nil {
+				settings.Channels = map[string]gwconfig.Channel{}
+			}
+			switch choice {
+			case "":
+				p, _ := gwconfig.Path()
+				cmd.Printf("Done. Tokens in the global .env; settings in %s\n", p)
+				return nil
+			case "telegram":
+				secrets[gwconfig.EnvTelegramToken] = secret(cmd, "Bot token (from @BotFather): ")
+				settings.Channels["telegram"] = gwconfig.Channel{AllowFrom: allowList(in, cmd)}
+			case "discord":
+				secrets[gwconfig.EnvDiscordToken] = secret(cmd, "Bot token (Discord developer portal): ")
+				settings.Channels["discord"] = gwconfig.Channel{AllowFrom: allowList(in, cmd)}
+			case "slack":
+				secrets[gwconfig.EnvSlackAppToken] = secret(cmd, "App-level token (xapp-…): ")
+				secrets[gwconfig.EnvSlackBotToken] = secret(cmd, "Bot token (xoxb-…): ")
+				settings.Channels["slack"] = gwconfig.Channel{AllowFrom: allowList(in, cmd)}
+			case "github":
+				secrets[gwconfig.EnvGitHubSecret] = secret(cmd, "Webhook secret: ")
+				// GitHub deliveries are HMAC-authenticated, so no allow-list here.
+				settings.Channels["github"] = gwconfig.Channel{
+					ReplyTo: strings.TrimSpace(prompt(in, cmd, "Route results to (e.g. telegram:123456, blank for none): ")),
+				}
+			case "whatsapp":
+				cmd.Println("Note: WhatsApp stays inactive until your Meta business is verified.")
+				cmd.Println("Once verified, set `whatsapp.active: true` in gateway.yaml to enable it.")
+				wa := gwconfig.Channel{
+					PhoneNumberID: strings.TrimSpace(prompt(in, cmd, "Phone number ID: ")),
+				}
+				secrets[gwconfig.EnvWhatsAppToken] = secret(cmd, "Access token: ")
+				secrets[gwconfig.EnvWhatsAppVerify] = secret(cmd, "Webhook verify token: ")
+				secrets[gwconfig.EnvWhatsAppSecret] = secret(cmd, "App secret (verifies inbound; required to activate): ")
+				wa.AllowFrom = allowList(in, cmd)
+				settings.Channels["whatsapp"] = wa
+			default:
+				cmd.Println("Unknown channel; pick one of telegram/discord/slack/github/whatsapp.")
+				continue
+			}
+
+			if len(secrets) > 0 {
+				if err := authflow.SetGlobalEnv(secrets); err != nil {
+					return err
+				}
+				// Reflect the just-written tokens so EnabledChannels sees them this loop.
+				for k, v := range secrets {
+					_ = os.Setenv(k, v)
+				}
+			}
+			if err := gwconfig.Save(settings); err != nil {
+				return err
+			}
+			cmd.Printf("Saved %s.\n", choice)
+		}
+	},
+}
+
+// allowList prompts for the principals allowed to drive the agent through this
+// channel. The gateway is default-deny, so an empty answer means no one can use
+// the channel yet; "*" allows anyone who can reach it.
+func allowList(in *bufio.Reader, cmd *cobra.Command) []string {
+	raw := prompt(in, cmd, "Allowed users — comma-separated stable user ids (not @handles), or * for anyone (blank = no one yet): ")
+	var out []string
+	for _, p := range strings.Split(raw, ",") {
+		if p = strings.TrimSpace(p); p != "" {
+			out = append(out, p)
+		}
+	}
+	return out
+}
+
+// prompt writes a prompt and reads one line.
+func prompt(in *bufio.Reader, cmd *cobra.Command, label string) string {
+	cmd.Print(label)
+	line, _ := in.ReadString('\n')
+	return strings.TrimRight(line, "\r\n")
+}
+
+// secret reads a value without echoing it when stdin is a terminal, falling back
+// to a plain read when it isn't (piped input).
+func secret(cmd *cobra.Command, label string) string {
+	cmd.Print(label)
+	fd := int(os.Stdin.Fd())
+	if term.IsTerminal(fd) {
+		b, err := term.ReadPassword(fd)
+		cmd.Println()
+		if err == nil {
+			return strings.TrimSpace(string(b))
+		}
+	}
+	line, _ := bufio.NewReader(os.Stdin).ReadString('\n')
+	return strings.TrimSpace(line)
+}
+
+func init() {
+	gatewayCmd.AddCommand(gatewaySetupCmd)
+	rootCmd.AddCommand(gatewayCmd)
+}

cmd/gateway_install.go

@@ -0,0 +1,161 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"runtime"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/memcode-ai/memcode/internal/atomicfile"
+)
+
+// gatewayInstallCmd installs the gateway as a managed background service so it
+// survives logout/reboot instead of living in a foreground terminal. It writes an
+// OS-native unit (launchd on macOS, systemd --user on Linux) that runs
+// `memcode gateway` in the current project, then prints how to start it.
+var gatewayInstallCmd = &cobra.Command{
+	Use:   "install",
+	Short: "Install the gateway as a background service (launchd/systemd)",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		bin, err := os.Executable()
+		if err != nil {
+			return fmt.Errorf("locating memcode binary: %w", err)
+		}
+		workDir, err := os.Getwd()
+		if err != nil {
+			return err
+		}
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return err
+		}
+		path, content, start, err := gatewayUnit(runtime.GOOS, home, bin, workDir)
+		if err != nil {
+			return err
+		}
+		if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
+			return err
+		}
+		if err := atomicfile.WriteFile(path, []byte(content), 0o644); err != nil {
+			return err
+		}
+		cmd.Printf("Installed gateway service for %s\n", workDir)
+		cmd.Printf("Unit: %s\n", path)
+		cmd.Printf("Start it with:\n  %s\n", start)
+		return nil
+	},
+}
+
+// gatewayUninstallCmd removes the service unit. It doesn't stop a running service
+// (the user unloads it with the printed command); it just deletes the unit.
+var gatewayUninstallCmd = &cobra.Command{
+	Use:   "uninstall",
+	Short: "Remove the installed gateway service unit",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return err
+		}
+		path, _, _, err := gatewayUnit(runtime.GOOS, home, "", "")
+		if err != nil {
+			return err
+		}
+		if err := os.Remove(path); err != nil && !os.IsNotExist(err) {
+			return err
+		}
+		cmd.Printf("Removed %s\n", path)
+		switch runtime.GOOS {
+		case "darwin":
+			cmd.Printf("Stop it (if running) with:\n  launchctl unload %s\n", path)
+		case "linux":
+			cmd.Printf("Stop it (if running) with:\n  systemctl --user disable --now memcode-gateway\n")
+		}
+		return nil
+	},
+}
+
+// hasControlChars rejects paths carrying newlines/NULs, which could inject extra
+// unit directives (a systemd ExecStart= line, a plist element) via the binary or
+// working-directory path.
+func hasControlChars(s string) bool { return strings.ContainsAny(s, "\n\r\x00") }
+
+// xmlEscape escapes a value for safe interpolation into the plist XML.
+var xmlEscape = strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;", `"`, "&quot;", "'", "&apos;").Replace
+
+// systemdQuote renders a path as a single double-quoted systemd argument,
+// escaping the % specifier introducer. The caller has already rejected paths
+// containing a double quote, so the value inside the quotes is safe.
+func systemdQuote(s string) string {
+	return `"` + strings.ReplaceAll(s, "%", "%%") + `"`
+}
+
+// gatewayUnit builds the service unit for goos: its file path, contents, and the
+// command to start it. bin/workDir may be empty when only the path is needed
+// (uninstall). Returns an error for an unsupported OS or a path with control
+// characters.
+func gatewayUnit(goos, home, bin, workDir string) (path, content, start string, err error) {
+	if hasControlChars(bin) || hasControlChars(workDir) {
+		return "", "", "", fmt.Errorf("binary or working-directory path contains control characters; refusing to write a service unit")
+	}
+	switch goos {
+	case "darwin":
+		bin, workDir := xmlEscape(bin), xmlEscape(workDir)
+		path = filepath.Join(home, "Library", "LaunchAgents", "ai.memcode.gateway.plist")
+		content = fmt.Sprintf(`<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>Label</key><string>ai.memcode.gateway</string>
+	<key>ProgramArguments</key>
+	<array>
+		<string>%s</string>
+		<string>gateway</string>
+	</array>
+	<key>WorkingDirectory</key><string>%s</string>
+	<key>RunAtLoad</key><true/>
+	<key>KeepAlive</key><true/>
+	<key>StandardOutPath</key><string>%s/.memcode/gateway.log</string>
+	<key>StandardErrorPath</key><string>%s/.memcode/gateway.log</string>
+</dict>
+</plist>
+`, bin, workDir, workDir, workDir)
+		start = "launchctl load " + path
+		return path, content, start, nil
+	case "linux":
+		// systemd parses ExecStart with its own quoting rules and treats % as a
+		// specifier introducer, so a path with a space or a % would corrupt the
+		// unit. Quote both paths and double any % (systemd's escape for a literal
+		// percent). A literal double-quote in a path can't be represented safely
+		// here, so reject it rather than emit a broken unit.
+		if strings.ContainsAny(bin, "\"") || strings.ContainsAny(workDir, "\"") {
+			return "", "", "", fmt.Errorf("binary or working-directory path contains a double quote; refusing to write a systemd unit")
+		}
+		qBin, qWork := systemdQuote(bin), systemdQuote(workDir)
+		path = filepath.Join(home, ".config", "systemd", "user", "memcode-gateway.service")
+		content = fmt.Sprintf(`[Unit]
+Description=memcode gateway
+After=network-online.target
+
+[Service]
+ExecStart=%s gateway
+WorkingDirectory=%s
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+`, qBin, qWork)
+		start = "systemctl --user daemon-reload && systemctl --user enable --now memcode-gateway"
+		return path, content, start, nil
+	default:
+		return "", "", "", fmt.Errorf("gateway install is not supported on %s (run `memcode gateway` directly)", goos)
+	}
+}
+
+func init() {
+	gatewayCmd.AddCommand(gatewayInstallCmd)
+	gatewayCmd.AddCommand(gatewayUninstallCmd)
+}