@smithers-orchestrator/agents 0.21.0 → 0.23.0

package/src/cli-surface/cliAgentSurfaceManifest.js

@@ -0,0 +1,490 @@
+/** @typedef {import("./CliAgentSurfaceTypes.ts").CliAgentSurfaceManifestEntry} CliAgentSurfaceManifestEntry */
+
+/**
+ * Compatibility contract for CLI-backed agents. Keep this list focused on the
+ * command surface Smithers emits directly; user-supplied extraArgs remain an
+ * escape hatch and are intentionally not modeled here.
+ *
+ * @type {readonly CliAgentSurfaceManifestEntry[]}
+ */
+export const CLI_AGENT_SURFACE_MANIFEST = [
+  {
+    id: "claude",
+    displayName: "Claude Code",
+    binary: "claude",
+    packageExport: "ClaudeCodeAgent",
+    defaultOutputFormat: "stream-json",
+    docsUrls: ["https://docs.anthropic.com/en/docs/claude-code/cli-reference"],
+    emittedFlags: [
+      "--print",
+      "--add-dir",
+      "--agent",
+      "--agents",
+      "--allow-dangerously-skip-permissions",
+      "--dangerously-skip-permissions",
+      "--permission-mode",
+      "--allowed-tools",
+      "--append-system-prompt",
+      "--betas",
+      "--chrome",
+      "--no-chrome",
+      "--continue",
+      "--debug",
+      "--debug-file",
+      "--disable-slash-commands",
+      "--disallowed-tools",
+      "--fallback-model",
+      "--file",
+      "--fork-session",
+      "--from-pr",
+      "--ide",
+      "--include-partial-messages",
+      "--input-format",
+      "--json-schema",
+      "--max-budget-usd",
+      "--mcp-config",
+      "--mcp-debug",
+      "--model",
+      "--no-session-persistence",
+      "--output-format",
+      "--plugin-dir",
+      "--replay-user-messages",
+      "--resume",
+      "--session-id",
+      "--setting-sources",
+      "--settings",
+      "--strict-mcp-config",
+      "--system-prompt",
+      "--tools",
+      "--verbose",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "configDir", env: "CLAUDE_CONFIG_DIR" },
+      { option: "apiKey", env: "ANTHROPIC_API_KEY" },
+      { option: "resume", flag: "--resume" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--resume"],
+      notes: "Native Claude session id.",
+    },
+  },
+  {
+    id: "codex",
+    displayName: "Codex",
+    binary: "codex",
+    packageExport: "CodexAgent",
+    defaultOutputFormat: "stream-json",
+    docsUrls: ["https://developers.openai.com/codex/cli/reference"],
+    emittedFlags: [
+      "-c",
+      "--enable",
+      "--disable",
+      "--image",
+      "--model",
+      "--oss",
+      "--local-provider",
+      "--sandbox",
+      "--profile",
+      "--full-auto",
+      "--dangerously-bypass-approvals-and-sandbox",
+      "--cd",
+      "--skip-git-repo-check",
+      "--add-dir",
+      "--output-schema",
+      "--color",
+      "--json",
+      "--output-last-message",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "configDir", env: "CODEX_HOME" },
+      { option: "apiKey", env: "OPENAI_API_KEY" },
+      { option: "resumeSession", notes: "Uses `codex exec resume <thread-id>`." },
+    ],
+    resume: {
+      kind: "subcommand",
+      emitted: ["exec", "resume"],
+      notes: "Resume uses `codex exec resume <thread-id>` and omits output schema wiring.",
+    },
+  },
+  {
+    id: "antigravity",
+    displayName: "Antigravity",
+    binary: "agy",
+    packageExport: "AntigravityAgent",
+    defaultOutputFormat: "text",
+    docsUrls: [
+      "https://antigravity.google/docs/cli-best-practices",
+      "https://antigravity.google/docs/cli-conversations",
+      "https://antigravity.google/docs/cli-plugins",
+    ],
+    emittedFlags: [
+      "-p",
+      "--cwd",
+      "--model",
+      "--sandbox",
+      "--dangerously-skip-permissions",
+      "--allowed-mcp-server-names",
+      "--allowed-tools",
+      "--add-dir",
+      "--continue",
+      "--conversation",
+      "--gemini_dir",
+    ],
+    supportedFlags: [
+      "-p",
+      "--cwd",
+      "--model",
+      "--sandbox",
+      "--dangerously-skip-permissions",
+      "--allowed-mcp-server-names",
+      "--allowed-tools",
+      "--add-dir",
+      "--continue",
+      "--conversation",
+      "-c",
+      "--gemini_dir",
+    ],
+    unsupportedFlags: [
+      {
+        flag: "--output-format",
+        reason: "Current agy builds do not expose an output-format flag; Smithers treats stdout as text.",
+      },
+      {
+        flag: "--include-directories",
+        replacement: "--add-dir",
+        reason: "The directory allow-list flag was renamed.",
+      },
+      {
+        flag: "--resume",
+        replacement: "--conversation",
+        reason: "Conversation resume now uses --conversation or -c.",
+      },
+      {
+        flag: "--list-sessions",
+        replacement: "/resume",
+        reason: "Conversation listing is an interactive slash command.",
+      },
+      {
+        flag: "--screen-reader",
+        reason: "Current agy builds do not expose this flag.",
+      },
+      {
+        flag: "--debug",
+        reason: "Current agy builds do not expose this flag.",
+      },
+      {
+        flag: "--extensions",
+        replacement: "agy plugin",
+        reason: "Extensions were renamed to plugins and are managed by the plugin subcommand.",
+      },
+      {
+        flag: "--list-extensions",
+        replacement: "agy plugin list",
+        reason: "Plugins are listed through the plugin subcommand.",
+      },
+      {
+        flag: "--delete-session",
+        replacement: "/resume",
+        reason: "Conversation management is handled inside the CLI session.",
+      },
+      {
+        flag: "--prompt",
+        replacement: "-p",
+        reason: "Non-interactive prompts use -p.",
+      },
+    ],
+    optionMappings: [
+      { option: "includeDirectories", flag: "--add-dir" },
+      { option: "resume", flag: "--conversation" },
+      { option: "conversation", flag: "--conversation" },
+      { option: "continue", flag: "--continue" },
+      { option: "configDir", flag: "--gemini_dir", env: "GEMINI_DIR" },
+      { option: "geminiDir", flag: "--gemini_dir", env: "GEMINI_DIR" },
+      { option: "apiKey", env: "GEMINI_API_KEY" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--conversation"],
+      notes: "Smithers maps native session ids to `agy --conversation <id>`.",
+    },
+  },
+  {
+    id: "gemini",
+    displayName: "Gemini",
+    binary: "gemini",
+    packageExport: "GeminiAgent",
+    defaultOutputFormat: "json",
+    docsUrls: ["https://github.com/google-gemini/gemini-cli"],
+    emittedFlags: [
+      "--debug",
+      "--model",
+      "--sandbox",
+      "--approval-mode",
+      "--yolo",
+      "--experimental-acp",
+      "--allowed-mcp-server-names",
+      "--allowed-tools",
+      "--extensions",
+      "--list-extensions",
+      "--resume",
+      "--list-sessions",
+      "--delete-session",
+      "--include-directories",
+      "--screen-reader",
+      "--output-format",
+      "--prompt",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "configDir", env: "GEMINI_DIR" },
+      { option: "apiKey", env: "GEMINI_API_KEY" },
+      { option: "resume", flag: "--resume" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--resume"],
+      notes: "Legacy Gemini CLI session id.",
+    },
+  },
+  {
+    id: "pi",
+    displayName: "Pi",
+    binary: "pi",
+    packageExport: "PiAgent",
+    defaultOutputFormat: "text",
+    docsUrls: ["https://github.com/withpi/pi"],
+    emittedFlags: [
+      "--print",
+      "--mode",
+      "--provider",
+      "--model",
+      "--api-key",
+      "--system-prompt",
+      "--append-system-prompt",
+      "--continue",
+      "--resume",
+      "--session",
+      "--session-dir",
+      "--no-session",
+      "--models",
+      "--list-models",
+      "--export",
+      "--tools",
+      "--no-tools",
+      "--extension",
+      "--no-extensions",
+      "--skill",
+      "--no-skills",
+      "--prompt-template",
+      "--no-prompt-templates",
+      "--theme",
+      "--no-themes",
+      "--thinking",
+      "--verbose",
+      "--files",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "resumeSession", flag: "--session" },
+      { option: "apiKey", flag: "--api-key" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--session"],
+      notes: "Per-call resumeSession maps to a Pi session id.",
+    },
+  },
+  {
+    id: "kimi",
+    displayName: "Kimi",
+    binary: "kimi",
+    packageExport: "KimiAgent",
+    defaultOutputFormat: "text",
+    docsUrls: ["https://github.com/MoonshotAI/kimi-cli"],
+    emittedFlags: [
+      "--print",
+      "--output-format",
+      "--final-message-only",
+      "--work-dir",
+      "--session",
+      "--continue",
+      "--model",
+      "--thinking",
+      "--no-thinking",
+      "--quiet",
+      "--agent",
+      "--agent-file",
+      "--mcp-config-file",
+      "--mcp-config",
+      "--skills-dir",
+      "--max-steps-per-turn",
+      "--max-retries-per-step",
+      "--max-ralph-iterations",
+      "--verbose",
+      "--debug",
+      "--prompt",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "configDir", env: "KIMI_SHARE_DIR" },
+      { option: "resumeSession", flag: "--session" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--session"],
+      notes: "Smithers persists the Kimi session id and reuses it through --session.",
+    },
+  },
+  {
+    id: "forge",
+    displayName: "Forge",
+    binary: "forge",
+    packageExport: "ForgeAgent",
+    defaultOutputFormat: "text",
+    docsUrls: ["https://forgecode.dev/docs/cli"],
+    emittedFlags: [
+      "--model",
+      "--provider",
+      "--agent",
+      "--conversation-id",
+      "--sandbox",
+      "--restricted",
+      "--verbose",
+      "--workflow",
+      "--event",
+      "--conversation",
+      "-C",
+      "--prompt",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "conversationId", flag: "--conversation-id" },
+      { option: "resumeSession", flag: "--conversation-id" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--conversation-id"],
+      notes: "Smithers persists Forge conversation ids.",
+    },
+  },
+  {
+    id: "amp",
+    displayName: "Amp",
+    binary: "amp",
+    packageExport: "AmpAgent",
+    defaultOutputFormat: "text",
+    docsUrls: ["https://ampcode.com/manual"],
+    emittedFlags: [
+      "--dangerously-allow-all",
+      "--model",
+      "--visibility",
+      "--mcp-config",
+      "--settings-file",
+      "--log-level",
+      "--log-file",
+      "--no-ide",
+      "--no-jetbrains",
+      "--no-color",
+      "--archive",
+      "--execute",
+      "--stream-json",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "dangerouslyAllowAll", flag: "--dangerously-allow-all" },
+    ],
+    resume: {
+      kind: "subcommand",
+      emitted: ["threads", "continue"],
+      notes: "Native hijack uses `amp threads continue`; headless generate starts a managed thread.",
+    },
+  },
+  {
+    id: "vibe",
+    displayName: "Vibe",
+    binary: "vibe",
+    packageExport: "VibeAgent",
+    defaultOutputFormat: "stream-json",
+    docsUrls: ["https://docs.mistral.ai/mistral-vibe/terminal"],
+    emittedFlags: [
+      "--agent",
+      "--max-turns",
+      "--max-price",
+      "--max-tokens",
+      "--enabled-tools",
+      "--trust",
+      "--output",
+      "--workdir",
+      "--prompt",
+      "--resume",
+      "-c",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "resumeSession", flag: "--resume" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--resume"],
+      notes: "Maps to vibe --resume <session-id> for headless continuation.",
+    },
+  },
+  {
+    id: "opencode",
+    displayName: "OpenCode",
+    binary: "opencode",
+    packageExport: "OpenCodeAgent",
+    defaultOutputFormat: "stream-json",
+    docsUrls: ["https://opencode.ai/docs/cli"],
+    emittedFlags: [
+      "run",
+      "-m",
+      "--dir",
+      "--format",
+      "--agent",
+      "-f",
+      "--continue",
+      "--session",
+      "--variant",
+      "--",
+    ],
+    supportedFlags: [],
+    unsupportedFlags: [],
+    optionMappings: [
+      { option: "sessionId", flag: "--session" },
+      { option: "resumeSession", flag: "--session" },
+      { option: "yolo", env: "OPENCODE_PERMISSION" },
+    ],
+    resume: {
+      kind: "flag",
+      emitted: ["--session"],
+      notes: "OpenCode receives a session id through --session for headless continuation.",
+    },
+  },
+];
+
+/**
+ * @param {string} id
+ * @returns {CliAgentSurfaceManifestEntry | undefined}
+ */
+export function getCliAgentSurfaceManifestEntry(id) {
+  return CLI_AGENT_SURFACE_MANIFEST.find((entry) => entry.id === id);
+}
+
+/**
+ * @returns {CliAgentSurfaceManifestEntry[]}
+ */
+export function listCliAgentSurfaceManifests() {
+  return [...CLI_AGENT_SURFACE_MANIFEST];
+}

