@smithers-orchestrator/agents 0.21.0 → 0.23.0

package/src/HermesAgentOptions.ts

@@ -0,0 +1,41 @@
+import type { openai } from "@ai-sdk/openai";
+import type { ToolSet } from "ai";
+import type { SdkAgentOptions } from "./SdkAgentOptions";
+
+/**
+ * Options for {@link HermesAgent}.
+ *
+ * Hermes (Nous Research) exposes an OpenAI-compatible HTTP API
+ * (`/v1/chat/completions`), so a Hermes agent is reached the same way as any
+ * OpenAI-compatible endpoint: point `baseURL` at the Hermes server. These mirror
+ * the string-model form of `OpenAIAgentOptions`.
+ */
+export type HermesAgentOptions<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+> = Omit<
+  SdkAgentOptions<CALL_OPTIONS, TOOLS, ReturnType<typeof openai>>,
+  "model"
+> & {
+  /**
+   * Model name exposed by your Hermes server. Defaults to `"hermes"`; override
+   * with whatever model id the server advertises.
+   */
+  model?: string;
+  /**
+   * Base URL of the Hermes OpenAI-compatible API, e.g. `http://127.0.0.1:5123/v1`.
+   * Falls back to the `HERMES_BASE_URL` environment variable.
+   */
+  baseURL?: string;
+  /**
+   * API key sent to the Hermes server. Falls back to `HERMES_API_KEY`, then
+   * `"hermes"` (local servers commonly ignore the value).
+   */
+  apiKey?: string;
+  /**
+   * Enable AI SDK native structured output. Off by default because a local
+   * Hermes server may not honor JSON-schema response formats — leaving it off
+   * makes Smithers fall back to prompt-based JSON extraction.
+   */
+  nativeStructuredOutput?: boolean;
+};

package/src/VibeAgent.js

