@semalt-ai/code 1.8.5 → 1.19.0

package/README.md

@@ -18,7 +18,7 @@ It provides an interactive chat interface, one-shot code generation, AI-assisted
 
 ## Requirements
 
-- Node.js `>=16`
+- Node.js `>=18` (Node 16 is end-of-life; `node --test` is unreliable on it)
 - An OpenAI-compatible API endpoint
 
 The default configuration expects a local API server at `http://127.0.0.1:8800`.
@@ -114,6 +114,14 @@ semalt-code [command] [options]
 - `semalt-code init`
   Creates or updates the local config file.
 
+- `semalt-code mcp <list|status|add|remove|auth>`
+  Manage MCP servers. `add` registers a server (stdio `command`/`args` or remote `--url`),
+  `status` connects and reports each server's tools, `auth` runs the OAuth flow for a remote
+  server (tokens are stored in the OS keychain). Discovered tools register as
+  `mcp__<server>__<tool>` and run through the same approval-gated agent loop as built-ins —
+  MCP results are treated as untrusted external content, and MCP tools require approval by
+  default (opt in per server with `allow`/`allowAll`). In chat, `/mcp` shows the same status.
+
 ### Options
 
 - `-m, --model <name>`
@@ -246,6 +254,99 @@ Saved profiles can then be selected inside chat mode with `/model` or `/models`.
 semalt-code --version
 ```
 
+## Embedding SDK
+
+`@semalt-ai/code` can be embedded in another program as a library, not just run as a
+CLI. There are **two tiers**, physically separated by the package `exports` map:
+
+| Import | Surface | Stability |
+|--------|---------|-----------|
+| `require('@semalt-ai/code')` | `createAgent` — the high-level facade | **Stable** (semver) |
+| `require('@semalt-ai/code/internals')` | `createAgentRunner`, `createApiClient`, the registries, … | **Unstable** — no guarantee, may change in any release |
+
+Both subpaths work for `require` and `import` (the package is CommonJS; ESM consumers
+get the named exports via interop).
+
+### The facade
+
+```js
+const { createAgent } = require('@semalt-ai/code');
+
+const agent = createAgent({
+  apiBase: 'http://127.0.0.1:8800',
+  apiKey:  process.env.SEMALT_API_KEY,
+  model:   'my-model',
+  // permission policy — see below
+});
+
+const res = await agent.run('Summarise README.md in three bullets');
+// res = { result, toolCalls, usage, cost, stopReason, verifyStatus, messages }
+console.log(res.result);
+
+await agent.close(); // REQUIRED — releases MCP connections / processes
+```
+
+`run(prompt, opts?)` executes a prompt to completion and returns the same structured
+envelope headless mode produces, plus `messages` so you can continue the conversation
+(`agent.run(next, { messages: res.messages })`). Stream events with
+`agent.on('token' | 'assistant' | 'tool' | 'tool-start' | 'error' | 'warning' | 'done', cb)`.
+
+### Permission policy — safe by default
+
+There is no terminal in embedded use, so the facade takes a **programmatic** permission
+policy. With **neither** a policy provided, the default is to **refuse every mutating /
+effectful tool** (read-only tools still run) — it never auto-approves:
+
+```js
+// 1) an async approver callback
+createAgent({ /* … */, approve: async (call) => {
+  // call = { actionType, description, tag, rule }
+  return call.tag !== 'delete_file'; // your decision
+}});
+
+// 2) preset allow/deny/ask rules (the same engine as the CLI's per-pattern rules)
+createAgent({ /* … */, rules: [
+  { tool: 'write_file', path: 'src/**', action: 'allow' },
+  { tool: 'shell',      pattern: 'git *', action: 'allow' },
+  { tool: 'shell',      pattern: '/curl.*\\| *sh/', action: 'deny' },
+]});
+
+// 3) coarse tiers (like --allow-fs/exec/net) and read-only
+createAgent({ /* … */, allow: ['fs', 'net'], readonly: true });
+```
+
+The **OS sandbox** and the **destructive-command deny-list** stay **on** regardless of
+there being no TTY. The sandbox is opt-out **only** via explicit config
+(`sandbox: { mode: 'off' }`); a host can permit running a command unsandboxed when the
+kernel primitive is missing by supplying `onUnsandboxed`. A `deny` rule and the
+deny-list are honored even under the deliberate `dangerouslySkipPermissions: true`
+gate opt-out.
+
+By default the SDK does **not** read your `~/.semalt-ai/config.json` (a server wants
+isolation, not the operator's personal defaults) — pass `loadUserConfig: true` to layer
+it in. Pass arbitrary config under `config: { … }`.
+
+### Lifecycle & multi-instance
+
+- **Always call `await agent.close()`** when done. It disconnects MCP servers and frees
+  handles. `run()` after `close()` throws.
+- Each `createAgent` instance keeps its **own config** — two instances never share
+  config state.
+- **Process-global state (documented limitation).** A few things are process-wide, not
+  per-instance, because they were built for the single-process CLI:
+  - the **dynamic tool registry** (MCP + `spawn_agent`) is global — two instances with
+    *different* MCP servers would see each other's tools;
+  - file-path confinement (`isPathSafe`) and the deny-list/secret/config guards read
+    `process.cwd()` and `process.argv` **once at module load**, so they're shared by all
+    instances and the deny-list opt-out requires launching the host process with
+    `--dangerously-skip-permissions`;
+  - the stdout-chrome-suppression flag is process-wide.
+
+  For most embeddings (one agent per process, or instances sharing a CWD and MCP set)
+  none of this matters; run fully-isolated agents in separate processes if it does.
+
+A runnable example lives in [`examples/embed.js`](examples/embed.js).
+
 ## How Responses Are Rendered
 
 The CLI formats streamed output for terminal readability:
@@ -259,13 +360,56 @@ The CLI formats streamed output for terminal readability:
 
 If the backend returns `reasoning_content`, the CLI also shows a lightweight `thinking` section during streaming.
 
+## Dependency Policy
+
+This project keeps its runtime dependency surface **minimal, vetted, and pinned**. It
+ran with **zero runtime dependencies** through its first phases; as of v1.9.0 it has a
+single one — the official Model Context Protocol SDK,
+[`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) —
+adopted to implement MCP against its reference (rather than hand-rolling the protocol).
+
+The policy for any runtime dependency:
+
+- **Minimal & justified** — added only when a Node.js built-in genuinely cannot do the
+  job, with a recorded rationale.
+- **Pinned to an exact version** — no `^`/`~` ranges in `package.json`. Upgrades are
+  deliberate, reviewed commits.
+- **Reviewed with the lockfile** — `package-lock.json` is committed; adding or bumping a
+  dependency is a reviewed change.
+
+**Supply-chain checks.** CI runs `npm ci` (lockfile integrity) and
+`npm audit --omit=dev --audit-level=high` (fails on HIGH/CRITICAL advisories in the
+runtime tree). The full audit-findings policy is documented in `CLAUDE.md`.
+
+The SDK is ESM-only while this project is CommonJS, so it is loaded in exactly one
+place — `lib/mcp/boundary.js`, via dynamic `import()` — and the rest of the codebase
+stays CommonJS.
+
 ## Notes and Limitations
 
