@the-open-engine/zeroshot 6.30.1 → 6.31.0

package/src/agent-cli-provider/omp/rpc-events.ts

@@ -0,0 +1,154 @@
+import {
+  emitAssistantSnapshot,
+  parseAssistantDelta,
+  parseToolExecutionEnd,
+  parseToolExecutionStart,
+  parseToolExecutionUpdate,
+  parseTurnEndResult,
+  resetAssistantSnapshot,
+} from '../assistant-stream';
+import { getRecord, getString, stringifyContent } from '../json';
+import type { OutputEvent } from '../types';
+import { MAX_NORMALIZED_OUTPUT_BYTES } from './rpc-bounds';
+import { OmpRpcProtocolError, type OmpRpcInboundFrame } from './rpc-protocol';
+
+export interface OmpRpcEventState {
+  lastAssistantText: string;
+  lastAssistantThinking: string;
+  lastToolId: string | null | undefined;
+  normalizedBytes: number;
+}
+
+export function createOmpRpcEventState(): OmpRpcEventState {
+  return {
+    lastAssistantText: '',
+    lastAssistantThinking: '',
+    lastToolId: undefined,
+    normalizedBytes: 0,
+  };
+}
+
+function chargeBytes(state: OmpRpcEventState, value: unknown): void {
+  state.normalizedBytes += Buffer.byteLength(stringifyContent(value), 'utf8');
+  if (state.normalizedBytes > MAX_NORMALIZED_OUTPUT_BYTES) {
+    throw new OmpRpcProtocolError(
+      'output-bound-exceeded',
+      `Normalized OMP RPC output exceeded the ${MAX_NORMALIZED_OUTPUT_BYTES}-byte cap for this task.`
+    );
+  }
+}
+
+function chargeEvent(state: OmpRpcEventState, event: OutputEvent): void {
+  switch (event.type) {
+    case 'text':
+    case 'thinking':
+      chargeBytes(state, event.text);
+      break;
+    case 'tool_call':
+      chargeBytes(state, event.input);
+      break;
+    case 'tool_result':
+      chargeBytes(state, event.content);
+      break;
+    case 'result':
+      chargeBytes(state, { result: event.result, error: event.error });
+      break;
+    default:
+      break;
+  }
+}
+
+function chargeEvents(
+  state: OmpRpcEventState,
+  events: readonly OutputEvent[]
+): readonly OutputEvent[] {
+  for (const event of events) chargeEvent(state, event);
+  return events;
+}
+
+function normalizeMessageUpdate(
+  frame: OmpRpcInboundFrame,
+  state: OmpRpcEventState
+): readonly OutputEvent[] {
+  const assistantMessageEvent = getRecord(frame, 'assistantMessageEvent');
+  if (assistantMessageEvent !== null) {
+    const event = parseAssistantDelta(assistantMessageEvent, state);
+    if (event !== null) {
+      chargeEvent(state, event);
+      return [event];
+    }
+  }
+  const message = getRecord(frame, 'message');
+  return message === null
+    ? []
+    : chargeEvents(state, emitAssistantSnapshot(message, state, { retainPreviousOnEmpty: true }));
+}
+
+function normalizeMessageSnapshot(
+  frame: OmpRpcInboundFrame,
+  state: OmpRpcEventState
+): readonly OutputEvent[] {
+  const message = getRecord(frame, 'message');
+  return message === null
+    ? []
+    : chargeEvents(state, emitAssistantSnapshot(message, state, { retainPreviousOnEmpty: true }));
+}
+
+function normalizeToolEvent(
+  frame: OmpRpcInboundFrame,
+  state: OmpRpcEventState
+): readonly OutputEvent[] {
+  const event =
+    frame.type === 'tool_execution_start'
+      ? parseToolExecutionStart(frame, state)
+      : frame.type === 'tool_execution_update'
+        ? parseToolExecutionUpdate(frame, state)
+        : parseToolExecutionEnd(frame, state);
+  if (event === null) return [];
+  chargeEvent(state, event);
+  return [event];
+}
+
+function normalizeTurnEnd(
+  frame: OmpRpcInboundFrame,
+  state: OmpRpcEventState
+): readonly OutputEvent[] {
+  const event = parseTurnEndResult(frame, {
+    failureMessage: 'OMP turn failed',
+    resultFallback: state.lastAssistantText,
+  });
+  const message = getRecord(frame, 'message');
+  const stopReason = message === null ? null : getString(message, 'stopReason');
+  const errorMessage = message === null ? null : getString(message, 'errorMessage');
+  chargeBytes(state, { result: event.result, error: errorMessage ?? stopReason ?? null });
+  return [event];
+}
+
+/**
+ * Normalize one decoded OMP RPC v2 event frame into zero or more OutputEvents. Control frames never
+ * leak into log, attach, or ledger output.
+ */
+export function normalizeOmpRpcFrame(
+  frame: OmpRpcInboundFrame,
+  state: OmpRpcEventState
+): readonly OutputEvent[] {
+  switch (frame.type) {
+    case 'message_start':
+      resetAssistantSnapshot(getRecord(frame, 'message'), state);
+      return [];
+    case 'message_update':
+      return normalizeMessageUpdate(frame, state);
+    case 'message_end':
+      return normalizeMessageSnapshot(frame, state);
+    case 'tool_execution_start':
+    case 'tool_execution_update':
+    case 'tool_execution_end':
+      return normalizeToolEvent(frame, state);
+    case 'turn_end':
+      return normalizeTurnEnd(frame, state);
+    default:
+      return [];
+  }
+}
+
+export { parseNormalizedOmpRpcEventLine } from './rpc-event-lines';

