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

package/src/agent/harness-agent-session.ts

@@ -0,0 +1,352 @@
+import type {
+  HarnessV1,
+  HarnessV1NetworkSandboxSession,
+  HarnessV1PendingToolApproval,
+  HarnessV1Prompt,
+  HarnessV1ResumeState,
+  HarnessV1SandboxProvider,
+  HarnessV1Session,
+  HarnessV1ToolSpec,
+} from '../v1';
+import type { Context, ToolSet } from '@ai-sdk/provider-utils';
+import type { TelemetryOptions } from 'ai';
+import type { HarnessAgentToolApprovalConfiguration } from './harness-agent-settings';
+import type { HarnessAgentToolApprovalContinuation } from './harness-agent-tool-approval-continuation';
+import { releaseBridgePort } from './internal/bridge-port-registry';
+import { validateResumeStateData } from './internal/resume-state-validation';
+import { runPrompt } from './internal/run-prompt';
+
+/**
+ * Live harness session held by the caller.
+ *
+ * Created by {@link import('./harness-agent').HarnessAgent.createSession}.
+ * Owns the underlying `HarnessV1Session`, the network sandbox session, and the
+ * bridge-port lease (when the provider wraps a caller-provided sandbox with a
+ * port pool).
+ *
+ * Pass the instance back to `agent.generate` / `agent.stream` on every
+ * call; end the local handle with `detach()`, `stop()`, or `destroy()`.
+ *
+ * After any lifecycle method has resolved, the session is unusable — any
+ * subsequent `generate`/`stream` call against it throws.
+ */
+export class HarnessAgentSession {
+  /**
+   * Stable identifier the harness adapter saw in `doStart`. The same
+   * string callers persist when they intend to resume the session in a
+   * future process.
+   */
+  readonly sessionId: string;
+
+  private readonly harness: HarnessV1;
+  private readonly sandboxProvider: HarnessV1SandboxProvider;
+  private readonly sessionWorkDir: string;
+  private underlyingSession: HarnessV1Session | undefined;
+  private sandboxSession: HarnessV1NetworkSandboxSession | undefined;
+  private leasedBridgePort: number | undefined;
+  private readonly toolApproval:
+    | HarnessAgentToolApprovalConfiguration
+    | undefined;
+  private readonly pendingToolApprovals = new Map<
+    string,
+    HarnessV1PendingToolApproval
+  >();
+  private stopped = false;
+
+  /**
+   * Whether this session was created from a resume payload. Captured at
+   * construction so it survives lifecycle cleanup.
+   */
+  readonly isResume: boolean;
+
+  constructor(options: {
+    sessionId: string;
+    harness: HarnessV1;
+    underlyingSession: HarnessV1Session;
+    sandboxSession: HarnessV1NetworkSandboxSession;
+    sandboxProvider: HarnessV1SandboxProvider;
+    leasedBridgePort?: number;
+    sessionWorkDir: string;
+    toolApproval: HarnessAgentToolApprovalConfiguration | undefined;
+    pendingToolApprovals?: readonly HarnessV1PendingToolApproval[];
+  }) {
+    this.sessionId = options.sessionId;
+    this.harness = options.harness;
+    this.underlyingSession = options.underlyingSession;
+    this.sandboxSession = options.sandboxSession;
+    this.sandboxProvider = options.sandboxProvider;
+    this.leasedBridgePort = options.leasedBridgePort;
+    this.sessionWorkDir = options.sessionWorkDir;
+    this.toolApproval = options.toolApproval;
+    for (const approval of options.pendingToolApprovals ?? []) {
+      this.pendingToolApprovals.set(approval.approvalId, approval);
+    }
+    this.isResume = options.underlyingSession.isResume;
+  }
+
+  /**
+   * Active network sandbox session.
+   *
+   * @internal — accessed by session turn and lifecycle drivers.
+   */
+  getSandboxSession(): HarnessV1NetworkSandboxSession {
+    if (this.stopped || this.sandboxSession == null) {
+      throw new Error(
+        `Harness session ${this.sessionId} has ended and cannot be reused.`,
+      );
+    }
+    return this.sandboxSession;
+  }
+
+  /**
+   * Working directory the agent runs in for this session. Used to strip the
+   * prefix from absolute paths in stream events before they reach consumers.
+   *
+   * @internal — accessed by session turn drivers.
+   */
+  getSessionWorkDir(): string {
+    return this.sessionWorkDir;
+  }
+
+  promptTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
+    prompt: HarnessV1Prompt;
+    instructions: string | undefined;
+    tools: TOOLS;
+    toolSpecs: HarnessV1ToolSpec[];
+    runtimeContext: RUNTIME_CONTEXT;
+    abortSignal: AbortSignal | undefined;
+    telemetry: TelemetryOptions | undefined;
+  }): ReturnType<typeof runPrompt<TOOLS, RUNTIME_CONTEXT>> {
+    const session = this.requireReusableSession();
+    if (this.pendingToolApprovals.size > 0) {
+      throw new Error(
+        `Harness session ${this.sessionId} has pending tool approvals and must be continued with approval responses before accepting a new prompt.`,
+      );
+    }
+    const sandboxSession = this.getSandboxSession();
+    return runPrompt<TOOLS, RUNTIME_CONTEXT>({
+      harness: this.harness,
+      session,
+      prompt: options.prompt,
+      instructions: options.instructions,
+      tools: options.tools,
+      toolSpecs: options.toolSpecs,
+      sandboxSession: sandboxSession.restricted(),
+      sessionWorkDir: this.sessionWorkDir,
+      runtimeContext: options.runtimeContext,
+      abortSignal: options.abortSignal,
+      telemetry: options.telemetry,
+      toolApproval: this.toolApproval,
+      pendingToolApprovals: this.getPendingToolApprovals(),
+      onPendingToolApproval: approval => {
+        this.pendingToolApprovals.set(approval.approvalId, approval);
+      },
+      onToolApprovalSettled: approvalId => {
+        this.pendingToolApprovals.delete(approvalId);
+      },
+    });
+  }
+
+  continueTurn<
+    TOOLS extends ToolSet,
+    RUNTIME_CONTEXT extends Context,
+  >(options: {
+    instructions: string | undefined;
+    tools: TOOLS;
+    toolSpecs: HarnessV1ToolSpec[];
+    runtimeContext: RUNTIME_CONTEXT;
+    abortSignal: AbortSignal | undefined;
+    telemetry: TelemetryOptions | undefined;
+    toolApprovalContinuations?:
+      | readonly HarnessAgentToolApprovalContinuation[]
+      | undefined;
+  }): ReturnType<typeof runPrompt<TOOLS, RUNTIME_CONTEXT>> {
+    const session = this.requireReusableSession();
+    const sandboxSession = this.getSandboxSession();
+    return runPrompt<TOOLS, RUNTIME_CONTEXT>({
+      harness: this.harness,
+      session,
+      mode: 'continue',
+      instructions: options.instructions,
+      tools: options.tools,
+      toolSpecs: options.toolSpecs,
+      sandboxSession: sandboxSession.restricted(),
+      sessionWorkDir: this.sessionWorkDir,
+      runtimeContext: options.runtimeContext,
+      abortSignal: options.abortSignal,
+      telemetry: options.telemetry,
+      toolApproval: this.toolApproval,
+      pendingToolApprovals: this.getPendingToolApprovals(),
+      toolApprovalContinuations: options.toolApprovalContinuations,
+      onPendingToolApproval: approval => {
+        this.pendingToolApprovals.set(approval.approvalId, approval);
+      },
+      onToolApprovalSettled: approvalId => {
+        this.pendingToolApprovals.delete(approvalId);
+      },
+    });
+  }
+
+  /**
+   * Ask the underlying runtime to compact its context. The runtime performs
+   * the compaction itself; when it completes, a `compaction` part appears on
+   * the active (or next) turn's stream. Safe to call between turns for
+   * runtimes whose compaction is session-scoped (e.g. Pi).
+   *
+   * Throws `HarnessCapabilityUnsupportedError` for harnesses that cannot
+   * trigger compaction manually (e.g. Codex, which still auto-compacts under
+   * the hood). Throws if the session has ended.
+   */
+  async compact(customInstructions?: string): Promise<void> {
+    await this.requireReusableSession().doCompact(customInstructions);
+  }
+
+  /**
+   * Park the session, returning a payload the caller can persist and later
+   * pass to `agent.createSession({ sessionId, resumeFrom })` to reconnect.
+   * The runtime and sandbox keep running; this local session handle becomes
+   * unusable.
+   */
+  async detach(): Promise<HarnessV1ResumeState> {
+    if (this.stopped || this.underlyingSession == null) {
+      throw new Error(
+        `Harness session ${this.sessionId} is not active and cannot be detached.`,
+      );
+    }
+    const session = this.underlyingSession;
+    try {
+      const raw = await session.doDetach();
+      const validated = await validateResumeStateData({
+        harness: this.harness,
+        state: raw as HarnessV1ResumeState,
+      });
+      return this.withPendingToolApprovals(validated);
+    } finally {
+      this.endLocalHandle({ releasePortLease: false });
+    }
+  }
+
+  /**
+   * Persist enough state to resume later, then stop the runtime and sandbox.
+   * Returns the resume state for a future
+   * `agent.createSession({ sessionId, resumeFrom })` call.
+   */
+  async stop(): Promise<HarnessV1ResumeState> {
+    if (this.stopped || this.underlyingSession == null) {
+      throw new Error(
+        `Harness session ${this.sessionId} is not active and cannot be stopped.`,
+      );
+    }
+    const session = this.underlyingSession;
+    const sandboxSession = this.getSandboxSession();
+    try {
+      const raw = await session.doStop();
+      const validated = await validateResumeStateData({
+        harness: this.harness,
+        state: raw as HarnessV1ResumeState,
+      });
+      return this.withPendingToolApprovals(validated);
+    } finally {
+      this.endLocalHandle({ releasePortLease: true });
+      await Promise.resolve(sandboxSession.stop()).catch(() => {});
+    }
+  }
+
+  /**
+   * Stop the runtime and discard resumability. The sandbox is destroyed when
+   * the provider supports destruction; otherwise it is stopped.
+   */
+  async destroy(): Promise<void> {
+    if (this.stopped) return;
+    const session = this.underlyingSession;
+    const sandboxSession = this.getSandboxSession();
+    this.endLocalHandle({ releasePortLease: true });
+    if (session != null) {
+      await Promise.resolve(session.doDestroy()).catch(() => {});
+    }
+    await Promise.resolve(
+      sandboxSession.destroy?.() ?? sandboxSession.stop(),
+    ).catch(() => {});
+  }
+
+  /**
+   * Gracefully freeze the active turn at the slice boundary and return the
+   * resume payload, **leaving the sandbox/runtime running** so the next process
+   * can resume. Resolves once the in-flight `stream()`/`continueTurn()`
+   * has cleanly wound down at a precise cursor (see
+   * {@link HarnessV1Session.doSuspendTurn}).
+   *
+   * After this call the session is marked stopped. This in-process handle no
+   * longer drives turns; a future slice creates a fresh session from the
+   * returned state. The sandbox is **not** stopped and no port lease is
+   * released, because bridge-backed adapters may still have a live bridge on
+   * that port.
+   */
+  async suspendTurn(): Promise<HarnessV1ResumeState> {
+    if (this.stopped || this.underlyingSession == null) {
+      throw new Error(
+        `Harness session ${this.sessionId} is not active and cannot be suspended.`,
+      );
+    }
+    const session = this.underlyingSession;
+    const raw = await session.doSuspendTurn();
+    const validated = await validateResumeStateData({
+      harness: this.harness,
+      state: raw as HarnessV1ResumeState,
+    });
+    // Drop the in-process references without stopping the sandbox or releasing
+    // the port lease: bridge-backed adapters may keep using that port.
+    this.stopped = true;
+    this.underlyingSession = undefined;
+    this.sandboxSession = undefined;
+    return this.withPendingToolApprovals(validated);
+  }
+
+  private getPendingToolApprovals(): readonly HarnessV1PendingToolApproval[] {
+    return Array.from(this.pendingToolApprovals.values());
+  }
+
+  private withPendingToolApprovals(
+    state: HarnessV1ResumeState,
+  ): HarnessV1ResumeState {
+    const pendingToolApprovals = this.getPendingToolApprovals();
+    if (pendingToolApprovals.length === 0) {
+      return {
+        harnessId: state.harnessId,
+        specificationVersion: state.specificationVersion,
+        data: state.data,
+      };
+    }
+    return {
+      ...state,
+      pendingToolApprovals,
+    };
+  }
+
+  private endLocalHandle(options: { releasePortLease: boolean }): void {
+    this.stopped = true;
+    this.underlyingSession = undefined;
+    this.sandboxSession = undefined;
+    if (options.releasePortLease) {
+      this.releasePortLease();
+    }
+  }
+
+  private releasePortLease(): void {
+    if (this.leasedBridgePort == null) return;
+    releaseBridgePort({
+      poolKey: this.sandboxProvider,
+      sessionId: this.sessionId,
+    });
+    this.leasedBridgePort = undefined;
+  }
+
+  private requireReusableSession(): HarnessV1Session {
+    if (this.stopped || this.underlyingSession == null) {
+      throw new Error(
+        `Harness session ${this.sessionId} has ended and cannot be reused.`,
+      );
+    }
+    return this.underlyingSession;
+  }
+}

