@ai-sdk/harness 0.0.0 → 1.0.0-canary.3

package/src/v1/harness-v1-bridge-protocol.ts

@@ -0,0 +1,310 @@
+import { z } from 'zod/v4';
+import {
+  harnessV1DebugConfigSchema,
+  harnessV1DebugLevelSchema,
+  type HarnessV1Diagnostic,
+} from './harness-v1-diagnostic';
+import {
+  harnessV1CompactionPartSchema,
+  harnessV1ErrorPartSchema,
+  harnessV1FileChangePartSchema,
+  harnessV1FinishPartSchema,
+  harnessV1FinishStepPartSchema,
+  harnessV1RawPartSchema,
+  harnessV1ReasoningDeltaPartSchema,
+  harnessV1ReasoningEndPartSchema,
+  harnessV1ReasoningStartPartSchema,
+  harnessV1StreamStartPartSchema,
+  harnessV1TextDeltaPartSchema,
+  harnessV1TextEndPartSchema,
+  harnessV1TextStartPartSchema,
+  harnessV1ToolApprovalRequestPartSchema,
+  harnessV1ToolCallPartSchema,
+  harnessV1ToolResultPartSchema,
+} from './harness-v1-stream-part';
+
+/*
+ * The bridge wire protocol shared by every bridge-backed harness adapter.
+ *
+ * This is the serialization of the host<->runtime contract for adapters that
+ * run the agent runtime inside the sandbox and talk to the host over a
+ * WebSocket. It exists ONLY because of that transport: untrusted JSON frames
+ * crossing the sandbox boundary need runtime validation, the connection needs
+ * a handshake, and the host drives turns with serialized commands. Every export
+ * here is therefore prefixed `harnessV1Bridge…`.
+ *
+ * It has three tiers:
+ *
+ *  1. The OUTBOUND events — `HarnessV1StreamPart` re-expressed as Zod (imported
+ *     member schemas from `harness-v1-stream-part.ts`), because the part type is
+ *     compile-time only and the frames need runtime validation at the boundary.
+ *  2. The transport/control frames that are NOT consumer events — `bridge-hello`
+ *     (handshake), `bridge-detach` (resume payload), `bridge-thread` (a resume
+ *     coordinate some runtimes announce). These ride the same socket.
+ *  3. The INBOUND command vocabulary the host sends back: the shared commands
+ *     live here; the per-adapter `start` payload extends
+ *     `harnessV1BridgeStartBaseSchema` and assembles the final inbound union in
+ *     the adapter package.
+ *
+ * Non-bridge adapters (e.g. Pi) do not use this layer at all — they have no
+ * serialization boundary and target the universal `HarnessV1StreamPart` type
+ * directly. That is the deliberate split: `harness-v1-stream-part.ts` is the
+ * transport-agnostic event vocabulary; this file is the bridge transport.
+ */
+
+/**
+ * The subset of a host-defined tool that travels on the `start` message. The
+ * runtime only needs the name, description, and JSON-Schema input to surface
+ * the tool; `execute` stays on the host.
+ */
+export const harnessV1BridgeToolWireSchema = z.object({
+  name: z.string(),
+  description: z.string().optional(),
+  inputSchema: z.unknown().optional(),
+});
+
+export type HarnessV1BridgeToolWire = z.infer<
+  typeof harnessV1BridgeToolWireSchema
+>;
+
+export const harnessV1BridgePermissionModeSchema = z.enum([
+  'allow-reads',
+  'allow-edits',
+  'allow-all',
+]);
+
+/**
+ * Common fields of the inbound `start` message. Each adapter extends this with
+ * its runtime-specific configuration (e.g. `thinking`/`continue` for Claude
+ * Code, `reasoningEffort`/`webSearch`/`skills`/`resumeThreadId` for Codex) and
+ * assembles the final inbound union from the shared command members below.
+ *
+ * `debug` carries the general `HarnessV1DebugConfig` — diagnostics config is not
+ * a bridge concept, it just happens to ride the `start` frame for bridge-backed
+ * adapters.
+ */
+export const harnessV1BridgeStartBaseSchema = z.object({
+  type: z.literal('start'),
+  prompt: z.string(),
+  tools: z.array(harnessV1BridgeToolWireSchema).optional(),
+  model: z.string().optional(),
+  debug: harnessV1DebugConfigSchema.optional(),
+  permissionMode: harnessV1BridgePermissionModeSchema.optional(),
+});
+
+// --- Transport / control frames (outbound, not consumer events) ---
+
+/**
+ * Sent the instant the bridge accepts an authenticated WS connection. The host
+ * waits for it before sending `start`/`resume`, because some sandbox runtimes
+ * complete the upstream WS handshake before the connection is wired through to
+ * the bridge process — anything sent in that gap is dropped. Carries the
+ * bridge's lifecycle `state` and highest emitted `seq` for reconnect.
+ */
+export const harnessV1BridgeHelloSchema = z.object({
+  type: z.literal('bridge-hello'),
+  state: z.string().optional(),
+  lastSeq: z.number().optional(),
+});
+
+/**
+ * The bridge's reply to an inbound `detach`. Carries the adapter-specific
+ * payload the host serializes into `HarnessV1ResumeState`.
+ */
+export const harnessV1BridgeDetachSchema = z.object({
+  type: z.literal('bridge-detach'),
+  data: z.unknown(),
+});
+
+/**
+ * A resume coordinate the bridge proactively announces (e.g. Codex's thread id)
+ * so the host can cache it for a later resume without waiting for `detach`.
+ */
+export const harnessV1BridgeThreadSchema = z.object({
+  type: z.literal('bridge-thread'),
+  threadId: z.string(),
+});
+
+// --- Diagnostics frames (outbound, not consumer events) ---
+
+/**
+ * One captured console line from inside the sandbox. The bridge line-buffers
+ * `process.stdout`/`process.stderr` and emits one of these per complete line.
+ * Routed host-side to the diagnostics sink, never to the consumer stream.
+ */
+export const harnessV1BridgeSandboxLogSchema = z.object({
+  type: z.literal('sandbox-log'),
+  source: z.string(),
+  stream: z.enum(['stdout', 'stderr']),
+  line: z.string(),
+});
+
+/**
+ * A structured diagnostic an adapter emits from inside the bridge via
+ * `turn.bridgeLog(...)`. Gated by the session's debug level + subsystem filter.
+ */
+export const harnessV1BridgeDebugEventSchema = z.object({
+  type: z.literal('debug-event'),
+  level: harnessV1DebugLevelSchema,
+  subsystem: z.string(),
+  message: z.string(),
+  attrs: z.record(z.string(), z.unknown()).optional(),
+  error: z
+    .object({
+      name: z.string().optional(),
+      message: z.string(),
+      stack: z.string().optional(),
+    })
+    .optional(),
+});
+
+/**
+ * Every frame a bridge can send to the host: the stream-part events plus the
+ * transport/control frames. This is the schema the host `SandboxChannel`
+ * validates inbound frames against.
+ */
+export const harnessV1BridgeOutboundMessageSchema = z.discriminatedUnion(
+  'type',
+  [
+    harnessV1StreamStartPartSchema,
+    harnessV1TextStartPartSchema,
+    harnessV1TextDeltaPartSchema,
+    harnessV1TextEndPartSchema,
+    harnessV1ReasoningStartPartSchema,
+    harnessV1ReasoningDeltaPartSchema,
+    harnessV1ReasoningEndPartSchema,
+    harnessV1ToolCallPartSchema,
+    harnessV1ToolApprovalRequestPartSchema,
+    harnessV1ToolResultPartSchema,
+    harnessV1FinishStepPartSchema,
+    harnessV1FinishPartSchema,
+    harnessV1FileChangePartSchema,
+    harnessV1CompactionPartSchema,
+    harnessV1ErrorPartSchema,
+    harnessV1RawPartSchema,
+    harnessV1BridgeHelloSchema,
+    harnessV1BridgeDetachSchema,
+    harnessV1BridgeThreadSchema,
+    harnessV1BridgeSandboxLogSchema,
+    harnessV1BridgeDebugEventSchema,
+  ],
+);
+
+export type HarnessV1BridgeOutboundMessage = z.infer<
+  typeof harnessV1BridgeOutboundMessageSchema
+>;
+
+export type HarnessV1BridgeSandboxLog = z.infer<
+  typeof harnessV1BridgeSandboxLogSchema
+>;
+
+export type HarnessV1BridgeDebugEvent = z.infer<
+  typeof harnessV1BridgeDebugEventSchema
+>;
+
+/**
+ * Normalize a bridge diagnostics wire frame into the transport-agnostic
+ * `HarnessV1Diagnostic` an adapter reports to the framework. A captured console
+ * line maps `stderr` → `warn` and `stdout` → `info`; a structured event passes
+ * its fields through. This is the seam where the bridge's serialization is
+ * lifted into the general emission shape every harness shares.
+ */
+export function harnessV1DiagnosticFromBridgeFrame(
+  frame: HarnessV1BridgeSandboxLog | HarnessV1BridgeDebugEvent,
+  context: { sessionId?: string; timestamp: number },
+): HarnessV1Diagnostic {
+  if (frame.type === 'sandbox-log') {
+    return {
+      level: frame.stream === 'stderr' ? 'warn' : 'info',
+      message: frame.line,
+      subsystem: `sandbox.log.${frame.source}`,
+      kind: 'log',
+      source: frame.source,
+      stream: frame.stream,
+      sessionId: context.sessionId,
+      timestamp: context.timestamp,
+    };
+  }
+  return {
+    level: frame.level,
+    message: frame.message,
+    subsystem: frame.subsystem,
+    kind: 'event',
+    attrs: frame.attrs,
+    error: frame.error,
+    sessionId: context.sessionId,
+    timestamp: context.timestamp,
+  };
+}
+
+// --- Shared inbound command members (host -> bridge) ---
+
+export const harnessV1BridgeToolResultInboundSchema = z.object({
+  type: z.literal('tool-result'),
+  toolCallId: z.string(),
+  output: z.unknown(),
+  isError: z.boolean().optional(),
+});
+
+export const harnessV1BridgeToolApprovalResponseInboundSchema = z.object({
+  type: z.literal('tool-approval-response'),
+  approvalId: z.string(),
+  approved: z.boolean(),
+  reason: z.string().optional(),
+});
+
+export const harnessV1BridgeUserMessageInboundSchema = z.object({
+  type: z.literal('user-message'),
+  text: z.string(),
+});
+
+export const harnessV1BridgeAbortInboundSchema = z.object({
+  type: z.literal('abort'),
+});
+
+export const harnessV1BridgeShutdownInboundSchema = z.object({
+  type: z.literal('shutdown'),
+});
+
+/**
+ * Reconnect: after re-establishing the socket the host asks the bridge to
+ * replay every buffered event with `seq > lastSeenEventId`.
+ */
+export const harnessV1BridgeResumeInboundSchema = z.object({
+  type: z.literal('resume'),
+  lastSeenEventId: z.number(),
+});
+
+/**
+ * The bridge replies with `bridge-detach` carrying any cached resume payload,
+ * then exits.
+ */
+export const harnessV1BridgeDetachInboundSchema = z.object({
+  type: z.literal('detach'),
+});
+
+/**
+ * The inbound command members shared by every bridge adapter. Spread these
+ * alongside the adapter's own `start` schema to build the final inbound union:
+ * `z.discriminatedUnion('type', [adapterStartSchema, ...harnessV1BridgeInboundCommandSchemas])`.
+ */
+export const harnessV1BridgeInboundCommandSchemas = [
+  harnessV1BridgeToolResultInboundSchema,
+  harnessV1BridgeToolApprovalResponseInboundSchema,
+  harnessV1BridgeUserMessageInboundSchema,
+  harnessV1BridgeAbortInboundSchema,
+  harnessV1BridgeShutdownInboundSchema,
+  harnessV1BridgeResumeInboundSchema,
+  harnessV1BridgeDetachInboundSchema,
+] as const;
+
+/**
+ * The JSON line the bridge writes to stdout once its WebSocket server is bound,
+ * announcing the port the host should connect to.
+ */
+export const harnessV1BridgeReadySchema = z.object({
+  type: z.literal('bridge-ready'),
+  port: z.number(),
+});
+
+export type HarnessV1BridgeReady = z.infer<typeof harnessV1BridgeReadySchema>;