package/src/agent-cli-provider/omp/rpc-protocol-contract.ts

@@ -0,0 +1,77 @@
+import { OMP_SUPPORTED_VERSION } from './release';
+
+export const OMP_RPC_CONTRACT_RELEASE = OMP_SUPPORTED_VERSION;
+
+export interface OmpRpcDecoderLimits {
+  readonly maxPhysicalFrameBytes: number;
+  readonly maxReassembledFrameBytes: number;
+  readonly maxConcurrentReassemblies: number;
+  readonly maxChunksPerFrame: number;
+  readonly maxInflightReassemblyBytes: number;
+}
+
+export const DEFAULT_OMP_RPC_DECODER_LIMITS: OmpRpcDecoderLimits = {
+  maxPhysicalFrameBytes: 1024 * 1024,
+  maxReassembledFrameBytes: 64 * 1024 * 1024,
+  maxConcurrentReassemblies: 1,
+  maxChunksPerFrame: 256,
+  maxInflightReassemblyBytes: 64 * 1024 * 1024,
+};
+
+export interface OmpRpcInboundFrame {
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+export interface OmpRpcCommand {
+  readonly id?: string;
+  readonly type: string;
+  readonly [key: string]: unknown;
+}
+
+export class OmpRpcProtocolError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'OmpRpcProtocolError';
+    this.code = code;
+  }
+}
+
+const KNOWN_PRE_NEGOTIATION_FRAME_TYPES: Readonly<Record<string, true>> = Object.freeze(Object.fromEntries([
+  'ready', 'available_commands_update', 'response', 'extension_error', 'agent_start', 'agent_end',
+  'turn_start', 'turn_end', 'message_start', 'message_update', 'message_end', 'tool_execution_start',
+  'tool_execution_update', 'tool_execution_end', 'auto_compaction_start', 'auto_compaction_end',
+  'auto_retry_start', 'auto_retry_end', 'ttsr_triggered', 'todo_reminder', 'todo_auto_clear',
+  'extension_ui_request', 'host_tool_call', 'host_tool_cancel', 'host_uri_request', 'host_uri_cancel',
+  'prompt_result', 'command_output', 'session_info_update', 'config_update', 'subagent_lifecycle',
+  'subagent_progress', 'subagent_event',
+].map((type) => [type, true] as const)));
+
+export function classifyOmpRpcFrameType(type: string): 'known-pre-negotiation' | 'v2-only' | 'unknown' {
+  if (type === 'rpc_chunk') return 'v2-only';
+  if (KNOWN_PRE_NEGOTIATION_FRAME_TYPES[type] === true) return 'known-pre-negotiation';
+  return 'unknown';
+}
+
+export function assertNoPreNegotiationRpcChunk(frameType: string, negotiatedV2: boolean): void {
+  if (frameType === 'rpc_chunk' && !negotiatedV2) {
+    throw new OmpRpcProtocolError(
+      'pre-negotiation-rpc-chunk',
+      'rpc_chunk frame received before protocol v2 negotiation succeeded.'
+    );
+  }
+}
+
+export function encodeOmpRpcCommand(command: OmpRpcCommand, maxFrameBytes: number): Buffer {
+  const line = `${JSON.stringify(command)}\n`;
+  const byteLength = Buffer.byteLength(line, 'utf8');
+  if (byteLength > maxFrameBytes) {
+    throw new OmpRpcProtocolError(
+      'outbound-frame-too-large',
+      `Outbound command of ${byteLength} bytes exceeds the ${maxFrameBytes}-byte limit.`
+    );
+  }
+  return Buffer.from(line, 'utf8');
+}

