@smithers-orchestrator/agents 0.16.0

package/src/BaseCliAgent/BaseCliAgentOptions.ts

@@ -0,0 +1,13 @@
+export type BaseCliAgentOptions = {
+  id?: string;
+  model?: string;
+  systemPrompt?: string;
+  instructions?: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  yolo?: boolean;
+  timeoutMs?: number;
+  idleTimeoutMs?: number;
+  maxOutputBytes?: number;
+  extraArgs?: string[];
+};

package/src/BaseCliAgent/CliOutputInterpreter.ts

@@ -0,0 +1,8 @@
+import type { AgentCliEvent } from "./AgentCliEvent";
+import type { RunCommandResult } from "./RunCommandResult";
+
+export type CliOutputInterpreter = {
+  onStdoutLine?: (line: string) => AgentCliEvent[] | AgentCliEvent | null | undefined;
+  onStderrLine?: (line: string) => AgentCliEvent[] | AgentCliEvent | null | undefined;
+  onExit?: (result: RunCommandResult) => AgentCliEvent[] | AgentCliEvent | null | undefined;
+};

package/src/BaseCliAgent/CliUsageInfo.ts

@@ -0,0 +1,7 @@
+export type CliUsageInfo = {
+  inputTokens?: number;
+  outputTokens?: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number;
+};

package/src/BaseCliAgent/CodexConfigOverrides.ts

@@ -0,0 +1,3 @@
+export type CodexConfigOverrides =
+  | Record<string, string | number | boolean | object | null>
+  | string[];

package/src/BaseCliAgent/PiExtensionUiRequest.ts

@@ -0,0 +1,10 @@
+// PiExtensionUiRequest is defined here because RunRpcCommandOptions references it.
+// It is re-exported from PiAgent.ts for the public API barrel.
+export type PiExtensionUiRequest = {
+  type: "extension_ui_request";
+  id: string;
+  method: string;
+  title?: string;
+  placeholder?: string;
+  [key: string]: unknown;
+};

package/src/BaseCliAgent/PiExtensionUiResponse.ts

@@ -0,0 +1,7 @@
+export type PiExtensionUiResponse = {
+  type: "extension_ui_response";
+  id: string;
+  value?: string;
+  cancelled?: boolean;
+  [key: string]: unknown;
+};

package/src/BaseCliAgent/RunCommandResult.ts

@@ -0,0 +1,5 @@
+export type RunCommandResult = {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+};

package/src/BaseCliAgent/buildGenerateResult.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+/** @typedef {import("ai").GenerateTextResult} GenerateTextResult */
+/** @typedef {import("ai").LanguageModelUsage} LanguageModelUsage */
+
+/**
+ * @param {string} text
+ * @param {unknown} output
+ * @param {string} modelId
+ * @param {LanguageModelUsage} [usage]
+ * @returns {GenerateTextResult<Record<string, never>, unknown>}
+ */
+export function buildGenerateResult(text, output, modelId, usage) {
+    const finalUsage = usage ?? {
+        inputTokens: undefined,
+        inputTokenDetails: {
+            noCacheTokens: undefined,
+            cacheReadTokens: undefined,
+            cacheWriteTokens: undefined,
+        },
+        outputTokens: undefined,
+        outputTokenDetails: {
+            textTokens: undefined,
+            reasoningTokens: undefined,
+        },
+        totalTokens: undefined,
+    };
+    return {
+        content: [{ type: "text", text }],
+        text,
+        reasoning: [],
+        reasoningText: undefined,
+        files: [],
+        sources: [],
+        toolCalls: [],
+        staticToolCalls: [],
+        dynamicToolCalls: [],
+        toolResults: [],
+        staticToolResults: [],
+        dynamicToolResults: [],
+        finishReason: "stop",
+        rawFinishReason: undefined,
+        usage: finalUsage,
+        totalUsage: finalUsage,
+        warnings: undefined,
+        request: {},
+        response: {
+            id: randomUUID(),
+            timestamp: new Date(),
+            modelId,
+            messages: [],
+        },
+        providerMetadata: undefined,
+        steps: [],
+        experimental_output: output,
+        output: output,
+    };
+}

package/src/BaseCliAgent/combineNonEmpty.js

@@ -0,0 +1,8 @@
+/**
+ * @param {Array<string | undefined>} parts
+ * @returns {string | undefined}
+ */
+export function combineNonEmpty(parts) {
+    const filtered = parts.map((part) => (part ?? "").trim()).filter(Boolean);
+    return filtered.length ? filtered.join("\n\n") : undefined;
+}