package/src/v1/harness-v1-builtin-tool.ts

@@ -0,0 +1,138 @@
+import { tool, type FlexibleSchema, type Tool } from '@ai-sdk/provider-utils';
+import { z } from 'zod';
+
+/**
+ * Cross-harness vocabulary of common built-in tool names with their baseline
+ * input schemas. Adapters that declare a built-in with one of these
+ * `commonName`s must accept (at least) every input the baseline schema
+ * accepts. Extra optional fields are encouraged.
+ *
+ * Used both as runtime values (spread into `ToolSet`s for inspection) and as
+ * a vocabulary source — `HarnessV1BuiltinToolName` is derived from its keys.
+ */
+export const HARNESS_V1_BUILTIN_TOOLS = {
+  read: tool({
+    description: 'Read file contents',
+    inputSchema: z.object({ file_path: z.string() }),
+    outputSchema: z.unknown(),
+  }),
+  write: tool({
+    description: 'Write content to a file',
+    inputSchema: z.object({ file_path: z.string(), content: z.string() }),
+    outputSchema: z.unknown(),
+  }),
+  edit: tool({
+    description: 'Edit a file by replacing text',
+    inputSchema: z.object({
+      file_path: z.string(),
+      old_string: z.string(),
+      new_string: z.string(),
+    }),
+    outputSchema: z.unknown(),
+  }),
+  bash: tool({
+    description: 'Execute a shell command',
+    inputSchema: z.object({ command: z.string() }),
+    outputSchema: z.unknown(),
+  }),
+  grep: tool({
+    description: 'Search file contents with regex',
+    inputSchema: z.object({ pattern: z.string() }),
+    outputSchema: z.unknown(),
+  }),
+  glob: tool({
+    description: 'Find files matching a glob pattern',
+    inputSchema: z.object({ pattern: z.string() }),
+    outputSchema: z.unknown(),
+  }),
+  webSearch: tool({
+    description: 'Search the web',
+    inputSchema: z.object({ query: z.string() }),
+    outputSchema: z.unknown(),
+  }),
+} as const;
+
+export type HarnessV1BuiltinToolName = keyof typeof HARNESS_V1_BUILTIN_TOOLS;
+
+export const HARNESS_V1_BUILTIN_TOOL_NAMES = Object.keys(
+  HARNESS_V1_BUILTIN_TOOLS,
+) as ReadonlyArray<HarnessV1BuiltinToolName>;
+
+export type HarnessV1BuiltinToolUseKind = 'readonly' | 'edit' | 'bash';
+
+/**
+ * A tool that the adapter's underlying runtime exposes natively. Extends the
+ * AI SDK `Tool` shape with two optional harness-specific fields:
+ *
+ *  - `nativeName`: the name as the underlying runtime knows it. Required
+ *    only when the tool's key in the harness's `builtinTools` is not the
+ *    native name — i.e. when the tool maps to a `commonName` (e.g. key
+ *    `'bash'` for Claude Code's native `'Bash'`). Tools without a common
+ *    equivalent are keyed by their native name directly, so `nativeName`
+ *    is redundant and omitted.
+ *  - `commonName`: cross-harness label drawn from
+ *    `HARNESS_V1_BUILTIN_TOOL_NAMES`. Set when the tool maps to a familiar
+ *    capability; consumers use it to recognize, e.g., that Claude Code's
+ *    `Bash` and Codex's `shell` are the same kind of tool.
+ *
+ * Always set both fields together via the `commonTool` helper, or neither
+ * (declare the tool with the AI SDK's `tool()` directly).
+ */
+export type HarnessV1BuiltinTool<INPUT = unknown, OUTPUT = unknown> = Tool<
+  INPUT,
+  OUTPUT,
+  any
+> & {
+  readonly nativeName?: string;
+  readonly commonName?: HarnessV1BuiltinToolName;
+  readonly toolUseKind?: HarnessV1BuiltinToolUseKind;
+};
+
+type InputOf<T> = T extends Tool<infer I, any, any> ? I : never;
+
+type StandardInputOf<N extends HarnessV1BuiltinToolName> = InputOf<
+  (typeof HARNESS_V1_BUILTIN_TOOLS)[N]
+>;
+
+/*
+ * Type-level superset check. If `TStandard` is assignable to `TAdapter`
+ * (i.e. the adapter accepts every input the standard accepts), the return
+ * type is `TOk`. Otherwise it's a tagged error tuple that surfaces a clear
+ * TypeScript error at the call site.
+ */
+type SupersetCheck<TStandard, TAdapter, TOk> = TStandard extends TAdapter
+  ? TOk
+  : [
+      'ERROR: adapter input schema must be a superset of the standard schema',
+      { expected: TStandard; got: TAdapter },
+    ];
+
+/**
+ * Declare a built-in tool that maps to a cross-harness common name. The
+ * adapter's input schema must accept every input the standard schema for
+ * `commonName` accepts. Extra optional fields are encouraged.
+ *
+ * If the schema is missing a field the standard requires (or has an
+ * incompatible type), the return type collapses to a tagged error tuple,
+ * which fails the surrounding `as const satisfies ToolSet` assignment and
+ * surfaces a readable TypeScript error at the offending entry.
+ */
+export function commonTool<TName extends HarnessV1BuiltinToolName, TInput>(
+  commonName: TName,
+  opts: {
+    readonly nativeName: string;
+    readonly toolUseKind?: HarnessV1BuiltinToolUseKind;
+    readonly description?: string;
+    readonly inputSchema: FlexibleSchema<TInput>;
+  },
+): SupersetCheck<StandardInputOf<TName>, TInput, HarnessV1BuiltinTool<TInput>> {
+  return {
+    ...tool({
+      description: opts.description,
+      inputSchema: opts.inputSchema as FlexibleSchema<TInput>,
+    }),
+    nativeName: opts.nativeName,
+    commonName,
+    toolUseKind: opts.toolUseKind,
+  } as never;
+}

