@the-open-engine/zeroshot 6.30.1 → 6.31.0

package/src/agent-cli-provider/omp/sdk-sidecar-output.ts

@@ -0,0 +1,235 @@
+import { isDeepStrictEqual } from 'node:util';
+
+import Ajv from 'ajv';
+
+import {
+  OMP_SDK_BACKEND_VERSION,
+  OMP_SDK_BUN_VERSION,
+  validateOmpSdkProtocolResultFrame,
+  type OmpSdkProtocolFrame,
+  type OmpSdkSidecarRequest,
+} from './sdk-protocol';
+import {
+  ALLOWED_YIELD_FIELDS,
+  SidecarFailure,
+  isRecord,
+  natural,
+  nonnegative,
+  type OmpSingleResult,
+  type YieldItem,
+} from './sdk-sidecar-types';
+import { classify } from './sdk-sidecar-runtime';
+
+function yieldItem(value: unknown): YieldItem {
+  if (!isRecord(value)) throw new SidecarFailure('sdk-error', 'sdk', false);
+  const type = value.type;
+  if (
+    Object.keys(value).some((key) => ALLOWED_YIELD_FIELDS[key] !== true) ||
+    (value.status !== 'success' && value.status !== 'aborted') ||
+    (value.error !== undefined && typeof value.error !== 'string') ||
+    (value.schemaOverridden !== undefined && typeof value.schemaOverridden !== 'boolean') ||
+    (value.useLastTurn !== undefined && typeof value.useLastTurn !== 'boolean') ||
+    (type !== undefined &&
+      !(typeof type === 'string' && type.length > 0) &&
+      !(
+        Array.isArray(type) &&
+        type.length > 0 &&
+        type.every((item) => typeof item === 'string' && item.length > 0)
+      ))
+  ) {
+    throw new SidecarFailure('sdk-error', 'sdk', false);
+  }
+  return value as YieldItem;
+}
+function terminalYield(result: OmpSingleResult): YieldItem {
+  const raw = result.extractedToolData?.yield;
+  if (!Array.isArray(raw) || raw.length !== 1) {
+    throw new SidecarFailure('schema-violation', 'schema', false);
+  }
+  const terminal = yieldItem(raw[0]);
+  if (
+    Array.isArray(terminal.type) ||
+    terminal.status !== 'success' ||
+    terminal.error !== undefined ||
+    terminal.useLastTurn === true ||
+    terminal.schemaOverridden === true ||
+    !Object.hasOwn(terminal, 'data')
+  ) {
+    throw new SidecarFailure('schema-violation', 'schema', false);
+  }
+  return terminal;
+}
+function immutableYieldData(value: unknown): unknown {
+  const pending = [value];
+  const seen = new Set<object>();
+  while (pending.length > 0) {
+    const current = pending.pop();
+    if (
+      current === null ||
+      typeof current === 'string' ||
+      typeof current === 'boolean' ||
+      (typeof current === 'number' && Number.isFinite(current))
+    ) {
+      continue;
+    }
+    if (typeof current !== 'object' || seen.has(current)) {
+      throw new SidecarFailure('schema-violation', 'schema', false);
+    }
+    seen.add(current);
+    if (Array.isArray(current)) {
+      current.forEach((child) => pending.push(child));
+      continue;
+    }
+    const prototype = Reflect.getPrototypeOf(current);
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new SidecarFailure('schema-violation', 'schema', false);
+    }
+    Object.values(current).forEach((child) => pending.push(child));
+  }
+  let encoded: unknown;
+  try {
+    encoded = JSON.stringify(value);
+  } catch {
+    throw new SidecarFailure('schema-violation', 'schema', false);
+  }
+  if (typeof encoded !== 'string') {
+    throw new SidecarFailure('schema-violation', 'schema', false);
+  }
+  const snapshot: unknown = JSON.parse(encoded);
+  const stack = [snapshot];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === null || typeof current !== 'object' || Object.isFrozen(current)) continue;
+    Object.values(current).forEach((child) => stack.push(child));
+    Object.freeze(current);
+  }
+  return snapshot;
+}
+function validateSchema(schema: unknown, value: unknown): void {
+  try {
+    if (typeof schema !== 'boolean' && (schema === null || typeof schema !== 'object')) {
+      throw new SidecarFailure('invalid-request', 'request', false);
+    }
+    const validate = new Ajv({
+      allErrors: true,
+      coerceTypes: false,
+      strict: false,
+      validateFormats: false,
+    }).compile(schema);
+    if (!validate(value)) throw new SidecarFailure('schema-violation', 'schema', false);
+  } catch (error) {
+    if (error instanceof SidecarFailure) throw error;
+    throw new SidecarFailure('invalid-request', 'request', false);
+  }
+}
+export function successfulValue(
+  result: OmpSingleResult,
+  request: OmpSdkSidecarRequest,
+  schema: unknown,
+  signal?: AbortSignal
+): unknown {
+  if (signal?.aborted) throw new SidecarFailure('cancelled', 'cancelled', false);
+  if (result.aborted === true) {
+    if (/timeout|timed out|deadline/i.test(result.abortReason ?? '')) {
+      throw new SidecarFailure('provider-timeout', 'timeout', true);
+    }
+    throw new SidecarFailure('cancelled', 'cancelled', false);
+  }
+  if (!Number.isInteger(result.exitCode)) throw new SidecarFailure('sdk-error', 'sdk', false);
+  if (result.exitCode !== 0) throw classify(result.retryFailure ?? result.error ?? result.stderr);
+  if (result.resolvedModel !== request.modelSelector) {
+    throw new SidecarFailure('model-resolution', 'model', false);
+  }
+  if (result.resolvedModelIsFallback === true) {
+    throw new SidecarFailure('model-fallback', 'model', false);
+  }
+  const structured = result.structuredOutput;
+  if (
+    structured?.source !== 'caller' ||
+    structured.mode !== 'strict' ||
+    structured.status !== 'valid' ||
+    !Object.hasOwn(structured, 'data')
+  ) {
+    throw new SidecarFailure('schema-violation', 'schema', false);
+  }
+  const terminal = terminalYield(result);
+  const terminalData = immutableYieldData(terminal.data);
+  const structuredData = immutableYieldData(structured.data);
+  if (!isDeepStrictEqual(terminalData, structuredData)) {
+    throw new SidecarFailure('schema-violation', 'schema', false);
+  }
+  validateSchema(schema, structuredData);
+  return structuredData;
+}
+function usage(result: OmpSingleResult): Record<string, unknown> {
+  const item = result.usage;
+  if (item === undefined) throw new SidecarFailure('sdk-error', 'sdk', false);
+  const tokenValues = [item.input, item.output, item.cacheRead, item.cacheWrite, item.totalTokens];
+  const costValues = [
+    item.cost.input,
+    item.cost.output,
+    item.cost.cacheRead,
+    item.cost.cacheWrite,
+    item.cost.total,
+  ];
+  if (
+    !tokenValues.every(natural) ||
+    !costValues.every(nonnegative) ||
+    !natural(result.requests) ||
+    !nonnegative(result.durationMs)
+  ) {
+    throw new SidecarFailure('sdk-error', 'sdk', false);
+  }
+  return {
+    source: 'omp-aggregate',
+    completeness: 'unknown',
+    inputTokens: item.input,
+    outputTokens: item.output,
+    cacheReadInputTokens: item.cacheRead,
+    cacheCreationInputTokens: item.cacheWrite,
+    totalTokens: item.totalTokens,
+    requests: result.requests,
+    durationMs: result.durationMs,
+    cost: item.cost,
+  };
+}
+function textResult(value: unknown): string {
+  if (!isRecord(value) || typeof value.result !== 'string') {
+    throw new SidecarFailure('schema-violation', 'schema', false);
+  }
+  return value.result;
+}
+export function resultFrame(
+  request: OmpSdkSidecarRequest,
+  result: OmpSingleResult,
+  rawValue: unknown
+): OmpSdkProtocolFrame {
+  const frame = {
+    protocolVersion: 1,
+    type: 'result',
+    runId: request.runId,
+    backend: { id: 'omp-sdk', version: OMP_SDK_BACKEND_VERSION },
+    runtime: { name: 'bun', version: OMP_SDK_BUN_VERSION },
+    requested: {
+      modelSelector: request.modelSelector,
+      reasoningEffort: request.reasoningEffort,
+      outputMode: request.outputMode,
+    },
+    resolved: { modelSelector: result.resolvedModel },
+    strictOutput: {
+      source: 'caller',
+      mode: 'strict',
+      status: 'valid',
+      yieldCount: 1,
+    },
+    fallback: false,
+    execution: { exitCode: 0, aborted: false },
+    value: request.outputMode === 'text' ? textResult(rawValue) : rawValue,
+    usage: usage(result),
+  };
+  try {
+    return validateOmpSdkProtocolResultFrame(frame, request);
+  } catch {
+    throw new SidecarFailure('sdk-error', 'sdk', false);
+  }
+}