package/src/BaseCliAgent/createAgentStdoutTextEmitter.js

@@ -0,0 +1,198 @@
+import { extractTextFromJsonValue } from "./extractTextFromJsonValue.js";
+/**
+ * @typedef {{ push: (chunk: string) => void; flush: (finalText?: string) => void; }} AgentStdoutTextEmitter
+ */
+/**
+ * @typedef {{ outputFormat?: string; onText?: (text: string) => void; }} AgentStdoutTextEmitterOptions
+ */
+
+/**
+ * @param {unknown} messages
+ * @returns {unknown | undefined}
+ */
+function extractLastAssistantMessage(messages) {
+    if (!Array.isArray(messages))
+        return undefined;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message && typeof message === "object"
+            && /** @type {Record<string, unknown>} */ (message).role === "assistant") {
+            return message;
+        }
+    }
+    return undefined;
+}
+/**
+ * @param {unknown} parsed
+ * @param {{ sawDeltaSinceBoundary: boolean }} state
+ * @returns {string[]}
+ */
+function extractCliStreamTextChunks(parsed, state) {
+    /** @type {string[]} */
+    const chunks = [];
+    /**
+   * @param {string | undefined} text
+   */
+    const emitDelta = (text) => {
+        if (!text)
+            return;
+        state.sawDeltaSinceBoundary = true;
+        chunks.push(text);
+    };
+    /**
+   * @param {string | undefined} text
+   */
+    const emitFinal = (text) => {
+        if (text && !state.sawDeltaSinceBoundary) {
+            chunks.push(text);
+        }
+        state.sawDeltaSinceBoundary = false;
+    };
+    if (!parsed || typeof parsed !== "object") {
+        return chunks;
+    }
+    const record = /** @type {Record<string, unknown>} */ (parsed);
+    const type = typeof record.type === "string" ? record.type : "";
+    const upperType = type.toUpperCase();
+    const delta = /** @type {Record<string, unknown> | undefined} */ (
+        record.delta && typeof record.delta === "object" ? record.delta : undefined
+    );
+    if (type === "content_block_delta" && delta?.type === "text_delta") {
+        emitDelta(typeof delta.text === "string" ? delta.text : undefined);
+    }
+    if (type === "message_update") {
+        const assistantEvent = /** @type {Record<string, unknown> | undefined} */ (
+            record.assistantMessageEvent && typeof record.assistantMessageEvent === "object"
+                ? record.assistantMessageEvent
+                : undefined
+        );
+        if (assistantEvent?.type === "text_delta" &&
+            typeof assistantEvent.delta === "string") {
+            emitDelta(assistantEvent.delta);
+        }
+    }
+    if (/delta/i.test(type) && type !== "content_block_delta" && type !== "message_update") {
+        if (typeof record.delta === "string") {
+            emitDelta(record.delta);
+        }
+        else if (typeof delta?.text === "string") {
+            emitDelta(delta.text);
+        }
+        else if (typeof record.text === "string") {
+            emitDelta(record.text);
+        }
+    }
+    if (type === "message" && record.role === "assistant") {
+        emitFinal(extractTextFromJsonValue(record.content ?? record.message ?? record));
+    }
+    if (upperType === "MESSAGE" && record.role === "assistant") {
+        if (record.delta === true && typeof record.content === "string") {
+            emitDelta(record.content);
+        }
+        else {
+            emitFinal(extractTextFromJsonValue(record.content ?? record.message ?? record));
+        }
+    }
+    if (record.role === "assistant" && typeof record.content === "string") {
+        emitFinal(record.content);
+    }
+    const message = /** @type {Record<string, unknown> | undefined} */ (
+        record.message && typeof record.message === "object" ? record.message : undefined
+    );
+    if (type === "assistant" && message?.role === "assistant") {
+        emitFinal(extractTextFromJsonValue(message));
+    }
+    if (type === "result") {
+        emitFinal(extractTextFromJsonValue(record.result ?? record.response ?? record.output ?? record));
+    }
+    if (type === "turn_end" && message?.role === "assistant") {
+        emitFinal(extractTextFromJsonValue(message));
+    }
+    if (type === "message_end" && message?.role === "assistant") {
+        emitFinal(extractTextFromJsonValue(message));
+    }
+    if (type === "agent_end") {
+        emitFinal(extractTextFromJsonValue(extractLastAssistantMessage(record.messages)));
+    }
+    if (type === "message_stop" ||
+        type === "turn.completed" ||
+        type === "turn_end" ||
+        type === "message_end" ||
+        type === "agent_end" ||
+        type === "result") {
+        state.sawDeltaSinceBoundary = false;
+    }
+    return chunks;
+}
+/**
+ * @param {AgentStdoutTextEmitterOptions} options
+ * @returns {AgentStdoutTextEmitter}
+ */
+export function createAgentStdoutTextEmitter(options) {
+    const { outputFormat, onText } = options;
+    let buffer = "";
+    let emittedAnyText = false;
+    const state = { sawDeltaSinceBoundary: false };
+    /**
+   * @param {string | undefined} text
+   */
+    const emitText = (text) => {
+        if (!onText || !text)
+            return;
+        emittedAnyText = true;
+        onText(text);
+    };
+    /**
+   * @param {string} line
+   */
+    const processLine = (line) => {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        for (const chunk of extractCliStreamTextChunks(parsed, state)) {
+            emitText(chunk);
+        }
+    };
+    return {
+        /**
+     * @param {string} chunk
+     */
+        push(chunk) {
+            if (!onText || !chunk)
+                return;
+            if (!outputFormat || outputFormat === "text") {
+                emitText(chunk);
+                return;
+            }
+            buffer += chunk;
+            let newlineIndex = buffer.indexOf("\n");
+            while (newlineIndex >= 0) {
+                const line = buffer.slice(0, newlineIndex);
+                processLine(line);
+                buffer = buffer.slice(newlineIndex + 1);
+                newlineIndex = buffer.indexOf("\n");
+            }
+        },
+        /**
+     * @param {string} [finalText]
+     */
+        flush(finalText) {
+            if (!onText)
+                return;
+            if (outputFormat && outputFormat !== "text" && buffer.trim()) {
+                processLine(buffer);
+            }
+            buffer = "";
+            if (!emittedAnyText && finalText) {
+                emitText(finalText);
+            }
+        },
+    };
+}