package/src/v1/harness-v1-call-warning.ts

@@ -0,0 +1,22 @@
+/**
+ * Warning emitted by a harness adapter during a call.
+ *
+ * Surfaces non-fatal issues such as unsupported options or quirks of the
+ * underlying agent runtime. Mirrors the shape of `SharedV4Warning` but lives
+ * in the harness namespace.
+ */
+export type HarnessV1CallWarning =
+  | {
+      type: 'unsupported-setting';
+      setting: string;
+      details?: string;
+    }
+  | {
+      type: 'unsupported-tool';
+      tool: string;
+      details?: string;
+    }
+  | {
+      type: 'other';
+      message: string;
+    };

package/src/v1/harness-v1-diagnostic.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod/v4';
+
+/*
+ * Diagnostics EMISSION contract — part of the `HarnessV1` spec.
+ *
+ * These are the types a harness adapter produces and receives: an adapter
+ * reports a `HarnessV1Diagnostic` to the framework (a bridge adapter normalizes
+ * its wire frames into one; a non-bridge adapter constructs one directly), and
+ * receives a `HarnessV1DebugConfig` to gate what it emits. They are distinct
+ * from the unaffixed host-facing `HarnessDiagnostic` / `HarnessDebugConfig`
+ * (the external/telemetry surface) — the framework maps between the two at the
+ * boundary, so the emission and consumption surfaces can evolve independently.
+ */
+
+/** Severity of a diagnostic, ordered most → least severe. */
+export const harnessV1DebugLevelSchema = z.enum([
+  'error',
+  'warn',
+  'info',
+  'debug',
+  'trace',
+]);
+
+export type HarnessV1DebugLevel = z.infer<typeof harnessV1DebugLevelSchema>;
+
+/**
+ * Per-session diagnostics configuration the framework hands an adapter (and the
+ * host sends on `start.debug`). When absent or `enabled` is false the adapter
+ * captures and emits nothing. `subsystems` filters structured events by dotted
+ * prefix; console capture is independent of the subsystem filter.
+ */
+export const harnessV1DebugConfigSchema = z.object({
+  enabled: z.boolean().optional(),
+  level: harnessV1DebugLevelSchema.optional(),
+  subsystems: z.array(z.string()).optional(),
+});
+
+export type HarnessV1DebugConfig = z.infer<typeof harnessV1DebugConfigSchema>;
+
+/**
+ * A diagnostic as emitted by a harness adapter. Structurally identical to the
+ * host-facing `HarnessDiagnostic` today, but kept separate: this is the spec's
+ * emission shape, that is the external consumption shape.
+ */
+export type HarnessV1Diagnostic = {
+  /** Severity. */
+  readonly level: HarnessV1DebugLevel;
+  /** Human-readable line (console capture) or message (structured event). */
+  readonly message: string;
+  /** Dotted subsystem (`sandbox.log.<source>` for console capture). */
+  readonly subsystem: string;
+  /** `'log'` = captured console line; `'event'` = structured emission. */
+  readonly kind: 'log' | 'event';
+  /** Originating source label (console capture). */
+  readonly source?: string;
+  /** Which standard stream the line came from (console capture). */
+  readonly stream?: 'stdout' | 'stderr';
+  /** Structured attributes (structured events only). */
+  readonly attrs?: Record<string, unknown>;
+  /** Error payload (structured events only). */
+  readonly error?: { name?: string; message: string; stack?: string };
+  /** The harness session this diagnostic originated from. */
+  readonly sessionId?: string;
+  /** Emission time (epoch ms). */
+  readonly timestamp: number;
+};