package/src/agent-cli-provider/omp/sdk-sidecar-runtime.ts

@@ -0,0 +1,244 @@
+import {
+  OMP_SDK_BACKEND_VERSION,
+  OMP_SDK_BUN_VERSION,
+  parseOmpSdkProtocolFrame,
+  type OmpSdkProtocolFrame,
+} from './sdk-protocol';
+import {
+  SidecarFailure,
+  isRecord,
+  type OmpAuthStorage,
+  type OmpModel,
+  type OmpModelRegistry,
+  type OmpModelRegistryConstructor,
+  type OmpSdkBindings,
+  type OmpSingleResult,
+} from './sdk-sidecar-types';
+
+export function bunVersion(): string | undefined {
+  const value = (globalThis as typeof globalThis & { Bun?: { version?: unknown } }).Bun?.version;
+  return typeof value === 'string' ? value : undefined;
+}
+function runtimeMember(container: unknown, name: string): unknown {
+  if (container === null || (typeof container !== 'object' && typeof container !== 'function')) {
+    throw new TypeError('invalid OMP SDK module');
+  }
+  const value: unknown = Reflect.get(container, name);
+  return value;
+}
+function isRuntimeCallable(value: unknown): value is (...args: unknown[]) => unknown {
+  return typeof value === 'function';
+}
+function runtimeCallable(value: unknown): (...args: unknown[]) => unknown {
+  if (!isRuntimeCallable(value)) throw new TypeError('invalid OMP SDK export');
+  return value;
+}
+function isRuntimeConstructor(value: unknown): value is OmpModelRegistryConstructor {
+  if (typeof value !== 'function') return false;
+  try {
+    Reflect.construct(Object, [], value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function runtimeConstructor(value: unknown): OmpModelRegistryConstructor {
+  if (!isRuntimeConstructor(value)) throw new TypeError('invalid OMP SDK constructor');
+  return value;
+}
+function isOmpAuthStorage(value: unknown): value is OmpAuthStorage {
+  return (
+    isRecord(value) &&
+    typeof value.close === 'function' &&
+    typeof value.hasAuth === 'function' &&
+    typeof value.setRuntimeApiKey === 'function'
+  );
+}
+export function requireOmpAuthStorage(value: unknown): OmpAuthStorage {
+  if (!isOmpAuthStorage(value)) throw new TypeError('invalid OMP AuthStorage');
+  return value;
+}
+function isOmpModelRegistry(value: unknown): value is OmpModelRegistry {
+  return (
+    isRecord(value) &&
+    typeof value.find === 'function' &&
+    typeof value.getAvailable === 'function' &&
+    typeof value.getError === 'function'
+  );
+}
+export function requireOmpModelRegistry(value: unknown): OmpModelRegistry {
+  if (!isOmpModelRegistry(value)) throw new TypeError('invalid OMP ModelRegistry');
+  return value;
+}
+function isOmpModel(value: unknown): value is OmpModel {
+  return isRecord(value) && typeof value.id === 'string' && typeof value.provider === 'string';
+}
+function isOmpUsage(value: unknown): value is NonNullable<OmpSingleResult['usage']> {
+  if (!isRecord(value) || !isRecord(value.cost)) return false;
+  return (
+    typeof value.input === 'number' &&
+    typeof value.output === 'number' &&
+    typeof value.cacheRead === 'number' &&
+    typeof value.cacheWrite === 'number' &&
+    typeof value.totalTokens === 'number' &&
+    typeof value.cost.input === 'number' &&
+    typeof value.cost.output === 'number' &&
+    typeof value.cost.cacheRead === 'number' &&
+    typeof value.cost.cacheWrite === 'number' &&
+    typeof value.cost.total === 'number'
+  );
+}
+function isOmpSingleResult(value: unknown): value is OmpSingleResult {
+  if (!isRecord(value)) return false;
+  const extractedToolData = value.extractedToolData;
+  return (
+    typeof value.durationMs === 'number' &&
+    typeof value.exitCode === 'number' &&
+    typeof value.requests === 'number' &&
+    typeof value.stderr === 'string' &&
+    (value.aborted === undefined || typeof value.aborted === 'boolean') &&
+    (value.abortReason === undefined || typeof value.abortReason === 'string') &&
+    (value.error === undefined || typeof value.error === 'string') &&
+    (value.resolvedModel === undefined || typeof value.resolvedModel === 'string') &&
+    (value.resolvedModelIsFallback === undefined ||
+      typeof value.resolvedModelIsFallback === 'boolean') &&
+    (value.structuredOutput === undefined || isRecord(value.structuredOutput)) &&
+    (extractedToolData === undefined ||
+      (isRecord(extractedToolData) && Object.values(extractedToolData).every(Array.isArray))) &&
+    (value.usage === undefined || isOmpUsage(value.usage))
+  );
+}
+export function requireOmpSingleResult(value: unknown): OmpSingleResult {
+  if (!isOmpSingleResult(value)) throw new TypeError('invalid OMP runSubprocess result');
+  return value;
+}
+// OMP is an optional sidecar-only dependency and must not load in the host process.
+async function importRuntimeModule(specifier: string): Promise<unknown> {
+  const runtimeModule: unknown = await import(specifier);
+  return runtimeModule;
+}
+
+export async function loadOmpSdk(): Promise<OmpSdkBindings> {
+  const [root, agents, resolver, broker] = await Promise.all([
+    importRuntimeModule('@oh-my-pi/pi-coding-agent'),
+    importRuntimeModule('@oh-my-pi/pi-coding-agent/task/agents'),
+    importRuntimeModule('@oh-my-pi/pi-coding-agent/config/model-resolver'),
+    importRuntimeModule('@oh-my-pi/pi-coding-agent/session/auth-broker-config'),
+  ]);
+  const authStorageExport = runtimeMember(root, 'AuthStorage');
+  const createAuthStorage = runtimeCallable(runtimeMember(authStorageExport, 'create'));
+  const settings = runtimeMember(root, 'Settings');
+  const isolatedSettings = runtimeCallable(runtimeMember(settings, 'isolated'));
+  const discoverBrokerAuthStorage = runtimeCallable(runtimeMember(broker, 'discoverAuthStorage'));
+  const getBundledAgent = runtimeCallable(runtimeMember(agents, 'getBundledAgent'));
+  const parseModelString = runtimeCallable(runtimeMember(resolver, 'parseModelString'));
+  const modelRegistry = runtimeConstructor(runtimeMember(root, 'ModelRegistry'));
+  const runSubprocess = runtimeCallable(runtimeMember(root, 'runSubprocess'));
+
+  return {
+    AuthStorage: {
+      async create(path: string): Promise<OmpAuthStorage> {
+        const value: unknown = await Promise.resolve(
+          Reflect.apply(createAuthStorage, authStorageExport, [path])
+        );
+        return requireOmpAuthStorage(value);
+      },
+    },
+    ModelRegistry: modelRegistry,
+    Settings: {
+      isolated(overrides: Readonly<Record<string, unknown>>): unknown {
+        const value: unknown = Reflect.apply(isolatedSettings, settings, [overrides]);
+        return value;
+      },
+    },
+    async discoverBrokerAuthStorage(
+      agentDirectory: string,
+      options: { cachePath: string; sourceLabel: string }
+    ): Promise<OmpAuthStorage> {
+      const value: unknown = await Promise.resolve(
+        Reflect.apply(discoverBrokerAuthStorage, broker, [agentDirectory, options])
+      );
+      return requireOmpAuthStorage(value);
+    },
+    getBundledAgent(name: string): Readonly<Record<string, unknown>> | undefined {
+      const value: unknown = Reflect.apply(getBundledAgent, agents, [name]);
+      if (value === undefined) return undefined;
+      if (!isRecord(value)) throw new TypeError('invalid OMP bundled agent');
+      return value;
+    },
+    parseModelString(
+      selector: string
+    ): { readonly id: string; readonly provider: string } | undefined {
+      const value: unknown = Reflect.apply(parseModelString, resolver, [selector]);
+      if (value === undefined) return undefined;
+      if (!isOmpModel(value)) throw new TypeError('invalid OMP model selector');
+      return value;
+    },
+    async runSubprocess(options: Readonly<Record<string, unknown>>): Promise<OmpSingleResult> {
+      const value: unknown = await Promise.resolve(Reflect.apply(runSubprocess, root, [options]));
+      return requireOmpSingleResult(value);
+    },
+  };
+}
+export function runIdFrom(value: unknown): string {
+  if (!isRecord(value) || typeof value.runId !== 'string') return 'unknown';
+  return /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value.runId) && Buffer.byteLength(value.runId) <= 128
+    ? value.runId
+    : 'unknown';
+}
+export function classify(error: unknown): SidecarFailure {
+  if (error instanceof SidecarFailure) return error;
+  const record = isRecord(error) ? error : undefined;
+  const code = typeof record?.code === 'string' ? record.code : '';
+  const status =
+    typeof record?.status === 'number'
+      ? record.status
+      : isRecord(record?.response) && typeof record.response.status === 'number'
+        ? record.response.status
+        : undefined;
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === 'string'
+        ? error
+        : typeof record?.errorMessage === 'string'
+          ? record.errorMessage
+          : '';
+  const searchable = `${code} ${message}`;
+  if (error instanceof Error && error.name === 'AbortError') {
+    return new SidecarFailure('cancelled', 'cancelled', false);
+  }
+  if (
+    status === 401 ||
+    status === 403 ||
+    /auth|unauthori[sz]ed|forbidden|api.?key/i.test(searchable)
+  ) {
+    return new SidecarFailure('provider-auth', 'auth', false);
+  }
+  if (status === 429 || /rate.?limit|too many requests|retry-after/i.test(searchable)) {
+    return new SidecarFailure('provider-rate-limit', 'rate-limit', true);
+  }
+  if (/timeout|timed out|deadline|etimedout/i.test(searchable)) {
+    return new SidecarFailure('provider-timeout', 'timeout', true);
+  }
+  if (/schema|structured output|yield/i.test(searchable)) {
+    return new SidecarFailure('schema-violation', 'schema', false);
+  }
+  return new SidecarFailure('provider-error', 'provider', status === undefined || status >= 500);
+}
+export function createOmpSdkErrorFrame(runId: string, error: unknown): OmpSdkProtocolFrame {
+  const failure = classify(error);
+  return parseOmpSdkProtocolFrame({
+    protocolVersion: 1,
+    type: 'error',
+    runId,
+    backend: { id: 'omp-sdk', version: OMP_SDK_BACKEND_VERSION },
+    runtime: { name: 'bun', version: OMP_SDK_BUN_VERSION },
+    error: {
+      code: failure.code,
+      category: failure.category,
+      retryable: failure.retryable,
+      redacted: true,
+    },
+  });
+}

package/src/agent-cli-provider/omp/sdk-sidecar-types.ts

@@ -0,0 +1,173 @@
+import type { OmpSdkErrorCategory, OmpSdkErrorCode } from './sdk-protocol';
+
+export const PRIVATE_BASE_ENV_KEYS = [
+  'HOME',
+  'XDG_CONFIG_HOME',
+  'XDG_CACHE_HOME',
+  'XDG_DATA_HOME',
+  'XDG_STATE_HOME',
+] as const;
+export const MAX_CREDENTIAL_COUNT = 32;
+export const MAX_CREDENTIAL_NAME_BYTES = 128;
+export const MAX_CREDENTIAL_VALUE_BYTES = 16 * 1024;
+export const CREDENTIAL_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const ALLOWED_YIELD_FIELDS: Readonly<Record<string, true>> = {
+  data: true,
+  error: true,
+  schemaOverridden: true,
+  status: true,
+  type: true,
+  useLastTurn: true,
+};
+
+export const ISOLATED_SETTINGS = {
+  'advisor.enabled': false,
+  'advisor.subagents': false,
+  'advisor.syncBacklog': 'off',
+  'async.enabled': false,
+  'async.maxJobs': 0,
+  'bash.direnv': 'off',
+  'bash.autoBackground.enabled': false,
+  'compaction.autoContinue': false,
+  'compaction.enabled': false,
+  'compaction.idleEnabled': false,
+  'compaction.midTurnEnabled': false,
+  'compaction.remoteEnabled': false,
+  'compaction.remoteStreamingV2Enabled': false,
+  'compaction.strategy': 'off',
+  'prewalk.enabled': false,
+  'retry.fallbackChains': {},
+  'retry.modelFallback': false,
+  'retry.usageAwareFallback': false,
+  'task.agentPrewalk': {},
+  'task.maxRecursionDepth': 0,
+  'task.maxRuntimeMs': 0,
+  'task.prewalk': false,
+  'task.softRequestBudget': 200,
+  'task.softRequestBudgetNotice': true,
+  'thinkingBudgets.high': 16384,
+  'thinkingBudgets.low': 2048,
+  'thinkingBudgets.max': 32768,
+  'thinkingBudgets.medium': 8192,
+  'thinkingBudgets.minimal': 1024,
+  'thinkingBudgets.xhigh': 32768,
+} as const;
+
+export interface OmpAuthStorage {
+  close(): void;
+  hasAuth(provider: string): boolean;
+  setRuntimeApiKey(provider: string, apiKey: string): void;
+}
+export interface OmpModel {
+  readonly api?: string;
+  readonly baseUrl?: string;
+  readonly id: string;
+  readonly provider: string;
+}
+export interface OmpModelRegistry {
+  find(provider: string, id: string): OmpModel | undefined;
+  getAvailable(): readonly OmpModel[];
+  getError(): unknown;
+}
+export interface OmpModelRegistryConstructor {
+  new (
+    authStorage: OmpAuthStorage,
+    modelsPath: string,
+    options?: { ignoreLocalModelConfig?: boolean }
+  ): unknown;
+}
+export interface OmpSingleResult {
+  readonly aborted?: boolean;
+  readonly abortReason?: string;
+  readonly durationMs: number;
+  readonly error?: string;
+  readonly exitCode: number;
+  readonly extractedToolData?: Readonly<Record<string, readonly unknown[]>>;
+  readonly requests: number;
+  readonly resolvedModel?: string;
+  readonly resolvedModelIsFallback?: boolean;
+  readonly retryFailure?: unknown;
+  readonly stderr: string;
+  readonly structuredOutput?: {
+    readonly data?: unknown;
+    readonly mode: unknown;
+    readonly source: unknown;
+    readonly status: unknown;
+  };
+  readonly usage?: {
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly cost: {
+      readonly cacheRead: number;
+      readonly cacheWrite: number;
+      readonly input: number;
+      readonly output: number;
+      readonly total: number;
+    };
+    readonly input: number;
+    readonly output: number;
+    readonly totalTokens: number;
+  };
+}
+export interface OmpSdkBindings {
+  readonly AuthStorage: { create(path: string): Promise<OmpAuthStorage> };
+  readonly ModelRegistry: OmpModelRegistryConstructor;
+  readonly Settings: { isolated(overrides: Readonly<Record<string, unknown>>): unknown };
+  readonly discoverBrokerAuthStorage: (
+    agentDirectory: string,
+    options: { cachePath: string; sourceLabel: string }
+  ) => Promise<OmpAuthStorage>;
+  readonly getBundledAgent: (name: string) => Readonly<Record<string, unknown>> | undefined;
+  readonly parseModelString: (
+    selector: string
+  ) => { readonly id: string; readonly provider: string } | undefined;
+  readonly runSubprocess: (options: Readonly<Record<string, unknown>>) => Promise<OmpSingleResult>;
+}
+export interface PrivateState {
+  readonly agentDirectory: string;
+  readonly authDatabasePath: string;
+  readonly brokerCachePath: string;
+  readonly modelsPath: string;
+  readonly discoveryCwd: string;
+  readonly root: string;
+}
+export interface YieldItem {
+  readonly data?: unknown;
+  readonly error?: string;
+  readonly schemaOverridden?: boolean;
+  readonly status?: 'success' | 'aborted';
+  readonly type?: string | readonly string[];
+  readonly useLastTurn?: boolean;
+}
+export interface CredentialChannel {
+  readonly values: Readonly<Record<string, string>>;
+}
+export interface OmpSdkSidecarOptions {
+  readonly loadOmpSdk?: () => Promise<OmpSdkBindings>;
+  readonly runtimeVersion?: () => string | undefined;
+  readonly signal?: AbortSignal;
+  readonly credentialChannelFd?: number;
+}
+
+export class SidecarFailure extends Error {
+  constructor(
+    readonly code: OmpSdkErrorCode,
+    readonly category: OmpSdkErrorCategory,
+    readonly retryable: boolean
+  ) {
+    super(code);
+    this.name = 'SidecarFailure';
+  }
+}
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function isUnknownArray(value: unknown): value is readonly unknown[] {
+  return Array.isArray(value);
+}
+export function nonnegative(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+export function natural(value: unknown): value is number {
+  return nonnegative(value) && Number.isInteger(value);
+}

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

@@ -0,0 +1,3 @@
+export { createOmpSdkErrorFrame } from './sdk-sidecar-runtime';
+export { executeOmpSdkSidecar, serializeOmpSdkFrame } from './sdk-sidecar-execute';
+export type { OmpSdkSidecarOptions } from './sdk-sidecar-types';