-- This project is currently a single-file CLI implementation centered in `index.js`.
-- It uses Node's built-in `http` and `https` modules and does not require extra runtime dependencies.
+- It uses Node's built-in `http` and `https` modules for all networking; the only
+  runtime dependency is the MCP SDK (see **Dependency Policy** above).
 - The `edit` command writes the model output directly back to the target file, so review prompts and backend behavior carefully.
 - Shell and file operations are approval-based, but they still execute on the local system after approval.
 
+### Not yet implemented
+
+A few capabilities are intentionally absent today — documented here so you don't build
+on something that isn't wired up. See **Deferred / Not Yet Implemented** in `CLAUDE.md`
+for the full list and roadmap status.
+
+- **MCP tools are interactive-chat only** — they are not connected in the `code`/`edit`/`shell`
+  one-shot commands or headless `-p/--print` mode.
+- **No session auto-resume** — there's no "resume your last session?" prompt at startup;
+  use `/history` (local sessions) or `--resume <chat-id>` (dashboard chats).
+- **Proxy env vars are not consumed** — `HTTPS_PROXY`/`HTTP_PROXY` are read into config but
+  outbound HTTP does not yet route through a proxy agent (matters on corporate networks).
+- Planned for Phase 4+: per-pattern permissions, self-verification, checkpoints/rewind, and an OS sandbox.
+
+## Contributing
+
+PRs must pass the CI pipeline (`npm ci` + `npm audit` + lint + tests on Linux/macOS/Windows, Node 18 & 20) before they can be merged. Run `npm ci && npm run lint && npm test` locally first. Any dependency change must follow the **Dependency Policy** above (exact pin, committed lockfile, justification).
+
 ## License
 
 MIT

