@smithers-orchestrator/agents 0.16.0

package/src/PiAgent.js

@@ -0,0 +1,468 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./BaseCliAgent/PiExtensionUiRequest.ts").PiExtensionUiRequest} PiExtensionUiRequest */
+/** @typedef {import("./BaseCliAgent/PiExtensionUiResponse.ts").PiExtensionUiResponse} PiExtensionUiResponse */
+// @smithers-type-exports-end
+
+import { Effect } from "effect";
+import { BaseCliAgent, buildGenerateResult, combineNonEmpty, extractPrompt, extractTextFromJsonValue, pushFlag, resolveTimeouts, runAgentPromise, runRpcCommandEffect, tryParseJson, asString, truncate, toolKindFromName, } from "./BaseCliAgent/index.js";
+import { normalizeCapabilityStringList, } from "./capability-registry/index.js";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { enrichReportWithErrorAnalysis, launchDiagnostics } from "./diagnostics/index.js";
+/** @typedef {import("./capability-registry/AgentCapabilityRegistry.ts").AgentCapabilityRegistry} AgentCapabilityRegistry */
+/** @typedef {import("./BaseCliAgent/CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
+/** @typedef {import("./BaseCliAgent/AgentCliEvent.ts").AgentCliEvent} AgentCliEvent */
+/** @typedef {import("ai").GenerateTextResult<Record<string, never>, unknown>} GenerateTextResult */
+/** @typedef {import("./PiAgentOptions.ts").PiAgentOptions} PiAgentOptions */
+/** @typedef {"text" | "json" | "stream-json" | "rpc"} PiMode */
+/**
+ * @typedef {{
+ *   prompt?: unknown;
+ *   messages?: unknown;
+ *   onEvent?: (event: AgentCliEvent) => unknown;
+ *   resumeSession?: unknown;
+ *   rootDir?: string;
+ *   timeout?: unknown;
+ *   abortSignal?: AbortSignal;
+ *   maxOutputBytes?: number;
+ *   onStdout?: (text: string) => void;
+ *   onStderr?: (text: string) => void;
+ *   [key: string]: unknown;
+ * }} PiGenerateOptions
+ */
+
+/**
+ * @param {PiAgentOptions} opts
+ */
+function resolvePiBuiltIns(opts) {
+    if (opts.noTools) {
+        return [];
+    }
+    return opts.tools?.length
+        ? normalizeCapabilityStringList(opts.tools)
+        : ["default"];
+}
+/**
+ * @param {PiAgentOptions} [opts]
+ * @returns {AgentCapabilityRegistry}
+ */
+export function createPiCapabilityRegistry(opts = {}) {
+    return {
+        version: 1,
+        engine: "pi",
+        runtimeTools: {},
+        mcp: {
+            bootstrap: "unsupported",
+            supportsProjectScope: false,
+            supportsUserScope: false,
+        },
+        skills: {
+            supportsSkills: true,
+            installMode: "files",
+            smithersSkillIds: normalizeCapabilityStringList(opts.skill),
+        },
+        humanInteraction: {
+            supportsUiRequests: true,
+            methods: ["extension_ui_request"],
+        },
+        builtIns: resolvePiBuiltIns(opts),
+    };
+}
+export class PiAgent extends BaseCliAgent {
+    opts;
+    capabilities;
+    cliEngine = "pi";
+    issuedSessionRef;
+    /**
+   * @param {PiAgentOptions} [opts]
+   */
+    constructor(opts = {}) {
+        super(opts);
+        this.opts = opts;
+        this.capabilities = createPiCapabilityRegistry(opts);
+    }
+    /**
+   * @param {PiGenerateOptions} [options]
+   * @returns {PiMode}
+   */
+    resolveMode(options) {
+        if (this.opts.mode === "rpc")
+            return "rpc";
+        if (options?.onEvent)
+            return "json";
+        return this.opts.mode ?? "text";
+    }
+    /**
+   * @param {{ prompt: string; cwd: string; options?: PiGenerateOptions; mode: PiMode; }} params
+   * @returns {string[]}
+   */
+    buildArgs(params) {
+        const args = [];
+        const { systemFromMessages } = extractPrompt(params.options);
+        const resumeSession = typeof params.options?.resumeSession === "string"
+            ? params.options.resumeSession
+            : undefined;
+        const effectiveSession = resumeSession ?? this.opts.session;
+        this.issuedSessionRef = effectiveSession;
+        if (params.mode === "text") {
+            if (this.opts.print !== false)
+                args.push("--print");
+        }
+        else {
+            args.push("--mode", params.mode);
+        }
+        pushFlag(args, "--provider", this.opts.provider);
+        pushFlag(args, "--model", this.opts.model ?? this.model);
+        pushFlag(args, "--api-key", this.opts.apiKey);
+        pushFlag(args, "--system-prompt", this.systemPrompt);
+        pushFlag(args, "--append-system-prompt", combineNonEmpty([this.opts.appendSystemPrompt, systemFromMessages]));
+        if (this.opts.continue)
+            args.push("--continue");
+        if (this.opts.resume)
+            args.push("--resume");
+        pushFlag(args, "--session", effectiveSession);
+        pushFlag(args, "--session-dir", this.opts.sessionDir);
+        const needsDurableSession = Boolean(params.options?.onEvent || effectiveSession);
+        const hasSessionFlags = needsDurableSession ||
+            Boolean(this.opts.sessionDir || this.opts.continue || this.opts.resume);
+        if (!needsDurableSession && (this.opts.noSession ?? (!hasSessionFlags))) {
+            args.push("--no-session");
+        }
+        if (this.opts.models) {
+            const models = Array.isArray(this.opts.models)
+                ? this.opts.models.join(",")
+                : this.opts.models;
+            args.push("--models", models);
+        }
+        if (this.opts.listModels !== undefined && this.opts.listModels !== false) {
+            if (typeof this.opts.listModels === "string") {
+                args.push("--list-models", this.opts.listModels);
+            }
+            else {
+                args.push("--list-models");
+            }
+        }
+        pushFlag(args, "--export", this.opts.export);
+        if (this.opts.tools?.length) {
+            args.push("--tools", this.opts.tools.join(","));
+        }
+        if (this.opts.noTools)
+            args.push("--no-tools");
+        if (this.opts.extension) {
+            for (const value of this.opts.extension) {
+                args.push("--extension", value);
+            }
+        }
+        if (this.opts.noExtensions)
+            args.push("--no-extensions");
+        if (this.opts.skill) {
+            for (const value of this.opts.skill) {
+                args.push("--skill", value);
+            }
+        }
+        if (this.opts.noSkills)
+            args.push("--no-skills");
+        if (this.opts.promptTemplate) {
+            for (const value of this.opts.promptTemplate) {
+                args.push("--prompt-template", value);
+            }
+        }
+        if (this.opts.noPromptTemplates)
+            args.push("--no-prompt-templates");
+        if (this.opts.theme) {
+            for (const value of this.opts.theme) {
+                args.push("--theme", value);
+            }
+        }
+        if (this.opts.noThemes)
+            args.push("--no-themes");
+        pushFlag(args, "--thinking", this.opts.thinking);
+        if (this.opts.verbose)
+            args.push("--verbose");
+        if (this.extraArgs?.length)
+            args.push(...this.extraArgs);
+        if (params.mode !== "rpc" && this.opts.files) {
+            for (const value of this.opts.files) {
+                args.push(`@${value}`);
+            }
+        }
+        if (params.prompt) {
+            args.push(params.prompt);
+        }
+        return args;
+    }
+    /**
+   * @returns {CliOutputInterpreter}
+   */
+    createOutputInterpreter() {
+        let sessionId = this.issuedSessionRef;
+        let emittedStarted = false;
+        let finalAnswer = "";
+        /**
+     * @param {unknown} value
+     */
+        const summarizeValue = (value) => {
+            if (value == null)
+                return undefined;
+            const text = extractTextFromJsonValue(value);
+            if (text)
+                return truncate(text, 400);
+            try {
+                return truncate(JSON.stringify(value), 400);
+            }
+            catch {
+                return truncate(String(value), 400);
+            }
+        };
+        /**
+     * @param {Record<string, unknown>} [detail]
+     * @returns {AgentCliEvent[]}
+     */
+        const startedEvents = (detail) => {
+            if (emittedStarted || !sessionId)
+                return [];
+            emittedStarted = true;
+            return [{
+                    type: "started",
+                    engine: this.cliEngine,
+                    title: "PI",
+                    resume: sessionId,
+                    detail,
+                }];
+        };
+        /**
+     * @param {string} line
+     * @returns {AgentCliEvent[]}
+     */
+        const parseLine = (line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return [];
+            let payload;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                    return [];
+                }
+                payload = parsed;
+            }
+            catch {
+                return [];
+            }
+            const type = asString(payload.type);
+            if (!type)
+                return [];
+            if (type === "session") {
+                sessionId = asString(payload.id) ?? sessionId;
+                return startedEvents({
+                    cwd: asString(payload.cwd),
+                    version: payload.version,
+                });
+            }
+            if (type === "message_update") {
+                const assistantEvent = payload.assistantMessageEvent;
+                if (assistantEvent?.type === "text_delta" && typeof assistantEvent.delta === "string") {
+                    finalAnswer += assistantEvent.delta;
+                }
+                return startedEvents();
+            }
+            if (type === "message_end" || type === "turn_end") {
+                const message = payload.message;
+                if (message?.role === "assistant") {
+                    const extracted = extractTextFromJsonValue(message);
+                    if (extracted) {
+                        finalAnswer = extracted;
+                    }
+                }
+                return startedEvents();
+            }
+            if (type === "tool_execution_start") {
+                const toolName = asString(payload.toolName) ?? "tool";
+                const toolId = asString(payload.toolCallId) ?? toolName;
+                return [
+                    ...startedEvents(),
+                    {
+                        type: "action",
+                        engine: this.cliEngine,
+                        phase: "started",
+                        entryType: "thought",
+                        action: {
+                            id: toolId,
+                            kind: toolKindFromName(toolName),
+                            title: toolName,
+                            detail: {
+                                args: payload.args,
+                            },
+                        },
+                        message: `Running ${toolName}`,
+                        level: "info",
+                    },
+                ];
+            }
+            if (type === "tool_execution_update") {
+                const toolName = asString(payload.toolName) ?? "tool";
+                const toolId = asString(payload.toolCallId) ?? toolName;
+                return [
+                    ...startedEvents(),
+                    {
+                        type: "action",
+                        engine: this.cliEngine,
+                        phase: "updated",
+                        entryType: "thought",
+                        action: {
+                            id: toolId,
+                            kind: toolKindFromName(toolName),
+                            title: toolName,
+                            detail: {
+                                args: payload.args,
+                            },
+                        },
+                        message: summarizeValue(payload.partialResult),
+                        level: "info",
+                    },
+                ];
+            }
+            if (type === "tool_execution_end") {
+                const toolName = asString(payload.toolName) ?? "tool";
+                const toolId = asString(payload.toolCallId) ?? toolName;
+                const ok = payload.isError !== true;
+                return [
+                    ...startedEvents(),
+                    {
+                        type: "action",
+                        engine: this.cliEngine,
+                        phase: "completed",
+                        entryType: "thought",
+                        action: {
+                            id: toolId,
+                            kind: toolKindFromName(toolName),
+                            title: toolName,
+                            detail: {
+                                result: summarizeValue(payload.result),
+                            },
+                        },
+                        message: summarizeValue(payload.result),
+                        ok,
+                        level: ok ? "info" : "warning",
+                    },
+                ];
+            }
+            return startedEvents();
+        };
+        return {
+            onStdoutLine: parseLine,
+            onExit: (result) => {
+                const started = !emittedStarted && sessionId
+                    ? startedEvents()
+                    : [];
+                return [
+                    ...started,
+                    {
+                        type: "completed",
+                        engine: this.cliEngine,
+                        ok: !result.exitCode || result.exitCode === 0,
+                        answer: finalAnswer || undefined,
+                        error: result.exitCode && result.exitCode !== 0
+                            ? result.stderr.trim() || `PI exited with code ${result.exitCode}`
+                            : undefined,
+                        resume: sessionId,
+                    },
+                ];
+            },
+        };
+    }
+    /**
+   * @param {PiGenerateOptions} [options]
+   * @returns {Promise<GenerateTextResult>}
+   */
+    async generate(options) {
+        const mode = this.resolveMode(options);
+        // Non-RPC modes delegate to BaseCliAgent.generate() which handles
+        // metrics, diagnostics, and the full process lifecycle.
+        if (mode !== "rpc") {
+            return super.generate(options);
+        }
+        // RPC mode requires a custom transport (stdin/stdout JSON-RPC).
+        if (this.opts.files?.length) {
+            throw new SmithersError("AGENT_RPC_FILE_ARGS", "RPC mode does not support file arguments");
+        }
+        const { prompt } = extractPrompt(options);
+        const callTimeouts = resolveTimeouts(options?.timeout, {
+            totalMs: this.timeoutMs,
+            idleMs: this.idleTimeoutMs,
+        });
+        const cwd = this.cwd ?? options?.rootDir ?? process.cwd();
+        const env = { ...process.env, ...this.env };
+        const args = this.buildArgs({ prompt, cwd, options, mode });
+        const diagnosticsPromise = launchDiagnostics("pi", env, cwd);
+        const interpreter = this.createOutputInterpreter();
+        /**
+     * @param {AgentCliEvent[] | AgentCliEvent | null | undefined} payload
+     */
+        const emitEvents = (payload) => {
+            if (!payload || !options?.onEvent)
+                return;
+            const events = Array.isArray(payload) ? payload : [payload];
+            for (const event of events) {
+                void Promise.resolve(options.onEvent(event)).catch(() => undefined);
+            }
+        };
+        /**
+     * @param {unknown} err
+     */
+        const diagnosticsEnrichment = (err) => Effect.tryPromise({
+            try: async () => {
+                if (!diagnosticsPromise)
+                    return;
+                const report = await diagnosticsPromise.catch(() => null);
+                if (report && err instanceof SmithersError) {
+                    enrichReportWithErrorAnalysis(report, err.message);
+                    err.details = { ...err.details, diagnostics: report };
+                }
+            },
+            catch: (cause) => toSmithersError(cause, "enrich diagnostics"),
+        }).pipe(Effect.ignore);
+        const rpcProgram = Effect.gen(this, function* () {
+            const rpcResult = yield* runRpcCommandEffect("pi", args, {
+                cwd,
+                env,
+                prompt,
+                timeoutMs: callTimeouts.totalMs,
+                idleTimeoutMs: callTimeouts.idleMs,
+                signal: options?.abortSignal,
+                maxOutputBytes: this.maxOutputBytes ?? options?.maxOutputBytes,
+                onStdout: options?.onStdout,
+                onStderr: options?.onStderr,
+                onJsonEvent: (event) => emitEvents(interpreter.onStdoutLine?.(JSON.stringify(event))),
+                onExtensionUiRequest: this.opts.onExtensionUiRequest,
+            });
+            emitEvents(interpreter.onExit?.({
+                stdout: rpcResult.text,
+                stderr: rpcResult.stderr,
+                exitCode: rpcResult.exitCode,
+            }));
+            return buildGenerateResult(rpcResult.text, rpcResult.output, this.opts.model ?? "pi", rpcResult.usage);
+        }).pipe(Effect.tapError(diagnosticsEnrichment));
+        return runAgentPromise(rpcProgram);
+    }
+    /**
+   * @param {{ prompt: string; systemPrompt?: string; cwd: string; options?: PiGenerateOptions; }} params
+   * @returns {Promise<{ command: string; args: string[]; stdin?: string; outputFormat?: string; outputFile?: string; cleanup?: () => Promise<void>; }>}
+   */
+    async buildCommand(params) {
+        const mode = this.resolveMode(params.options);
+        if (mode === "rpc") {
+            throw new SmithersError("AGENT_BUILD_COMMAND", "Pi RPC mode uses the custom RPC transport");
+        }
+        return {
+            command: "pi",
+            args: this.buildArgs({
+                prompt: params.prompt,
+                cwd: params.cwd,
+                options: params.options,
+                mode,
+            }),
+            outputFormat: mode,
+        };
+    }
+}

