@zvada/agent-server 0.2.1 → 0.3.0

package/src/core/agents/codex-app-server/codex-app-server-agent.ts

@@ -5,7 +5,12 @@ import type {
 	PermissionToolCall,
 } from "../../../protocol/index.ts";
 import { AsyncQueue, codexReasoningEffort } from "../../../protocol/index.ts";
-import type { AgentExecuteOptions, PermissionRequestHandler, RawAgentEvent } from "../base.ts";
+import type {
+	AgentExecuteOptions,
+	CancelResult,
+	PermissionRequestHandler,
+	RawAgentEvent,
+} from "../base.ts";
 import { BaseAgent } from "../base.ts";
 import { configFingerprint } from "../config-fingerprint.ts";
 import { SessionStore } from "../session-store.ts";
@@ -59,10 +64,10 @@ type UserInput = { type: "text"; text: string; text_elements: [] } | { type: "im
 
 function mapSandbox(mode: PermissionMode | undefined): string {
 	switch (mode) {
-		case "bypassPermissions":
+		case "bypass_permissions":
 			return "danger-full-access";
-		case "acceptEdits":
-		case "dontAsk":
+		case "accept_edits":
+		case "dont_ask":
 			// Never-ask posture, but inside the normal sandbox — danger-full is
 			// reserved for the explicitly dangerous mode.
 			return "workspace-write";
@@ -77,6 +82,14 @@ function toUserInput(input: AgentInput): UserInput[] {
 	for (const part of input) {
 		if (part.type === "text") out.push({ type: "text", text: part.text, text_elements: [] });
 		else if (part.url) out.push({ type: "image", url: part.url });
+		else if (part.type === "image" && part.data) {
+			// Codex's user input carries images by URL only; a pasted image arrives
+			// as base64 `data` and used to be dropped SILENTLY while the negotiated
+			// capability said supported. A data URL delivers it on the same field —
+			// and a Codex build that rejects it fails the turn loudly instead of
+			// the prompt losing its attachment with no trace.
+			out.push({ type: "image", url: `data:${part.mimeType};base64,${part.data}` });
+		}
 	}
 	return out.length ? out : [{ type: "text", text: "", text_elements: [] }];
 }
@@ -255,8 +268,14 @@ export class CodexAppServerAgent extends BaseAgent {
 			const handler = session.permissionHandler;
 			if (!handler) return decline;
 			const decision = await handler(approvalToolCall(method, params));
+			// Codex's approval reply is a bare verdict — no slot for
+			// `decision.updatedInput`, so an edited input cannot be honoured here
+			// (only claude-code's `canUseTool` can execute the edit). An edited
+			// approval therefore DECLINES: accepting would run input nobody
+			// approved.
 			switch (decision.decision) {
 				case "allow":
+					if (decision.updatedInput !== undefined) return decline;
 					return v2 ? { decision: "accept" } : { decision: "approved" };
 				case "cancel":
 					return v2 ? { decision: "cancel" } : { decision: "abort" };
@@ -369,8 +388,8 @@ export class CodexAppServerAgent extends BaseAgent {
 		}
 	}
 
-	override async cancel(sessionId: string): Promise<void> {
-		await super.cancel(sessionId);
+	override async cancel(sessionId: string): Promise<CancelResult> {
+		return await super.cancel(sessionId);
 	}
 
 	override async release(sessionId: string): Promise<void> {

package/src/core/agents/codex-sdk/codex-sdk-agent.ts

@@ -77,10 +77,10 @@ export function codexThreadCompatible(
 
 function mapSandbox(mode: PermissionMode | undefined): ThreadOptions["sandboxMode"] {
 	switch (mode) {
-		case "bypassPermissions":
+		case "bypass_permissions":
 			return "danger-full-access";
-		case "acceptEdits":
-		case "dontAsk":
+		case "accept_edits":
+		case "dont_ask":
 			// Never-ask posture, but inside the normal sandbox — danger-full is
 			// reserved for the explicitly dangerous mode.
 			return "workspace-write";

package/src/core/agents/types.ts

@@ -26,7 +26,7 @@ export type AdapterEvent =
 	  }
 	/** Context-window gauge snapshot (→ `session.usage`). */
 	| { kind: "usage"; used: number; size?: number; cost?: number }
-	/** History-compaction boundary (→ `session.compacted`). */
+	/** History-compaction boundary (→ the `session.compaction` entity). */
 	| { kind: "compacted"; trigger?: string; preTokens?: number; postTokens?: number };
 
 /** Terminal result of a turn, surfaced on `turn.ended`. */

package/src/core/diagnostics.ts

@@ -0,0 +1,59 @@
+/**
+ * The engine's diagnostics port: operational signals the engine used to
+ * swallow (best-effort paths that must not fail a turn) surfaced to the host
+ * instead. Products log/metric these; the engine never does its own logging.
+ * Handler errors are always swallowed — a diagnostics sink must never be able
+ * to break a turn.
+ */
+
+/**
+ * Known diagnostic kinds (open set — new kinds may appear in minor versions;
+ * the `(string & {})` arm keeps the union open without losing autocomplete):
+ *  - `interruptTimeout` — a cancel's SDK interrupt round-trip timed out
+ *    (the turn was reported `confirmed: false`; the agent may still run).
+ *  - `resumeFallback` — a requested resume failed and the turn re-ran on a
+ *    fresh session (also visible as `session.created.resumed: false`).
+ *  - `sinkError` — an EventSink emit threw; the event was dropped for that
+ *    sink and the turn continued.
+ *  - `proxyUpstreamAuth` — the BYOK proxy's upstream rejected the real key
+ *    (401/403): the stored key is invalid/expired, not the placeholder.
+ */
+export type DiagnosticKind =
+	| "interruptTimeout"
+	| "resumeFallback"
+	| "sinkError"
+	| "proxyUpstreamAuth"
+	| (string & {});
+
+export interface EngineDiagnostic {
+	type: DiagnosticKind;
+	sessionId?: string;
+	message: string;
+	detail?: unknown;
+	timestamp: number;
+}
+
+/**
+ * Declared `=> void` so any callback shape is assignable (TS's void-return
+ * exemption covers `() => diagnostics.push(d)` AND async handlers); a
+ * returned promise is still detected at runtime and its rejection swallowed.
+ */
+export type DiagnosticHandler = (diagnostic: EngineDiagnostic) => void;
+
+/** Invoke a handler without letting it break the calling path — sync throws
+ * AND async rejections are swallowed (the diagnostics sink owns its own
+ * reliability). Stamps the timestamp so call sites don't repeat it. */
+export function emitDiagnostic(
+	handler: DiagnosticHandler | undefined,
+	diagnostic: Omit<EngineDiagnostic, "timestamp">,
+): void {
+	if (!handler) return;
+	try {
+		const result = handler({ ...diagnostic, timestamp: Date.now() }) as unknown;
+		if (result instanceof Promise) {
+			result.catch(() => {});
+		}
+	} catch {
+		// see above
+	}
+}

package/src/core/index.ts

@@ -1,7 +1,8 @@
 // @zvada/agent-server/core — harness-agnostic agent execution engine.
 
 // Runtime
-export { AgentRuntime, type RunSummary } from "./runtime/agent-runtime.ts";
+export { AgentRuntime, type RunSummary, type TurnAdmission } from "./runtime/agent-runtime.ts";
+export { type DiagnosticHandler, type EngineDiagnostic, emitDiagnostic } from "./diagnostics.ts";
 export {
 	type EventSink,
 	callbackSink,
@@ -14,6 +15,7 @@ export { EventProcessor } from "./runtime/event-processor.ts";
 export {
 	type Agent,
 	type AgentExecuteOptions,
+	type CancelResult,
 	type RawAgentEvent,
 	BaseAgent,
 } from "./agents/base.ts";
@@ -24,7 +26,7 @@ export {
 	classifyError,
 	isRecoverable,
 	isCancellation,
-} from "./agents/error-classifier.ts";
+} from "../protocol/errors.ts";
 
 // Adapter contract
 export type {
@@ -57,6 +59,7 @@ export {
 export type { ClaudeSdkOptionOverrides, SdkMcpServers } from "./agents/claude-code/options.ts";
 export type {
 	ClaudeHooksFactory,
+	ClaudeSessionEndReason,
 	ClaudeSessionExtras,
 	ClaudeToolPolicy,
 } from "./agents/claude-code/generator-session.ts";
@@ -108,6 +111,7 @@ export {
 	CliNotFoundError,
 	CliProvisionError,
 	HarnessNotFoundError,
+	TurnConflictError,
 } from "./utils/errors.ts";
 
 // Re-export the wire contract for convenience.

package/src/core/presets.ts

@@ -8,6 +8,7 @@ import { CodexAppServerAgent } from "./agents/codex-app-server/codex-app-server-
 import { createCodexSdkTransformer } from "./agents/codex-sdk/adapter.ts";
 import { CodexSdkAgent } from "./agents/codex-sdk/codex-sdk-agent.ts";
 import { AgentRegistry } from "./agents/registry.ts";
+import type { DiagnosticHandler } from "./diagnostics.ts";
 import { CliProvisioner, type ProvisionOptions } from "./provision/provisioner.ts";
 import { AgentRuntime } from "./runtime/agent-runtime.ts";
 
@@ -32,6 +33,14 @@ export interface CreateRegistryOptions {
 	 * `resolveCliPath` stays provisioner-wired here.
 	 */
 	claudeCode?: Omit<ClaudeCodeAgentOptions, "resolveCliPath">;
+	/**
+	 * Operational diagnostics port (see `EngineDiagnostic`): interrupt
+	 * timeouts, resume fallbacks, sink failures — signals the engine must not
+	 * fail a turn over, surfaced for the host to log/metric. Applied to the
+	 * runtime and every harness that emits them; a harness-level
+	 * `claudeCode.onDiagnostic` overrides for that harness.
+	 */
+	onDiagnostic?: DiagnosticHandler;
 }
 
 /** Build a registry with the standard harnesses wired to their adapters. */
@@ -50,7 +59,11 @@ export function createAgentRegistry(opts: CreateRegistryOptions = {}): AgentRegi
 	const registry = new AgentRegistry();
 	if (enabled.has("claude-code")) {
 		registry.register(
-			new ClaudeCodeAgent({ ...opts.claudeCode, resolveCliPath: claudeCli }),
+			new ClaudeCodeAgent({
+				onDiagnostic: opts.onDiagnostic,
+				...opts.claudeCode,
+				resolveCliPath: claudeCli,
+			}),
 			createClaudeCodeTransformer,
 		);
 	}
@@ -74,5 +87,5 @@ export function createAgentRegistry(opts: CreateRegistryOptions = {}): AgentRegi
 
 /** Convenience: a ready-to-use runtime with the standard harnesses. */
 export function createAgentRuntime(opts: CreateRegistryOptions = {}): AgentRuntime {
-	return new AgentRuntime(createAgentRegistry(opts));
+	return new AgentRuntime(createAgentRegistry(opts), { onDiagnostic: opts.onDiagnostic });
 }

package/src/core/provision/pins.ts

@@ -27,7 +27,11 @@ export type CliTool = (typeof CLI_TOOLS)[number];
  *   set `provision.pins.codex` to their SDK's vendored version.
  */
 export const DEFAULT_PINS: Record<CliTool, string> = {
-	claude: "0.3.168",
+	// Held at 0.3.220: the paired CLI (2.1.220) honors `--thinking-display
+	// summarized`, so reasoning parts carry text. 2.1.233 ignores the flag and
+	// streams token-estimate placeholders instead — bump only after verifying
+	// thinking summaries still flow (see options.ts extraArgs).
+	claude: "0.3.220",
 	// 0.146.1 re-verified 2026-08-06: generate-ts snapshot carries our full
 	// surface unchanged (thread/turn/item methods, tokenUsage w/ window,
 	// approvals) and a live turn ran clean incl. the gpt-5.6-sol default.

package/src/core/proxy/anthropic-proxy.ts

@@ -1,13 +1,24 @@
+import { type DiagnosticHandler, emitDiagnostic } from "../diagnostics.ts";
 import { type ApiKeyStore, apiKeyStore } from "./api-key-store.ts";
 
 /** Placeholder key handed to the agent subprocess; swapped for the real one here. */
 export const PROXY_PLACEHOLDER_KEY = "sk-proxy-managed";
 
+/** Minimal fetch shape (`globalThis.fetch` qualifies; injectable for tests/platforms). */
+export type FetchLike = (
+	input: string | URL | Request,
+	init?: RequestInit & { duplex?: "half" },
+) => Promise<Response>;
+
 export interface AnthropicProxyOptions {
 	/** Store to resolve real credentials from. Defaults to the shared `apiKeyStore`. */
 	store?: ApiKeyStore;
 	/** Path prefix the proxy is mounted under. Default `/proxy/anthropic`. */
 	pathPrefix?: string;
+	/** Fetch implementation (test seam / platform override). Default `globalThis.fetch`. */
+	fetch?: FetchLike;
+	/** Notified on upstream 401/403 — the STORED key is bad, not the placeholder. */
+	onDiagnostic?: DiagnosticHandler;
 }
 
 /**
@@ -15,8 +26,15 @@ export interface AnthropicProxyOptions {
  * implementing the BYOK Anthropic proxy. Mount it in any server (Bun, Hono,
  * Workers, Node 18+). Requests come in at `{prefix}/{sessionId}/{...path}`; the
  * handler looks up the real key for `sessionId`, swaps the `x-api-key` header,
- * and forwards to the configured upstream — streaming the response through
- * unchanged (SSE included).
+ * and forwards to the configured upstream. Responses are NOT passed through
+ * verbatim — two host-runtime bugs require reshaping (both hit Claude Code as
+ * its API client, found in agnt's production sidecar):
+ *   - SSE bodies are pumped through a `TransformStream`: Bun's HTTP server
+ *     mishandles direct ReadableStream passthrough for SSE and the node
+ *     client sees a premature "terminated".
+ *   - Non-SSE responses drop `content-encoding`/`content-length`/
+ *     `transfer-encoding`: fetch already decompressed the body, so the
+ *     original headers make the client gunzip plain bytes (ZlibError).
  *
  * Point the agent at it with:
  *   ANTHROPIC_BASE_URL=http://localhost:PORT/proxy/anthropic/<sessionId>
@@ -64,6 +82,61 @@ export function createAnthropicProxy(
 		// Required when forwarding a streaming request body on fetch.
 		if (request.body) init.duplex = "half";
 
-		return fetch(`${entry.upstreamBaseUrl}${subPath}${url.search}`, init);
+		const doFetch: FetchLike = options.fetch ?? (globalThis.fetch as FetchLike);
+		let upstream: Response;
+		try {
+			upstream = await doFetch(`${entry.upstreamBaseUrl}${subPath}${url.search}`, init);
+		} catch (error) {
+			// An unreachable upstream must surface as a structured API error the
+			// agent can classify, not a host-framework 500 with an opaque body.
+			return new Response(
+				JSON.stringify({
+					type: "error",
+					error: {
+						type: "api_error",
+						message: error instanceof Error ? error.message : "proxy request failed",
+					},
+				}),
+				{ status: 502, headers: { "content-type": "application/json" } },
+			);
+		}
+
+		if (upstream.status === 401 || upstream.status === 403) {
+			emitDiagnostic(options.onDiagnostic, {
+				type: "proxyUpstreamAuth",
+				sessionId,
+				message: `upstream rejected the stored key for session ${sessionId} (${upstream.status})`,
+				detail: { status: upstream.status },
+			});
+		}
+
+		const contentType = upstream.headers.get("content-type") ?? "";
+		// Media type only — parameters (charset) stripped, case-insensitive, so
+		// `text/event-streamish` or a parameter VALUE never selects SSE handling.
+		const mediaType = (contentType.split(";", 1)[0] ?? "").trim().toLowerCase();
+		if (mediaType === "text/event-stream" && upstream.body) {
+			// Pumped through a fresh stream — see the header comment for why raw
+			// passthrough breaks on Bun. pipeTo (not a manual read/write loop) so a
+			// downstream disconnect propagates cancellation to the upstream body
+			// and the socket is released instead of held open.
+			const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>();
+			void upstream.body.pipeTo(writable).catch(() => {
+				// downstream went away or upstream died — both ends settled by pipeTo
+			});
+			return new Response(readable, {
+				status: upstream.status,
+				headers: { "content-type": "text/event-stream", "cache-control": "no-cache" },
+			});
+		}
+
+		const responseHeaders = new Headers(upstream.headers);
+		responseHeaders.delete("content-encoding");
+		responseHeaders.delete("content-length");
+		responseHeaders.delete("transfer-encoding");
+		return new Response(upstream.body, {
+			status: upstream.status,
+			statusText: upstream.statusText,
+			headers: responseHeaders,
+		});
 	};
 }