package/src/agent-cli-provider/{omp-rpc-protocol.ts → omp/rpc-protocol.ts}

@@ -1,104 +1,13 @@
-import { getNumber, getString, isRecord } from './json';
-import { OMP_SUPPORTED_VERSION } from './omp-release';
-
-// Purely for traceability/doc; no runtime coupling to omp-release's spawn/install concerns.
-export const OMP_RPC_CONTRACT_RELEASE = OMP_SUPPORTED_VERSION;
-
-export interface OmpRpcDecoderLimits {
-  readonly maxPhysicalFrameBytes: number;
-  readonly maxReassembledFrameBytes: number;
-  readonly maxConcurrentReassemblies: number;
-  readonly maxChunksPerFrame: number;
-  readonly maxInflightReassemblyBytes: number;
-}
-
-// Verified against the pinned OMP release's rpc-frame.ts: MAX_RPC_FRAME_BYTES=1MiB, MAX_RPC_REASSEMBLED_BYTES=64MiB,
-// RPC_CHUNK_PAYLOAD_BYTES=256KiB -> ceil(64MiB/256KiB)=256 chunks max. The real decoder tracks exactly one
-// pending sequence at a time, so maxConcurrentReassemblies/maxInflightReassemblyBytes mirror that ceiling.
-export const DEFAULT_OMP_RPC_DECODER_LIMITS: OmpRpcDecoderLimits = {
-  maxPhysicalFrameBytes: 1024 * 1024,
-  maxReassembledFrameBytes: 64 * 1024 * 1024,
-  maxConcurrentReassemblies: 1,
-  maxChunksPerFrame: 256,
-  maxInflightReassemblyBytes: 64 * 1024 * 1024,
-};
-
-export interface OmpRpcInboundFrame {
-  readonly type: string;
-  readonly [key: string]: unknown;
-}
-
-export interface OmpRpcCommand {
-  readonly id?: string;
-  readonly type: string;
-  readonly [key: string]: unknown;
-}
-
-export class OmpRpcProtocolError extends Error {
-  readonly code: string;
-
-  constructor(code: string, message: string) {
-    super(message);
-    this.name = 'OmpRpcProtocolError';
-    this.code = code;
-  }
-}
-
-const KNOWN_PRE_NEGOTIATION_FRAME_TYPES: ReadonlySet<string> = new Set([
-  'ready',
-  'available_commands_update',
-  'response',
-  'extension_error',
-  'agent_start',
-  'agent_end',
-  'turn_start',
-  'turn_end',
-  'message_start',
-  'message_update',
-  'message_end',
-  'tool_execution_start',
-  'tool_execution_update',
-  'tool_execution_end',
-  'auto_compaction_start',
-  'auto_compaction_end',
-  'auto_retry_start',
-  'auto_retry_end',
-  'ttsr_triggered',
-  'todo_reminder',
-  'todo_auto_clear',
-  'extension_ui_request',
-  'host_tool_call',
-  'host_tool_cancel',
-  'host_uri_request',
-  'host_uri_cancel',
-  'prompt_result',
-  'command_output',
-  'session_info_update',
-  'config_update',
-  'subagent_lifecycle',
-  'subagent_progress',
-  'subagent_event',
-]);
-
-export function classifyOmpRpcFrameType(
-  type: string
-): 'known-pre-negotiation' | 'v2-only' | 'unknown' {
-  if (type === 'rpc_chunk') return 'v2-only';
-  if (KNOWN_PRE_NEGOTIATION_FRAME_TYPES.has(type)) return 'known-pre-negotiation';
-  return 'unknown';
-}
-
-export function assertNoPreNegotiationRpcChunk(frameType: string, negotiatedV2: boolean): void {
-  if (frameType === 'rpc_chunk' && !negotiatedV2) {
-    throw new OmpRpcProtocolError(
-      'pre-negotiation-rpc-chunk',
-      'rpc_chunk frame received before protocol v2 negotiation succeeded.'
-    );
-  }
-}
-
+import { getNumber, getString, isRecord } from '../json';
+import {
+  OmpRpcProtocolError,
+  assertNoPreNegotiationRpcChunk,
+  type OmpRpcDecoderLimits,
+  type OmpRpcInboundFrame,
+} from './rpc-protocol-contract';
+
+export * from './rpc-protocol-contract';
 const STRICT_BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
