@ai-sdk/harness 0.0.0 → 1.0.0-beta.15

package/CHANGELOG.md

@@ -0,0 +1,117 @@
+# @ai-sdk/harness
+
+## 1.0.0-beta.15
+
+### Patch Changes
+
+- Updated dependencies [b097c52]
+  - ai@7.0.0-beta.178
+
+## 1.0.0-beta.14
+
+### Patch Changes
+
+- b8396f0: trigger initial beta release
+- Updated dependencies [b8396f0]
+  - @ai-sdk/provider-utils@5.0.0-beta.49
+  - @ai-sdk/provider@4.0.0-beta.19
+  - ai@7.0.0-beta.177
+
+## 1.0.0-canary.13
+
+### Patch Changes
+
+- ai@7.0.0-canary.176
+
+## 1.0.0-canary.12
+
+### Patch Changes
+
+- Updated dependencies [6ec57f5]
+  - ai@7.0.0-canary.175
+
+## 1.0.0-canary.11
+
+### Patch Changes
+
+- be83911: fix(harness): reject bridge startup when the WebSocket port cannot be bound
+
+## 1.0.0-canary.10
+
+### Patch Changes
+
+- ai@7.0.0-canary.174
+
+## 1.0.0-canary.9
+
+### Patch Changes
+
+- ai@7.0.0-canary.173
+
+## 1.0.0-canary.8
+
+### Patch Changes
+
+- aae0138: fix(harness): make listening for sandbox bridge readiness compatible with Bun
+
+## 1.0.0-canary.7
+
+### Patch Changes
+
+- 3d87086: fix(harness): guard against invalid resuming a session vs continuing a turn
+- 1ea15a3: fix(harness): fix various bugs with harness skills not being correctly processed by the harness adapters
+- Updated dependencies [aeda373]
+- Updated dependencies [25a64f8]
+- Updated dependencies [375fdd7]
+- Updated dependencies [f18b08f]
+- Updated dependencies [b4507d5]
+  - @ai-sdk/provider-utils@5.0.0-canary.48
+  - ai@7.0.0-canary.172
+
+## 1.0.0-canary.6
+
+### Patch Changes
+
+- Updated dependencies [89ad56f]
+- Updated dependencies [f9a496f]
+- Updated dependencies [3295831]
+  - ai@7.0.0-canary.171
+
+## 1.0.0-canary.5
+
+### Patch Changes
+
+- d77bed4: chore(harness): separate harness spec types (v1) from consumer-facing types
+- Updated dependencies [bae5e2b]
+- Updated dependencies [69d7128]
+  - ai@7.0.0-canary.170
+  - @ai-sdk/provider-utils@5.0.0-canary.47
+
+## 1.0.0-canary.4
+
+### Patch Changes
+
+- 3d9a50c: feat(harness): implement harness adapters for Claude Code, Codex, Pi
+
+## 1.0.0-canary.3
+
+### Patch Changes
+
+- 21d3d60: feat(harness): implement harness specification
+- Updated dependencies [a5018ab]
+- Updated dependencies [21d3d60]
+- Updated dependencies [426dbbb]
+- Updated dependencies [7fd3360]
+  - ai@7.0.0-canary.169
+
+## 1.0.0-canary.2
+
+### Patch Changes
+
+- 6c7a3e5: Start the `1.0.0` canary release line for the experimental harness and sandbox packages. They were unintentionally published as `0.0.0-canary.*` because they were scaffolded with a `0.0.0-canary.0` premajor version, which semver could not advance past on a major bump.
+
+## 0.0.0-canary.1
+
+### Major Changes
+
+- 9d6dbe0: feat(harness): add sandbox specific expansion for harness abstraction, add `sandbox-just-bash` and `sandbox-vercel`

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2023 Vercel, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,142 @@
+# AI SDK - Harness Specification and Agent
+
+_This package is **experimental**._
+
+`HarnessAgent` implementation plus the underlying harness specification, including an expanded network session sandbox interface to support harness sandbox needs.
+
+## Setup
+
+```bash
+npm i @ai-sdk/harness
+```
+
+## Usage
+
+```ts
+import { HarnessAgent } from '@ai-sdk/harness/agent';
+import { createClaudeCode } from '@ai-sdk/harness-claude-code';
+import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';
+import { tool } from 'ai';
+import { z } from 'zod';
+
+const agent = new HarnessAgent({
+  harness: createClaudeCode(),
+  id: 'auth-agent',
+  system: 'You are a careful refactoring assistant. Prefer minimal diffs.',
+  sandbox: createVercelSandbox({
+    runtime: 'node24',
+    ports: [4000],
+  }),
+  onSandboxSession: async ({ session, sessionWorkDir, abortSignal }) => {
+    await session.writeTextFile({
+      path: `${sessionWorkDir}/README.md`,
+      content: 'Workspace notes for this session.',
+      abortSignal,
+    });
+  },
+  tools: {
+    deploy: tool({
+      description: 'Deploy to a target environment',
+      inputSchema: z.object({ env: z.enum(['staging', 'production']) }),
+      execute: async ({ env }) => ({ url: await deployTo(env) }),
+    }),
+  },
+  harnessOptions: {
+    'claude-code': { thinking: 'adaptive' },
+  },
+});
+
+const session = await agent.createSession();
+
+try {
+  const result = await agent.generate({
+    session,
+    prompt: 'Fix the failing test in src/auth.ts',
+  });
+  console.log(result.text);
+
+  // Streaming
+  const stream = await agent.stream({
+    session,
+    prompt: 'Now write a regression test',
+  });
+  for await (const part of stream.fullStream) {
+    if (part.type === 'text-delta') {
+      process.stdout.write(part.text);
+    }
+  }
+} finally {
+  await session.destroy();
+}
+```
+
+`sandbox` is a required `HarnessV1SandboxProvider` — the agent calls `provider.createSession()` when a session starts. Use `onSandboxSession` to prepare the acquired sandbox before the harness adapter starts. The hook runs for fresh and resumed sessions, so keep it idempotent. Use `session.detach()` to park a bridge-backed session for later attach, `session.stop()` to save state and stop the sandbox, or `session.destroy()` to clean up without keeping resume state. Bridge-backed adapters (claude-code, codex) require a provider that exposes ports — `@ai-sdk/sandbox-vercel` is the supported choice today. `@ai-sdk/sandbox-just-bash` is suitable only for non-bridge flows.
+
+### Available harnesses
+
+- `@ai-sdk/harness-claude-code`
+- `@ai-sdk/harness-codex`
+- `@ai-sdk/harness-opencode` (WIP)
+- `@ai-sdk/harness-goose` (WIP)
+- `@ai-sdk/harness-mastra` (WIP)
+- `@ai-sdk/harness-deepagents` (WIP)
+- `@ai-sdk/harness-openai-agents` (WIP)
+- `@ai-sdk/harness-pi` (WIP)
+
+## Implementing a harness
+
+Implement the `HarnessV1` factory and a `HarnessV1Session` whose `doPrompt` emits events; the agent surface, streaming, tool execution, and multi-turn state are handled for you. Read `startOpts.sandboxSession` for the network sandbox session the agent created and will stop on cleanup. Call `sandboxSession.restricted()` for the tool-safe file-IO/exec/spawn surface.
+
+```ts
+import type { HarnessV1, HarnessV1Session } from '@ai-sdk/harness';
+
+export function myHarness(): HarnessV1 {
+  return {
+    specificationVersion: 'harness-v1',
+    harnessId: 'my-harness',
+    builtinTools: [],
+    doStart: async startOpts => {
+      const session: HarnessV1Session = {
+        sessionId: startOpts.sessionId,
+        isResume: false,
+        doPromptTurn: async promptOpts => {
+          promptOpts.emit({ type: 'text-start', id: 't' });
+          promptOpts.emit({ type: 'text-delta', id: 't', delta: 'Hello.' });
+          promptOpts.emit({ type: 'text-end', id: 't' });
+          promptOpts.emit({
+            type: 'finish',
+            finishReason: { unified: 'stop', raw: 'stop' },
+            totalUsage: {
+              inputTokens: {
+                total: 0,
+                noCache: 0,
+                cacheRead: undefined,
+                cacheWrite: undefined,
+              },
+              outputTokens: { total: 0, text: 0, reasoning: undefined },
+            },
+          });
+          return { submitToolResult: async () => {}, done: Promise.resolve() };
+        },
+        doContinueTurn: async () => ({
+          submitToolResult: async () => {},
+          done: Promise.resolve(),
+        }),
+        doCompact: async () => {},
+        doStop: async () => ({
+          harnessId: 'my-harness',
+          specificationVersion: 'harness-v1',
+          data: {},
+        }),
+        doDestroy: async () => {},
+        doSuspendTurn: async () => ({
+          harnessId: 'my-harness',
+          specificationVersion: 'harness-v1',
+          data: {},
+        }),
+      };
+      return session;
+    },
+  };
+}
+```