package/src/cli-surface/index.js

@@ -0,0 +1,5 @@
+export {
+  CLI_AGENT_SURFACE_MANIFEST,
+  getCliAgentSurfaceManifestEntry,
+  listCliAgentSurfaceManifests,
+} from "./cliAgentSurfaceManifest.js";

package/src/diagnostics/runDiagnostics.js

@@ -19,10 +19,15 @@ const PER_CHECK_TIMEOUT_MS = 5_000;
  */
 async function runCheck(check, ctx) {
     const start = performance.now();
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    let timeoutHandle;
     try {
         return await Promise.race([
             check.run(ctx),
-            new Promise((_, reject) => setTimeout(() => reject(new SmithersError("AGENT_DIAGNOSTIC_TIMEOUT", "diagnostic check timed out", { timeoutMs: PER_CHECK_TIMEOUT_MS })), PER_CHECK_TIMEOUT_MS)),
+            new Promise((_, reject) => {
+                timeoutHandle = setTimeout(() => reject(new SmithersError("AGENT_DIAGNOSTIC_TIMEOUT", "diagnostic check timed out", { timeoutMs: PER_CHECK_TIMEOUT_MS })), PER_CHECK_TIMEOUT_MS);
+                timeoutHandle.unref?.();
+            }),
         ]);
     }
     catch (err) {
@@ -33,6 +38,9 @@ async function runCheck(check, ctx) {
             durationMs: performance.now() - start,
         };
     }
+    finally {
+        clearTimeout(timeoutHandle);
+    }
 }
 /**
  * @param {AgentDiagnosticStrategy} strategy