package/src/agent/harness-agent-settings.ts

@@ -0,0 +1,131 @@
+import type {
+  HarnessV1,
+  HarnessV1PermissionMode,
+  HarnessV1SandboxProvider,
+  HarnessV1Skill,
+} from '../v1';
+import type {
+  HarnessDebugConfig,
+  HarnessDiagnostic,
+} from './harness-diagnostics';
+import type {
+  Experimental_SandboxSession as SandboxSession,
+  ToolSet,
+} from '@ai-sdk/provider-utils';
+import type { TelemetryOptions, ToolApprovalStatus } from 'ai';
+
+export type HarnessAgentToolApprovalConfiguration = Readonly<
+  Record<string, ToolApprovalStatus>
+>;
+
+/**
+ * Construction-time settings for a `HarnessAgent`.
+ *
+ * Per-call settings (prompt, abortSignal, callbacks) belong on the
+ * `AgentCallParameters` / `AgentStreamParameters` passed to `generate` /
+ * `stream` and are not duplicated here.
+ */
+export type HarnessAgentSettings<
+  THarness extends HarnessV1<any> = HarnessV1,
+  TUserTools extends ToolSet = {},
+> = {
+  /**
+   * The harness adapter driving the underlying agent runtime. Its
+   * `builtinTools` are merged with the user-defined `tools` and exposed to
+   * AI SDK consumers in the typed `tool-call` stream.
+   */
+  readonly harness: THarness;
+
+  /**
+   * Stable identifier for this agent instance. Exposed via `agent.id`.
+   * If omitted, `agent.id` is `undefined`.
+   */
+  readonly id?: string;
+
+  /**
+   * Tools available to the underlying runtime in addition to the harness's
+   * own builtins. The agent forwards each tool to the harness as a
+   * `HarnessV1ToolSpec`; when the runtime calls one, the agent executes
+   * `tool.execute()` on the host and submits the result back to the harness.
+   *
+   * User tools take precedence over harness builtins on key collision —
+   * declare a tool with the same name as a builtin to override.
+   */
+  readonly tools?: TUserTools;
+
+  /**
+   * Skills made available to the underlying runtime for the lifetime of
+   * the session. Each adapter decides how to surface skills (file in the
+   * working tree, prompt prefix, …).
+   */
+  readonly skills?: ReadonlyArray<HarnessV1Skill>;
+
+  /**
+   * Instructions for the underlying agent runtime. Adapters prepend this to
+   * the first user message of a fresh session, once — it is not re-applied on
+   * later turns or when resuming a previously ended session.
+   */
+  readonly instructions?: string;
+
+  /**
+   * Built-in tool permission mode. Defaults to `'allow-all'`, preserving the
+   * existing bypass-permissions behavior unless users opt in.
+   */
+  readonly permissionMode?: HarnessV1PermissionMode;
+
+  /**
+   * Per custom-tool approval statuses. This mirrors AI SDK `toolApproval`
+   * object configuration for host-executed tools, without callback support.
+   *
+   * `not-applicable` and `approved` run the tool, `user-approval` pauses the
+   * turn for a user decision, and `denied` immediately submits an
+   * `execution-denied` result.
+   */
+  readonly toolApproval?: HarnessAgentToolApprovalConfiguration;
+
+  /**
+   * Sandbox provider whose `create()` produces the network sandbox session the
+   * harness runs against. Its `restricted()` view is also propagated to user
+   * tool `execute()` calls (as the `experimental_sandbox` field), typed as
+   * `Experimental_SandboxSession` so tools cannot reach the infra surface.
+   */
+  readonly sandbox: HarnessV1SandboxProvider;
+
+  /**
+   * Called after each sandbox session is acquired and the session work
+   * directory exists, before the harness adapter starts. Runs for fresh and
+   * resumed sessions.
+   *
+   * Use this to write per-session config, install lightweight tools, activate
+   * licenses, or prepare files in `sessionWorkDir`. Keep it idempotent if the
+   * agent may resume sessions.
+   */
+  readonly onSandboxSession?: (opts: {
+    readonly session: SandboxSession;
+    readonly sessionWorkDir: string;
+    readonly abortSignal?: AbortSignal;
+  }) => Promise<void>;
+
+  /**
+   * Telemetry configuration. The harness drives AI SDK's pluggable
+   * `Telemetry` integration contract from the turn lifecycle, so a harness turn
+   * appears in a consumer's traces with the same span shape as `streamText`.
+   * Register an integration here (e.g. `@ai-sdk/otel`) or globally via
+   * `registerTelemetry`. The harness itself stays OpenTelemetry-agnostic.
+   */
+  readonly telemetry?: TelemetryOptions;
+
+  /**
+   * Diagnostics configuration. Enables bridge log forwarding (sandbox
+   * console + structured `debug-event`s) and the `HARNESS_DEBUG` stderr default.
+   * Set `{ enabled: true }` to turn it on in code; env vars fill unset fields.
+   */
+  readonly debug?: HarnessDebugConfig;
+
+  /**
+   * Programmatic sink for forwarded bridge diagnostics. Receives every
+   * captured console line and structured event, normalized. Independent of the
+   * stderr default — wire this to capture diagnostics in code.
+   */
+  readonly onLog?: (event: HarnessDiagnostic) => void;
+};