@@ -0,0 +1,214 @@
+import {
+  BaseCliAgent,
+  pushFlag,
+  isRecord,
+  asString,
+  createSyntheticIdGenerator,
+} from "./BaseCliAgent/index.js";
+
+/** @typedef {import("./BaseCliAgent/index.ts").BaseCliAgentOptions} BaseCliAgentOptions */
+/** @typedef {import("./capability-registry/index.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
+/** @typedef {import("./BaseCliAgent/index.ts").CliOutputInterpreter} CliOutputInterpreter */
+
+/**
+ * @param {VibeAgentOptions} [opts]
+ * @returns {AgentCapabilityRegistry}
+ */
+export function createVibeCapabilityRegistry(opts = {}) {
+  return {
+    version: 1,
+    engine: "vibe",
+    runtimeTools: {},
+    mcp: {
+      bootstrap: "project-config",
+      supportsProjectScope: true,
+      supportsUserScope: true,
+    },
+    skills: {
+      supportsSkills: true,
+      installMode: "plugin",
+      smithersSkillIds: [],
+    },
+    humanInteraction: {
+      supportsUiRequests: false,
+      methods: [],
+    },
+    builtIns: ["default"],
+  };
+}
+
+/**
+ * @typedef {BaseCliAgentOptions & {
+ *   agent?: string;
+ *   maxTurns?: number;
+ *   maxPrice?: number;
+ *   maxTokens?: number;
+ *   enabledTools?: string[];
+ *   sessionId?: string;
+ *   continueSession?: boolean;
+ * }} VibeAgentOptions
+ */
+
+export class VibeAgent extends BaseCliAgent {
+  /** @type {VibeAgentOptions} */
+  opts;
+  /** @type {AgentCapabilityRegistry} */
+  capabilities;
+  /** @type {"vibe"} */
+  cliEngine = "vibe";
+  /** @type {string | undefined} */
+  issuedSessionId;
+
+  /**
+   * @param {VibeAgentOptions} [opts]
+   */
+  constructor(opts = {}) {
+    super({ ...opts, yolo: opts.yolo ?? false });
+    this.opts = opts;
+    this.capabilities = createVibeCapabilityRegistry(opts);
+  }
+
+  /**
+   * @returns {CliOutputInterpreter}
+   */
+  createOutputInterpreter() {
+    let finalAnswer = "";
+    let didEmitStarted = false;
+    let didEmitCompleted = false;
+    const nextSyntheticId = createSyntheticIdGenerator();
+
+    /**
+     * @param {string} line
+     * @returns {import("./BaseCliAgent/index.ts").AgentCliEvent[]}
+     */
+    const parseLine = (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return [];
+
+      /** @type {Record<string, unknown>} */
+      let payload;
+      try {
+        payload = JSON.parse(trimmed);
+      } catch {
+        return [];
+      }
+
+      if (!isRecord(payload)) return [];
+      const role = asString(payload.role);
+      const content = asString(payload.content);
+      if (role !== "assistant" || !content) return [];
+
+      const events = [];
+
+      if (!didEmitStarted) {
+        didEmitStarted = true;
+        events.push({
+          type: "started",
+          engine: this.cliEngine,
+          title: "Vibe",
+          resume: this.issuedSessionId,
+        });
+      }
+
+      const id = nextSyntheticId("vibe-message");
+      finalAnswer += content;
+
+      events.push({
+        type: "action",
+        engine: this.cliEngine,
+        phase: "updated",
+        entryType: "message",
+        action: { id, kind: "turn", title: "assistant" },
+        message: content,
+      });
+
+      return events;
+    };
+
+    return {
+      onStdoutLine: parseLine,
+
+      onExit: (result) => {
+        if (didEmitCompleted) return [];
+        didEmitCompleted = true;
+
+        const ok = (result.exitCode ?? 0) === 0;
+
+        const events = [];
+        if (!didEmitStarted) {
+          events.push({
+            type: "started",
+            engine: this.cliEngine,
+            title: "Vibe",
+            resume: this.issuedSessionId,
+          });
+        }
+
+        events.push({
+          type: "completed",
+          engine: this.cliEngine,
+          ok,
+          answer: ok ? finalAnswer || undefined : undefined,
+          error: ok
+            ? undefined
+            : result.stderr?.trim() ||
+              `vibe exited with code ${result.exitCode ?? -1}`,
+          resume: this.issuedSessionId,
+        });
+
+        return events;
+      },
+    };
+  }
+
+  /**
+   * @param {{ prompt: string; systemPrompt?: string; cwd: string; options: any }} params
+   */
+  async buildCommand(params) {
+    const args = [];
+
+    const resumeSession = typeof params.options?.resumeSession === "string"
+      ? params.options.resumeSession
+      : undefined;
+    const effectiveSession = resumeSession ?? this.opts.sessionId;
+    this.issuedSessionId = effectiveSession;
+    if (this.opts.continueSession && !effectiveSession) {
+      args.push("-c");
+    }
+    pushFlag(args, "--resume", effectiveSession);
+
+    pushFlag(args, "--agent", this.opts.agent);
+    if (this.opts.maxTurns !== undefined) {
+      args.push("--max-turns", String(this.opts.maxTurns));
+    }
+    if (this.opts.maxPrice !== undefined) {
+      args.push("--max-price", String(this.opts.maxPrice));
+    }
+    if (this.opts.maxTokens !== undefined) {
+      args.push("--max-tokens", String(this.opts.maxTokens));
+    }
+    if (this.opts.enabledTools?.length) {
+      for (const tool of this.opts.enabledTools) {
+        args.push("--enabled-tools", tool);
+      }
+    }
+
+    args.push("--trust");
+    args.push("--output", "streaming");
+    pushFlag(args, "--workdir", params.cwd);
+
+    if (this.extraArgs?.length) args.push(...this.extraArgs);
+
+    const systemPrefix = params.systemPrompt
+      ? `${params.systemPrompt}\n\n`
+      : "";
+    const fullPrompt = `${systemPrefix}${params.prompt ?? ""}`;
+    pushFlag(args, "--prompt", fullPrompt);
+
+    return {
+      command: "vibe",
+      args,
+      outputFormat: "stream-json",
+    };
+  }
+}

