@tangle-network/sandbox 0.0.0-develop.20260514223840.b2abd84

package/dist/openai/index.d.ts

@@ -0,0 +1,642 @@
+import { Response, ResponseCreateParamsBase, ResponseOutputItem, ResponseStreamEvent, ResponseUsage } from "openai/resources/responses/responses";
+import { ChatCompletionChunk, ChatCompletionMessageParam, ChatCompletionTool } from "openai/resources/chat/completions/completions";
+import { Completion } from "openai/resources/completions";
+import { EmbeddingCreateParams } from "openai/resources/embeddings";
+
+//#region src/openai/hooks.d.ts
+/**
+ * Tool-call hook surface.
+ *
+ * Every tool dispatched by the Run executor flows through an ordered
+ * `HookChain`. Hooks observe the call (`beforeToolCall`) and the result
+ * (`afterToolCall`) and may allow, rewrite, block, override, or
+ * terminate. The chain composes built-in hooks (audit-log, egress
+ * policy, cost cap, rate limit, destructive-action guard, screenshot
+ * redaction) with partner-supplied hooks. The route layer wires the
+ * chain into the Run state machine in `runs.ts`.
+ *
+ * Semantics:
+ *   - `beforeToolCall`: `allow` → next hook; `rewrite` → mutates the
+ *     args carried into subsequent hooks and the executor; `block` →
+ *     short-circuits the chain and is surfaced as an error tool result.
+ *   - `afterToolCall`: `pass` → next hook; `override` → mutates the
+ *     result carried into subsequent hooks and the response; `terminate`
+ *     → short-circuits and ends the run with the supplied reason.
+ */
+interface ToolCallContext {
+  runId: string;
+  threadId?: string;
+  partnerId: string;
+  toolName: string;
+  args: unknown;
+  callId: string;
+  timestamp: number;
+}
+interface ToolResult {
+  content: unknown;
+  isError?: boolean;
+  details?: Record<string, unknown>;
+}
+type BeforeHookOutcome = {
+  action: "allow";
+} | {
+  action: "block";
+  reason: string;
+} | {
+  action: "rewrite";
+  args: unknown;
+};
+type AfterHookOutcome = {
+  action: "pass";
+} | {
+  action: "override";
+  result: ToolResult;
+} | {
+  action: "terminate";
+  reason: string;
+};
+interface HookSurface {
+  beforeToolCall?(ctx: ToolCallContext): Promise<BeforeHookOutcome>;
+  afterToolCall?(ctx: ToolCallContext, result: ToolResult): Promise<AfterHookOutcome>;
+}
+/**
+ * Sequential hook composer. Hooks run in registration order; `block` and
+ * `terminate` short-circuit. `rewrite` and `override` thread their
+ * mutated payloads through to the remaining hooks so subsequent hooks
+ * observe the rewritten args / overridden result.
+ */
+declare class HookChain {
+  private readonly hooks;
+  constructor(hooks?: HookSurface[]);
+  /** Number of hooks in the chain. */
+  get size(): number;
+  /**
+   * Run every `beforeToolCall` in registration order. Returns the first
+   * non-`allow` outcome (block/rewrite), or `allow` if the chain ran
+   * clean. `rewrite` outcomes are threaded forward so later hooks see
+   * the mutated args.
+   */
+  runBefore(ctx: ToolCallContext): Promise<BeforeHookOutcome>;
+  /**
+   * Run every `afterToolCall` in registration order. Returns the first
+   * `terminate` outcome immediately. `override` outcomes are threaded
+   * forward so later hooks see the mutated result; the final result is
+   * surfaced as the last `override`, or `pass` if no hook overrode.
+   */
+  runAfter(ctx: ToolCallContext, result: ToolResult): Promise<AfterHookOutcome>;
+}
+interface AuditEvent {
+  phase: "before" | "after";
+  runId: string;
+  threadId?: string;
+  partnerId: string;
+  toolName: string;
+  callId: string;
+  timestamp: number;
+  args?: unknown;
+  result?: ToolResult;
+}
+interface AuditLogOptions {
+  sink?: (event: AuditEvent) => Promise<void> | void;
+}
+/**
+ * Emits a structured `AuditEvent` for every tool call (before + after).
+ * Default sink is `console.info`. The route layer swaps the sink for
+ * the eval-runs DuckDB writer.
+ */
+declare function auditLogHook(opts?: AuditLogOptions): HookSurface;
+interface EgressPolicyOptions {
+  allowList?: string[];
+  denyList?: string[];
+  allowFn?: (ctx: ToolCallContext) => Promise<boolean>;
+}
+/**
+ * Best-effort allow/deny filter for tool-call URLs.
+ *
+ * Block tool calls that look network-ish (toolName matches the network
+ * regex OR args contain url-like fields) when the resolved host hits
+ * the deny list. The allow list is treated as an explicit allowance —
+ * when set, only listed hosts pass; unmatched hosts are blocked.
+ * `allowFn` overrides both lists when present.
+ *
+ * **What this hook does NOT catch.** It inspects URL-shaped strings in
+ * the tool-call arguments only. The following bypass it silently:
+ *
+ *   - URLs encoded as base64 / hex / `Buffer.from(...)` literals
+ *   - URLs assembled at execution time from string fragments
+ *   - URLs reached via redirects, DNS rebinding, or proxy hosts that
+ *     match the allow list but forward to denied destinations
+ *   - Network calls made by spawned subprocesses, generated code, or
+ *     tools whose argument schema does not name a URL field
+ *
+ * Treat this hook as a UX guardrail (clearer error messages,
+ * short-circuiting obvious mistakes) on top of a real egress boundary
+ * — not as one. When egress containment is a security requirement
+ * (exfil prevention, data residency), enforce it at the runtime
+ * sandbox layer (egress firewall, CNI policy, outbound proxy with
+ * mTLS) where the agent cannot evade it.
+ */
+declare function egressPolicyHook(opts?: EgressPolicyOptions): HookSurface;
+interface CostCapOptions {
+  ceiling: number;
+  getCurrentCost?: (partnerId: string) => Promise<number>;
+}
+/**
+ * Terminates the run when the partner's accumulated cost is at or
+ * above `ceiling`. The cost lookup is injected so any usage ledger can
+ * back it.
+ */
+declare function costCapHook(opts: CostCapOptions): HookSurface;
+interface ActionRateLimitOptions {
+  perSecondPerSession: number;
+  /** Optional clock injection for tests. Defaults to `Date.now`. */
+  now?: () => number;
+}
+/**
+ * Token-bucket rate limiter scoped per session id (`runId`) over
+ * `computer-use:*` tool calls. Excess calls are blocked with a clear
+ * reason. Non-`computer-use` tools pass through untouched.
+ */
+declare function actionRateLimitHook(opts: ActionRateLimitOptions): HookSurface;
+interface RedactionRegion {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+interface ScreenshotRedactionOptions {
+  regions?: RedactionRegion[];
+  /** Optional logger for the no-sharp warning path. Defaults to `console.warn`. */
+  warn?: (msg: string) => void;
+}
+/**
+ * Applied AFTER `computer-use:screenshot`. v1 ships without the
+ * `sharp` dependency: when regions are configured, we surface a warning
+ * exactly once per process and pass the screenshot through untouched.
+ * Pixel-blur lands in a follow-up that introduces `sharp` deliberately.
+ */
+declare function screenshotRedactionHook(opts?: ScreenshotRedactionOptions): HookSurface;
+interface DestructiveActionGuardOptions {
+  denyPatterns: RegExp[];
+}
+/**
+ * Block before-execute when a `computer-use:type` text or
+ * `computer-use:click` label matches any deny pattern. Mitigates
+ * destructive-action sequences (e.g. "delete account", "wire transfer")
+ * before they hit the OS.
+ */
+declare function destructiveActionGuardHook(opts: DestructiveActionGuardOptions): HookSurface;
+//#endregion
+//#region src/openai/types.d.ts
+/**
+ * Internal types for the OpenAI translator core.
+ *
+ * The translator is a pure function layer between OpenAI's wire formats
+ * (chat.completions, completions, responses, embeddings) and the Tangle
+ * sandbox run input/output. Types defined here are SDK-internal — public
+ * OpenAI shapes are imported from `openai/resources/...` directly so the
+ * translator's outputs satisfy the upstream type system at compile time.
+ */
+/**
+ * A Tangle SSE event as emitted by the sandbox runtime. The event union is
+ * intentionally open at the data level — every concrete Tangle event has a
+ * known `type` plus a payload whose shape depends on the type. Translators
+ * narrow on `type` and read the fields they need.
+ *
+ * Event types currently emitted by the runtime:
+ *   - `start`                 — handshake, no payload of interest.
+ *   - `execution.started`     — run has begun, no payload of interest.
+ *   - `status`                — signal frames (build_passed, tests_failed, etc.).
+ *   - `token`                 — incremental text token.
+ *   - `message.part.updated`  — provider-native part updates (text deltas,
+ *                                tool state transitions, reasoning blocks).
+ *   - `raw`                   — provider-native passthrough, including
+ *                                `tool-invocation` and `computer-use` payloads.
+ *   - `session.updated`       — session metadata, no payload of interest.
+ *   - `error`                 — terminal error frame.
+ *   - `done`                  — terminal completion frame, optionally with usage.
+ */
+interface TangleSSEEvent {
+  type: string;
+  [key: string]: unknown;
+}
+/**
+ * A single multimodal part on a user/assistant turn. Mirrors the structural
+ * shape of OpenAI's `ChatCompletionContentPart` so we can pass it through
+ * unchanged to providers that accept the OpenAI shape natively, while still
+ * letting non-vision providers reject at the capability layer.
+ */
+type MultimodalPart = {
+  type: "text";
+  text: string;
+} | {
+  type: "image_url";
+  image_url: {
+    url: string;
+    detail?: "auto" | "low" | "high";
+  };
+} | {
+  type: "input_audio";
+  input_audio: {
+    data: string;
+    format: "wav" | "mp3";
+  };
+};
+/**
+ * One reconstructed prior turn for the sandbox run input. The translator
+ * collapses an OpenAI-shape message thread (system / user / assistant /
+ * tool) into an ordered list of prior turns plus a single trailing task.
+ */
+interface PriorTurn {
+  /** Final assistant text on this turn, if any. Tool-only turns omit this. */
+  assistantText?: string;
+  /** Tool calls the assistant emitted on this turn. */
+  toolCalls?: PriorToolCall[];
+  /** Tool results threaded back from the user side, keyed to `toolCalls[i].id`. */
+  toolResults?: PriorToolResult[];
+  /** User-side multimodal content for the turn, when the user sent parts. */
+  userParts?: MultimodalPart[];
+}
+interface PriorToolCall {
+  id: string;
+  name: string;
+  /** JSON-stringified arguments as emitted by the model. */
+  arguments: string;
+}
+interface PriorToolResult {
+  /** Matches the `toolCalls[i].id` from the assistant turn. */
+  toolCallId: string;
+  /** Tool output as a string (OpenAI tool messages carry a string body). */
+  content: string;
+}
+/**
+ * Shape of a tool descriptor preserved from the OpenAI request. The
+ * translator does not interpret tool schemas — it forwards them so the
+ * provider receives the same schema the caller authored.
+ */
+interface SandboxToolSpec {
+  type: "function";
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown> | null;
+    strict?: boolean | null;
+  };
+}
+/**
+ * Resolved input handed to the sandbox run executor. The fields are
+ * provider-agnostic; the executor materializes them into whatever shape
+ * the chosen provider expects.
+ */
+interface SandboxRunInput {
+  /** Provider id stripped of the `tangle/` prefix (e.g. `claude-code`). */
+  provider: string;
+  /** Optional variant after the provider id (e.g. `sonnet` for `tangle/opencode/sonnet`). */
+  variant?: string;
+  /** Concatenated system / developer instructions. */
+  instructions?: string;
+  /** Trailing user task — the message the agent acts on. */
+  task: string;
+  /** Multimodal parts attached to the trailing user task, when present. */
+  taskParts?: MultimodalPart[];
+  /** Reconstructed history before `task`, ordered oldest → newest. */
+  priorTurns?: PriorTurn[];
+  /** Forwarded tool descriptors (function tools only at this layer). */
+  tools?: SandboxToolSpec[];
+  /** Capability hints derived from the request (e.g. computer_use). */
+  capabilities?: string[];
+  /** True when any user message contained non-text parts. */
+  multimodal?: boolean;
+}
+/**
+ * Mutable per-stream context threaded through the chunk translators. The
+ * translator is a pure function over (event, ctx); the context tracks
+ * cross-event state that must persist for the lifetime of one stream
+ * (chunk index, tool-call buffering, the synthetic message id).
+ */
+interface TranslatorContext {
+  /** Stable id assigned to the run; used as the `id` on every chunk. */
+  runId: string;
+  /** Model id echoed back on every chunk (caller-supplied, e.g. `tangle/claude-code`). */
+  modelId: string;
+  /** Monotonic chunk index — each emitted chunk increments. */
+  chunkIndex: number;
+  /** Tool calls observed during the stream, keyed by call id. */
+  toolCallBuffer: Map<string, BufferedToolCall>;
+  /** Unix timestamp (seconds) when the stream was opened. */
+  createdAt: number;
+}
+interface BufferedToolCall {
+  /** Position in the order tool calls were observed. */
+  index: number;
+  id: string;
+  name: string;
+  /** JSON-stringified arguments. */
+  arguments: string;
+}
+/**
+ * Construct a fresh translator context. The factory is deliberately tiny
+ * — call sites that need to override fields can do so via the partial.
+ */
+declare function createTranslatorContext(init: Pick<TranslatorContext, "runId" | "modelId"> & Partial<TranslatorContext>): TranslatorContext;
+//#endregion
+//#region src/openai/translate/responses.d.ts
+/**
+ * Persistence interface for `previous_response_id` chains. The route layer
+ * supplies a concrete impl (DuckDB-backed in production, in-memory in
+ * tests). The translator is store-agnostic.
+ */
+interface ResponseStore {
+  /** Look up the prior turns recorded under a previous response id. */
+  getPriorTurns(responseId: string): Promise<PriorTurn[] | null>;
+  /** Persist the prior turns produced by a response. */
+  putPriorTurns(responseId: string, priorTurns: PriorTurn[]): Promise<void>;
+}
+/**
+ * Resolve a `previous_response_id` into the prior-turns prefix that
+ * gets prepended to the new request. Throws when the id is supplied but
+ * unknown — silently dropping it would corrupt conversation continuity.
+ */
+declare function resolvePreviousResponseId(prevId: string | undefined, store: ResponseStore): Promise<{
+  priorTurns: PriorTurn[];
+}>;
+/**
+ * Aggregate a Tangle SSE event sequence into the Responses-API output[]
+ * array plus a usage envelope. This is the non-streaming path: callers
+ * collect every event, hand them all in, and get back a settled response
+ * payload ready to return as JSON.
+ */
+declare function assembleResponseOutput(events: TangleSSEEvent[]): {
+  output: ResponseOutputItem[];
+  usage: ResponseUsage;
+};
+/**
+ * Fold every usage frame in a Tangle event sequence into a single
+ * ResponseUsage envelope. Multiple `done` events are tolerated (e.g.
+ * during retries) by summing.
+ */
+declare function usageFromEvents(events: TangleSSEEvent[]): ResponseUsage;
+declare class ResponsesValidationError extends Error {
+  readonly type = "invalid_request_error";
+  readonly code: string;
+  readonly param: string | undefined;
+  constructor(message: string, code: string, param?: string);
+}
+/**
+ * Reject Responses requests that ask for tool types Tangle cannot
+ * service. Function tools, the OpenAI computer-use preview tool, and
+ * the code interpreter (every Tangle sandbox can run code) are
+ * accepted; web_search and file_search are explicitly rejected with
+ * the OpenAI error shape.
+ */
+declare function validateResponsesRequest(req: ResponseCreateParamsBase): void;
+/**
+ * Build a settled `Response` shell from an aggregated output + usage.
+ * Caller fills in the runtime-specific fields (id, model, created_at,
+ * status, instructions, etc.) to avoid having to re-derive them inside
+ * the translator.
+ */
+declare function buildResponseShell(args: {
+  id: string;
+  model: string;
+  createdAt: number;
+  output: ResponseOutputItem[];
+  usage: ResponseUsage;
+  instructions?: string | null;
+  previousResponseId?: string | null;
+}): Response;
+//#endregion
+//#region src/openai/responses-store.d.ts
+declare class InMemoryResponseStore implements ResponseStore {
+  private readonly chains;
+  getPriorTurns(responseId: string): Promise<PriorTurn[] | null>;
+  putPriorTurns(responseId: string, priorTurns: PriorTurn[]): Promise<void>;
+  /** Convenience accessor for tests / debug; not part of `ResponseStore`. */
+  size(): number;
+  /** Drop a chain. */
+  delete(responseId: string): boolean;
+  /** Drop everything. Useful between test cases. */
+  clear(): void;
+}
+//#endregion
+//#region src/openai/runs.d.ts
+/**
+ * Tangle-internal run events surfaced to consumers of `Run.events()`.
+ * The low-level `runEvents()` iterator emits the raw sandbox event
+ * frames (`TangleSSEEvent`) directly; the high-level state machine
+ * wraps each frame in a typed envelope plus emits its own
+ * status-transition and tool-dispatch events for consumers that don't
+ * want to parse SSE shapes themselves.
+ */
+type RunEvent = {
+  type: "status";
+  status: RunStatus;
+  previous: RunStatus | null;
+} | {
+  type: "stream";
+  event: TangleSSEEvent;
+} | {
+  type: "tool_call";
+  ctx: ToolCallContext;
+} | {
+  type: "tool_result";
+  ctx: ToolCallContext;
+  result: ToolResult;
+} | {
+  type: "tool_blocked";
+  ctx: ToolCallContext;
+  reason: string;
+} | {
+  type: "requires_action";
+  pendingCallIds: string[];
+} | {
+  type: "completed";
+} | {
+  type: "failed";
+  reason: string;
+} | {
+  type: "cancelled";
+  reason?: string;
+};
+type RunStatus = "queued" | "in_progress" | "requires_action" | "completed" | "failed" | "cancelled" | "expired";
+/**
+ * Minimal interface the low-level `runEvents()` consumes. The route
+ * layer adapts the concrete `SandboxClient` SSE stream onto this
+ * surface so the Run executor stays decoupled from any specific HTTP
+ * shape. `cancel()` is best-effort — the source should stop producing
+ * events as soon as it observes a cancellation.
+ */
+interface RunEventSource {
+  open(threadId: string | undefined, runId: string): AsyncIterable<TangleSSEEvent>;
+  /** Optional: append a steer message and re-open the stream for the same run. */
+  steer?(threadId: string | undefined, runId: string, message: {
+    role: "user";
+    content: string;
+  }): Promise<void>;
+  /** Optional: submit tool outputs and resume from `requires_action`. */
+  submitToolOutputs?(threadId: string | undefined, runId: string, outputs: ToolOutput[]): Promise<void>;
+  /** Optional: server-side cancel hint. */
+  cancel?(threadId: string | undefined, runId: string): Promise<void>;
+}
+interface ToolOutput {
+  toolCallId: string;
+  output: ToolResult;
+}
+/**
+ * Pure async iterator over the underlying source. No state, no
+ * buffering. Iteration ends when the source closes or yields a
+ * terminal frame; the iterator itself does not classify frames.
+ */
+declare function runEvents(threadId: string | undefined, runId: string, source: RunEventSource): AsyncIterable<TangleSSEEvent>;
+interface RunOptions {
+  id: string;
+  threadId?: string;
+  partnerId: string;
+  source: RunEventSource;
+  hooks?: HookChain;
+  /** Caller-supplied tool executor. Required when the underlying stream
+   *  does not auto-execute tools server-side (the typical Tangle path). */
+  executeTool?: (ctx: ToolCallContext) => Promise<ToolResult>;
+  onStatusChange?: (status: RunStatus, previous: RunStatus | null) => void;
+}
+/**
+ * High-level `Run`. Drives the underlying `RunEventSource`, manages
+ * status transitions, dispatches tool calls through the hook chain,
+ * and surfaces a typed `RunEvent` stream to consumers.
+ */
+declare class Run {
+  readonly id: string;
+  readonly threadId: string | undefined;
+  readonly partnerId: string;
+  private _status;
+  private readonly source;
+  private readonly hooks;
+  private readonly executeTool;
+  private readonly onStatusChange;
+  private readonly queue;
+  private startPromise;
+  private pendingCalls;
+  private cancelRequested;
+  constructor(opts: RunOptions);
+  get status(): RunStatus;
+  /**
+   * Subscribe to typed events. May only be consumed once per Run.
+   *
+   * The single-consumer constraint is permanent for the lifetime of
+   * the Run instance, including AFTER the run completes — calling
+   * `events()` a second time always throws, even if the first
+   * consumer drained the iterator to completion. This is intentional:
+   * the queue is a one-shot stream, not a re-readable buffer, and
+   * events are dropped after delivery to avoid unbounded retention.
+   * Callers that need to revisit terminal state should keep a handle
+   * to the original iterator's drained values, or use the Run's
+   * status/result accessors.
+   */
+  events(): AsyncIterable<RunEvent>;
+  /**
+   * Drive the underlying stream to completion. Idempotent: subsequent
+   * calls return the same in-flight promise.
+   */
+  start(): Promise<void>;
+  /**
+   * Cancel an in-flight run. Sets status to `cancelled` and closes
+   * the event queue. Tries the source-level cancel hint as a
+   * best-effort heads-up to the upstream stream.
+   */
+  cancel(reason?: string): Promise<void>;
+  /**
+   * Append a user message to the thread and restart the stream. The
+   * source's `steer` hook is invoked when present; otherwise we throw
+   * because a stateless source cannot honor a steer.
+   */
+  steer(message: {
+    role: "user";
+    content: string;
+  }): Promise<void>;
+  /**
+   * Resume a `requires_action` run by submitting tool outputs. The
+   * outputs are forwarded to the source so the upstream agent can
+   * continue. Status transitions back to `in_progress`.
+   */
+  submitToolOutputs(outputs: ToolOutput[]): Promise<void>;
+  /** Externally drive the run into the `expired` terminal status. */
+  expire(): void;
+  private transition;
+  private driveStream;
+  private handleToolCall;
+}
+//#endregion
+//#region src/openai/translate/chunks.d.ts
+declare function sandboxEventToChatChunk(event: TangleSSEEvent, ctx: TranslatorContext): ChatCompletionChunk | null;
+declare function sandboxEventToCompletionChunk(event: TangleSSEEvent, ctx: TranslatorContext): Completion | null;
+declare function sandboxEventToResponsesEvent(event: TangleSSEEvent, ctx: TranslatorContext): ResponseStreamEvent | null;
+//#endregion
+//#region src/openai/translate/embeddings.d.ts
+type NormalizedEmbeddingInput = {
+  kind: "text";
+  values: string[];
+} | {
+  kind: "tokens";
+  values: number[][];
+};
+interface NormalizedEmbeddingRequest {
+  model: string;
+  input: NormalizedEmbeddingInput;
+  dimensions?: number;
+  encodingFormat: "float" | "base64";
+  user?: string;
+}
+/**
+ * Error shape used for rejecting embedding requests. The route layer
+ * lifts these into OpenAI's `{ error: { type, code, message } }` body.
+ */
+declare class EmbeddingValidationError extends Error {
+  readonly type = "invalid_request_error";
+  readonly code: string;
+  readonly param: string | undefined;
+  constructor(message: string, code: string, param?: string);
+}
+/**
+ * Validate and normalize an embedding request. Throws
+ * `EmbeddingValidationError` on any rejection.
+ */
+declare function validateEmbeddingRequest(req: EmbeddingCreateParams): NormalizedEmbeddingRequest;
+//#endregion
+//#region src/openai/translate/finish-reason.d.ts
+/**
+ * Map a Tangle outcome string + tool-call presence to an OpenAI
+ * `finish_reason`. Shared across chat / completions / responses
+ * translators so all three surfaces report the same termination reason
+ * for the same underlying outcome.
+ *
+ * Inputs:
+ *   - `outcome` is the Tangle terminal status (`success`, `failure`,
+ *     `length_exceeded`, `content_filtered`, `error`, `cancelled`, ...).
+ *   - `hasToolCall` is true when the run emitted at least one tool call
+ *     before terminating.
+ *
+ * Mapping:
+ *   - `success` + tool_call → `tool_calls` (model handed control back).
+ *   - `success`             → `stop`.
+ *   - `length_exceeded`     → `length`.
+ *   - `content_filtered`    → `content_filter`.
+ *   - everything else       → `stop` (route layer surfaces the error).
+ */
+type OpenAIFinishReason = "stop" | "length" | "tool_calls" | "content_filter";
+declare function outcomeToFinishReason(outcome: string, hasToolCall: boolean): OpenAIFinishReason;
+//#endregion
+//#region src/openai/translate/messages.d.ts
+/**
+ * Translate an OpenAI chat-shape message thread into a SandboxRunInput.
+ *
+ * @param messages  Ordered messages as the OpenAI client would send them.
+ * @param tools     Optional function tool descriptors to forward unchanged.
+ * @param model     Caller-supplied model id (`tangle/<provider>[/<variant>]`).
+ *
+ * @throws when the resolved provider id is empty, when the message thread
+ *         lacks any user message, or when an `assistant` `tool_calls` item
+ *         is malformed (missing id/name/arguments).
+ */
+declare function openaiMessagesToSandboxInput(messages: ChatCompletionMessageParam[], tools: ChatCompletionTool[] | undefined, model: string): SandboxRunInput;
+//#endregion
+export { type ActionRateLimitOptions, type AfterHookOutcome, type AuditEvent, type AuditLogOptions, type BeforeHookOutcome, type BufferedToolCall, type CostCapOptions, type DestructiveActionGuardOptions, type EgressPolicyOptions, EmbeddingValidationError, HookChain, type HookSurface, InMemoryResponseStore, type MultimodalPart, type NormalizedEmbeddingInput, type NormalizedEmbeddingRequest, type OpenAIFinishReason, type PriorToolCall, type PriorToolResult, type PriorTurn, type RedactionRegion, type ResponseStore, ResponsesValidationError, Run, type RunEvent, type RunEventSource, type RunOptions, type RunStatus, type SandboxRunInput, type SandboxToolSpec, type ScreenshotRedactionOptions, type TangleSSEEvent, type ToolCallContext, type ToolOutput, type ToolResult, type TranslatorContext, actionRateLimitHook, assembleResponseOutput, auditLogHook, buildResponseShell, costCapHook, createTranslatorContext, destructiveActionGuardHook, egressPolicyHook, openaiMessagesToSandboxInput, outcomeToFinishReason, resolvePreviousResponseId, runEvents, sandboxEventToChatChunk, sandboxEventToCompletionChunk, sandboxEventToResponsesEvent, screenshotRedactionHook, usageFromEvents, validateEmbeddingRequest, validateResponsesRequest };