@smithers-orchestrator/agents 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@smithers-orchestrator/agents",
+  "version": "0.16.0",
+  "description": "AI SDK and CLI agent adapters for Smithers",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./BaseCliAgent": {
+      "types": "./src/index.d.ts",
+      "import": "./src/BaseCliAgent/index.js",
+      "default": "./src/BaseCliAgent/index.js"
+    },
+    "./agent-contract": {
+      "types": "./src/index.d.ts",
+      "import": "./src/agent-contract/index.js",
+      "default": "./src/agent-contract/index.js"
+    },
+    "./diagnostics": {
+      "types": "./src/index.d.ts",
+      "import": "./src/diagnostics/index.js",
+      "default": "./src/diagnostics/index.js"
+    },
+    "./capability-registry": {
+      "types": "./src/index.d.ts",
+      "import": "./src/capability-registry/index.js",
+      "default": "./src/capability-registry/index.js"
+    },
+    "./cli-capabilities": {
+      "types": "./src/index.d.ts",
+      "import": "./src/cli-capabilities/index.js",
+      "default": "./src/cli-capabilities/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.36",
+    "@ai-sdk/openai": "^3.0.41",
+    "ai": "^6.0.69",
+    "zod": "^4.3.6",
+    "@smithers-orchestrator/driver": "0.16.0",
+    "@smithers-orchestrator/errors": "0.16.0",
+    "@smithers-orchestrator/observability": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "tsup --dts-only"
+  }
+}

package/src/AgentLike.ts

@@ -0,0 +1,28 @@
+import type { AgentCapabilityRegistry } from "./capability-registry";
+
+/**
+ * Represents an entity capable of generating responses or actions based on prompts.
+ * This is typically an AI agent interface.
+ */
+export type AgentLike = {
+  /** Optional unique identifier for the agent */
+  id?: string;
+  /** Available tools the agent can use */
+  tools?: Record<string, unknown>;
+  /** Optional structured capability registry for cache and diagnostics */
+  capabilities?: AgentCapabilityRegistry;
+  /**
+   * Generates a response or action based on the provided arguments.
+   *
+   * @param args - The arguments for generation
+   * @param args.options - Optional provider-specific configuration
+   * @param args.abortSignal - Signal to abort the generation request
+   * @param args.prompt - The input text prompt to generate from
+   * @param args.timeout - Optional timeout configuration in milliseconds
+   * @param args.onStdout - Callback for streaming standard output text
+   * @param args.onStderr - Callback for streaming standard error text
+   * @param args.outputSchema - Optional Zod schema defining the expected structured output format
+   * @returns A promise resolving to the generated output
+   */
+  generate: (args: unknown) => Promise<unknown>;
+};

package/src/AmpAgent.js

