@smithers-orchestrator/agents 0.20.0 → 0.20.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smithers-orchestrator/agents",
-  "version": "0.20.0",
+  "version": "0.20.3",
   "description": "AI SDK and CLI agent adapters for Smithers",
   "type": "module",
   "sideEffects": false,
@@ -50,9 +50,9 @@
     "ai": "^6.0.168",
     "effect": "^3.21.1",
     "zod": "^4.3.6",
-    "@smithers-orchestrator/driver": "0.20.0",
-    "@smithers-orchestrator/errors": "0.20.0",
-    "@smithers-orchestrator/observability": "0.20.0"
+    "@smithers-orchestrator/driver": "0.20.3",
+    "@smithers-orchestrator/errors": "0.20.3",
+    "@smithers-orchestrator/observability": "0.20.3"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/src/BaseCliAgent/NormalizedTokenUsage.ts

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

package/src/BaseCliAgent/extractTextFromJsonValue.js

@@ -5,6 +5,10 @@
 export function extractTextFromJsonValue(value) {
     if (typeof value === "string")
         return value;
+    if (Array.isArray(value)) {
+        const text = value.map((item) => extractTextFromJsonValue(item) ?? "").join("");
+        return text || undefined;
+    }
     if (!value || typeof value !== "object")
         return undefined;
     const record = /** @type {Record<string, unknown>} */ (value);
@@ -12,37 +16,21 @@ export function extractTextFromJsonValue(value) {
         return record.text;
     if (typeof record.content === "string")
         return record.content;
+    if (typeof record.output_text === "string")
+        return record.output_text;
     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 "";
-        })
+        const text = record.content
+            .map((part) => extractTextFromJsonValue(part) ?? "")
             .join("");
-        if (parts.trim())
-            return parts;
+        if (text)
+            return text;
     }
     if (record.type === "text" && record.part)
         return extractTextFromJsonValue(record.part);
-    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);
+    for (const field of ["response", "message", "result", "output", "data", "item"]) {
+        const text = extractTextFromJsonValue(record[field]);
+        if (text)
+            return text;
+    }
     return undefined;
 }

package/src/BaseCliAgent/index.js

@@ -10,6 +10,7 @@
 /** @typedef {import("./BaseCliAgentOptions.ts").BaseCliAgentOptions} BaseCliAgentOptions */
 /** @typedef {import("./CliOutputInterpreter.ts").CliOutputInterpreter} CliOutputInterpreter */
 /** @typedef {import("./CliUsageInfo.ts").CliUsageInfo} CliUsageInfo */
+/** @typedef {import("./NormalizedTokenUsage.ts").NormalizedTokenUsage} NormalizedTokenUsage */
 /** @typedef {import("./CodexConfigOverrides.ts").CodexConfigOverrides} CodexConfigOverrides */
 /** @typedef {import("./PiExtensionUiRequest.ts").PiExtensionUiRequest} PiExtensionUiRequest */
 /** @typedef {import("./PiExtensionUiResponse.ts").PiExtensionUiResponse} PiExtensionUiResponse */
@@ -21,6 +22,7 @@ export { combineNonEmpty } from "./combineNonEmpty.js";
 export { extractPrompt } from "./extractPrompt.js";
 export { tryParseJson } from "./tryParseJson.js";
 export { extractTextFromJsonValue } from "./extractTextFromJsonValue.js";
+export { normalizeTokenUsage } from "./normalizeTokenUsage.js";
 export { createAgentStdoutTextEmitter } from "./createAgentStdoutTextEmitter.js";
 export { truncateToBytes } from "./truncateToBytes.js";
 export { buildGenerateResult } from "./buildGenerateResult.js";

package/src/BaseCliAgent/normalizeTokenUsage.js