package/agent/index.ts

@@ -0,0 +1,47 @@
+export { HarnessAgent } from '../src/agent/harness-agent';
+export type {
+  HarnessAgentSettings,
+  HarnessAgentToolApprovalConfiguration,
+} from '../src/agent/harness-agent-settings';
+export type {
+  HarnessAgentAdapter,
+  HarnessAgentAdapterSession,
+  HarnessAgentBuiltinTool,
+  HarnessAgentBuiltinToolName,
+  HarnessAgentBuiltinTools,
+  HarnessAgentBuiltinToolUseKind,
+  HarnessAgentContinueTurnOptions,
+  HarnessAgentContinueTurnState,
+  HarnessAgentLifecycleState,
+  HarnessAgentPendingToolApproval,
+  HarnessAgentPermissionMode,
+  HarnessAgentPrompt,
+  HarnessAgentPromptControl,
+  HarnessAgentPromptTurnOptions,
+  HarnessAgentResumeSessionState,
+  HarnessAgentSkill,
+  HarnessAgentStartOptions,
+  HarnessAgentStreamPart,
+  HarnessAgentToolSpec,
+} from '../src/agent/harness-agent-types';
+export { HarnessAgentSession } from '../src/agent/harness-agent-session';
+export {
+  collectHarnessAgentToolApprovalContinuations,
+  type HarnessAgentToolApprovalContinuation,
+} from '../src/agent/harness-agent-tool-approval-continuation';
+export { prewarmHarness } from '../src/agent/prewarm';
+export type {
+  HarnessDebugConfig,
+  HarnessDebugLevel,
+  HarnessDiagnostic,
+  HarnessDiagnosticConsumer,
+} from '../src/agent/observability/types';
+export { HarnessError } from '../src/errors/harness-error';
+export { HarnessCapabilityUnsupportedError } from '../src/errors/harness-capability-unsupported-error';
+export {
+  createFileReporter,
+  createTraceTreeReporter,
+  type FileReporter,
+  type FileReporterOptions,
+  type TraceTreeReporterOptions,
+} from '../src/agent/observability';

package/bridge/index.ts

@@ -0,0 +1,10 @@
+export { runBridge } from '../src/bridge';
+export type {
+  RunBridgeOptions,
+  BridgeTurn,
+  BridgeEvent,
+  BridgeState,
+  BridgeHandle,
+  BridgeDebugConfig,
+  BridgeDebugLevel,
+} from '../src/bridge';