package/src/VibeAgentOptions.ts

@@ -0,0 +1,11 @@
+import type { BaseCliAgentOptions } from "./BaseCliAgent/BaseCliAgentOptions";
+
+export type VibeAgentOptions = BaseCliAgentOptions & {
+  agent?: string;
+  maxTurns?: number;
+  maxPrice?: number;
+  maxTokens?: number;
+  enabledTools?: string[];
+  sessionId?: string;
+  continueSession?: boolean;
+};

package/src/agent-contract/createSmithersAgentContract.js

@@ -30,6 +30,7 @@ const WORKFLOW_TOOL_NAMES = new Set([
 ]);
 const APPROVAL_TOOL_NAMES = new Set([
     "approve",
+    "ask_human",
     "deny",
     "list_pending_approvals",
     "resolve_approval",

package/src/agent-contract/renderSmithersAgentPromptGuidance.js

@@ -77,5 +77,9 @@ export function renderSmithersAgentPromptGuidance(contract, options = {}) {
     if (destructiveTools.length > 0) {
         lines.push(`Potentially destructive tools: ${joinToolNames(destructiveTools, prefix)}. Confirm intent before using them unless the user already asked for that action.`);
     }
+    const askHumanTool = contract.tools.find((tool) => tool.name === "ask_human");
+    if (askHumanTool) {
+        lines.push(`When you are blocked, uncertain, missing information, or about to take an irreversible or destructive action, you MUST call ${displayToolName(askHumanTool, prefix)} (or run \`smithers ask-human "<question>"\`) to ask a human and wait for the decision. Never guess or proceed on an assumption — if the request comes back blocked (cancelled/expired), stop and do not proceed.`);
+    }
     return lines.join("\n");
 }

package/src/capability-registry/AgentCapabilityRegistry.ts

@@ -2,7 +2,7 @@ import type { AgentToolDescriptor } from "./AgentToolDescriptor";
 
 export type AgentCapabilityRegistry = {
   version: 1;
-  engine: "claude-code" | "codex" | "antigravity" | "gemini" | "kimi" | "pi" | "amp" | "forge" | "opencode";
+  engine: "claude-code" | "codex" | "antigravity" | "gemini" | "kimi" | "pi" | "amp" | "forge" | "opencode" | "vibe";
   runtimeTools: Record<string, AgentToolDescriptor>;
   mcp: {
     bootstrap: "inline-config" | "project-config" | "allow-list" | "unsupported";

package/src/cli-capabilities/CliAgentCapabilityAdapterId.ts

@@ -1,8 +1,11 @@
 export type CliAgentCapabilityAdapterId =
   | "claude"
+  | "amp"
   | "antigravity"
   | "codex"
+  | "forge"
   | "gemini"
   | "kimi"
   | "opencode"
-  | "pi";
+  | "pi"
+  | "vibe";

package/src/cli-capabilities/CliAgentCapabilityReportEntry.ts

@@ -1,4 +1,5 @@
 import type { AgentCapabilityRegistry } from "../capability-registry";
+import type { CliAgentSurfaceManifestEntry } from "../cli-surface/CliAgentSurfaceTypes";
 import type { CliAgentCapabilityAdapterId } from "./CliAgentCapabilityAdapterId";
 
 export type CliAgentCapabilityReportEntry = {
@@ -6,4 +7,5 @@ export type CliAgentCapabilityReportEntry = {
   binary: string;
   fingerprint: string;
   capabilities: AgentCapabilityRegistry;
+  surface: CliAgentSurfaceManifestEntry;
 };

package/src/cli-capabilities/getCliAgentCapabilityDoctorReport.js

@@ -1,5 +1,8 @@
 import { getCliAgentCapabilityReport } from "./getCliAgentCapabilityReport.js";
 /** @typedef {import("./CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityDoctorReport} CliAgentCapabilityDoctorReport */
+/** @typedef {import("./CliAgentCapabilityDoctorReport.ts").CliAgentCapabilityIssue} CliAgentCapabilityIssue */
+/** @typedef {import("./CliAgentCapabilityReportEntry.ts").CliAgentCapabilityReportEntry} CliAgentCapabilityReportEntry */
+/** @typedef {import("../capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
 
 /**
  * @param {AgentCapabilityRegistry} registry
@@ -71,12 +74,56 @@ function diagnoseCapabilityRegistry(registry) {
     }
     return issues;
 }
+
+/**
+ * @param {CliAgentCapabilityReportEntry} entry
+ * @returns {CliAgentCapabilityIssue[]}
+ */
+function diagnoseSurfaceContract(entry) {
+    const issues = [];
+    const emitted = new Set(entry.surface.emittedFlags);
+    for (const unsupported of entry.surface.unsupportedFlags) {
+        if (emitted.has(unsupported.flag)) {
+            issues.push({
+                code: "unsupported-flag-emitted",
+                message: `${entry.id} emits ${unsupported.flag}, but the surface manifest marks it unsupported.${unsupported.replacement ? ` Replacement: ${unsupported.replacement}.` : ""}`,
+                severity: "error",
+            });
+        }
+    }
+    if (entry.surface.binary !== entry.binary) {
+        issues.push({
+            code: "surface-binary-mismatch",
+            message: `${entry.id} capability binary is ${entry.binary}, but the surface manifest says ${entry.surface.binary}.`,
+            severity: "error",
+        });
+    }
+    if (entry.surface.docsUrls.length === 0) {
+        issues.push({
+            code: "missing-surface-docs",
+            message: `${entry.id} has no source URL recorded for its CLI surface.`,
+            severity: "warning",
+        });
+    }
+    if (entry.surface.resume.kind !== "none" && entry.surface.resume.emitted.length === 0) {
+        issues.push({
+            code: "missing-resume-emission",
+            message: `${entry.id} declares ${entry.surface.resume.kind} resume support but no emitted resume tokens.`,
+            severity: "warning",
+        });
+    }
+    return issues;
+}
+
 /**
  * @returns {CliAgentCapabilityDoctorReport}
  */
 export function getCliAgentCapabilityDoctorReport() {
     const agents = getCliAgentCapabilityReport().map((entry) => {
-        const issues = diagnoseCapabilityRegistry(entry.capabilities);
+        const issues = [
+            ...diagnoseCapabilityRegistry(entry.capabilities),
+            ...diagnoseSurfaceContract(entry),
+        ];
         return {
             ...entry,
             ok: issues.length === 0,

package/src/cli-capabilities/getCliAgentCapabilityReport.js

@@ -1,14 +1,23 @@
 import { hashCapabilityRegistry, normalizeCapabilityRegistry, } from "../capability-registry/index.js";
+import { createAmpCapabilityRegistry } from "../AmpAgent.js";
 import { createAntigravityCapabilityRegistry } from "../AntigravityAgent.js";
 import { createClaudeCodeCapabilityRegistry } from "../ClaudeCodeAgent.js";
 import { createCodexCapabilityRegistry } from "../CodexAgent.js";
+import { createForgeCapabilityRegistry } from "../ForgeAgent.js";
 import { createGeminiCapabilityRegistry } from "../GeminiAgent.js";
 import { createKimiCapabilityRegistry } from "../KimiAgent.js";
 import { createOpenCodeCapabilityRegistry } from "../OpenCodeAgent.js";
 import { createPiCapabilityRegistry } from "../PiAgent.js";
+import { createVibeCapabilityRegistry } from "../VibeAgent.js";
+import { getCliAgentSurfaceManifestEntry } from "../cli-surface/index.js";
 /** @typedef {import("./CliAgentCapabilityReportEntry.ts").CliAgentCapabilityReportEntry} CliAgentCapabilityReportEntry */
 
 const CLI_AGENT_CAPABILITY_ADAPTERS = [
+    {
+        id: "amp",
+        binary: "amp",
+        buildRegistry: () => createAmpCapabilityRegistry(),
+    },
     {
         id: "claude",
         binary: "claude",
@@ -29,6 +38,11 @@ const CLI_AGENT_CAPABILITY_ADAPTERS = [
         binary: "gemini",
         buildRegistry: () => createGeminiCapabilityRegistry(),
     },
+    {
+        id: "forge",
+        binary: "forge",
+        buildRegistry: () => createForgeCapabilityRegistry(),
+    },
     {
         id: "kimi",
         binary: "kimi",
@@ -44,6 +58,11 @@ const CLI_AGENT_CAPABILITY_ADAPTERS = [
         binary: "pi",
         buildRegistry: () => createPiCapabilityRegistry(),
     },
+    {
+        id: "vibe",
+        binary: "vibe",
+        buildRegistry: () => createVibeCapabilityRegistry(),
+    },
 ];
 /**
  * @returns {CliAgentCapabilityReportEntry[]}
@@ -54,11 +73,16 @@ export function getCliAgentCapabilityReport() {
         if (!capabilities) {
             throw new Error(`Capability registry missing for adapter ${adapter.id}`);
         }
+        const surface = getCliAgentSurfaceManifestEntry(adapter.id);
+        if (!surface) {
+            throw new Error(`CLI surface manifest missing for adapter ${adapter.id}`);
+        }
         return {
             id: adapter.id,
             binary: adapter.binary,
             fingerprint: hashCapabilityRegistry(capabilities),
             capabilities,
+            surface,
         };
     });
 }

package/src/cli-capabilities/index.js

@@ -9,3 +9,8 @@
 export { getCliAgentCapabilityReport } from "./getCliAgentCapabilityReport.js";
 export { getCliAgentCapabilityDoctorReport } from "./getCliAgentCapabilityDoctorReport.js";
 export { formatCliAgentCapabilityDoctorReport } from "./formatCliAgentCapabilityDoctorReport.js";
+export {
+  CLI_AGENT_SURFACE_MANIFEST,
+  getCliAgentSurfaceManifestEntry,
+  listCliAgentSurfaceManifests,
+} from "../cli-surface/index.js";

package/src/cli-surface/CliAgentSurfaceTypes.ts

@@ -0,0 +1,34 @@
+import type { CliAgentCapabilityAdapterId } from "../cli-capabilities/CliAgentCapabilityAdapterId";
+
+export type CliAgentSurfaceOptionMapping = {
+  option: string;
+  flag?: string;
+  env?: string;
+  notes?: string;
+};
+
+export type CliAgentUnsupportedFlag = {
+  flag: string;
+  replacement?: string;
+  reason: string;
+};
+
+export type CliAgentSurfaceResumeContract = {
+  kind: "flag" | "subcommand" | "env" | "none";
+  emitted: string[];
+  notes: string;
+};
+
+export type CliAgentSurfaceManifestEntry = {
+  id: CliAgentCapabilityAdapterId;
+  displayName: string;
+  binary: string;
+  packageExport: string;
+  defaultOutputFormat: "text" | "json" | "stream-json" | "rpc";
+  docsUrls: string[];
+  emittedFlags: string[];
+  supportedFlags: string[];
+  unsupportedFlags: CliAgentUnsupportedFlag[];
+  optionMappings: CliAgentSurfaceOptionMapping[];
+  resume: CliAgentSurfaceResumeContract;
+};