package/src/PiAgentOptions.ts

@@ -0,0 +1,40 @@
+import type { BaseCliAgentOptions } from "./BaseCliAgent/BaseCliAgentOptions";
+import type { PiExtensionUiRequest } from "./BaseCliAgent/PiExtensionUiRequest";
+import type { PiExtensionUiResponse } from "./BaseCliAgent/PiExtensionUiResponse";
+
+export type PiAgentOptions = BaseCliAgentOptions & {
+  provider?: string;
+  model?: string;
+  apiKey?: string;
+  systemPrompt?: string;
+  appendSystemPrompt?: string;
+  mode?: "text" | "json" | "rpc";
+  print?: boolean;
+  continue?: boolean;
+  resume?: boolean;
+  session?: string;
+  sessionDir?: string;
+  noSession?: boolean;
+  models?: string | string[];
+  listModels?: boolean | string;
+  tools?: string[];
+  noTools?: boolean;
+  extension?: string[];
+  noExtensions?: boolean;
+  skill?: string[];
+  noSkills?: boolean;
+  promptTemplate?: string[];
+  noPromptTemplates?: boolean;
+  theme?: string[];
+  noThemes?: boolean;
+  thinking?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+  export?: string;
+  files?: string[];
+  verbose?: boolean;
+  onExtensionUiRequest?: (
+    request: PiExtensionUiRequest,
+  ) =>
+    | Promise<PiExtensionUiResponse | null>
+    | PiExtensionUiResponse
+    | null;
+};