package/src/v1/harness-v1-metadata.ts

@@ -0,0 +1,13 @@
+import type { JSONValue } from '@ai-sdk/provider';
+
+/**
+ * Adapter-namespaced opaque data attached to harness events.
+ *
+ * Mirrors the `providerMetadata` pattern from `@ai-sdk/provider`, but lives
+ * in the harness namespace because a harness is a peer concept to a
+ * provider, not a kind of provider.
+ *
+ * Keys are harness ids (e.g. `'claude-code'`). Inner values are arbitrary
+ * JSON-serializable data the adapter chooses to surface to callers.
+ */
+export type HarnessV1Metadata = Record<string, Record<string, JSONValue>>;

package/src/v1/harness-v1-network-sandbox-session.ts

@@ -0,0 +1,123 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+
+/**
+ * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. The
+ * harness keeps this for the lifetime of a session. It is itself a
+ * {@link SandboxSession} (file I/O, exec, spawn) and adds the infra surface on
+ * top: port resolution, lifecycle, and network-policy mutation.
+ *
+ * Code that should only touch the filesystem and spawn processes receives the
+ * reduced view from {@link HarnessV1NetworkSandboxSession.restricted}, never the
+ * network sandbox session itself — so it cannot stop the sandbox or change its
+ * network policy.
+ */
+export interface HarnessV1NetworkSandboxSession extends SandboxSession {
+  /**
+   * Stable identifier for the underlying sandbox resource. Used by the
+   * harness session manager as the durable lookup key for cross-process
+   * resume — the framework persists this on the resume payload so a future
+   * process can call `HarnessV1SandboxProvider.resume?({ sessionId })` and
+   * reach the same resource. Providers populate it from their native
+   * identifier (Vercel: the sandbox name; just-bash: a UUID minted at
+   * create time).
+   */
+  readonly id: string;
+
+  /**
+   * The sandbox's default working directory — the absolute path that
+   * `run`/`spawn` resolve relative commands against when no `workingDirectory`
+   * is given. Read from the live sandbox (it is provider-specific and
+   * configurable at create time: Vercel defaults to `/vercel/sandbox`,
+   * just-bash to `/home/user`), never hardcoded.
+   *
+   * The framework composes each session's working directory underneath this
+   * path (`<defaultWorkingDirectory>/<harnessId>-<sessionId>`) so adapters do
+   * not bake a provider-specific base into their own paths.
+   */
+  readonly defaultWorkingDirectory: string;
+
+  /** Ports the sandbox exposes; resolvable to public URLs via `getPortUrl`. */
+  readonly ports: ReadonlyArray<number>;
+
+  /**
+   * Resolve a publicly-reachable URL for a sandbox-exposed port. Bridge-backed
+   * adapters call this to open their WebSocket to the in-sandbox bridge.
+   */
+  readonly getPortUrl: (options: {
+    port: number;
+    protocol?: 'http' | 'https' | 'ws';
+  }) => PromiseLike<string>;
+
+  /** Stop the sandbox. Idempotent. */
+  readonly stop: () => PromiseLike<void>;
+
+  /**
+   * Destroy/delete the sandbox resource when supported. Optional because some
+   * providers only have a stop/dispose concept. Implementations must handle
+   * both a still-running sandbox and a previously stopped sandbox.
+   */
+  readonly destroy?: () => PromiseLike<void>;
+
+  /**
+   * Update the sandbox's outbound network policy. Optional — implementations
+   * without a local enforcement primitive (e.g. just-bash) omit this. Callers
+   * use optional-call (`sandboxSession.setNetworkPolicy?.(policy)`); a
+   * missing implementation is a no-op.
+   */
+  readonly setNetworkPolicy?: (
+    policy: HarnessV1NetworkPolicy,
+  ) => PromiseLike<void>;
+
+  /**
+   * Replace the set of ports exposed by the sandbox. Full-replacement
+   * semantics: ports omitted from the array are deregistered. Optional —
+   * implementations that cannot expose ports (e.g. just-bash) omit this.
+   */
+  readonly setPorts?: (
+    ports: ReadonlyArray<number>,
+    options?: { abortSignal?: AbortSignal },
+  ) => PromiseLike<void>;
+
+  /**
+   * Reduced view of this session, typed as the bare {@link SandboxSession}
+   * (file I/O, exec, spawn) — nothing that could stop the sandbox or change
+   * its network policy. Pass this to user-tool `execute()` calls and other
+   * code that must not reach the infra surface.
+   *
+   * The returned object points at exactly the same underlying sandbox
+   * resource as the network sandbox session it was produced from; it is only a
+   * narrower surface over the same resource, not a separate sandbox.
+   */
+  readonly restricted: () => SandboxSession;
+}
+
+/**
+ * Outbound network policy applied by the sandbox runtime.
+ *
+ * `'allow-all'` and `'deny-all'` are convenience presets. `'custom'` is an
+ * allow-list with an optional CIDR deny-list that takes precedence:
+ *
+ * - Reachable hosts are the union of `allowedHosts` and `allowedCIDRs`.
+ * - `deniedCIDRs` wins over both, useful for blocking cloud-metadata IPs while
+ *   otherwise allowing broad access.
+ *
+ * The two `'custom'` branches share the same discriminator but each requires
+ * a different allow field. Specifying `'custom'` with only `deniedCIDRs`
+ * (deny-only) is rejected at compile time — functionally it would be
+ * equivalent to `'deny-all'`.
+ */
+export type HarnessV1NetworkPolicy =
+  | { mode: 'allow-all' }
+  | { mode: 'deny-all' }
+  | {
+      mode: 'custom';
+      allowedHosts: ReadonlyArray<string>;
+      allowedCIDRs?: ReadonlyArray<string>;
+      deniedCIDRs?: ReadonlyArray<string>;
+    }
+  | {
+      mode: 'custom';
+      allowedHosts?: ReadonlyArray<string>;
+      allowedCIDRs: ReadonlyArray<string>;
+      deniedCIDRs?: ReadonlyArray<string>;
+    };

package/src/v1/harness-v1-observability.ts

@@ -0,0 +1,20 @@
+import type {
+  HarnessV1DebugConfig,
+  HarnessV1Diagnostic,
+} from './harness-v1-diagnostic';
+
+/**
+ * Diagnostics wiring the framework hands to an adapter's `doStart`. `report` is
+ * the general emission sink: a bridge adapter normalizes each wire frame into a
+ * `HarnessV1Diagnostic` (via `harnessV1DiagnosticFromBridgeFrame`) and calls it;
+ * a non-bridge adapter constructs a `HarnessV1Diagnostic` from its host-side
+ * logs/errors and calls it directly. `debug` gates what the adapter emits.
+ * Absent when the consumer has not enabled diagnostics.
+ */
+export type HarnessV1Observability = {
+  /** Per-session debug config gating what the adapter captures/emits. */
+  readonly debug?: HarnessV1DebugConfig;
+
+  /** General emission sink — any adapter reports a `HarnessV1Diagnostic` here. */
+  readonly report?: (diagnostic: HarnessV1Diagnostic) => void;
+};