@@ -0,0 +1,90 @@
+/**
+ * @typedef {import('./NormalizedTokenUsage.ts').NormalizedTokenUsage} NormalizedTokenUsage
+ */
+
+/** @type {Record<keyof NormalizedTokenUsage, ReadonlyArray<ReadonlyArray<string>>>} */
+const usageFieldAliases = {
+    inputTokens: [
+        ["inputTokens"],
+        ["promptTokens"],
+        ["prompt_tokens"],
+        ["input_tokens"],
+        ["input"],
+        ["models", "gemini", "tokens", "input"],
+    ],
+    outputTokens: [
+        ["outputTokens"],
+        ["completionTokens"],
+        ["completion_tokens"],
+        ["output_tokens"],
+        ["output"],
+        ["models", "gemini", "tokens", "output"],
+    ],
+    cacheReadTokens: [
+        ["cacheReadTokens"],
+        ["cache_read_input_tokens"],
+        ["cached_input_tokens"],
+        ["cache_read_tokens"],
+        ["inputTokenDetails", "cacheReadTokens"],
+    ],
+    cacheWriteTokens: [
+        ["cacheWriteTokens"],
+        ["cache_write_input_tokens"],
+        ["cache_creation_input_tokens"],
+        ["cache_write_tokens"],
+        ["inputTokenDetails", "cacheWriteTokens"],
+    ],
+    reasoningTokens: [
+        ["reasoningTokens"],
+        ["reasoning_tokens"],
+        ["outputTokenDetails", "reasoningTokens"],
+    ],
+    totalTokens: [
+        ["totalTokens"],
+        ["total_tokens"],
+    ],
+};
+
+/**
+ * @param {unknown} value
+ * @param {ReadonlyArray<string>} path
+ * @returns {unknown}
+ */
+function readUsagePath(value, path) {
+    let current = value;
+    for (const segment of path) {
+        if (!current || typeof current !== "object")
+            return undefined;
+        current = /** @type {Record<string, unknown>} */ (current)[segment];
+    }
+    return current;
+}
+
+/**
+ * @param {NormalizedTokenUsage} usage
+ * @returns {boolean}
+ */
+function hasMeaningfulTokenUsage(usage) {
+    return Object.values(usage).some((value) => typeof value === "number" && Number.isFinite(value) && value > 0);
+}
+
+/**
+ * @param {unknown} usage
+ * @returns {NormalizedTokenUsage | null}
+ */
+export function normalizeTokenUsage(usage) {
+    if (!usage || typeof usage !== "object")
+        return null;
+    /** @type {NormalizedTokenUsage} */
+    const normalized = {};
+    for (const [field, aliases] of /** @type {Array<[keyof NormalizedTokenUsage, ReadonlyArray<ReadonlyArray<string>>]>} */ (Object.entries(usageFieldAliases))) {
+        for (const path of aliases) {
+            const value = readUsagePath(usage, path);
+            if (typeof value === "number") {
+                normalized[field] = value;
+                break;
+            }
+        }
+    }
+    return hasMeaningfulTokenUsage(normalized) ? normalized : null;
+}

package/src/OpenAIAgent.js

@@ -1,4 +1,5 @@
-import { openai } from "@ai-sdk/openai";
+import { createOpenAI, openai } from "@ai-sdk/openai";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
 import { Output, ToolLoopAgent, } from "ai";
 import { resolveSdkModel } from "./resolveSdkModel.js";
 import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js";