package/src/BaseCliAgent/extractPrompt.js

@@ -0,0 +1,88 @@
+import { extractTextFromJsonValue } from "./extractTextFromJsonValue.js";
+/** @typedef {import("ai").ModelMessage} ModelMessage */
+/**
+ * @typedef {{ prompt: string; systemFromMessages?: string; }} PromptParts
+ */
+
+/**
+ * @param {unknown} content
+ * @returns {string}
+ */
+function contentToText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => {
+            if (typeof part === "string")
+                return part;
+            if (part && typeof part === "object") {
+                const partRecord = /** @type {Record<string, unknown>} */ (part);
+                if (typeof partRecord.text === "string")
+                    return partRecord.text;
+                if (typeof partRecord.content === "string")
+                    return partRecord.content;
+            }
+            return "";
+        })
+            .join("");
+    }
+    if (content == null)
+        return "";
+    return String(content);
+}
+/**
+ * @param {ReadonlyArray<ModelMessage>} messages
+ * @returns {PromptParts}
+ */
+function messagesToPrompt(messages) {
+    /** @type {string[]} */
+    const systemParts = [];
+    /** @type {string[]} */
+    const promptParts = [];
+    for (const msg of messages) {
+        const text = contentToText(msg.content);
+        if (!text)
+            continue;
+        const role = msg.role;
+        if (role === "system") {
+            systemParts.push(text);
+            continue;
+        }
+        if (role) {
+            promptParts.push(`${String(role).toUpperCase()}: ${text}`);
+        }
+        else {
+            promptParts.push(text);
+        }
+    }
+    return {
+        prompt: promptParts.join("\n\n"),
+        systemFromMessages: systemParts.length
+            ? systemParts.join("\n\n")
+            : undefined,
+    };
+}
+/**
+ * @param {unknown} options
+ * @returns {PromptParts}
+ */
+export function extractPrompt(options) {
+    if (!options || typeof options !== "object")
+        return { prompt: "" };
+    const opts = /** @type {Record<string, unknown>} */ (options);
+    if ("prompt" in opts) {
+        const promptInput = opts.prompt;
+        if (typeof promptInput === "string") {
+            return { prompt: promptInput };
+        }
+        if (Array.isArray(promptInput)) {
+            return messagesToPrompt(/** @type {ModelMessage[]} */ (promptInput));
+        }
+        return { prompt: "" };
+    }
+    if (Array.isArray(opts.messages)) {
+        return messagesToPrompt(/** @type {ModelMessage[]} */ (opts.messages));
+    }
+    return { prompt: "" };
+}