package/src/agent/harness-agent-tool-approval-continuation.ts

@@ -0,0 +1,94 @@
+import { HarnessError } from '../errors/harness-error';
+import type {
+  ModelMessage,
+  ToolApprovalRequest,
+  ToolApprovalResponse,
+} from '@ai-sdk/provider-utils';
+
+export type HarnessAgentToolApprovalContinuation = {
+  readonly approvalResponse: ToolApprovalResponse;
+  readonly toolCall: {
+    readonly type: 'tool-call';
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input: unknown;
+    readonly providerExecuted?: boolean;
+  };
+};
+
+/**
+ * Extract approval decisions that should continue a suspended harness turn.
+ *
+ * AI SDK clients send approval decisions as a trailing `role: "tool"` message
+ * containing `tool-approval-response` parts. The response only carries the
+ * approval id, so the harness has to recover the matching approval request
+ * locally to find the original tool call before it can resume the paused turn.
+ * Responses that already have a tool result are ignored, because those
+ * approvals were already consumed by a prior continuation.
+ */
+export function collectHarnessAgentToolApprovalContinuations(input: {
+  messages: readonly ModelMessage[];
+}): readonly HarnessAgentToolApprovalContinuation[] {
+  const lastMessage = input.messages.at(-1);
+  if (lastMessage?.role !== 'tool') return [];
+
+  const toolCallsByToolCallId = new Map<
+    string,
+    HarnessAgentToolApprovalContinuation['toolCall']
+  >();
+  const approvalRequestsByApprovalId = new Map<string, ToolApprovalRequest>();
+  for (const message of input.messages) {
+    if (message.role !== 'assistant' || typeof message.content === 'string') {
+      continue;
+    }
+    for (const part of message.content) {
+      if (part.type === 'tool-call') {
+        toolCallsByToolCallId.set(part.toolCallId, {
+          type: 'tool-call',
+          toolCallId: part.toolCallId,
+          toolName: part.toolName,
+          input: part.input,
+          ...(part.providerExecuted !== undefined
+            ? { providerExecuted: part.providerExecuted }
+            : {}),
+        });
+      } else if (part.type === 'tool-approval-request') {
+        approvalRequestsByApprovalId.set(part.approvalId, part);
+      }
+    }
+  }
+
+  const toolResultIds = new Set<string>();
+  for (const part of lastMessage.content) {
+    if (part.type === 'tool-result') {
+      toolResultIds.add(part.toolCallId);
+    }
+  }
+
+  const continuations: HarnessAgentToolApprovalContinuation[] = [];
+  for (const part of lastMessage.content) {
+    if (part.type !== 'tool-approval-response') continue;
+
+    const approvalRequest = approvalRequestsByApprovalId.get(part.approvalId);
+    if (approvalRequest == null) {
+      throw new HarnessError({
+        message: `Tool approval response '${part.approvalId}' does not match a prior tool approval request.`,
+      });
+    }
+    if (toolResultIds.has(approvalRequest.toolCallId)) continue;
+
+    const toolCall = toolCallsByToolCallId.get(approvalRequest.toolCallId);
+    if (toolCall == null) {
+      throw new HarnessError({
+        message: `Tool approval request '${approvalRequest.approvalId}' references unknown tool call '${approvalRequest.toolCallId}'.`,
+      });
+    }
+
+    continuations.push({
+      approvalResponse: part,
+      toolCall,
+    });
+  }
+
+  return continuations;
+}