@@ -17,16 +18,29 @@ import { streamResultToGenerateResult } from "./streamResultToGenerateResult.js"
 
 export class OpenAIAgent extends ToolLoopAgent {
     hijackEngine = "openai-sdk";
-    supportsNativeStructuredOutput = true;
     /**
    * @param {OpenAIAgentOptions<CALL_OPTIONS, TOOLS>} opts
    */
     constructor(opts) {
-        const { model, ...rest } = opts;
+        const { model, baseURL, apiKey, nativeStructuredOutput, ...rest } = opts;
+        const hasProviderConfig = baseURL !== undefined || apiKey !== undefined;
+        if (hasProviderConfig && typeof model !== "string") {
+            throw new SmithersError("AGENT_CONFIG_INVALID", "OpenAIAgent baseURL/apiKey can only be used when model is a string. For a prebuilt model, put provider settings in createOpenAI({ baseURL, apiKey }) before calling the provider.", {
+                hasBaseURL: baseURL !== undefined,
+                hasApiKey: apiKey !== undefined,
+            });
+        }
+        const provider = hasProviderConfig
+            ? createOpenAI({
+                ...(baseURL !== undefined ? { baseURL } : {}),
+                ...(apiKey !== undefined ? { apiKey } : {}),
+            })
+            : openai;
         super({
             ...rest,
-            model: resolveSdkModel(model, openai),
+            model: resolveSdkModel(model, provider),
         });
+        this.supportsNativeStructuredOutput = nativeStructuredOutput !== false;
     }
     /**
    * @param {AgentGenerateOptions} [args]
@@ -36,7 +50,7 @@ export class OpenAIAgent extends ToolLoopAgent {
         const promptArgs = "messages" in args
             ? { messages: args.messages }
             : { prompt: args.prompt };
-        const outputArgs = args.outputSchema
+        const outputArgs = this.supportsNativeStructuredOutput && args.outputSchema
             ? { output: Output.object({ schema: args.outputSchema }) }
             : {};
         if (!args.onStdout) {

package/src/OpenAIAgentOptions.ts

@@ -2,7 +2,40 @@ import type { openai } from "@ai-sdk/openai";
 import type { ToolSet } from "ai";
 import type { SdkAgentOptions } from "./SdkAgentOptions";
 
+type OpenAIAgentCommonOptions<
+  CALL_OPTIONS,
+  TOOLS extends ToolSet,
+> = Omit<
+  SdkAgentOptions<CALL_OPTIONS, TOOLS, ReturnType<typeof openai>>,
+  "model"
+> & {
+  /**
+   * Disable AI SDK native structured output and let Smithers use prompt-based JSON extraction.
+   * Useful for OpenAI-compatible local servers that do not honor JSON schema response formats.
+   */
+  nativeStructuredOutput?: boolean;
+};
+
+type OpenAIAgentStringModelOptions = {
+  model: string;
+  /**
+   * Base URL for OpenAI-compatible API calls, e.g. a local llama.cpp server.
+   */
+  baseURL?: string;
+  /**
+   * API key sent to OpenAI-compatible endpoints. Local servers often accept "none".
+   */
+  apiKey?: string;
+};
+
+type OpenAIAgentPrebuiltModelOptions = {
+  model: ReturnType<typeof openai>;
+  baseURL?: never;
+  apiKey?: never;
+};
+
 export type OpenAIAgentOptions<
   CALL_OPTIONS = never,
   TOOLS extends ToolSet = {},
-> = SdkAgentOptions<CALL_OPTIONS, TOOLS, ReturnType<typeof openai>>;
+> = OpenAIAgentCommonOptions<CALL_OPTIONS, TOOLS> &
+  (OpenAIAgentStringModelOptions | OpenAIAgentPrebuiltModelOptions);

package/src/index.d.ts

@@ -101,7 +101,33 @@ type SdkAgentOptions<CALL_OPTIONS = never, TOOLS extends ToolSet = {}, MODEL = a
     model: string | MODEL;
 };
 
-type OpenAIAgentOptions$2<CALL_OPTIONS = never, TOOLS extends ToolSet = {}> = SdkAgentOptions<CALL_OPTIONS, TOOLS, ReturnType<typeof openai>>;
+type OpenAIAgentCommonOptions<CALL_OPTIONS, TOOLS extends ToolSet> = Omit<SdkAgentOptions<CALL_OPTIONS, TOOLS, ReturnType<typeof openai>>, "model"> & {
+    /**
+     * Disable AI SDK native structured output and let Smithers use prompt-based JSON extraction.
+     * Useful for OpenAI-compatible local servers that do not honor JSON schema response formats.
+     */
+    nativeStructuredOutput?: boolean;
+};
+
+type OpenAIAgentStringModelOptions = {
+    model: string;
+    /**
+     * Base URL for OpenAI-compatible API calls, e.g. a local llama.cpp server.
+     */
+    baseURL?: string;
+    /**
+     * API key sent to OpenAI-compatible endpoints. Local servers often accept "none".
+     */
+    apiKey?: string;
+};
+
+type OpenAIAgentPrebuiltModelOptions = {
+    model: ReturnType<typeof openai>;
+    baseURL?: never;
+    apiKey?: never;
+};
+
+type OpenAIAgentOptions$2<CALL_OPTIONS = never, TOOLS extends ToolSet = {}> = OpenAIAgentCommonOptions<CALL_OPTIONS, TOOLS> & (OpenAIAgentStringModelOptions | OpenAIAgentPrebuiltModelOptions);
 
 type AnthropicAgentOptions$2<CALL_OPTIONS = never, TOOLS extends ToolSet = {}> = SdkAgentOptions<CALL_OPTIONS, TOOLS, ReturnType<typeof anthropic>>;