package/src/BaseCliAgent/extractTextFromJsonValue.js

@@ -0,0 +1,46 @@
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+export function extractTextFromJsonValue(value) {
+    if (typeof value === "string")
+        return value;
+    if (!value || typeof value !== "object")
+        return undefined;
+    const record = /** @type {Record<string, unknown>} */ (value);
+    if (typeof record.text === "string")
+        return record.text;
+    if (typeof record.content === "string")
+        return record.content;
+    if (Array.isArray(record.content)) {
+        const parts = record.content
+            .map((part) => {
+            if (!part)
+                return "";
+            if (typeof part === "string")
+                return part;
+            if (typeof part !== "object")
+                return "";
+            const partRecord = /** @type {Record<string, unknown>} */ (part);
+            if (typeof partRecord.text === "string")
+                return partRecord.text;
+            if (typeof partRecord.content === "string")
+                return partRecord.content;
+            return "";
+        })
+            .join("");
+        if (parts.trim())
+            return parts;
+    }
+    if (record.response)
+        return extractTextFromJsonValue(record.response);
+    if (record.message)
+        return extractTextFromJsonValue(record.message);
+    if (record.result)
+        return extractTextFromJsonValue(record.result);
+    if (record.output)
+        return extractTextFromJsonValue(record.output);
+    if (record.data)
+        return extractTextFromJsonValue(record.data);
+    return undefined;
+}

package/src/BaseCliAgent/index.js

@@ -0,0 +1,32 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./AgentCliEvent.ts").AgentCliActionEvent} AgentCliActionEvent */
+/** @typedef {import("./AgentCliActionKind.ts").AgentCliActionKind} AgentCliActionKind */
+/** @typedef {import("./AgentCliEvent.ts").AgentCliActionPhase} AgentCliActionPhase */
+/** @typedef {import("./AgentCliEvent.ts").AgentCliCompletedEvent} AgentCliCompletedEvent */
+/** @typedef {import("./AgentCliEvent.ts").AgentCliEvent} AgentCliEvent */
+/** @typedef {import("./AgentCliEvent.ts").AgentCliEventLevel} AgentCliEventLevel */
+/** @typedef {import("./AgentCliEvent.ts").AgentCliStartedEvent} AgentCliStartedEvent */
+/** @typedef {import("./BaseCliAgentOptions.ts").BaseCliAgentOptions} BaseCliAgentOptions */
+/** @typedef {import("./CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
+/** @typedef {import("./CliUsageInfo.ts").CliUsageInfo} CliUsageInfo */
+/** @typedef {import("./CodexConfigOverrides.ts").CodexConfigOverrides} CodexConfigOverrides */
+/** @typedef {import("./PiExtensionUiRequest.ts").PiExtensionUiRequest} PiExtensionUiRequest */
+/** @typedef {import("./PiExtensionUiResponse.ts").PiExtensionUiResponse} PiExtensionUiResponse */
+/** @typedef {import("./RunCommandResult.ts").RunCommandResult} RunCommandResult */
+// @smithers-type-exports-end
+
+export { resolveTimeouts } from "./resolveTimeouts.js";
+export { combineNonEmpty } from "./combineNonEmpty.js";
+export { extractPrompt } from "./extractPrompt.js";
+export { tryParseJson } from "./tryParseJson.js";
+export { extractTextFromJsonValue } from "./extractTextFromJsonValue.js";
+export { createAgentStdoutTextEmitter } from "./createAgentStdoutTextEmitter.js";
+export { truncateToBytes } from "./truncateToBytes.js";
+export { buildGenerateResult } from "./buildGenerateResult.js";
+export { runCommandEffect } from "./runCommandEffect.js";
+export { runRpcCommandEffect } from "./runRpcCommandEffect.js";
+export { pushFlag } from "./pushFlag.js";
+export { pushList } from "./pushList.js";
+export { normalizeCodexConfig } from "./normalizeCodexConfig.js";
+export { BaseCliAgent, extractUsageFromOutput, runAgentPromise } from "./BaseCliAgent.js";
+export { isRecord, asString, asNumber, truncate, toolKindFromName, isLikelyRuntimeMetadata, shouldSurfaceUnparsedStdout, createSyntheticIdGenerator, } from "./parseHelpers.js";

package/src/BaseCliAgent/normalizeCodexConfig.js

