@factory/droid-sdk 0.6.0 → 0.7.0

package/docs/daemon-usage-guide.md

@@ -1,544 +0,0 @@
-# Daemon SDK Usage Guide
-
-The daemon SDK connects to a running `droid daemon` process over WebSocket instead of spawning a new subprocess per session. This enables multiple concurrent sessions over a single connection and is the transport used by Slack, Linear, REST API, and Automations integrations.
-
-## Getting Started
-
-```bash
-npm install @factory/droid-sdk
-```
-
-Requires a running `droid daemon` (the SDK will auto-start one locally) and a `FACTORY_API_KEY`. For simpler use cases that don't need concurrent sessions, see the [SDK Usage Guide](./sdk-usage-guide.md) which covers exec mode (`run()`, `createSession()`).
-
-```ts
-import { connectDaemon, DroidMessageType } from '@factory/droid-sdk';
-
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-const session = await connection.createSession({ cwd: process.cwd() });
-
-for await (const msg of session.stream('What files are in this directory?')) {
-  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
-  if (msg.type === DroidMessageType.Result)
-    console.log(`Done in ${msg.durationMs}ms`);
-}
-
-await session.close();
-await connection.close();
-```
-
----
-
-## Daemon vs Exec Mode
-
-|           | Exec mode (`run`, `createSession`)     | Daemon mode (`connectDaemon`)                 |
-| --------- | -------------------------------------- | --------------------------------------------- |
-| Transport | Spawns `droid exec` subprocess (stdio) | WebSocket to `droid daemon`                   |
-| Sessions  | One per subprocess                     | Multiple per connection                       |
-| Auth      | Explicit (`apiKey`)                    | Explicit (`apiKey`)                           |
-| Use case  | Simple scripts, CI                     | Server-side integrations, long-lived services |
-
-Use daemon mode when you need multiple concurrent sessions, want to avoid subprocess overhead, or are building a server-side integration.
-
----
-
-## Connect to Local Daemon
-
-The simplest form -- the SDK spawns a local daemon and authenticates with the provided API key.
-
-```ts
-import { connectDaemon } from '@factory/droid-sdk';
-
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-```
-
-### Connect to Remote Machine
-
-```ts
-import { connectDaemon, MachineType } from '@factory/droid-sdk';
-
-// Ephemeral sandbox (e2b)
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-  machine: {
-    type: MachineType.Ephemeral,
-    sandboxId: 'sandbox-abc123',
-    workspaceId: 'ws-xyz',
-  },
-});
-
-// Computer relay
-const connection2 = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-  machine: {
-    type: MachineType.Computer,
-    computerId: 'comp-abc123',
-  },
-});
-```
-
-### Direct URL
-
-Skip machine-based resolution and connect to a specific WebSocket endpoint.
-
-```ts
-const connection = await connectDaemon({
-  url: 'ws://127.0.0.1:37643',
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-```
-
-### Connection Retries
-
-```ts
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-  maxRetries: 3, // Retry connect+authenticate cycle up to 3 times
-});
-```
-
----
-
-## Create a Session
-
-```ts
-import {
-  connectDaemon,
-  AutonomyLevel,
-  ReasoningEffort,
-} from '@factory/droid-sdk';
-
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-
-const session = await connection.createSession({
-  cwd: '/path/to/project',
-  modelId: 'claude-sonnet-4-20250514',
-  autonomyLevel: AutonomyLevel.High,
-  reasoningEffort: ReasoningEffort.High,
-});
-```
-
----
-
-## Stream a Response
-
-`stream()` yields complete messages by default: assistant text, tool calls, tool results, and the final result.
-
-```ts
-import { DroidMessageType } from '@factory/droid-sdk';
-
-for await (const msg of session.stream('Refactor the utils module.')) {
-  switch (msg.type) {
-    case DroidMessageType.Assistant:
-      console.log(msg.text);
-      break;
-    case DroidMessageType.ToolCall:
-      console.log(`[Tool] ${msg.toolUse.name}`);
-      break;
-    case DroidMessageType.ToolResult:
-      console.log(`[Result] ${msg.isError ? 'Error' : 'OK'}`);
-      break;
-    case DroidMessageType.Result:
-      console.log(`Done in ${msg.durationMs}ms, turns: ${msg.numTurns}`);
-      break;
-  }
-}
-```
-
-## Partial Message Streaming
-
-Enable `includePartialMessages` to get token-by-token deltas as they arrive.
-
-```ts
-import { DroidMessageType } from '@factory/droid-sdk';
-
-for await (const msg of session.stream('Explain recursion.', {
-  includePartialMessages: true,
-})) {
-  if (msg.type === DroidMessageType.AssistantTextDelta) {
-    process.stdout.write(msg.text);
-  }
-}
-```
-
----
-
-## Fire-and-Forget with send()
-
-`send()` dispatches a prompt and returns after the daemon acknowledges it. The agent runs in the background -- you don't wait for completion. Use this for delegation workflows (e.g., Slack bot triggers a task).
-
-```ts
-await session.send('Fix all lint errors in src/.');
-// Returns immediately after daemon ACK.
-// The agent works in the background.
-```
-
----
-
-## Multi-turn Session
-
-Context is preserved across `stream()` calls on the same session.
-
-```ts
-import { DroidMessageType } from '@factory/droid-sdk';
-
-const session = await connection.createSession({ cwd: process.cwd() });
-
-for await (const msg of session.stream('Remember: the secret is 42.')) {
-  // consume first turn
-}
-
-for await (const msg of session.stream('What is the secret?')) {
-  if (msg.type === DroidMessageType.Assistant) console.log(msg.text); // "42"
-}
-
-await session.close();
-```
-
----
-
-## Resume a Previous Session
-
-Reconnect to a session that was created earlier (on this connection or a previous one).
-
-```ts
-import { DroidMessageType } from '@factory/droid-sdk';
-
-const session = await connection.resumeSession('existing-session-id');
-
-for await (const msg of session.stream('Continue where we left off.')) {
-  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
-}
-
-await session.close();
-```
-
----
-
-## Concurrent Sessions
-
-A single daemon connection supports multiple sessions running simultaneously. The SDK routes notifications to the correct session automatically.
-
-```ts
-import {
-  connectDaemon,
-  DaemonSession,
-  DroidMessageType,
-} from '@factory/droid-sdk';
-
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-
-const [session1, session2] = await Promise.all([
-  connection.createSession({ cwd: '/project-a' }),
-  connection.createSession({ cwd: '/project-b' }),
-]);
-
-// Stream on both concurrently
-const [result1, result2] = await Promise.all([
-  collectResult(session1, 'Fix tests in project A.'),
-  collectResult(session2, 'Add logging to project B.'),
-]);
-
-await session1.close();
-await session2.close();
-await connection.close();
-
-async function collectResult(
-  session: DaemonSession,
-  prompt: string
-): Promise<string> {
-  let text = '';
-  for await (const msg of session.stream(prompt)) {
-    if (msg.type === DroidMessageType.Result) text = msg.result;
-  }
-  return text;
-}
-```
-
----
-
-## Interrupt a Session
-
-### From the session object
-
-```ts
-import { DroidMessageType } from '@factory/droid-sdk';
-
-// Interrupt after receiving some output
-for await (const msg of session.stream('Write a long essay.')) {
-  if (msg.type === DroidMessageType.Assistant) {
-    await session.interrupt();
-    break;
-  }
-}
-```
-
-### With AbortSignal
-
-```ts
-const controller = new AbortController();
-setTimeout(() => controller.abort(), 5000);
-
-try {
-  for await (const msg of session.stream('Write a long essay.', {
-    abortSignal: controller.signal,
-  })) {
-    // ...
-  }
-} catch {
-  console.log('Aborted after 5 seconds');
-}
-```
-
-### From the connection (without a session object)
-
-```ts
-await connection.interruptSession('session-id-to-interrupt');
-```
-
----
-
-## Permission Handler
-
-Programmatically approve or reject tool calls.
-
-```ts
-import {
-  ToolConfirmationOutcome,
-  ToolConfirmationType,
-} from '@factory/droid-sdk';
-
-const session = await connection.createSession({
-  cwd: process.cwd(),
-  permissionHandler(params) {
-    const safe = params.toolUses.every(
-      (item) => item.details.type === ToolConfirmationType.Create
-    );
-    return safe
-      ? ToolConfirmationOutcome.ProceedOnce
-      : ToolConfirmationOutcome.Cancel;
-  },
-});
-```
-
----
-
-## Ask-User Handler
-
-Programmatically answer questions that Droid asks during execution.
-
-```ts
-const session = await connection.createSession({
-  cwd: process.cwd(),
-  askUserHandler(params) {
-    return {
-      cancelled: false,
-      answers: params.questions.map((q) => ({
-        index: q.index,
-        question: q.question,
-        answer: q.options[0] ?? 'yes',
-      })),
-    };
-  },
-});
-```
-
----
-
-## SDK-backed MCP Tools
-
-Define custom tools that Droid can call during a session.
-
-```ts
-import {
-  connectDaemon,
-  createSdkMcpServer,
-  DroidMessageType,
-  tool,
-  ToolConfirmationOutcome,
-} from '@factory/droid-sdk';
-import { z } from 'zod';
-
-const server = createSdkMcpServer({
-  name: 'my-tools',
-  tools: [
-    tool(
-      'lookup',
-      'Look up a user by name',
-      { name: z.string() },
-      ({ name }) => `${name} is user #42.`
-    ),
-  ],
-});
-
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-const session = await connection.createSession({
-  cwd: process.cwd(),
-  mcpServers: [server],
-  permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
-});
-
-for await (const msg of session.stream('Look up Alice.')) {
-  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
-}
-
-await session.close();
-await connection.close();
-```
-
----
-
-## Raw Notification Subscription
-
-Subscribe to raw protocol notifications for custom event handling.
-
-```ts
-import { SessionNotificationType } from '@factory/droid-sdk';
-
-const unsubscribe = session.onNotification(
-  (notification) => {
-    console.log('Notification:', notification);
-  },
-  { type: SessionNotificationType.DROID_WORKING_STATE_CHANGED }
-);
-
-// ... use the session ...
-
-unsubscribe();
-```
-
----
-
-## Error Handling
-
-The daemon SDK throws the same typed errors as exec mode.
-
-```ts
-import {
-  connectDaemon,
-  ConnectionError,
-  TimeoutError,
-  SessionNotFoundError,
-  ProtocolError,
-} from '@factory/droid-sdk';
-
-try {
-  const connection = await connectDaemon({
-    apiKey: process.env.FACTORY_API_KEY!,
-  });
-  const session = await connection.resumeSession('nonexistent-id');
-} catch (error) {
-  if (error instanceof SessionNotFoundError) {
-    console.log(`Session not found: ${error.sessionId}`);
-  } else if (error instanceof TimeoutError) {
-    console.log('Request timed out');
-  } else if (error instanceof ConnectionError) {
-    console.log(`Connection failed: ${error.message}`);
-  } else if (error instanceof ProtocolError) {
-    console.log(`Protocol error ${error.code}: ${error.message}`);
-  }
-}
-```
-
----
-
-## Lifecycle Pattern
-
-Always close sessions and connections when done.
-
-```ts
-import { connectDaemon } from '@factory/droid-sdk';
-
-const connection = await connectDaemon({
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-
-try {
-  const session = await connection.createSession({ cwd: process.cwd() });
-  try {
-    for await (const msg of session.stream('Do the thing.')) {
-      // ...
-    }
-  } finally {
-    await session.close();
-  }
-} finally {
-  await connection.close();
-}
-```
-
----
-
-## Configuration Reference
-
-### `ConnectDaemonOptions`
-
-| Field          | Type               | Required | Description                                                            |
-| :------------- | :----------------- | :------- | :--------------------------------------------------------------------- |
-| `apiKey`       | `string`           | **Yes**  | Factory API key for authentication.                                    |
-| `machine`      | `SDKMachineConfig` | No       | Machine target. Defaults to local daemon.                              |
-| `url`          | `string`           | No       | Direct WebSocket URL. Overrides machine resolution.                    |
-| `maxRetries`   | `number`           | No       | Retry budget for connect+authenticate cycle.                           |
-| `daemonPort`   | `number`           | No       | WebSocket port override. Default: `37643`.                             |
-| `relayBaseUrl` | `string`           | No       | Relay URL for computer connections. Default: `wss://relay.factory.ai`. |
-
-### `SDKMachineConfig`
-
-| Variant     | Fields                             | Description                   |
-| :---------- | :--------------------------------- | :---------------------------- |
-| `Local`     | `{ type: MachineType.Local }`      | Local daemon on this machine. |
-| `Ephemeral` | `{ type, sandboxId, workspaceId }` | e2b sandbox.                  |
-| `Computer`  | `{ type, computerId }`             | Remote computer via relay.    |
-
-### `DaemonSessionOptions`
-
-| Field                     | Type                     | Description                                    |
-| :------------------------ | :----------------------- | :--------------------------------------------- |
-| `cwd`                     | `string`                 | Working directory for the session.             |
-| `modelId`                 | `string`                 | LLM model identifier.                          |
-| `autonomyLevel`           | `AutonomyLevel`          | `Off` \| `Low` \| `Medium` \| `High`.          |
-| `interactionMode`         | `DroidInteractionMode`   | `Auto` \| `Spec` \| `AGI`.                     |
-| `reasoningEffort`         | `ReasoningEffort`        | `Off` \| `Low` \| `Medium` \| `High` \| `Max`. |
-| `specModeModelId`         | `string`                 | Override model for spec mode.                  |
-| `specModeReasoningEffort` | `ReasoningEffort`        | Override reasoning effort for spec mode.       |
-| `mcpServers`              | `DroidMcpServerConfig[]` | MCP server configurations.                     |
-| `enabledToolIds`          | `string[]`               | Tool allowlist.                                |
-| `disabledToolIds`         | `string[]`               | Tool denylist.                                 |
-| `tags`                    | `SessionTag[]`           | Session tags for categorization.               |
-| `permissionHandler`       | `PermissionHandler`      | Tool confirmation callback.                    |
-| `askUserHandler`          | `AskUserHandler`         | Structured user-input callback.                |
-| `sessionSource`           | `SessionSource`          | Attribution metadata.                          |
-
-### `DaemonResumeOptions`
-
-| Field               | Type                     | Description                     |
-| :------------------ | :----------------------- | :------------------------------ |
-| `permissionHandler` | `PermissionHandler`      | Tool confirmation callback.     |
-| `askUserHandler`    | `AskUserHandler`         | Structured user-input callback. |
-| `mcpServers`        | `DroidMcpServerConfig[]` | MCP servers to attach.          |
-
-### `SendOptions`
-
-| Field          | Type                  | Description                            |
-| :------------- | :-------------------- | :------------------------------------- |
-| `images`       | `Base64ImageSource[]` | Base64-encoded image attachments.      |
-| `files`        | `DocumentSource[]`    | Document/file attachments.             |
-| `outputFormat` | `OutputFormat`        | Structured output JSON schema request. |
-
-### Key Classes
-
-| Class                | Description                                                                |
-| :------------------- | :------------------------------------------------------------------------- |
-| `DaemonConnection`   | Manages the WebSocket connection. Creates/resumes sessions.                |
-| `DaemonSession`      | A single session. Provides `stream()`, `send()`, `interrupt()`, `close()`. |
-| `DaemonClient`       | Low-level RPC client. Used internally by `DaemonSession`.                  |
-| `WebSocketTransport` | WebSocket transport with retry and reconnection.                           |