package/examples/embed.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Embedding SDK example (Task 5.2)
+// ---------------------------------------------------------------------------
+//
+// Shows the supported, stable way to embed the agent in another program via the
+// `createAgent` facade: a permission policy that defaults safe, streaming
+// events, the structured run result, and the required close() teardown.
+//
+// Run it against any OpenAI-compatible endpoint:
+//
+//     SEMALT_API_BASE=http://127.0.0.1:8800 \
+//     SEMALT_API_KEY=sk-… \
+//     SEMALT_MODEL=my-model \
+//     node examples/embed.js "List the files in this directory"
+//
+// (From outside this repo, `require('@semalt-ai/code')` instead of the relative
+// path below.)
+
+const { createAgent } = require('../lib/sdk'); // → require('@semalt-ai/code')
+
+async function main() {
+  const prompt = process.argv.slice(2).join(' ') || 'Say hello and tell me what tools you have.';
+
+  const agent = createAgent({
+    apiBase: process.env.SEMALT_API_BASE || 'http://127.0.0.1:8800',
+    apiKey:  process.env.SEMALT_API_KEY  || 'any',
+    model:   process.env.SEMALT_MODEL    || 'default',
+
+    // Permission policy. With NONE of these, the SDK refuses every mutating
+    // tool (the safe default). Here we approve read-only-ish work but veto
+    // anything destructive — your host decides.
+    approve: async ({ tag, description }) => {
+      const denied = new Set(['delete_file', 'remove_dir', 'move_file']);
+      const ok = !denied.has(tag);
+      console.error(`[approve] ${ok ? 'ALLOW' : 'DENY '} ${tag} — ${description}`);
+      return ok;
+    },
+
+    // The OS sandbox + deny-list stay ON by default. To run unsandboxed when the
+    // kernel primitive is missing you'd opt in explicitly, e.g.:
+    //   sandbox: { mode: 'off' },
+    //   onUnsandboxed: async () => true,
+  });
+
+  // Stream activity (advisory — the run result is authoritative).
+  agent.on('token', (t) => process.stdout.write(t));
+  agent.on('tool', (e) => console.error(`\n[tool] ${e.tag} (${e.ms}ms)`));
+  agent.on('warning', (m) => console.error(`[warn] ${m}`));
+
+  try {
+    const res = await agent.run(prompt);
+    console.log('\n\n--- result ---');
+    console.log(res.result);
+    console.log('--- meta ---');
+    console.log(JSON.stringify({
+      toolCalls: res.toolCalls.length,
+      usage: res.usage,
+      cost: res.cost,
+      stopReason: res.stopReason,
+      verifyStatus: res.verifyStatus,
+    }, null, 2));
+  } finally {
+    // ALWAYS close — releases MCP connections / spawned processes.
+    await agent.close();
+  }
+}
+
+main().catch((err) => {
+  console.error('embed example failed:', err.message);
+  process.exit(1);
+});

package/index.js

@@ -6,7 +6,8 @@ const os = require('os');
 const path = require('path');
 
 const { PACKAGE_JSON } = require('./lib/constants');
-const { loadConfig, saveConfig, configSet, configShow } = require('./lib/config');
+const { loadConfig, loadUserConfig, saveConfig, configSet, configShow, userLayerForPersist, readUserConfig, loadProjectConfig } = require('./lib/config');
+const { loadRuleLayers } = require('./lib/permission-rules');
 const ui = require('./lib/ui');
 const { registerTerminalCleanup } = require('./lib/ui/terminal');
 const { createPermissionManager } = require('./lib/permissions');
@@ -14,6 +15,7 @@ const { createToolExecutor, extractToolCalls } = require('./lib/tools');
 const { readFileContext } = require('./lib/context');
 const { createApiClient } = require('./lib/api');
 const { createAgentRunner } = require('./lib/agent');
+const { createCheckpointStore, latestSession } = require('./lib/checkpoints');
 const { createCommands } = require('./lib/commands');
 const { parseArgs } = require('./lib/args');
 const { CONFIG_PATH } = require('./lib/constants');