@@ -0,0 +1,232 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./AmpAgentOptions.ts").AmpAgentOptions} AmpAgentOptions */
+// @smithers-type-exports-end
+
+import { BaseCliAgent, pushFlag, isRecord, asString, toolKindFromName, createSyntheticIdGenerator, } from "./BaseCliAgent/index.js";
+/** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
+
+/**
+ * Agent implementation that wraps the 'amp' CLI executable.
+ * It translates generation requests into CLI arguments and executes the process.
+ */
+export class AmpAgent extends BaseCliAgent {
+    opts;
+    capabilities;
+    cliEngine = "amp";
+    /**
+     * Initializes a new AmpAgent with the given options.
+     *
+     * @param {AmpAgentOptions} [opts] - Configuration options for the agent
+     */
+    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"],
+        };
+    }
+    /**
+   * @returns {CliOutputInterpreter}
+   */
+    createOutputInterpreter() {
+        let sessionId;
+        let finalAnswer = "";
+        let didEmitCompleted = false;
+        const nextSyntheticId = createSyntheticIdGenerator();
+        /**
+     * @param {string} line
+     * @returns {AgentCliEvent[]}
+     */
+        const parseLine = (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return [];
+            let payload;
+            try {
+                payload = JSON.parse(trimmed);
+            }
+            catch {
+                return [];
+            }
+            if (!isRecord(payload))
+                return [];
+            const type = asString(payload.type);
+            if (!type)
+                return [];
+            if (type === "system" && asString(payload.subtype) === "init") {
+                sessionId = asString(payload.session_id);
+                return [{
+                        type: "started",
+                        engine: this.cliEngine,
+                        title: "Amp",
+                        resume: sessionId,
+                        detail: {
+                            cwd: asString(payload.cwd),
+                            tools: payload.tools,
+                        },
+                    }];
+            }
+            if (type === "assistant") {
+                const message = isRecord(payload.message) ? payload.message : undefined;
+                const content = Array.isArray(message?.content) ? message.content : [];
+                const events = [];
+                for (const block of content) {
+                    if (!isRecord(block))
+                        continue;
+                    if (block.type === "text" && typeof block.text === "string") {
+                        finalAnswer += block.text;
+                        continue;
+                    }
+                    if (block.type === "tool_use") {
+                        const name = asString(block.name) ?? "tool";
+                        const id = asString(block.id) ?? nextSyntheticId("amp-tool");
+                        events.push({
+                            type: "action",
+                            engine: this.cliEngine,
+                            phase: "started",
+                            entryType: "thought",
+                            action: {
+                                id,
+                                kind: toolKindFromName(name),
+                                title: name,
+                                detail: {
+                                    input: block.input,
+                                    parentToolUseId: payload.parent_tool_use_id,
+                                },
+                            },
+                            message: `Running ${name}`,
+                            level: "info",
+                        });
+                    }
+                }
+                return events;
+            }
+            if (type === "user") {
+                const message = isRecord(payload.message) ? payload.message : undefined;
+                const content = Array.isArray(message?.content) ? message.content : [];
+                const events = [];
+                for (const block of content) {
+                    if (!isRecord(block) || block.type !== "tool_result")
+                        continue;
+                    const id = asString(block.tool_use_id) ?? nextSyntheticId("amp-tool");
+                    events.push({
+                        type: "action",
+                        engine: this.cliEngine,
+                        phase: "completed",
+                        entryType: "thought",
+                        action: {
+                            id,
+                            kind: "tool",
+                            title: "tool result",
+                            detail: {
+                                parentToolUseId: payload.parent_tool_use_id,
+                            },
+                        },
+                        message: asString(block.content),
+                        ok: block.is_error !== true,
+                        level: block.is_error === true ? "warning" : "info",
+                    });
+                }
+                return events;
+            }
+            if (type === "result") {
+                if (didEmitCompleted)
+                    return [];
+                didEmitCompleted = true;
+                const ok = payload.is_error !== true;
+                return [{
+                        type: "completed",
+                        engine: this.cliEngine,
+                        ok,
+                        answer: finalAnswer || asString(payload.result),
+                        error: ok ? undefined : asString(payload.error),
+                        resume: asString(payload.session_id) ?? sessionId,
+                        usage: isRecord(payload.usage) ? payload.usage : undefined,
+                    }];
+            }
+            return [];
+        };
+        return {
+            onStdoutLine: parseLine,
+            onExit: (result) => {
+                if (didEmitCompleted)
+                    return [];
+                if (result.exitCode === 0)
+                    return [];
+                didEmitCompleted = true;
+                return [{
+                        type: "completed",
+                        engine: this.cliEngine,
+                        ok: false,
+                        answer: finalAnswer || undefined,
+                        error: result.stderr.trim() || `Amp exited with code ${result.exitCode}`,
+                        resume: sessionId,
+                    }];
+            },
+        };
+    }
+    /**
+   * @param {{ prompt: string; systemPrompt?: string; cwd: string; options: any; }} params
+   */
+    async buildCommand(params) {
+        const args = [];
+        const yoloEnabled = this.opts.yolo ?? this.yolo;
+        // Dangerous allow all (yolo mode) — must come before --execute
+        if (this.opts.dangerouslyAllowAll || yoloEnabled) {
+            args.push("--dangerously-allow-all");
+        }
+        // Model / mode
+        pushFlag(args, "--model", this.opts.model ?? this.model);
+        // Visibility for new threads
+        pushFlag(args, "--visibility", this.opts.visibility);
+        // MCP config
+        pushFlag(args, "--mcp-config", this.opts.mcpConfig);
+        // Settings file
+        pushFlag(args, "--settings-file", this.opts.settingsFile);
+        // Log level
+        pushFlag(args, "--log-level", this.opts.logLevel);
+        // Log file
+        pushFlag(args, "--log-file", this.opts.logFile);
+        // IDE integration — disable by default for headless execution
+        args.push("--no-ide");
+        args.push("--no-jetbrains");
+        // Color handling
+        args.push("--no-color");
+        // Archive thread after execution to keep things clean
+        args.push("--archive");
+        if (this.extraArgs?.length)
+            args.push(...this.extraArgs);
+        // Build prompt with system prompt prepended
+        const systemPrefix = params.systemPrompt
+            ? `${params.systemPrompt}\n\n`
+            : "";
+        const fullPrompt = `${systemPrefix}${params.prompt ?? ""}`;
+        // Execute mode with prompt as argument
+        args.push("--execute", fullPrompt);
+        const useStreamJson = Boolean(params.options?.onEvent);
+        if (useStreamJson) {
+            args.push("--stream-json");
+        }
+        return {
+            command: "amp",
+            args,
+            outputFormat: useStreamJson ? "stream-json" : "text",
+        };
+    }
+}

package/src/AmpAgentOptions.ts

