@smithers-orchestrator/agents 0.21.0 → 0.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.21.0",
+  "version": "0.23.0",
   "description": "AI SDK and CLI agent adapters for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -47,12 +47,13 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.71",
     "@ai-sdk/openai": "^3.0.53",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "ai": "^6.0.168",
     "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/errors": "0.21.0",
-    "@smithers-orchestrator/observability": "0.21.0",
-    "@smithers-orchestrator/driver": "0.21.0"
+    "@smithers-orchestrator/errors": "0.23.0",
+    "@smithers-orchestrator/driver": "0.23.0",
+    "@smithers-orchestrator/observability": "0.23.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
@@ -60,7 +61,7 @@
     "typescript": "~5.9.3"
   },
   "scripts": {
-    "test": "bun test tests",
+    "test": "bun test --timeout=60000 --max-concurrency=1 tests",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build": "tsup --dts-only"
   }

package/src/AmpAgent.js

@@ -6,6 +6,31 @@ import { BaseCliAgent, pushFlag, isRecord, asString, toolKindFromName, createSyn
 /** @typedef {import("./capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
 /** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 
+/**
+ * @returns {AgentCapabilityRegistry}
+ */
+export function createAmpCapabilityRegistry() {
+    return {
+        version: 1,
+        engine: "amp",
+        runtimeTools: {},
+        mcp: {
+            bootstrap: "project-config",
+            supportsProjectScope: true,
+            supportsUserScope: false,
+        },
+        skills: {
+            supportsSkills: false,
+            smithersSkillIds: [],
+        },
+        humanInteraction: {
+            supportsUiRequests: false,
+            methods: [],
+        },
+        builtIns: ["default"],
+    };
+}
+
 /**
  * Agent implementation that wraps the 'amp' CLI executable.
  * It translates generation requests into CLI arguments and executes the process.
@@ -23,25 +48,7 @@ export class AmpAgent extends BaseCliAgent {
     constructor(opts = {}) {
         super(opts);
         this.opts = opts;
-        this.capabilities = {
-            version: 1,
-            engine: "amp",
-            runtimeTools: {},
-            mcp: {
-                bootstrap: "project-config",
-                supportsProjectScope: true,
-                supportsUserScope: false,
-            },
-            skills: {
-                supportsSkills: false,
-                smithersSkillIds: [],
-            },
-            humanInteraction: {
-                supportsUiRequests: false,
-                methods: [],
-            },
-            builtIns: ["default"],
-        };
+        this.capabilities = createAmpCapabilityRegistry();
     }
     /**
    * @returns {CliOutputInterpreter}

package/src/AntigravityAgent.js

@@ -1,9 +1,51 @@
 import { BaseCliAgent, pushFlag, pushList, isRecord, asString, truncate, toolKindFromName, createSyntheticIdGenerator, } from "./BaseCliAgent/index.js";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { normalizeCapabilityStringList, } from "./capability-registry/index.js";
+import { getCliAgentSurfaceManifestEntry } from "./cli-surface/index.js";
 /** @typedef {import("./capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
 /** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 /** @typedef {import("./AntigravityAgentOptions.ts").AntigravityAgentOptions} AntigravityAgentOptions */
 
+const ANTIGRAVITY_SURFACE = getCliAgentSurfaceManifestEntry("antigravity");
+
+/**
+ * @param {string} option
+ * @param {string} flag
+ * @returns {SmithersError}
+ */
+function unsupportedAntigravityOption(option, flag) {
+    const rule = ANTIGRAVITY_SURFACE?.unsupportedFlags.find((entry) => entry.flag === flag);
+    const replacement = rule?.replacement ? ` Use ${rule.replacement} instead.` : "";
+    const reason = rule?.reason ? ` ${rule.reason}` : "";
+    return new SmithersError("AGENT_CONFIG_INVALID", `AntigravityAgent option "${option}" maps to unsupported agy flag ${flag}.${reason}${replacement}`, {
+        agentEngine: "antigravity",
+        option,
+        flag,
+        replacement: rule?.replacement,
+        failureRetryable: false,
+    });
+}
+
+/**
+ * @param {AntigravityAgentOptions} opts
+ */
+function assertSupportedAntigravityOptions(opts) {
+    if (opts.debug)
+        throw unsupportedAntigravityOption("debug", "--debug");
+    if (opts.screenReader)
+        throw unsupportedAntigravityOption("screenReader", "--screen-reader");
+    if (opts.outputFormat !== undefined)
+        throw unsupportedAntigravityOption("outputFormat", "--output-format");
+    if (opts.listSessions)
+        throw unsupportedAntigravityOption("listSessions", "--list-sessions");
+    if (opts.deleteSession !== undefined)
+        throw unsupportedAntigravityOption("deleteSession", "--delete-session");
+    if (opts.extensions?.length)
+        throw unsupportedAntigravityOption("extensions", "--extensions");
+    if (opts.listExtensions)
+        throw unsupportedAntigravityOption("listExtensions", "--list-extensions");
+}
+
 /**
  * @param {AntigravityAgentOptions} opts
  */
@@ -209,15 +251,13 @@ export class AntigravityAgent extends BaseCliAgent {
    * @param {{ prompt: string; systemPrompt?: string; cwd: string; options: any; }} params
    */
     async buildCommand(params) {
+        assertSupportedAntigravityOptions(this.opts);
         const args = [];
         const yoloEnabled = this.opts.dangerouslySkipPermissions ?? this.opts.yolo ?? this.yolo;
-        const outputFormat = this.opts.outputFormat ??
-            (params.options?.onEvent ? "stream-json" : "json");
         const resumeSession = typeof params.options?.resumeSession === "string"
             ? params.options.resumeSession
-            : this.opts.resume;
-        if (this.opts.debug)
-            args.push("--debug");
+            : this.opts.conversation ?? this.opts.resume;
+        args.push("--cwd", params.cwd);
         pushFlag(args, "--model", this.opts.model ?? this.model);
         if (this.opts.sandbox)
             args.push("--sandbox");
@@ -232,18 +272,11 @@ export class AntigravityAgent extends BaseCliAgent {
                 pushList(args, "--allowed-tools", this.opts.allowedTools);
             }
         }
-        pushList(args, "--extensions", this.opts.extensions);
-        if (this.opts.listExtensions)
-            args.push("--list-extensions");
-        pushFlag(args, "--resume", resumeSession);
-        if (this.opts.listSessions)
-            args.push("--list-sessions");
-        pushFlag(args, "--delete-session", this.opts.deleteSession);
-        pushList(args, "--include-directories", this.opts.includeDirectories);
-        if (this.opts.screenReader)
-            args.push("--screen-reader");
+        if (this.opts.continue)
+            args.push("--continue");
+        pushFlag(args, "--conversation", resumeSession);
+        pushList(args, "--add-dir", this.opts.includeDirectories);
         pushFlag(args, "--gemini_dir", this.opts.geminiDir ?? this.opts.configDir);
-        pushFlag(args, "--output-format", outputFormat);
         if (this.extraArgs?.length)
             args.push(...this.extraArgs);
         const systemPrefix = params.systemPrompt
@@ -253,14 +286,16 @@ export class AntigravityAgent extends BaseCliAgent {
             ? "\n\nREMINDER: Your response MUST be ONLY the required raw JSON object. Do not include prose, markdown, or code fences. The first character must be `{` and the last character must be `}`.\n"
             : "";
         const fullPrompt = `${systemPrefix}${params.prompt ?? ""}${jsonReminder}`;
-        args.push("--prompt", fullPrompt);
+        args.push("-p", fullPrompt);
         const accountEnv = {};
+        if (this.opts.geminiDir ?? this.opts.configDir)
+            accountEnv.GEMINI_DIR = this.opts.geminiDir ?? this.opts.configDir;
         if (this.opts.apiKey)
             accountEnv.GEMINI_API_KEY = this.opts.apiKey;
         return {
             command: this.opts.binary ?? "agy",
             args,
-            outputFormat,
+            outputFormat: "text",
             env: Object.keys(accountEnv).length > 0 ? accountEnv : undefined,
         };
     }

package/src/AntigravityAgentOptions.ts

@@ -1,30 +1,71 @@
 import type { BaseCliAgentOptions } from "./BaseCliAgent/BaseCliAgentOptions";
 
 export type AntigravityAgentOptions = BaseCliAgentOptions & {
-  debug?: boolean;
   model?: string;
   sandbox?: boolean;
   yolo?: boolean;
   dangerouslySkipPermissions?: boolean;
   allowedMcpServerNames?: string[];
   allowedTools?: string[];
+  /**
+   * @deprecated Antigravity renamed extensions to plugins and manages them via
+   * `agy plugin`; launch-time extension flags are rejected at runtime.
+   */
   extensions?: string[];
+  /**
+   * @deprecated Use `agy plugin list` outside Smithers. This option is rejected
+   * at runtime because current `agy` builds no longer accept it during launch.
+   */
   listExtensions?: boolean;
+  /**
+   * Native Antigravity conversation id. Smithers emits `--conversation`.
+   */
+  conversation?: string;
+  /**
+   * Continue the latest Antigravity conversation. Smithers emits `--continue`.
+   */
+  continue?: boolean;
+  /**
+   * @deprecated Use `conversation`; Smithers still maps this to
+   * `--conversation` for compatibility.
+   */
   resume?: string;
+  /**
+   * @deprecated Conversation listing is interactive via `/resume`; this option
+   * is rejected at runtime.
+   */
   listSessions?: boolean;
+  /**
+   * @deprecated Conversation deletion is not a supported non-interactive
+   * launch flag; this option is rejected at runtime.
+   */
   deleteSession?: string;
   includeDirectories?: string[];
+  /**
+   * @deprecated Current `agy` builds do not expose `--screen-reader`; this
+   * option is rejected at runtime.
+   */
   screenReader?: boolean;
+  /**
+   * @deprecated Current `agy` builds do not expose `--output-format`; Smithers
+   * reads Antigravity stdout as text.
+   */
   outputFormat?: "text" | "json" | "stream-json";
+  /**
+   * @deprecated Current `agy` builds do not expose `--debug`; this option is
+   * rejected at runtime.
+   */
+  debug?: boolean;
   /**
    * Antigravity CLI binary to execute. The official CLI currently installs
    * `agy`; this exists for test harnesses and future binary renames.
    */
   binary?: string;
   /**
-   * Path to an isolated Google CLI config root. Passed as `--gemini_dir` so
-   * Antigravity reads/writes `<configDir>/antigravity-cli/...` instead of the
-   * user's default `~/.gemini/antigravity-cli/...`.
+   * Path to an isolated Google CLI config root. Smithers passes it as
+   * `--gemini_dir` and `GEMINI_DIR` so Antigravity reads/writes
+   * `<configDir>/antigravity-cli/...` instead of the user's default
+   * `~/.gemini/antigravity-cli/...`.
    */
   configDir?: string;
   /**

package/src/BaseCliAgent/AgentGenerateOptions.ts

@@ -20,5 +20,17 @@ export type AgentGenerateOptions = {
   isRetry?: unknown;
   retryAttempt?: unknown;
   schemaRetry?: unknown;
+  /**
+   * Run context for the task this agent invocation belongs to. Surfaced to the
+   * spawned agent process (and its subprocesses) as SMITHERS_RUN_ID / NODE_ID /
+   * ITERATION / ATTEMPT so the agent can address its own run — e.g. to raise a
+   * blocking `smithers ask-human` request.
+   */
+  taskContext?: {
+    runId?: string;
+    nodeId?: string;
+    iteration?: number;
+    attempt?: number;
+  };
   [key: string]: unknown;
 };

package/src/BaseCliAgent/BaseCliAgent.js

@@ -14,6 +14,7 @@ import { extractTextFromJsonValue } from "./extractTextFromJsonValue.js";
 import { createAgentStdoutTextEmitter } from "./createAgentStdoutTextEmitter.js";
 import { buildGenerateResult } from "./buildGenerateResult.js";
 import { runCommandEffect } from "./runCommandEffect.js";
+import { taskContextEnv } from "./taskContextEnv.js";
 /** @typedef {import("./AgentCliEvent.ts").AgentCliEvent} AgentCliEvent */
 
 /** @typedef {import("./AgentGenerateOptions.ts").AgentGenerateOptions} AgentGenerateOptions */
@@ -458,6 +459,7 @@ export function extractUsageFromOutput(raw) {
     const lines = stripOscSequences(raw).split(/\r?\n/).filter(Boolean);
     const usage = {};
     let found = false;
+    let countedIncremental = false;
     for (const line of lines) {
         let parsed;
         try {
@@ -480,6 +482,7 @@ export function extractUsageFromOutput(raw) {
                     (usage.cacheWriteTokens ?? 0) + u.cache_creation_input_tokens;
             }
             found = true;
+            countedIncremental = true;
             continue;
         }
         if (parsed.type === "message_delta" && parsed.usage) {
@@ -488,8 +491,19 @@ export function extractUsageFromOutput(raw) {
                     (usage.outputTokens ?? 0) + parsed.usage.output_tokens;
             }
             found = true;
+            countedIncremental = true;
             continue;
         }
+        if (parsed.type === "result") {
+            // Claude Code stream-json emits a terminal "result" event whose
+            // top-level usage summarizes tokens already accumulated from the
+            // per-message message_start/message_delta events. If we counted
+            // those incrementally, skip this event to avoid double-counting.
+            // Otherwise fall through so the usage is still captured.
+            if (countedIncremental) {
+                continue;
+            }
+        }
         if (parsed.type === "turn.completed" && parsed.usage) {
             const u = parsed.usage;
             if (u.input_tokens) {
@@ -615,7 +629,11 @@ export class BaseCliAgent {
             idleMs: this.idleTimeoutMs,
         });
         const cwd = this.cwd ?? options?.rootDir ?? process.cwd();
-        const env = { ...process.env, ...this.env };
+        const env = {
+            ...process.env,
+            ...this.env,
+            ...taskContextEnv(options?.taskContext),
+        };
         const combinedSystem = combineNonEmpty([
             this.systemPrompt,
             systemFromMessages,

package/src/BaseCliAgent/runRpcCommandEffect.js

@@ -13,7 +13,7 @@ import { truncateToBytes } from "./truncateToBytes.js";
 
 /** @typedef {import("./PiExtensionUiRequest.ts").PiExtensionUiRequest} PiExtensionUiRequest */
 /**
- * @typedef {{ cwd: string; env: Record<string, string>; prompt: string; timeoutMs?: number; idleTimeoutMs?: number; signal?: AbortSignal; maxOutputBytes?: number; onStdout?: (chunk: string) => void; onStderr?: (chunk: string) => void; onJsonEvent?: (event: Record<string, unknown>) => Promise<void> | void; onExtensionUiRequest?: (request: PiExtensionUiRequest) => Promise<PiExtensionUiResponse | null> | PiExtensionUiResponse | null; }} RunRpcCommandOptions
+ * @typedef {{ cwd: string; env: Record<string, string>; prompt: string; timeoutMs?: number; idleTimeoutMs?: number; signal?: AbortSignal; maxOutputBytes?: number; onStdout?: (chunk: string) => void; onStderr?: (chunk: string) => void; onJsonEvent?: (event: Record<string, unknown>) => Promise<void> | void; onExtensionUiRequest?: (request: PiExtensionUiRequest) => Promise<PiExtensionUiResponse | null> | PiExtensionUiResponse | null; spawnFn?: typeof spawn; }} RunRpcCommandOptions
  */
 
 /**
@@ -61,7 +61,7 @@ function createInactivityTimer(timeoutMs, onTimeout) {
  * @returns {Effect.Effect<{ text: string; output: unknown; stderr: string; exitCode: number | null; usage?: any; }, SmithersError>}
  */
 export function runRpcCommandEffect(command, args, options) {
-    const { cwd, env, prompt, timeoutMs, idleTimeoutMs, signal, maxOutputBytes, onStdout, onStderr, onJsonEvent, onExtensionUiRequest, } = options;
+    const { cwd, env, prompt, timeoutMs, idleTimeoutMs, signal, maxOutputBytes, onStdout, onStderr, onJsonEvent, onExtensionUiRequest, spawnFn = spawn, } = options;
     const span = `agent:${command}:rpc`;
     const logAnnotations = {
         agentCommand: command,
@@ -82,7 +82,7 @@ export function runRpcCommandEffect(command, args, options) {
         let extractedUsage = undefined;
         let stderrTruncated = false;
         logDebug("starting agent RPC command", logAnnotations, span);
-        const child = spawn(command, args, {
+        const child = spawnFn(command, args, {
             cwd,
             env,
             detached: true,
@@ -108,6 +108,8 @@ export function runRpcCommandEffect(command, args, options) {
             if (settled)
                 return;
             settled = true;
+            inactivity.clear();
+            totalTimeout.clear();
             if (signal) {
                 signal.removeEventListener("abort", onAbort);
             }
@@ -131,6 +133,8 @@ export function runRpcCommandEffect(command, args, options) {
             if (settled)
                 return;
             settled = true;
+            inactivity.clear();
+            totalTimeout.clear();
             if (signal) {
                 signal.removeEventListener("abort", onAbort);
             }

package/src/BaseCliAgent/taskContextEnv.js

@@ -0,0 +1,31 @@
+/**
+ * Map a task's run context into the `SMITHERS_*` environment variables that a
+ * Smithers-spawned agent — and any subprocess it runs, e.g. `smithers ask-human` —
+ * uses to identify the run/node it belongs to. Undefined/blank fields are omitted
+ * so we never clobber an inherited value with `"undefined"`.
+ *
+ * @param {{ runId?: string, nodeId?: string, iteration?: number, attempt?: number } | null | undefined} taskContext
+ * @returns {Record<string, string>}
+ */
+export function taskContextEnv(taskContext) {
+    if (!taskContext) {
+        return {};
+    }
+    /** @type {Record<string, string>} */
+    const env = {};
+    if (typeof taskContext.runId === "string" && taskContext.runId.length > 0) {
+        env.SMITHERS_RUN_ID = taskContext.runId;
+    }
+    if (typeof taskContext.nodeId === "string" && taskContext.nodeId.length > 0) {
+        env.SMITHERS_NODE_ID = taskContext.nodeId;
+    }
+    if (typeof taskContext.iteration === "number" &&
+        Number.isInteger(taskContext.iteration)) {
+        env.SMITHERS_ITERATION = String(taskContext.iteration);
+    }
+    if (typeof taskContext.attempt === "number" &&
+        Number.isInteger(taskContext.attempt)) {
+        env.SMITHERS_ATTEMPT = String(taskContext.attempt);
+    }
+    return env;
+}

package/src/BaseCliAgent/truncateToBytes.js

@@ -9,5 +9,22 @@ export function truncateToBytes(text, maxBytes) {
     const buf = Buffer.from(text, "utf8");
     if (buf.length <= maxBytes)
         return text;
-    return buf.subarray(0, maxBytes).toString("utf8");
+    let end = maxBytes;
+    // Back off any UTF-8 continuation bytes (0b10xxxxxx) so the slice ends on a
+    // codepoint boundary, then drop the lead byte if its sequence is incomplete.
+    while (end > 0 && (buf[end] & 0xc0) === 0x80)
+        end--;
+    if (end > 0) {
+        const lead = buf[end - 1];
+        let seqLen = 1;
+        if ((lead & 0xe0) === 0xc0)
+            seqLen = 2;
+        else if ((lead & 0xf0) === 0xe0)
+            seqLen = 3;
+        else if ((lead & 0xf8) === 0xf0)
+            seqLen = 4;
+        if ((end - 1) + seqLen > maxBytes)
+            end--;
+    }
+    return buf.subarray(0, end).toString("utf8");
 }

package/src/ClaudeCodeAgent.js

@@ -383,7 +383,7 @@ export class ClaudeCodeAgent extends BaseCliAgent {
             args.push("--chrome");
         if (this.opts.noChrome)
             args.push("--no-chrome");
-        if (this.opts.continue)
+        if (this.opts.continue || params.options?.continueSession)
             args.push("--continue");
         if (this.opts.debug === true) {
             args.push("--debug");
@@ -445,9 +445,27 @@ export class ClaudeCodeAgent extends BaseCliAgent {
             args.push("--verbose");
         if (this.extraArgs?.length)
             args.push(...this.extraArgs);
+        // Durability: inject a PostToolUse hook that calls back into smithers for a
+        // strict Tier 1 snapshot at each file-edit / Bash boundary. Only when the
+        // engine passes a socket path (durability enabled); additive --settings.
+        const durabilitySocket = typeof params.options?.durabilitySocket === "string"
+            ? params.options.durabilitySocket
+            : undefined;
+        if (durabilitySocket) {
+            args.push("--settings", JSON.stringify({
+                hooks: {
+                    PostToolUse: [{
+                        matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash",
+                        hooks: [{ type: "command", command: "smithers snapshot-hook" }],
+                    }],
+                },
+            }));
+        }
         if (params.prompt)
             args.push(params.prompt);
         const accountEnv = {};
+        if (durabilitySocket)
+            accountEnv.SMITHERS_SNAPSHOT_SOCK = durabilitySocket;
         if (this.opts.configDir)
             accountEnv.CLAUDE_CONFIG_DIR = this.opts.configDir;
         if (this.opts.apiKey)

package/src/CodexAgent.js

@@ -510,7 +510,7 @@ export class CodexAgent extends BaseCliAgent {
         const resumeSession = typeof params.options?.resumeSession === "string"
             ? params.options.resumeSession
             : undefined;
-        const args = resumeSession ? ["exec", "resume", resumeSession] : ["exec"];
+        const args = resumeSession ? ["exec", "resume"] : ["exec"];
         const yoloEnabled = this.opts.yolo ?? this.yolo;
         const configOverrides = normalizeCodexConfig(this.opts.config);
         for (const entry of configOverrides) {
@@ -520,21 +520,26 @@ export class CodexAgent extends BaseCliAgent {
         pushList(args, "--disable", this.opts.disable);
         pushList(args, "--image", this.opts.image);
         pushFlag(args, "--model", this.opts.model ?? this.model);
-        if (this.opts.oss)
+        if (!resumeSession && this.opts.oss)
             args.push("--oss");
-        pushFlag(args, "--local-provider", this.opts.localProvider);
-        pushFlag(args, "--sandbox", this.opts.sandbox);
-        pushFlag(args, "--profile", this.opts.profile);
-        if (this.opts.fullAuto) {
+        if (!resumeSession)
+            pushFlag(args, "--local-provider", this.opts.localProvider);
+        if (!resumeSession)
+            pushFlag(args, "--sandbox", this.opts.sandbox);
+        if (!resumeSession)
+            pushFlag(args, "--profile", this.opts.profile);
+        if (!resumeSession && this.opts.fullAuto) {
             args.push("--full-auto");
         }
         else if (yoloEnabled || this.opts.dangerouslyBypassApprovalsAndSandbox) {
             args.push("--dangerously-bypass-approvals-and-sandbox");
         }
-        pushFlag(args, "--cd", this.opts.cd);
+        if (!resumeSession)
+            pushFlag(args, "--cd", this.opts.cd);
         if (this.opts.skipGitRepoCheck)
             args.push("--skip-git-repo-check");
-        pushList(args, "--add-dir", this.opts.addDir);
+        if (!resumeSession)
+            pushList(args, "--add-dir", this.opts.addDir);
         if (!resumeSession) {
             pushFlag(args, "--output-schema", this.opts.outputSchema);
         }
@@ -562,6 +567,8 @@ export class CodexAgent extends BaseCliAgent {
         pushFlag(args, "--output-last-message", outputFile);
         if (this.extraArgs?.length)
             args.push(...this.extraArgs);
+        if (resumeSession)
+            args.push(resumeSession);
         const systemPrefix = params.systemPrompt
             ? `${params.systemPrompt}\n\n`
             : "";

package/src/ForgeAgent.js

@@ -5,6 +5,31 @@ import { randomUUID } from "node:crypto";
 /** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 /** @typedef {import("./ForgeAgentOptions.ts").ForgeAgentOptions} ForgeAgentOptions */
 
+/**
+ * @returns {AgentCapabilityRegistry}
+ */
+export function createForgeCapabilityRegistry() {
+    return {
+        version: 1,
+        engine: "forge",
+        runtimeTools: {},
+        mcp: {
+            bootstrap: "unsupported",
+            supportsProjectScope: false,
+            supportsUserScope: false,
+        },
+        skills: {
+            supportsSkills: false,
+            smithersSkillIds: [],
+        },
+        humanInteraction: {
+            supportsUiRequests: false,
+            methods: [],
+        },
+        builtIns: ["default"],
+    };
+}
+
 export class ForgeAgent extends BaseCliAgent {
     opts;
     /** @type {AgentCapabilityRegistry} */
@@ -17,25 +42,7 @@ export class ForgeAgent extends BaseCliAgent {
     constructor(opts = {}) {
         super(opts);
         this.opts = opts;
-        this.capabilities = {
-            version: 1,
-            engine: "forge",
-            runtimeTools: {},
-            mcp: {
-                bootstrap: "unsupported",
-                supportsProjectScope: false,
-                supportsUserScope: false,
-            },
-            skills: {
-                supportsSkills: false,
-                smithersSkillIds: [],
-            },
-            humanInteraction: {
-                supportsUiRequests: false,
-                methods: [],
-            },
-            builtIns: ["default"],
-        };
+        this.capabilities = createForgeCapabilityRegistry();
     }
     /**
    * @returns {CliOutputInterpreter}

package/src/HermesAgent.js

@@ -0,0 +1,41 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { OpenAIAgent } from "./OpenAIAgent.js";
+
+/**
+ * @template [CALL_OPTIONS=never], [TOOLS=import("ai").ToolSet]
+ * @typedef {import("./HermesAgentOptions.ts").HermesAgentOptions<CALL_OPTIONS, TOOLS>} HermesAgentOptions
+ */
+
+/**
+ * Hermes (Nous Research) agent, reached over its OpenAI-compatible HTTP API.
+ *
+ * A thin wrapper over {@link OpenAIAgent}: it points the OpenAI-compatible
+ * provider at the Hermes server (`baseURL` / `HERMES_BASE_URL`) and disables AI
+ * SDK native structured output by default, since a local Hermes server may not
+ * honor JSON-schema response formats. Everything else — tool loops, streaming,
+ * prompt-based structured output — comes from the shared OpenAI path.
+ *
+ * @template [CALL_OPTIONS=never], [TOOLS=import("ai").ToolSet]
+ */
+export class HermesAgent extends OpenAIAgent {
+  /**
+   * @param {HermesAgentOptions<CALL_OPTIONS, TOOLS>} [opts]
+   */
+  constructor(opts = {}) {
+    const {
+      model = "hermes",
+      baseURL = process.env.HERMES_BASE_URL,
+      apiKey = process.env.HERMES_API_KEY ?? "hermes",
+      nativeStructuredOutput = false,
+      ...rest
+    } = opts;
+    if (baseURL === undefined || baseURL.trim() === "") {
+      throw new SmithersError(
+        "AGENT_CONFIG_INVALID",
+        "HermesAgent requires a baseURL (or the HERMES_BASE_URL env var) pointing at the Hermes OpenAI-compatible API, e.g. http://127.0.0.1:5123/v1.",
+        {},
+      );
+    }
+    super({ ...rest, model, baseURL, apiKey, nativeStructuredOutput });
+  }
+}