@go-hare/claude-agent-sdk 0.3.177

package/LICENSE.md

@@ -0,0 +1 @@
+© Anthropic PBC. All rights reserved. Use is subject to the Legal Agreements outlined here: https://code.claude.com/docs/en/legal-and-compliance.

package/README.md

@@ -0,0 +1,64 @@
+# Claude Agent SDK
+
+![](https://img.shields.io/badge/Node.js-18%2B-brightgreen?style=flat-square) [![npm]](https://www.npmjs.com/package/@go-hare/claude-agent-sdk)
+
+[npm]: https://img.shields.io/npm/v/@go-hare/claude-agent-sdk.svg?style=flat-square
+
+The Claude Agent SDK enables you to programmatically build AI agents with Claude Code's capabilities. Create autonomous agents that can understand codebases, edit files, run commands, and execute complex workflows.
+
+**Learn more in the [official documentation](https://platform.claude.com/docs/en/agent-sdk/overview)**.
+
+## Get started
+
+Install the Claude Agent SDK:
+
+```sh
+npm install @go-hare/claude-agent-sdk
+```
+
+## Compiled binaries (`bun build --compile`)
+
+When bundling your application into a single executable with `bun build --compile`, the SDK cannot resolve the native CLI binary at runtime — `require.resolve` doesn't work from inside the compiled `$bunfs` (or `B:\~BUN\...` on Windows) virtual filesystem.
+
+Embed the platform-specific binary as a file asset, extract it to a real path, and pass it explicitly:
+
+```js
+import binPath from '@go-hare/claude-code-darwin-arm64/claude' with { type: 'file' }
+import { extractFromBunfs } from '@go-hare/claude-agent-sdk/extract'
+import { query } from '@go-hare/claude-agent-sdk'
+
+const cliPath = extractFromBunfs(binPath)
+
+for await (const message of query({
+  prompt: '…',
+  options: { pathToClaudeCodeExecutable: cliPath },
+})) { /* … */ }
+```
+
+Each compiled executable embeds one platform's binary, matching your `--target`. Cross-compiling requires installing the non-matching platform package (e.g. `npm install @go-hare/claude-code-linux-x64 --force`). On Windows the binary subpath is `/claude.exe` (e.g. `@go-hare/claude-code-win32-x64/claude.exe`).
+
+## Migrating from the Claude Code SDK
+
+The Claude Code SDK is now the Claude Agent SDK. Please check out the [migration guide](https://platform.claude.com/docs/en/agent-sdk/migration-guide) for details on breaking changes.
+
+## Reporting Bugs
+
+We welcome your feedback. File a [GitHub issue](https://github.com/go-hare/claude-agent-sdk-typescript/issues) to report bugs or request features.
+
+## Connect on Discord
+
+Join the [Claude Developers Discord](https://anthropic.com/discord) to connect with other developers building with the Claude Agent SDK. Get help, share feedback, and discuss your projects with the community.
+
+## Data collection, usage, and retention
+
+When you use the Claude Agent SDK, we collect feedback, which includes usage data (such as code acceptance or rejections), associated conversation data, and user feedback submitted via the /bug command.
+
+### How we use your data
+
+See our [data usage policies](https://docs.anthropic.com/en/docs/claude-code/data-usage).
+
+### Privacy safeguards
+
+We have implemented several safeguards to protect your data, including limited retention periods for sensitive information and restricted access to user session data.
+
+For full details, please review our [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms) and [Privacy Policy](https://www.anthropic.com/legal/privacy).

package/agentSdkTypes.d.ts

@@ -0,0 +1 @@
+export * from './sdk.js'

package/assistant.d.ts

@@ -0,0 +1,135 @@
+/**
+ * API surface definition for @anthropic-ai/claude-agent-sdk/assistant.
+ *
+ * Source of truth for the /assistant export's public types. Imports ONLY
+ * from agentSdkTypes.ts so the compiled .d.ts has exactly one import to
+ * rewrite (./agentSdkTypes → ./sdk) for the flat package layout.
+ *
+ * Compiled by scripts/build-ant-sdk-typings.sh; runtime in
+ * agentSdkAssistant.ts (bun-built to assistant.mjs).
+ *
+ * Type definitions below are copied from src/assistant/worker.ts and
+ * src/assistant/daemonBridge.ts. Keep in sync — those are the
+ * implementation source of truth.
+ */
+import type { CanUseTool, ConnectRemoteControlOptions, InboundPrompt, Options, PermissionResult, SDKMessage, SDKUserMessage } from './agentSdkTypes.js';
+export type { ConnectRemoteControlOptions, InboundPrompt };
+/**
+ * Worker-persisted state. Checkpointed on turn boundaries, bridge
+ * reconnects, and teardown.
+ * @alpha
+ */
+export type WorkerState = {
+    claudeSessionId?: string;
+    lastSSESequenceNum?: number;
+    bridgeSessionId?: string;
+};
+/** @alpha */
+export type WorkerStateAdapter = {
+    load(): Promise<WorkerState | null>;
+    save(state: WorkerState): Promise<void>;
+};
+/**
+ * Third argument to the SDK's CanUseTool callback.
+ * @alpha
+ */
+export type CanUseToolContext = Parameters<CanUseTool>[2];
+/**
+ * Structured failure from `runAssistantWorker`. `kind` lets callers branch
+ * on handling — conflict UI, retry with backoff, or bail.
+ * @alpha
+ */
+export type AssistantWorkerError = {
+    kind: 'conflict' | 'auth' | 'network' | 'unknown';
+    detail: string;
+};
+/** @alpha */
+export type AssistantWorkerResult = {
+    ok: true;
+    handle: AssistantWorkerHandle;
+} | {
+    ok: false;
+    error: AssistantWorkerError;
+};
+/** @alpha */
+export type AssistantWorkerOptions = {
+    /**
+     * Bridge connection config — passed through to `connectRemoteControl`.
+     * `initialSSESequenceNum` is seeded from `stateAdapter.load()` if unset.
+     */
+    bridge: ConnectRemoteControlOptions;
+    /**
+     * Runs in a sandbox (VM, container) where the sandbox boundary IS the
+     * trust boundary. Injects `CLAUDE_CODE_SANDBOXED=1` so the CLI's
+     * directory trust check passes. Default false.
+     */
+    sandboxed?: boolean;
+    /**
+     * Cron-horizon polling. Worker reads `<dir>/.claude/scheduled_tasks.json`
+     * every 10s and spawns the child ~5s before a fire is due. Omit to
+     * disable cron-driven spawn.
+     */
+    scheduling?: {
+        dir: string;
+        horizonMs?: number;
+        leadMs?: number;
+    };
+    /**
+     * Called each time the worker spawns query(). `base` carries
+     * `assistant:true`, `cwd`, `resume`, `stderr`, and the worker's
+     * bridge-wired `canUseTool`. Spread over `base` to add MCP servers,
+     * VM spawn, env vars, system prompt, tool lists.
+     *
+     * May be async — dispatch awaits VM spawn, system prompt build, and
+     * OAuth token fetch before each query() spawn.
+     */
+    buildQueryOptions: (base: Options) => Options | Promise<Options>;
+    /**
+     * Called BEFORE the bridge permission prompt. Return a PermissionResult
+     * to short-circuit; undefined to fall through to the bridge.
+     */
+    canUseToolPreFilter?: (toolName: string, input: Record<string, unknown>, ctx: CanUseToolContext) => Promise<PermissionResult | undefined>;
+    /**
+     * Called AFTER the bridge resolves (or pre-filter short-circuits).
+     * Lets callers persist "always allow" to their own cache.
+     */
+    onPermissionResolved?: (toolName: string, result: PermissionResult) => void;
+    /**
+     * Applied to every SDKMessage after the worker's own filter, before
+     * bridge write. Return null to drop. Used for VM→host path translation.
+     */
+    transformOutbound?: (msg: SDKMessage) => SDKMessage | null;
+    /**
+     * Where to persist WorkerState. Omit to run stateless — fresh
+     * claudeSessionId and SSE seq on every restart.
+     */
+    stateAdapter?: WorkerStateAdapter;
+    /**
+     * Pushed into the input queue at worker start. Daemon passes install.md
+     * on first-run; dispatch passes seed messages or omits.
+     */
+    initialPrompt?: string;
+    /** Despawn child after this much quiet. Default 5 minutes. */
+    userIdleMs?: number;
+    signal: AbortSignal;
+    log?: (msg: string) => void;
+};
+/** @alpha */
+export type AssistantWorkerHandle = {
+    readonly sessionUrl: string;
+    readonly bridgeSessionId: string;
+    readonly claudeSessionId: string | undefined;
+    /** Push a prompt into the input queue without going through the bridge. */
+    pushPrompt(content: string | SDKUserMessage['message']['content']): void;
+    interrupt(): Promise<void>;
+    /** Resolves when the fan-in loop exits and teardown completes. */
+    done: Promise<void>;
+    teardown(): Promise<void>;
+};
+/**
+ * Run a single-session assistant worker: connect to the claude.ai bridge,
+ * spawn query() on demand (inbound prompt or cron due), proxy permissions
+ * through the bridge, despawn on idle.
+ * @alpha
+ */
+export declare function runAssistantWorker(opts: AssistantWorkerOptions): Promise<AssistantWorkerResult>;