@@ -31,9 +33,19 @@ function getConfig() {
   return config;
 }
 
+// Persist a caller's config object to the USER file, then re-merge the layered
+// view. Only the keys the caller actually changed (vs the current merged view)
+// are layered onto config.json, so env/project/flag overrides the caller merely
+// carried along are never baked in (Task 2.2). All getConfig()/setConfig() call
+// sites are unchanged — they still see the merged view and pass full objects.
+function persistConfig(nextConfig) {
+  const layer = userLayerForPersist(nextConfig, config, loadUserConfig());
+  saveConfig(layer);
+  config = loadConfig();
+}
+
 function setConfig(nextConfig) {
-  config = nextConfig;
-  saveConfig(config);
+  persistConfig(nextConfig);
 }
 
 // Pre-scan argv for permission tier flags before creating PermissionManager
@@ -47,17 +59,99 @@ if (_argv.includes('--allow-all')) {
   if (_argv.includes('--allow-net')) _allowedTiers.push('net');
 }
 const _readonly = _argv.includes('--readonly');
+// The single explicit opt-out of all safety. Pre-scanned here (like the tier
+// flags) so the PermissionManager is constructed with the right mode before any
+// command runs. tools.js reads the same flag from argv for the deny-list bypass.
+const _skipPermissions = _argv.includes('--dangerously-skip-permissions');
 
-const permissionManager = createPermissionManager(ui, { allowedTiers: _allowedTiers, readonly: _readonly });
-const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(permissionManager, ui, getConfig);
+// Per-pattern permission rules (Task 4.1). The user and project layers are read
+// INDEPENDENTLY (not through the shallow-merged config) so the project layer
+// stays separate and can be structurally prevented from widening the user
+// posture. Malformed rules are dropped with a startup warning.
+const _ruleLayers = loadRuleLayers(
+  readUserConfig(),
+  loadProjectConfig(process.cwd()),
+  // audit: allowed — pre-UI startup warning, fires before the TUI initialises.
+  (msg) => process.stderr.write(`⚠ ${msg}\n`),
+);
+
+const permissionManager = createPermissionManager(ui, {
+  allowedTiers: _allowedTiers,
+  readonly: _readonly,
+  skipPermissions: _skipPermissions,
+  rules: _ruleLayers,
+  cwd: process.cwd(),
+});
+// Checkpoints & rewind (Task 4.3). One store per process, shared by the executor
+// (capture point) and the agent runner (per-turn linkage). It auto-generates a
+// session id; cmdChat realigns it with the chat session.id before any turn.
+//
+// Restore-path re-validation (Task 4.3b, Part 1): a rewind that would write/delete
+// a path is re-checked against the CURRENT guards — isPathSafe (CWD confinement /
+// --allow-anywhere), the secret-file guard, the protected-config write guard, and
+// any active `deny` permission rule — so a restore can never re-write a path the
+// guards now forbid. A failing target is refused (skipped), never aborting the
+// whole rewind; `force` does NOT bypass this (it overrides only the external-mod
+// check). This guard lives in the executor owner, not anywhere the model reaches.
+const { isPathSafe: _isPathSafe, isProtectedSecretPath: _isProtectedSecretPath, isProtectedConfigPath: _isProtectedConfigPath } = require('./lib/tools');
+function restoreGuard(targetPath, { willDelete } = {}) {
+  if (!_isPathSafe(targetPath)) return { ok: false, reason: 'path is now outside the allowed area (isPathSafe / --allow-anywhere)' };
+  if (_isProtectedSecretPath(targetPath)) return { ok: false, reason: 'path is a protected secret file' };
+  if (_isProtectedConfigPath(targetPath)) return { ok: false, reason: 'path is a protected config path' };
+  const verdict = permissionManager.resolveRule([willDelete ? 'delete_file' : 'write_file', targetPath]);
+  if (verdict && verdict.decision === 'deny') {
+    return { ok: false, reason: `blocked by a deny permission rule${verdict.reason ? ` (${verdict.reason})` : ''}` };
+  }
+  return { ok: true };
+}
+const checkpointStore = createCheckpointStore({ getConfig, restoreGuard });
+// OS sandbox fallback approver (Task 4.4). When the kernel sandbox is unavailable
+// in `auto` mode, agentExecShell asks a HUMAN here before running a command
+// unsandboxed. Non-TTY → refuse (no way to ask → never a silent unsandboxed run).
+// This lives in the executor owner, NOT anywhere the model can reach, so the
+// agent can never approve its own escape.
+async function onUnsandboxed({ command, reason, installHint } = {}) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  // audit: allowed — interactive confirm outside the agent's stream.
+  process.stderr.write(`\n⚠ OS sandbox unavailable (${reason}). The command will run WITHOUT kernel-level confinement:\n    ${command}\n`);
+  if (installHint) process.stderr.write(`  ${installHint}\n`);
+  try {
+    const idx = await ui.interactiveSelect(
+      ['No, do not run it', 'Yes, run it unsandboxed'],
+      (item, isSelected) => {
+        const cursor = isSelected ? `${ui.FG_YELLOW}❯${ui.RST}` : ' ';
+        const style = isSelected ? ui.FG_CYAN : ui.FG_GRAY;
+        return `  ${cursor} ${style}${item}${ui.RST}`;
+      },
+      { initialIndex: 0 },
+    );
+    return idx === 1;
+  } catch {
+    return false;
+  }
+}
 const apiClient = createApiClient({
   getConfig,
+  // Route the api.js learned-context-length persistence through the same
+  // user-layer rebase so a learned value lands in config.json without baking
+  // in any active env/project/flag override (Task 2.2).
   saveConfig: (nextConfig) => {
-    saveConfig(nextConfig);
-    config = nextConfig;
+    persistConfig(nextConfig);
   },
   ui,
 });
