@sayknow-cli/ai 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-06-24
+
+### Fixed
+
+- Reject truncated or incomplete streamed tool calls instead of executing them with partial arguments, so a cut-off tool-call payload fails fast rather than running against a mismatched schema.
+
 ## [0.7.1] - 2026-06-23
 
 ### Changed

package/dist/types/providers/mock.d.ts

@@ -60,6 +60,8 @@ export type MockContent = string | {
     name: string;
     /** Object form is preferred; strings are passed through verbatim. */
     arguments: Record<string, unknown> | string;
+    /** Simulate a provider-flagged truncated call (cut off mid-arguments). */
+    incompleteArguments?: boolean;
 };
 /** One scripted response. */
 export interface MockResponse {

package/dist/types/providers/openai-responses-shared.d.ts

@@ -1,6 +1,6 @@
 import type OpenAI from "openai";
 import type { ResponseInput, ResponseInputContent, ResponseOutputItem } from "openai/resources/responses/responses";
-import { type Api, type AssistantMessage, type ImageContent, type Model, type ServiceTier, type StopReason, type StreamOptions, type TextContent, type TextSignatureV1, type ToolResultMessage } from "../types";
+import { type Api, type AssistantMessage, type ImageContent, type Model, type ServiceTier, type StopReason, type StreamOptions, type TextContent, type TextSignatureV1, type ToolCall, type ToolResultMessage } from "../types";
 import type { AssistantMessageEventStream } from "../utils/event-stream";
 export declare function encodeTextSignatureV1(id: string, phase?: TextSignatureV1["phase"]): string;
 export declare function parseTextSignature(signature: string | undefined): {
@@ -44,6 +44,21 @@ export interface ProcessResponsesStreamOptions {
     onOutputItemDone?: (item: ResponseOutputItem) => void;
 }
 export declare function processResponsesStream<TApi extends Api>(openaiStream: AsyncIterable<OpenAI.Responses.ResponseStreamEvent>, output: AssistantMessage, stream: AssistantMessageEventStream, model: Model<TApi>, options?: ProcessResponsesStreamOptions): Promise<void>;
+/**
+ * Mark tool-call blocks left incomplete by a length-truncated response so the
+ * agent loop rejects them instead of executing a best-effort partial parse.
+ *
+ * The universal signal is finalization: a call that never received its terminal
+ * `output_item.done` (passed in via `isFinalized`) was cut off mid-arguments.
+ * This covers both JSON function calls and raw-input custom tools without
+ * mis-flagging a *completed* custom tool whose raw input is not valid JSON. As a
+ * defensive secondary, a finalized JSON function call whose buffered arguments
+ * still don't parse (e.g. a misbehaving relay) is flagged too. No-op unless the
+ * turn stopped for length.
+ *
+ * Shared by both Responses providers (`openai-responses`, `openai-codex-responses`).
+ */
+export declare function flagTruncatedToolCalls(output: AssistantMessage, stopReason: StopReason, isFinalized: (block: ToolCall) => boolean): void;
 export declare function mapOpenAIResponsesStopReason(status: OpenAI.Responses.ResponseStatus | undefined): StopReason;
 /** Initial empty `AssistantMessage` that streaming providers accumulate into. */
 export declare function createInitialResponsesAssistantMessage(api: Api, provider: string, modelId: string): AssistantMessage;

package/dist/types/types.d.ts

@@ -338,6 +338,14 @@ export interface ToolCall {
      * JSON function tools.
      */
     customWireName?: string;
+    /**
+     * Set when the provider detected the argument JSON was truncated — the model
+     * hit its output-token limit (or the response was otherwise cut short) before
+     * emitting a complete arguments object. The `arguments` field then holds a
+     * best-effort partial parse and must not be executed as-is; the agent loop
+     * rejects the call with a retryable error instead.
+     */
+    incompleteArguments?: boolean;
 }
 export interface Usage {
     /** Non-cached input tokens (matches the bucket the provider bills as new input). */

package/dist/types/utils/json-parse.d.ts

@@ -8,3 +8,11 @@ export declare function parseJsonWithRepair<T>(json: string): T;
  * @returns Parsed object or empty object if parsing fails
  */
 export declare function parseStreamingJson<T = Record<string, unknown>>(partialJson: string | undefined): T;
+/**
+ * Whether a string is a complete, well-formed JSON document (strict parse, no
+ * repair). Used to distinguish a tool-call argument blob that finished cleanly
+ * from one that was cut off mid-stream (truncation). An empty / whitespace-only
+ * string is treated as complete: a tool invoked with no arguments legitimately
+ * streams an empty buffer and must not be flagged as truncated.
+ */
+export declare function isCompleteJson(text: string | undefined): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/ai",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "Unified LLM API with automatic model discovery and provider configuration",
 	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
 	"author": "jaybeyond",
@@ -43,7 +43,7 @@
 	"dependencies": {
 		"@anthropic-ai/sdk": "^0.94.0",
 		"@bufbuild/protobuf": "^2.12.0",
-		"@sayknow-cli/utils": "0.3.0",
+		"@sayknow-cli/utils": "0.3.1",
 		"openai": "^6.36.0",
 		"partial-json": "^0.1.7",
 		"zod": "4.4.3"

package/src/providers/mock.ts

@@ -73,6 +73,8 @@ export type MockContent =
 			name: string;
 			/** Object form is preferred; strings are passed through verbatim. */
 			arguments: Record<string, unknown> | string;
+			/** Simulate a provider-flagged truncated call (cut off mid-arguments). */
+			incompleteArguments?: boolean;
 	  };
 
 /** One scripted response. */
@@ -416,6 +418,7 @@ function normalizeContent(input: MockContent, state: MockModel): TextContent | T
 			id: input.id ?? generateToolCallId(state),
 			name: input.name,
 			arguments: typeof input.arguments === "string" ? input.arguments : { ...input.arguments },
+			...(input.incompleteArguments ? { incompleteArguments: true } : {}),
 		} as ToolCall;
 	}
 	return input;

package/src/providers/openai-codex-responses.ts

@@ -78,6 +78,7 @@ import {
 	convertResponsesInputContent,
 	encodeResponsesToolCallId,
 	encodeTextSignatureV1,
+	flagTruncatedToolCalls,
 	mapOpenAIResponsesStopReason,
 	populateResponsesUsageFromResponse,
 } from "./openai-responses-shared";
@@ -254,6 +255,8 @@ interface CodexStreamRuntime {
 	providerRetryAttempt: number;
 	sawTerminalEvent: boolean;
 	canSafelyReplayWebsocketOverSse: boolean;
+	/** Ids of tool calls that received their terminal `output_item.done`. */
+	finalizedToolCallIds: Set<string>;
 }
 
 interface CodexStreamProcessingContext {
@@ -910,6 +913,7 @@ function createCodexStreamRuntime(initial: {
 		providerRetryAttempt: 0,
 		sawTerminalEvent: false,
 		canSafelyReplayWebsocketOverSse: true,
+		finalizedToolCallIds: new Set<string>(),
 	};
 }
 
@@ -1267,9 +1271,11 @@ function handleOutputItemDone(
 	}
 
 	if (item.type === "function_call") {
+		const id = encodeResponsesToolCallId(item.call_id, item.id);
+		runtime.finalizedToolCallIds.add(id);
 		const toolCall: ToolCall = {
 			type: "toolCall",
-			id: encodeResponsesToolCallId(item.call_id, item.id),
+			id,
 			name: item.name,
 			arguments: parseStreamingJson(item.arguments || "{}"),
 		};
@@ -1279,13 +1285,15 @@ function handleOutputItemDone(
 	}
 
 	if (item.type === "custom_tool_call") {
+		const id = encodeResponsesToolCallId(item.call_id, item.id);
+		runtime.finalizedToolCallIds.add(id);
 		const rawInput =
 			runtime.currentBlock?.type === "toolCall" && runtime.currentBlock.partialJson
 				? runtime.currentBlock.partialJson
 				: (item.input ?? "");
 		const toolCall: ToolCall = {
 			type: "toolCall",
-			id: encodeResponsesToolCallId(item.call_id, item.id),
+			id,
 			name: item.name,
 			arguments: { input: rawInput },
 			customWireName: item.name,
@@ -1349,6 +1357,10 @@ function handleResponseCompleted(
 	calculateCost(model, output.usage);
 	applyCodexServiceTierPricing(model, output.usage, response?.service_tier, runtime.requestBodyForState.service_tier);
 	output.stopReason = mapOpenAIResponsesStopReason(response?.status as OpenAI.Responses.ResponseStatus | undefined);
+	// A response cut short for length may have stopped mid-tool-call. Flag any
+	// call that never received its `output_item.done` so the agent loop rejects
+	// the truncated arguments instead of executing a best-effort partial parse.
+	flagTruncatedToolCalls(output, output.stopReason, block => runtime.finalizedToolCallIds.has(block.id));
 	if (output.content.some(block => block.type === "toolCall") && output.stopReason === "stop") {
 		output.stopReason = "toolUse";
 	}

package/src/providers/openai-completions.ts

@@ -51,7 +51,7 @@ import {
 	getStreamFirstEventTimeoutMs,
 	iterateWithIdleTimeout,
 } from "../utils/idle-iterator";
-import { parseStreamingJson } from "../utils/json-parse";
+import { isCompleteJson, parseStreamingJson } from "../utils/json-parse";
 import { parseGitHubCopilotApiKey } from "../utils/oauth/github-copilot";
 import { getKimiCommonHeaders } from "../utils/oauth/kimi";
 import { notifyProviderResponse } from "../utils/provider-response";
@@ -889,6 +889,17 @@ export const streamOpenAICompletions: StreamFunction<"openai-completions"> = (
 				}
 			}
 
+			// A turn cut short for length may have stopped mid-tool-call. The open
+			// block's `partialArgs` would otherwise be repaired into a plausible-
+			// but-wrong object by `finishCurrentBlock`; flag it first so the agent
+			// loop rejects the truncated call instead of executing it.
+			if (output.stopReason === "length" && currentBlock?.type === "toolCall") {
+				const partial = (currentBlock as { partialArgs?: string }).partialArgs;
+				if (partial !== undefined && !isCompleteJson(partial)) {
+					currentBlock.incompleteArguments = true;
+				}
+			}
+
 			finishCurrentBlock(currentBlock);
 
 			const firstEventTimeoutError = abortTracker.getLocalAbortReason();

package/src/providers/openai-responses-shared.ts

@@ -30,7 +30,7 @@ import {
 } from "../types";
 import { normalizeResponsesToolCallId } from "../utils";
 import type { AssistantMessageEventStream } from "../utils/event-stream";
-import { parseStreamingJson } from "../utils/json-parse";
+import { isCompleteJson, parseStreamingJson } from "../utils/json-parse";
 import { joinTextWithImagePlaceholder, NON_VISION_IMAGE_PLACEHOLDER, partitionVisionContent } from "./vision-guard";
 
 export function encodeTextSignatureV1(id: string, phase?: TextSignatureV1["phase"]): string {
@@ -710,6 +710,13 @@ export async function processResponsesStream<TApi extends Api>(
 							: "Unknown error (no error details in response)";
 				throw new Error(message);
 			}
+			// A response cut short for length (`incomplete`) may have stopped
+			// mid-tool-call. Any tool-call item still tracked in `items` never
+			// received its terminal `output_item.done`, so it was cut off; flag it
+			// (along with any finalized-but-unparseable JSON call) so the agent loop
+			// rejects it instead of executing repaired/partial arguments.
+			const openBlocks = new Set<unknown>(Array.from(items.values(), entry => entry.block));
+			flagTruncatedToolCalls(output, output.stopReason, block => !openBlocks.has(block));
 			if (output.content.some(block => block.type === "toolCall") && output.stopReason === "stop") {
 				output.stopReason = "toolUse";
 			}
@@ -728,6 +735,41 @@ export async function processResponsesStream<TApi extends Api>(
 	}
 }
 
+/**
+ * Mark tool-call blocks left incomplete by a length-truncated response so the
+ * agent loop rejects them instead of executing a best-effort partial parse.
+ *
+ * The universal signal is finalization: a call that never received its terminal
+ * `output_item.done` (passed in via `isFinalized`) was cut off mid-arguments.
+ * This covers both JSON function calls and raw-input custom tools without
+ * mis-flagging a *completed* custom tool whose raw input is not valid JSON. As a
+ * defensive secondary, a finalized JSON function call whose buffered arguments
+ * still don't parse (e.g. a misbehaving relay) is flagged too. No-op unless the
+ * turn stopped for length.
+ *
+ * Shared by both Responses providers (`openai-responses`, `openai-codex-responses`).
+ */
+export function flagTruncatedToolCalls(
+	output: AssistantMessage,
+	stopReason: StopReason,
+	isFinalized: (block: ToolCall) => boolean,
+): void {
+	if (stopReason !== "length") return;
+	for (const block of output.content) {
+		if (block.type !== "toolCall") continue;
+		if (!isFinalized(block)) {
+			block.incompleteArguments = true;
+			continue;
+		}
+		// Finalized: custom tools carry raw (non-JSON) input and are complete once
+		// finalized; only JSON function calls get the parse double-check.
+		if (!block.customWireName) {
+			const partial = (block as { partialJson?: string }).partialJson;
+			if (partial !== undefined && !isCompleteJson(partial)) block.incompleteArguments = true;
+		}
+	}
+}
+
 export function mapOpenAIResponsesStopReason(status: OpenAI.Responses.ResponseStatus | undefined): StopReason {
 	if (!status) return "stop";
 	switch (status) {

package/src/types.ts

@@ -490,6 +490,14 @@ export interface ToolCall {
 	 * JSON function tools.
 	 */
 	customWireName?: string;
+	/**
+	 * Set when the provider detected the argument JSON was truncated — the model
+	 * hit its output-token limit (or the response was otherwise cut short) before
+	 * emitting a complete arguments object. The `arguments` field then holds a
+	 * best-effort partial parse and must not be executed as-is; the agent loop
+	 * rejects the call with a retryable error instead.
+	 */
+	incompleteArguments?: boolean;
 }
 
 export interface Usage {

package/src/utils/json-parse.ts

@@ -146,3 +146,21 @@ export function parseStreamingJson<T = Record<string, unknown>>(partialJson: str
 		}
 	}
 }
+
+/**
+ * Whether a string is a complete, well-formed JSON document (strict parse, no
+ * repair). Used to distinguish a tool-call argument blob that finished cleanly
+ * from one that was cut off mid-stream (truncation). An empty / whitespace-only
+ * string is treated as complete: a tool invoked with no arguments legitimately
+ * streams an empty buffer and must not be flagged as truncated.
+ */
+export function isCompleteJson(text: string | undefined): boolean {
+	const trimmed = text?.trim();
+	if (!trimmed) return true;
+	try {
+		JSON.parse(trimmed);
+		return true;
+	} catch {
+		return false;
+	}
+}