-
 function decodeStrictBase64(data: unknown): Buffer {
   if (typeof data !== 'string' || data.length === 0 || !STRICT_BASE64_PATTERN.test(data)) {
     throw new OmpRpcProtocolError(
@@ -388,14 +297,3 @@ export class OmpRpcFrameDecoder {
   }
 }
 
-export function encodeOmpRpcCommand(command: OmpRpcCommand, maxFrameBytes: number): Buffer {
-  const line = `${JSON.stringify(command)}\n`;
-  const byteLength = Buffer.byteLength(line, 'utf8');
-  if (byteLength > maxFrameBytes) {
-    throw new OmpRpcProtocolError(
-      'outbound-frame-too-large',
-      `Outbound command of ${byteLength} bytes exceeds the ${maxFrameBytes}-byte limit.`
-    );
-  }
-  return Buffer.from(line, 'utf8');
-}

package/src/agent-cli-provider/omp/sdk-contract.ts

@@ -0,0 +1,123 @@
+import { isRecord } from '../json';
+import type { OmpSdkErrorCategory } from './sdk-protocol';
+import type { ProcessResult } from '../process-runner';
+import type { ErrorClassification } from '../types';
+
+export type ContractOmpSdkTerminal =
+  | {
+      readonly type: 'result';
+      readonly frame: Readonly<Record<string, unknown>>;
+      readonly event: Readonly<Record<string, unknown>> & {
+        readonly type: 'result';
+        readonly success: boolean;
+      };
+    }
+  | {
+      readonly type: 'error';
+      readonly frame: Readonly<Record<string, unknown>> & {
+        readonly error: {
+          readonly category: OmpSdkErrorCategory;
+          readonly retryable: boolean;
+        };
+      };
+    };
+
+export interface ContractOmpSdkProcessResult extends ProcessResult {
+  readonly terminal: ContractOmpSdkTerminal;
+  readonly progress: readonly unknown[];
+  readonly diagnosticStderr: string;
+  readonly cleanupAttestation: Readonly<Record<string, unknown>>;
+}
+
+export function isOmpSdkErrorCategory(value: unknown): value is OmpSdkErrorCategory {
+  switch (value) {
+    case 'request':
+    case 'model':
+    case 'auth':
+    case 'rate-limit':
+    case 'timeout':
+    case 'provider':
+    case 'schema':
+    case 'cancelled':
+    case 'sdk':
+    case 'cleanup':
+    case 'internal':
+      return true;
+    default:
+      return false;
+  }
+}
+
+export function isContractOmpSdkTerminal(value: unknown): value is ContractOmpSdkTerminal {
+  if (!isRecord(value) || !isRecord(value.frame) || value.frame.type !== value.type) {
+    return false;
+  }
+  if (value.type === 'result') {
+    return (
+      isRecord(value.event) &&
+      value.event.type === 'result' &&
+      typeof value.event.success === 'boolean'
+    );
+  }
+  if (value.type !== 'error' || !isRecord(value.frame.error)) return false;
+  return (
+    isOmpSdkErrorCategory(value.frame.error.category) &&
+    typeof value.frame.error.retryable === 'boolean'
+  );
+}
+
+export function isContractOmpSdkProcessResult(
+  result: ProcessResult
+): result is ContractOmpSdkProcessResult {
+  return (
+    'terminal' in result &&
+    isContractOmpSdkTerminal(result.terminal) &&
+    'progress' in result &&
+    Array.isArray(result.progress) &&
+    'diagnosticStderr' in result &&
+    typeof result.diagnosticStderr === 'string' &&
+    'cleanupAttestation' in result &&
+    isRecord(result.cleanupAttestation)
+  );
+}
+
+export type OmpSdkErrorClassification = ErrorClassification & {
+  readonly category: OmpSdkErrorCategory;
+};
+
+export function ompSdkFailureClassification(
+  result: ContractOmpSdkProcessResult
+): OmpSdkErrorClassification | null {
+  if (result.terminal.type !== 'error') return null;
+  const { category, retryable } = result.terminal.frame.error;
+  return {
+    category,
+    retryable,
+    kind:
+      category === 'cancelled'
+        ? 'cancelled'
+        : retryable
+          ? 'unknown-retryable'
+          : 'permanent-pattern',
+  };
+}
+
+export function invokeEvidence(
+  result: ProcessResult,
+  timeoutMs: number | undefined
+): Record<string, unknown> {
+  const sdkResult = isContractOmpSdkProcessResult(result) ? result : null;
+  return {
+    exitCode: result.exitCode,
+    signal: result.signal,
+    durationMs: result.durationMs,
+    timedOut: result.timedOut ?? false,
+    timeoutMs: result.timeoutMs ?? timeoutMs ?? null,
+    ...(sdkResult === null
+      ? {}
+      : {
+          terminal: sdkResult.terminal.frame,
+          cleanupAttestation: sdkResult.cleanupAttestation,
+        }),
+  };
+}

package/src/agent-cli-provider/omp/sdk-process-credentials.ts

@@ -0,0 +1,55 @@
+import { OMP_SDK_MAX_CREDENTIAL_BYTES } from './sdk-protocol';
+import { OmpSdkProcessRunnerError } from './sdk-process-error';
+
+const CREDENTIAL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const MAX_CREDENTIAL_COUNT = 32;
+const MAX_CREDENTIAL_NAME_BYTES = 128;
+const MAX_CREDENTIAL_VALUE_BYTES = 16 * 1024;
+
+export function credentialPayload(
+  names: readonly string[],
+  source: Readonly<Record<string, string | undefined>>
+): { readonly payload: Buffer; readonly secretValues: readonly string[] } {
+  if (names.length > MAX_CREDENTIAL_COUNT || new Set(names).size !== names.length) {
+    throw new OmpSdkProcessRunnerError(
+      'credential-error',
+      'OMP SDK credential name set is invalid.'
+    );
+  }
+  const values: Record<string, string> = {};
+  const secretValues: string[] = [];
+  for (const name of names) {
+    const value = source[name];
+    if (
+      !CREDENTIAL_NAME.test(name) ||
+      Buffer.byteLength(name) > MAX_CREDENTIAL_NAME_BYTES ||
+      typeof value !== 'string' ||
+      value.length === 0 ||
+      Buffer.byteLength(value) > MAX_CREDENTIAL_VALUE_BYTES
+    ) {
+      throw new OmpSdkProcessRunnerError(
+        'credential-error',
+        `OMP SDK credential ${name} is missing or invalid.`
+      );
+    }
+    values[name] = value;
+    secretValues.push(value);
+  }
+  const payload = Buffer.from(JSON.stringify({ protocolVersion: 1, values }), 'utf8');
+  if (payload.byteLength > OMP_SDK_MAX_CREDENTIAL_BYTES) {
+    payload.fill(0);
+    throw new OmpSdkProcessRunnerError(
+      'credential-error',
+      'OMP SDK credential document is oversized.'
+    );
+  }
+  return { payload, secretValues };
+}
+
+export function redactDiagnostic(value: string, secrets: readonly string[]): string {
+  let redacted = value;
+  for (const secret of secrets) {
+    if (secret.length > 0) redacted = redacted.split(secret).join('[REDACTED]');
+  }
+  return redacted;
+}

package/src/agent-cli-provider/omp/sdk-process-error.ts

@@ -0,0 +1,9 @@
+export class OmpSdkProcessRunnerError extends Error {
+  readonly code: 'cleanup-error' | 'containment-error' | 'credential-error' | 'protocol-error';
+
+  constructor(code: OmpSdkProcessRunnerError['code'], message: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = 'OmpSdkProcessRunnerError';
+    this.code = code;
+  }
+}

package/src/agent-cli-provider/omp/sdk-process-io.ts

@@ -0,0 +1,92 @@
+import type { ChildProcess } from 'node:child_process';
+import { Writable } from 'node:stream';
+
+import {
+  OMP_SDK_BACKEND_VERSION,
+  OMP_SDK_BUN_VERSION,
+  parseOmpSdkProtocolFrame,
+  type OmpSdkCollectedTerminal,
+  type OmpSdkSidecarRequest,
+} from './sdk-protocol';
+import { OmpSdkProcessRunnerError } from './sdk-process-private-runtime';
+
+export const MAX_STDERR_BYTES = 64 * 1024;
+export const DEFAULT_TERMINATION_GRACE_MS = 250;
+export const DEFAULT_REAP_TIMEOUT_MS = 2_000;
+const TEST_IDENTITY_CAP_ENV = 'ZEROSHOT_OMP_TEST_IDENTITY_CAP';
+export interface ChildOutcome {
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly spawnError?: Error;
+}
+
+export function cancelledTerminal(request: OmpSdkSidecarRequest): OmpSdkCollectedTerminal {
+  const frame = parseOmpSdkProtocolFrame({
+    protocolVersion: 1,
+    type: 'error',
+    runId: request.runId,
+    backend: { id: 'omp-sdk', version: OMP_SDK_BACKEND_VERSION },
+    runtime: { name: 'bun', version: OMP_SDK_BUN_VERSION },
+    error: { code: 'cancelled', category: 'cancelled', retryable: false, redacted: true },
+  });
+  if (frame.type !== 'error') throw new Error('cancelled terminal construction failed');
+  return { type: 'error', frame };
+}
+
+export function childClose(child: ChildProcess): Promise<ChildOutcome> {
+  return new Promise((resolveClose) => {
+    const spawned = child.pid !== undefined;
+    let spawnError: Error | undefined;
+    child.once('error', (error) => {
+      if (!spawned) spawnError = error;
+    });
+    child.once('close', (exitCode, signal) => {
+      resolveClose({ exitCode, signal, ...(spawnError === undefined ? {} : { spawnError }) });
+    });
+  });
+}
+
+export function credentialWriter(child: ChildProcess): Writable {
+  const channel = child.stdio[3];
+  if (!(channel instanceof Writable)) {
+    throw new OmpSdkProcessRunnerError(
+      'protocol-error',
+      'OMP SDK credential channel was not created.'
+    );
+  }
+  channel.on('error', () => {
+    // Keep late peer-reset errors observed after the one-shot write callback from becoming uncaught.
+  });
+  return channel;
+}
+
+export async function writeCredentials(channel: Writable, payload: Buffer): Promise<void> {
+  try {
+    await new Promise<void>((resolveWrite, rejectWrite) => {
+      channel.once('error', rejectWrite);
+      channel.end(payload, () => {
+        channel.removeListener('error', rejectWrite);
+        resolveWrite();
+      });
+    });
+  } finally {
+    payload.fill(0);
+  }
+}
+
+export function duration(value: number | undefined, fallback: number): number {
+  return value !== undefined && Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+export function testIdentityCapArgument(): readonly string[] {
+  const source = process.env.NODE_ENV === 'test' ? process.env[TEST_IDENTITY_CAP_ENV] : undefined;
+  if (source === undefined) return [];
+  const cap = Number(source);
+  if (!Number.isSafeInteger(cap) || cap < 8 || cap > 4_096) {
+    throw new OmpSdkProcessRunnerError(
+      'protocol-error',
+      'OMP SDK private test identity cap is invalid.'
+    );
+  }
+  return [String(cap)];
+}