+const { agentExecShell, agentExecFile, describePermission } = createToolExecutor(permissionManager, ui, getConfig, {
+  checkpointStore,
+  onUnsandboxed,
+  // Web-fetch secondary summarizer (Task W.1): http_get runs a separate cheap
+  // LLM call to summarize extracted page content; only the summary enters the
+  // main context.
+  webChat: (messages, opts) => apiClient.chatComplete(messages, opts),
+  // Web search (Task W.2b): the web_search tool calls the backend /api/search
+  // via dashboardSearch and returns compact snippets so the agent can pick
+  // targeted URLs to fetch with http_get instead of guessing.
+  webSearch: (query, opts) => apiClient.dashboardSearch(query, opts),
+});
 const { runAgentLoop } = createAgentRunner({
   chatStream: apiClient.chatStream,
   extractToolCalls: (reply, options = {}) => extractToolCalls(reply, {
@@ -70,7 +164,38 @@ const { runAgentLoop } = createAgentRunner({
   permissionManager,
   ui,
   getConfig,
+  checkpoints: checkpointStore,
+  // Command hooks + self-verification run through the same OS sandbox as
+  // agentExecShell (Pre-Task 5.0a); share the human-approval fallback so an
+  // unavailable sandbox can be approved interactively (never a silent run).
+  onUnsandboxed,
 });
+// Subagents (Task 3.6). Register the `spawn_agent` tool once at startup so it is
+// available in both interactive chat and headless one-shot runs. The manager
+// builds CONSTRAINED child runners that share this process's permission manager
+// (no privilege escalation) and reuse the same executors. Custom agent
+// definitions are discovered from .semalt/agents (project) + ~/.semalt-ai/agents.
+const { createSubagentManager, discoverAgentDefs, buildSpawnAgentEntry } = require('./lib/subagents');
+const { registerDynamicTool } = require('./lib/tool_registry');
+try {
+  const subagentManager = createSubagentManager({
+    chatStream: apiClient.chatStream,
+    extractToolCalls: (reply, options = {}) => extractToolCalls(reply, {
+      repairMalformedXml: !!getConfig().repair_malformed_tool_xml,
+      ...options,
+    }),
+    agentExecShell,
+    agentExecFile,
+    describePermission,
+    permissionManager,
+    ui,
+    getConfig,
+    agentDefs: discoverAgentDefs({ cwd: process.cwd() }),
+    maxConcurrency: getConfig().subagents && getConfig().subagents.max_concurrency,
+  });
+  registerDynamicTool(buildSpawnAgentEntry(subagentManager));
+} catch { /* subagents are best-effort; never block startup */ }
+
 const commands = createCommands({
   getConfig,
   setConfig,
@@ -80,6 +205,7 @@ const commands = createCommands({
   runAgentLoop,
   readFileContext,
   agentExecShell,
+  checkpointStore,
 });
 
 async function main() {
@@ -92,6 +218,24 @@ async function main() {
 
   const command = rawArgs[0];
 
+  // Internal entry (Task 5.3): the detached child of a background task. Not a
+  // user-facing command — `semalt-code run --background` spawns it. It reads its
+  // spec from <taskDir> and runs the agent via the SDK facade with the
+  // launch-fixed policy, writing progress/result/status into the task dir. No
+  // terminal to reach after this point — pure execution.
+  if (command === '__bg-exec') {
+    const taskDir = rawArgs[1];
+    if (!taskDir) { process.exit(1); }
+    const { runBackgroundChild } = require('./lib/background');
+    try {
+      const r = await runBackgroundChild({ taskDir });
+      process.exit(r && r.status === 'completed' ? 0 : 1);
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+
   if (command === '--help' || command === '-h') {
     writer.scrollback(`
 Semalt.AI — Self-hosted AI Coding Assistant
@@ -104,17 +248,25 @@ Commands:
   code <prompt>     Generate code from a prompt
   edit <file> <instruction>  Edit a file with AI
   shell <command>   Run and optionally analyze a shell command
+  run --background <prompt>   Launch a detached background agent task
+  tasks <subcmd>    Manage background tasks: list | status | result | kill | prune
   login             Authorize CLI via browser
   whoami            Show current authorized user
   logout            Clear current CLI login
+  auth set-key [k]  Store the API key in the OS keychain (not plaintext config)
+  mcp <subcmd>      Manage MCP servers: list | status | add | remove | auth
   models            Choose a model
   init              Initialize config
+  rewind [seq] [code|conversation|both]   List checkpoints or restore files and/or conversation (default both)
+  sandbox           Show OS sandbox status (mode, tool, availability, network)
 
 Options:
   -m, --model <name>      Model name
   -r, --resume <chat-id>  Resume a saved chat     (chat command)
   -f, --file <path>       Load file into context  (code command)
+  --image <path>          Attach an image (PNG/JPEG/WebP/GIF); repeatable
   -a, --analyze           Analyze output with AI  (shell command)
+  -b, --background        Launch as a detached background task  (run command)
   --dry-run               Don't save changes      (edit command)
   --api-base <url>        API base URL            (init)
   --api-key  <key>        API key                 (init)
@@ -132,8 +284,20 @@ Options:
   --allow-net             Auto-approve network operations
   --allow-all             Auto-approve everything (use carefully)
   --allow-anywhere        Allow writes outside the project CWD and in sensitive dirs
+  --no-network            Kernel-level no-network for sandboxed shell commands
+                          (bwrap --unshare-net / Seatbelt deny). Binary on/off —
+                          no host proxy, no domain allowlist, no TLS interception.
+                          Same effect as sandbox.network "off" in config.
   --readonly              Block all write operations
-  --new                   Skip session resume prompt
+  --max-iterations <n>    Cap agent-loop iterations per turn (default 50);
+                          0 or "unlimited" removes the cap (power-user choice)
+  --no-verify             Skip self-verification (config.verify) for this run
+  --dangerously-skip-permissions
+                          DANGER: fully auto-approve every tool call AND disable
+                          the destructive-command deny-list and config-file read
+                          guard. The only way to auto-approve in non-TTY mode;
+                          without it, headless runs refuse calls that would need
+                          interactive confirmation. Use only in trusted sandboxes.
   -v, --version           Show CLI version
 
 Config: ${CONFIG_PATH}
@@ -166,11 +330,45 @@ Config: ${CONFIG_PATH}
     await commands.cmdWhoAmI();
   } else if (command === 'logout') {
     await commands.cmdLogout();
+  } else if (command === 'auth') {
+    const sub = rawArgs[1];
+    if (sub === 'set-key') {
+      await commands.cmdAuthSetKey(rawArgs[2]);
+    } else {
+      process.stderr.write(`Usage: semalt-code auth set-key [key]\n`);
+      process.exit(1);
+    }
+  } else if (command === 'run') {
+    const { opts, positional } = parseArgs(rawArgs.slice(1));
+    if (opts.background) {
+      await commands.cmdRun(opts, positional);
+    } else {
+      // `run` without --background is a foreground one-shot, like `code`.
+      await commands.cmdCode(opts, positional);
+    }
+  } else if (command === 'tasks') {
+    await commands.cmdTasks(rawArgs[1], rawArgs.slice(2));
+  } else if (command === 'mcp') {
+    await commands.cmdMcp(rawArgs[1], rawArgs.slice(2));
   } else if (command === 'models') {
     await commands.cmdModels();
   } else if (command === 'init') {
     const { opts } = parseArgs(rawArgs.slice(1));
     commands.cmdInit(opts);
+  } else if (command === 'doctor') {
+    const { diagnose, formatDoctorReport } = require('./lib/doctor');
+    const ping = async () => {
+      const cfg = getConfig();
+      if (!cfg.auth_token) return null;
+      try { const r = await apiClient.dashboardWhoAmI(); return !!(r && r.user); } catch { return false; }
+    };
+    const result = await diagnose({ getConfig, pingDashboard: ping });
+    writer.scrollback(formatDoctorReport(result));
+    await writer.flush();
+  } else if (command === 'sandbox') {
+    const { sandboxStatusReport } = require('./lib/sandbox');
+    writer.scrollback(sandboxStatusReport({ getConfig }));
+    await writer.flush();
   } else if (command === 'audit') {
     try {
       const content = fs.readFileSync(AUDIT_LOG, 'utf8');
@@ -189,6 +387,43 @@ Config: ${CONFIG_PATH}
       writer.scrollback('No audit log found.');
     }
     await writer.flush();
+  } else if (command === 'rewind') {
+    // Standalone rewind: a fresh process with no in-memory session, so target
+    // the most-recently-active session's checkpoints. Conversation rewind here
+    // operates on the saved session file (SessionStorage) of the same id.
+    const { formatCheckpointList, formatRewindResult, normalizeRewindMode, REWIND_MODES } = require('./lib/checkpoints');
+    const { SessionStorage } = require('./lib/storage');
+    const force = rawArgs.includes('--force') || rawArgs.includes('force');
+    const tokens = rawArgs.slice(1).filter((a) => a !== '--force' && a !== 'force');
+    const modeToken = tokens.find((t) => REWIND_MODES.includes(String(t).toLowerCase()));
+    const mode = normalizeRewindMode(modeToken);
+    const target = tokens.find((t) => t !== modeToken);
+    const session = latestSession();
+    if (!session) {
+      writer.scrollback('No checkpoints found.');
+      await writer.flush();
+      return;
+    }
+    const store = createCheckpointStore({ getConfig, sessionId: session, restoreGuard });
+    if (!target || target === 'list') {
+      writer.scrollback(formatCheckpointList(store.list(session), { session }));
+    } else if (mode === null) {
+      writer.scrollback(`Unknown rewind mode "${modeToken}". Use one of: ${REWIND_MODES.join(', ')}.`);
+    } else {
+      // Load the saved session's messages for a conversation/both rewind. The
+      // checkpoint session id matches the SessionStorage id (chat aligns them).
+      let saved = null;
+      const wantConversation = mode === 'conversation' || mode === 'both';
+      if (wantConversation) { try { saved = new SessionStorage().load(session); } catch { saved = null; } }
+      const messages = saved && Array.isArray(saved.messages) ? saved.messages : null;
+      const res = store.rewind(target === 'last' ? 'last' : target, { force, session, mode, messages });
+      if (res.conversation && res.conversation.ok && saved) {
+        saved.messages = res.conversation.messages;
+        try { new SessionStorage().save(saved); } catch { /* best effort */ }
+      }
+      writer.scrollback(formatRewindResult(res));
+    }
+    await writer.flush();
   } else if (command === 'config') {
     const sub = rawArgs[1];
     if (sub === 'set') {
@@ -213,8 +448,14 @@ Config: ${CONFIG_PATH}
     }
     await writer.flush();
   } else {
-    const { opts } = parseArgs(rawArgs);
-    await commands.cmdChat(opts);
+    const { opts, positional } = parseArgs(rawArgs);
+    // `-p/--print` (or any --output-format) turns a bare prompt into a headless
+    // one-shot run instead of opening interactive chat (Task 2.4).
+    if (opts.print) {
+      await commands.cmdCode(opts, positional);
+    } else {
+      await commands.cmdChat(opts);
+    }
   }
 }