@@ -0,0 +1,26 @@
+import type { BaseCliAgentOptions } from "./BaseCliAgent/BaseCliAgentOptions";
+
+/**
+ * Configuration options for the AmpAgent.
+ */
+export type AmpAgentOptions = BaseCliAgentOptions & {
+  /** Visibility setting for the new thread (e.g., private, public) */
+  visibility?: "private" | "public" | "workspace" | "group";
+  /** Path to a specific MCP configuration file */
+  mcpConfig?: string;
+  /** Path to a specific settings file */
+  settingsFile?: string;
+  /** Logging severity level */
+  logLevel?: "error" | "warn" | "info" | "debug" | "audit";
+  /** File path to write logs to */
+  logFile?: string;
+  /**
+   * If true, dangerously allows all commands without asking for permission.
+   * Equivalent to yolo mode but explicit.
+   */
+  dangerouslyAllowAll?: boolean;
+  /** Whether to enable IDE integrations (disabled by default in AmpAgent) */
+  ide?: boolean;
+  /** Whether to enable JetBrains IDE integration */
+  jetbrains?: boolean;
+};

package/src/AnthropicAgent.js

@@ -0,0 +1,54 @@
+import { anthropic } from "@ai-sdk/anthropic";
+import { ToolLoopAgent, } from "ai";
+import { resolveSdkModel } from "./resolveSdkModel.js";
+import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js";
+/** @typedef {import("ai").AgentCallParameters} AgentCallParameters */
+
+/**
+ * @template [CALL_OPTIONS=never], [TOOLS=import("ai").ToolSet]
+ * @typedef {import("./AnthropicAgentOptions.ts").AnthropicAgentOptions<CALL_OPTIONS, TOOLS>} AnthropicAgentOptions
+ */
+/**
+ * @template CALL_OPTIONS, TOOLS
+ * @typedef {AgentCallParameters<CALL_OPTIONS, TOOLS> & { onStdout?: (text: string) => void; onStderr?: (text: string) => void; onEvent?: (event: unknown) => Promise<void> | void; outputSchema?: import("zod").ZodTypeAny; resumeSession?: string; }} ExtendedGenerateArgs
+ */
+/** @typedef {import("ai").GenerateTextResult} GenerateTextResult */
+
+export class AnthropicAgent extends ToolLoopAgent {
+    hijackEngine = "anthropic-sdk";
+    /**
+   * @param {AnthropicAgentOptions<CALL_OPTIONS, TOOLS>} opts
+   */
+    constructor(opts) {
+        const { model, ...rest } = opts;
+        super({
+            ...rest,
+            model: resolveSdkModel(model, anthropic),
+        });
+    }
+    /**
+   * @param {ExtendedGenerateArgs<CALL_OPTIONS, TOOLS>} args
+   * @returns {Promise<GenerateTextResult<TOOLS, never>>}
+   */
+    generate(args) {
+        const promptArgs = "messages" in args
+            ? { messages: args.messages }
+            : { prompt: args.prompt };
+        if (!args.onStdout) {
+            return super.generate({
+                options: args.options,
+                abortSignal: args.abortSignal,
+                ...promptArgs,
+                timeout: args.timeout,
+                onStepFinish: args.onStepFinish,
+            });
+        }
+        return super.stream({
+            options: args.options,
+            abortSignal: args.abortSignal,
+            ...promptArgs,
+            timeout: args.timeout,
+            onStepFinish: args.onStepFinish,
+        }).then((stream) => streamResultToGenerateResult(stream, args.onStdout));
+    }
+}

package/src/AnthropicAgentOptions.ts

@@ -0,0 +1,8 @@
+import type { anthropic } from "@ai-sdk/anthropic";
+import type { ToolSet } from "ai";
+import type { SdkAgentOptions } from "./SdkAgentOptions";
+
+export type AnthropicAgentOptions<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+> = SdkAgentOptions<CALL_OPTIONS, TOOLS, ReturnType<typeof anthropic>>;

package/src/BaseCliAgent/AgentCliActionKind.ts

@@ -0,0 +1,10 @@
+export type AgentCliActionKind =
+  | "turn"
+  | "command"
+  | "tool"
+  | "file_change"
+  | "web_search"
+  | "todo_list"
+  | "reasoning"
+  | "warning"
+  | "note";

package/src/BaseCliAgent/AgentCliEvent.ts

@@ -0,0 +1,44 @@
+import type { AgentCliActionKind } from "./AgentCliActionKind";
+
+export type AgentCliActionPhase = "started" | "updated" | "completed";
+
+export type AgentCliEventLevel = "debug" | "info" | "warning" | "error";
+
+export type AgentCliStartedEvent = {
+  type: "started";
+  engine: string;
+  title: string;
+  resume?: string;
+  detail?: Record<string, unknown>;
+};
+
+export type AgentCliActionEvent = {
+  type: "action";
+  engine: string;
+  phase: AgentCliActionPhase;
+  entryType?: "thought" | "message";
+  action: {
+    id: string;
+    kind: AgentCliActionKind;
+    title: string;
+    detail?: Record<string, unknown>;
+  };
+  message?: string;
+  ok?: boolean;
+  level?: AgentCliEventLevel;
+};
+
+export type AgentCliCompletedEvent = {
+  type: "completed";
+  engine: string;
+  ok: boolean;
+  answer?: string;
+  error?: string;
+  resume?: string;
+  usage?: Record<string, unknown>;
+};
+
+export type AgentCliEvent =
+  | AgentCliStartedEvent
+  | AgentCliActionEvent
+  | AgentCliCompletedEvent;