package/src/SdkAgentOptions.ts

@@ -0,0 +1,16 @@
+import type {
+  ToolLoopAgentSettings,
+  ToolSet,
+} from "ai";
+
+export type SdkAgentOptions<
+  CALL_OPTIONS = never,
+  TOOLS extends ToolSet = {},
+  MODEL = any,
+> = Omit<ToolLoopAgentSettings<CALL_OPTIONS, TOOLS>, "model"> & {
+  /**
+   * Either a provider model id string or a preconstructed AI SDK language model.
+   * Passing a model instance is mainly useful for tests and advanced provider setup.
+   */
+  model: string | MODEL;
+};

package/src/agent-contract/SmithersAgentContract.ts

@@ -0,0 +1,10 @@
+import type { SmithersToolSurface } from "./SmithersToolSurface";
+import type { SmithersAgentContractTool } from "./SmithersAgentContractTool";
+
+export type SmithersAgentContract = {
+  toolSurface: SmithersToolSurface;
+  serverName: string;
+  tools: SmithersAgentContractTool[];
+  promptGuidance: string;
+  docsGuidance: string;
+};

package/src/agent-contract/SmithersAgentContractTool.ts

@@ -0,0 +1,8 @@
+import type { SmithersAgentToolCategory } from "./SmithersAgentToolCategory";
+
+export type SmithersAgentContractTool = {
+  name: string;
+  description: string;
+  destructive: boolean;
+  category: SmithersAgentToolCategory;
+};

package/src/agent-contract/SmithersAgentToolCategory.ts

@@ -0,0 +1,6 @@
+export type SmithersAgentToolCategory =
+  | "runs"
+  | "approvals"
+  | "workflows"
+  | "debug"
+  | "admin";

package/src/agent-contract/SmithersListedTool.ts

@@ -0,0 +1,4 @@
+export type SmithersListedTool = {
+  name: string;
+  description?: string | null;
+};

package/src/agent-contract/SmithersToolSurface.ts

@@ -0,0 +1 @@
+export type SmithersToolSurface = "raw" | "semantic";