@@ -0,0 +1,22 @@
+
+/** @typedef {import("./CodexConfigOverrides.ts").CodexConfigOverrides} CodexConfigOverrides */
+/**
+ * @param {CodexConfigOverrides} [config]
+ * @returns {string[]}
+ */
+export function normalizeCodexConfig(config) {
+    if (!config)
+        return [];
+    if (Array.isArray(config))
+        return config.map(String);
+    const entries = Object.entries(config);
+    return entries.map(([key, value]) => {
+        if (value === null)
+            return `${key}=null`;
+        if (typeof value === "string")
+            return `${key}=${value}`;
+        if (typeof value === "number" || typeof value === "boolean")
+            return `${key}=${value}`;
+        return `${key}=${JSON.stringify(value)}`;
+    });
+}

package/src/BaseCliAgent/parseHelpers.js

@@ -0,0 +1,111 @@
+
+/** @typedef {import("./AgentCliActionKind.ts").AgentCliActionKind} AgentCliActionKind */
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+export function isRecord(value) {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+export function asString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/**
+ * @param {unknown} value
+ * @returns {number | undefined}
+ */
+export function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+export function truncate(value, maxLength = 240) {
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return `${value.slice(0, maxLength - 1)}…`;
+}
+const TOOL_KIND_KEYWORDS = [
+    [["bash", "shell", "command"], "command"],
+    [["search", "web"], "web_search"],
+    [["todo", "plan"], "todo_list"],
+    [["write", "edit", "file"], "file_change"],
+];
+/**
+ * @param {string | undefined} name
+ * @param {ReadonlyArray<readonly [string[], AgentCliActionKind]>} [extraRules]
+ * @returns {AgentCliActionKind}
+ */
+export function toolKindFromName(name, extraRules) {
+    const normalized = (name ?? "").toLowerCase();
+    if (!normalized)
+        return "tool";
+    const rules = extraRules
+        ? [...TOOL_KIND_KEYWORDS, ...extraRules]
+        : TOOL_KIND_KEYWORDS;
+    for (const [keywords, kind] of rules) {
+        for (const keyword of keywords) {
+            if (normalized.includes(keyword)) {
+                return kind;
+            }
+        }
+    }
+    return "tool";
+}
+const RUNTIME_METADATA_MARKERS = [
+    "\"mcp_servers\"",
+    "\"slash_commands\"",
+    "\"permissionmode\"",
+    "\"claude_code_version\"",
+    "\"apikeysource\"",
+    "\"plugins\"",
+    "\"skills\"",
+];
+/**
+ * @param {string} value
+ * @returns {boolean}
+ */
+export function isLikelyRuntimeMetadata(value) {
+    const lower = value.toLowerCase();
+    let matchCount = 0;
+    for (const marker of RUNTIME_METADATA_MARKERS) {
+        if (lower.includes(marker)) {
+            matchCount += 1;
+        }
+    }
+    return matchCount >= 3;
+}
+/**
+ * @param {string} line
+ * @returns {boolean}
+ */
+export function shouldSurfaceUnparsedStdout(line) {
+    if (isLikelyRuntimeMetadata(line)) {
+        return false;
+    }
+    if (line.length > 220) {
+        return false;
+    }
+    const lower = line.toLowerCase();
+    return (lower.includes("error") ||
+        lower.includes("failed") ||
+        lower.includes("denied") ||
+        lower.includes("exception") ||
+        lower.includes("timeout"));
+}
+/**
+ * @returns {(prefix: string) => string}
+ */
+export function createSyntheticIdGenerator() {
+    let counter = 0;
+    return (prefix) => {
+        counter += 1;
+        return `${prefix}-${counter}`;
+    };
+}

package/src/BaseCliAgent/pushFlag.js

@@ -0,0 +1,18 @@
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @param {string | number | boolean} [value]
+ */
+export function pushFlag(args, flag, value) {
+    if (value === undefined)
+        return;
+    if (value === true) {
+        args.push(flag);
+    }
+    else if (value === false) {
+        return;
+    }
+    else {
+        args.push(flag, String(value));
+    }
+}

package/src/BaseCliAgent/pushList.js

@@ -0,0 +1,10 @@
+/**
+ * @param {string[]} args
+ * @param {string} flag
+ * @param {string[]} [values]
+ */
+export function pushList(args, flag, values) {
+    if (!values || values.length === 0)
+        return;
+    args.push(flag, ...values.map(String));
+}