@factory/droid-sdk 0.1.4 → 0.2.0

package/docs/typescript-sdk-reference.md

@@ -0,0 +1,372 @@
+# Agent SDK reference - TypeScript
+
+> Public API reference for `@factory/droid-sdk`, the TypeScript SDK for the Factory Droid CLI.
+
+## Documentation Index
+
+Use these pages together:
+
+- API reference: `docs/typescript-sdk-reference.md`
+- Example walkthroughs: `docs/examples/`
+- Source exports: [`src/index.ts`](../src/index.ts)
+- Runnable repo examples: [`examples/`](../examples)
+
+## Installation
+
+```bash
+npm install @factory/droid-sdk
+```
+
+## Requirements
+
+- Node.js `18+`
+- The `droid` CLI installed and available on your `PATH`
+
+## What this SDK provides
+
+The SDK wraps `droid exec` as a subprocess and exposes two main patterns:
+
+- `query()` for one-shot prompt/response flows
+- `createSession()` / `resumeSession()` for multi-turn sessions
+
+It also includes:
+
+- streaming message events
+- permission and ask-user handlers
+- MCP server management
+- spec mode controls
+- tool allow/deny controls
+- session utilities such as rename, fork, compact, and rewind
+- local session discovery with `listSessions()`
+- low-level access via `ProcessTransport`, `ProtocolEngine`, and `DroidClient`
+
+## Example walkthroughs
+
+For copy-pasteable walkthroughs and complete scripts, see:
+
+- [One-shot query](./examples/one-shot-query.md)
+- [Multi-turn session](./examples/multi-turn-session.md)
+- [Permission handler](./examples/permission-handler.md)
+- [Initialization metadata](./examples/init-metadata.md)
+- [Spec mode approval flow](./examples/spec-mode.md)
+- [Tool controls](./examples/tool-controls.md)
+- [List saved sessions](./examples/list-sessions.md)
+
+## Functions
+
+### `query()`
+
+Starts a one-shot prompt, streams `DroidMessage` events, and cleans up automatically when the stream ends.
+
+```ts
+function query(options: QueryOptions): DroidQuery;
+```
+
+#### `QueryOptions`
+
+`QueryOptions` extends `CreateSessionOptions` and adds:
+
+| Field    | Type     | Description                              |
+| :------- | :------- | :--------------------------------------- |
+| `prompt` | `string` | Prompt to send as the first user message |
+
+#### `DroidQuery`
+
+`DroidQuery` is an `AsyncGenerator<DroidMessage>` with extra controls:
+
+| Member        | Type                               | Description                               |
+| :------------ | :--------------------------------- | :---------------------------------------- |
+| `interrupt()` | `() => Promise<void>`              | Gracefully interrupts the current turn    |
+| `abort()`     | `() => void`                       | Forcefully closes the subprocess          |
+| `sessionId`   | `string \| null`                   | Session ID after initialization completes |
+| `initResult`  | `InitializeSessionResult \| null`  | Raw initialization result                 |
+| `initialized` | `Promise<InitializeSessionResult>` | Resolves when initialization finishes     |
+
+#### Notes
+
+- `query()` accepts `abortSignal`
+- `query()` sends text only; image/file message attachments are supported on `DroidSession`, not `query()`
+
+### `createSession()`
+
+Creates a persistent `DroidSession` for multi-turn conversations.
+
+```ts
+function createSession(options?: CreateSessionOptions): Promise<DroidSession>;
+```
+
+### `resumeSession()`
+
+Reconnects to an existing session by ID.
+
+```ts
+function resumeSession(
+  sessionId: string,
+  options?: ResumeSessionOptions
+): Promise<DroidSession>;
+```
+
+### `listSessions()`
+
+Discovers saved sessions directly from `~/.factory/sessions/` without spawning `droid`.
+
+```ts
+function listSessions(
+  options?: ListSessionsOptions
+): Promise<SessionMetadata[]>;
+```
+
+#### `ListSessionsOptions`
+
+| Field             | Type      | Description                                                       |
+| :---------------- | :-------- | :---------------------------------------------------------------- |
+| `cwd`             | `string`  | Scope results to a project directory. Defaults to `process.cwd()` |
+| `fetchOutsideCWD` | `boolean` | Return sessions across all projects                               |
+| `numSessions`     | `number`  | Maximum number of sessions to return                              |
+| `sessionsDir`     | `string`  | Override the session storage root                                 |
+
+#### Returned `SessionMetadata`
+
+Common fields include:
+
+- `id`
+- `title`
+- `sessionTitle`
+- `owner`
+- `messageCount`
+- `modifiedTime`
+- `createdTime`
+- `isFavorite`
+- `cwd`
+- `decompSessionType`
+- `decompMissionId`
+
+Archived sessions are excluded automatically, and results are sorted by `modifiedTime` descending.
+
+## `DroidSession`
+
+Returned by `createSession()` and `resumeSession()`.
+
+### Core methods
+
+| Method                   | Description                                                            |
+| :----------------------- | :--------------------------------------------------------------------- |
+| `stream(text, options?)` | Sends a message and yields `DroidMessage` events until `turn_complete` |
+| `send(text, options?)`   | Sends a message and returns aggregated text, messages, and token usage |
+| `interrupt()`            | Gracefully interrupts the current turn                                 |
+| `close()`                | Closes the underlying connection                                       |
+| `updateSettings(params)` | Updates model/session settings                                         |
+| `enterSpecMode(params?)` | Switches the current session into spec mode                            |
+
+### Session utilities
+
+| Method                    | Description                                            |
+| :------------------------ | :----------------------------------------------------- |
+| `forkSession()`           | Creates a new server-side session from the current one |
+| `renameSession(params)`   | Renames the current session                            |
+| `compactSession(params?)` | Requests server-side compaction                        |
+| `getRewindInfo(params)`   | Fetches rewind metadata                                |
+| `executeRewind(params)`   | Executes a rewind                                      |
+
+### MCP and discovery helpers
+
+| Method                              | Description                                              |
+| :---------------------------------- | :------------------------------------------------------- |
+| `addMcpServer(params)`              | Adds an MCP server                                       |
+| `removeMcpServer(params)`           | Removes an MCP server                                    |
+| `toggleMcpServer(params)`           | Enables or disables a server                             |
+| `listMcpServers()`                  | Lists configured MCP servers                             |
+| `listMcpTools()`                    | Lists tools exposed by connected MCP servers             |
+| `authenticateMcpServer(params)`     | Starts MCP OAuth/authentication flow                     |
+| `listSkills()`                      | Lists available skills                                   |
+| `listTools(params?)`                | Lists the exec tool catalog and current allow/deny state |
+| `onNotification(callback, filter?)` | Subscribes to raw session notifications                  |
+
+### Properties
+
+| Property     | Type                                           | Description                 |
+| :----------- | :--------------------------------------------- | :-------------------------- |
+| `sessionId`  | `string`                                       | Active session ID           |
+| `initResult` | `InitializeSessionResult \| LoadSessionResult` | Raw initialize/load payload |
+
+### Message attachments
+
+`session.stream()` and `session.send()` accept `MessageOptions`:
+
+| Field    | Type                  | Description                      |
+| :------- | :-------------------- | :------------------------------- |
+| `images` | `Base64ImageSource[]` | Inline image attachments         |
+| `files`  | `DocumentSource[]`    | Inline file/document attachments |
+
+### `DroidResult`
+
+Returned by `session.send()`:
+
+| Field        | Type                       | Description                       |
+| :----------- | :------------------------- | :-------------------------------- |
+| `text`       | `string`                   | Concatenated assistant text       |
+| `messages`   | `DroidMessage[]`           | All stream messages from the turn |
+| `tokenUsage` | `TokenUsageUpdate \| null` | Final token usage if available    |
+
+## Stream message model
+
+All streamed events are part of the `DroidMessage` union and are discriminated by `type`.
+
+### Common message types
+
+| Type                    | Description                                 |
+| :---------------------- | :------------------------------------------ |
+| `assistant_text_delta`  | Assistant text token                        |
+| `thinking_text_delta`   | Thinking/reasoning token                    |
+| `tool_use`              | Tool invocation                             |
+| `tool_result`           | Tool result                                 |
+| `tool_progress`         | Tool progress update                        |
+| `working_state_changed` | Agent state transition                      |
+| `token_usage_update`    | Token counter update                        |
+| `create_message`        | Full assistant message                      |
+| `permission_resolved`   | Permission outcome                          |
+| `settings_updated`      | Session settings changed                    |
+| `session_title_updated` | Session title changed                       |
+| `mcp_status_changed`    | MCP status changed                          |
+| `mcp_auth_required`     | MCP authentication required                 |
+| `mcp_auth_completed`    | MCP authentication completed                |
+| `error`                 | Error from the process                      |
+| `turn_complete`         | End-of-turn sentinel synthesized by the SDK |
+
+### Mission and AGI messages
+
+When running in `DroidInteractionMode.AGI`, the stream can also emit:
+
+- `mission_state_changed`
+- `mission_features_changed`
+- `mission_progress_entry`
+- `mission_heartbeat`
+- `mission_worker_started`
+- `mission_worker_completed`
+
+## Configuration and enums
+
+High-value exported enums include:
+
+- `DroidInteractionMode`
+- `AutonomyLevel`
+- `ReasoningEffort`
+- `ToolConfirmationOutcome`
+- `ToolConfirmationType`
+- `SessionNotificationType`
+- `DroidWorkingState`
+- `McpServerType`
+- `McpServerStatus`
+- `McpAuthOutcome`
+- `MissionState`
+- `FeatureStatus`
+- `SettingsLevel`
+- `SkillLocation`
+
+### Common `CreateSessionOptions`
+
+`CreateSessionOptions` supports the main runtime controls:
+
+| Field                           | Description                                        |
+| :------------------------------ | :------------------------------------------------- |
+| `cwd`                           | Working directory                                  |
+| `machineId`                     | Machine identifier passed during initialization    |
+| `modelId`                       | Default model                                      |
+| `autonomyLevel`                 | Command autonomy level                             |
+| `interactionMode`               | `Auto`, `Spec`, or `AGI`                           |
+| `reasoningEffort`               | LLM reasoning depth                                |
+| `specModeModelId`               | Spec-mode model override                           |
+| `specModeReasoningEffort`       | Spec-mode reasoning override                       |
+| `mcpServers`                    | Initial MCP server configs                         |
+| `enabledToolIds`                | Explicit tool allowlist                            |
+| `disabledToolIds`               | Explicit tool denylist                             |
+| `tags`                          | Session tags; the SDK also appends its own SDK tag |
+| `permissionHandler`             | Tool confirmation callback                         |
+| `askUserHandler`                | Structured user-input callback                     |
+| `transport`                     | Custom transport override                          |
+| `execPath` / `execArgs` / `env` | Subprocess configuration                           |
+| `abortSignal`                   | External cancellation signal                       |
+
+## Permission and ask-user handling
+
+The high-level APIs support:
+
+- `permissionHandler` for tool approval decisions
+- `askUserHandler` for structured clarification flows
+
+For spec mode, approval flows also support fresh-session outcomes such as `ToolConfirmationOutcome.ProceedNewSessionHigh`.
+
+## MCP support
+
+The SDK supports:
+
+- configuring MCP servers at session startup
+- adding/removing/toggling servers during a session
+- listing MCP servers and tools
+- starting authentication flows with `authenticateMcpServer()`
+- receiving `mcp_auth_required` and `mcp_auth_completed` stream events
+
+Advanced auth controls such as cancelling or clearing MCP auth are available on the low-level `DroidClient`.
+
+## Low-level APIs
+
+Most users should use `query()` and `DroidSession`, but the package also exports lower layers.
+
+### `ProcessTransport`
+
+Spawns `droid exec --input-format stream-jsonrpc --output-format stream-jsonrpc` and implements the transport interface used by the client.
+
+### `ProtocolEngine`
+
+Handles JSON-RPC framing, request/response correlation, notifications, permission requests, and ask-user requests.
+
+### `DroidClient`
+
+Low-level typed JSON-RPC client. Use it when you need direct RPC access beyond `DroidSession`.
+
+Notable client-only capabilities include:
+
+- `killWorkerSession()`
+- `cancelMcpAuth()`
+- `clearMcpAuth()`
+- `submitMcpAuthCode()`
+- `listMcpRegistry()`
+- `toggleMcpTool()`
+- `submitBugReport()`
+
+## Runtime validation and schemas
+
+The package exports its Zod schema surface from `src/schemas/index.ts`, including:
+
+- request and response schemas
+- notification schemas
+- enum schemas and constants
+- message/content schemas
+- mission schemas
+- MCP schemas
+
+This makes it possible to validate protocol payloads at runtime in advanced integrations.
+
+## Errors
+
+The SDK exports these custom errors:
+
+| Error                  | Description                               |
+| :--------------------- | :---------------------------------------- |
+| `ConnectionError`      | Failed to connect to the Droid subprocess |
+| `ProtocolError`        | JSON-RPC or protocol-level failure        |
+| `SessionError`         | Base session error                        |
+| `SessionNotFoundError` | Requested session does not exist          |
+| `TimeoutError`         | RPC timed out                             |
+| `ProcessExitError`     | The subprocess exited unexpectedly        |
+
+## Feature coverage in this document
+
+This reference intentionally documents only features confirmed in the current SDK implementation and recent shipped commits, including:
+
+- spec mode controls
+- tool controls
+- initialization metadata
+- session forking
+- filesystem-based session discovery
+- rename, compact, rewind, and MCP/session management APIs

package/examples/.gitkeep

@@ -0,0 +1 @@
+

package/examples/abort-session-stream.ts

@@ -0,0 +1,67 @@
+/**
+ * Manual smoke test for cancelling `session.stream(..., { abortSignal })`.
+ *
+ * Starts a long-running streaming turn, aborts it after a short delay, then
+ * verifies the stream rejects with the abort reason.
+ *
+ * Usage:
+ *   npx tsx examples/abort-session-stream.ts
+ *   npx tsx examples/abort-session-stream.ts 3000
+ */
+
+import { createSession, DroidMessageType } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const abortAfterMs = Number(process.argv[2] ?? 2000);
+  if (!Number.isFinite(abortAfterMs) || abortAfterMs <= 0) {
+    throw new Error('Abort delay must be a positive number of milliseconds.');
+  }
+
+  const controller = new AbortController();
+  const session = await createSession({ cwd: process.cwd() });
+  let textDeltaCount = 0;
+  let receivedText = '';
+
+  const timeout = setTimeout(() => {
+    controller.abort(new Error(`Aborted after ${abortAfterMs}ms`));
+  }, abortAfterMs);
+
+  try {
+    console.log(`Session created: ${session.sessionId}`);
+    console.log(`Aborting after ${abortAfterMs}ms\n`);
+
+    const prompt =
+      'Write a long, detailed explanation of how compilers work, including ' +
+      'lexing, parsing, semantic analysis, optimization, and code generation.';
+
+    for await (const message of session.stream(prompt, {
+      abortSignal: controller.signal,
+    })) {
+      if (message.type === DroidMessageType.AssistantTextDelta) {
+        textDeltaCount++;
+        receivedText += message.text;
+        process.stdout.write(message.text);
+      }
+    }
+
+    throw new Error('Expected stream to abort, but it completed normally.');
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('Aborted after')) {
+      console.log('\n\n=== Abort confirmed ===');
+      console.log(`Received text deltas before abort: ${textDeltaCount}`);
+      console.log(`Received characters before abort: ${receivedText.length}`);
+      return;
+    }
+
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    await session.close();
+    console.log('Session closed.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/droid-dev-structured-output.ts

@@ -0,0 +1,44 @@
+/**
+ * One-off integration smoke test for JSON output against droid-dev.
+ *
+ * Usage:
+ *   npx tsx examples/droid-dev-structured-output.ts
+ *   DROID_EXEC_PATH=/path/to/droid-dev npx tsx examples/droid-dev-structured-output.ts
+ */
+
+import { z } from 'zod';
+
+import { run } from '../src/index.js';
+
+const PersonSchema = z.object({
+  name: z.literal('Ada Lovelace'),
+  language: z.literal('TypeScript'),
+  score: z.number(),
+});
+
+async function main(): Promise<void> {
+  const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid-dev';
+
+  const result = await run(
+    [
+      'Return a structured object for Ada Lovelace.',
+      'Use name "Ada Lovelace", language "TypeScript", and score 99.',
+      'Return only valid JSON and do not include markdown fences.',
+    ].join(' '),
+    {
+      execPath,
+      cwd: process.cwd(),
+    }
+  );
+
+  const parsed = PersonSchema.parse(JSON.parse(result.text));
+
+  console.log(`droid executable: ${execPath}`);
+  console.log('structured output:', JSON.stringify(parsed, null, 2));
+  console.log(`messages received: ${result.messages.length}`);
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/fork-session.ts

@@ -0,0 +1,42 @@
+/**
+ * Fork session example.
+ *
+ * Demonstrates:
+ * - creating a session and establishing some context
+ * - calling `forkSession()` to get a new server-side session ID
+ * - resuming the fork and continuing from the copied context
+ *
+ * Usage:
+ *   npx tsx examples/fork-session.ts
+ */
+
+import { createSession, resumeSession } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const session = await createSession({ cwd: process.cwd() });
+  let fork: Awaited<ReturnType<typeof resumeSession>> | null = null;
+
+  try {
+    console.log(`Original session: ${session.sessionId}\n`);
+
+    await session.send('Remember this phrase exactly: mango sunrise');
+
+    const { newSessionId } = await session.forkSession();
+    console.log(`Forked session:   ${newSessionId}\n`);
+
+    fork = await resumeSession(newSessionId, { cwd: process.cwd() });
+
+    const result = await fork.send('What phrase did I ask you to remember?');
+    console.log('Fork response:');
+    console.log(result.text);
+  } finally {
+    await fork?.close();
+    await session.close();
+    console.log('\nBoth sessions closed.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/init-metadata.ts

@@ -0,0 +1,76 @@
+/**
+ * Initialization metadata example.
+ *
+ * Demonstrates:
+ * - `query().sessionId`, `query().initResult`, and `query().initialized`
+ * - `session.initResult` from `createSession()`
+ * - `resumed.initResult` from `resumeSession()`
+ *
+ * Usage:
+ *   npx tsx examples/init-metadata.ts
+ */
+
+import {
+  createSession,
+  DroidMessageType,
+  query,
+  resumeSession,
+} from '../src/index.js';
+
+async function main(): Promise<void> {
+  const stream = query({
+    prompt: 'Reply with "ready" and nothing else.',
+    cwd: process.cwd(),
+  });
+
+  console.log('=== query() metadata ===');
+  console.log(`Before initialization: sessionId=${String(stream.sessionId)}`);
+  console.log(`Before initialization: initResult=${String(stream.initResult)}`);
+
+  const initialized = await stream.initialized;
+  console.log(`After initialization: sessionId=${initialized.sessionId}`);
+  console.log(`Model: ${String(initialized.settings.modelId)}`);
+  console.log(
+    `Cached initResult matches initialized: ${String(stream.initResult === initialized)}`
+  );
+
+  let text = '';
+  for await (const msg of stream) {
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      text += msg.text;
+    }
+  }
+  console.log(`Response: ${JSON.stringify(text.trim())}\n`);
+
+  console.log('=== createSession() / resumeSession() metadata ===');
+  const session = await createSession({ cwd: process.cwd() });
+  let resumed: Awaited<ReturnType<typeof resumeSession>> | null = null;
+
+  try {
+    console.log(`Created session: ${session.sessionId}`);
+    console.log(
+      `createSession().initResult.settings.modelId=${String(session.initResult.settings.modelId)}`
+    );
+
+    resumed = await resumeSession(session.sessionId, {
+      cwd: process.cwd(),
+    });
+
+    console.log(`Resumed session: ${resumed.sessionId}`);
+    console.log(
+      `resumeSession().initResult.cwd=${String(resumed.initResult.cwd)}`
+    );
+    console.log(
+      `resumeSession().initResult.availableModels=${String(resumed.initResult.availableModels?.length ?? 0)}`
+    );
+  } finally {
+    await resumed?.close();
+    await session.close();
+    console.log('\nSessions closed.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/interrupt-session.ts

@@ -0,0 +1,67 @@
+/**
+ * Interrupt session example.
+ *
+ * Demonstrates using `session.interrupt()` to stop the agent mid-turn.
+ * Starts a streaming turn with a long-running prompt, waits for a few
+ * `AssistantTextDelta` messages, then sends an interrupt and continues
+ * consuming the stream until `TurnComplete`.
+ *
+ * Usage:
+ *   npx tsx examples/interrupt-session.ts
+ */
+
+import { createSession, DroidMessageType } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const session = await createSession({ cwd: process.cwd() });
+  try {
+    console.log(`Session created: ${session.sessionId}\n`);
+
+    const prompt =
+      'Write a detailed essay about the history of computing, from the ' +
+      'earliest mechanical calculators to modern quantum computers.';
+    console.log(`Prompt: "${prompt}"\n`);
+
+    let deltaCount = 0;
+    let interrupted = false;
+
+    for await (const msg of session.stream(prompt)) {
+      switch (msg.type) {
+        case DroidMessageType.AssistantTextDelta:
+          deltaCount++;
+          process.stdout.write(msg.text);
+
+          if (deltaCount === 5 && !interrupted) {
+            interrupted = true;
+            console.log('\n\n>>> Sending interrupt after 5 text deltas...\n');
+            await session.interrupt();
+          }
+          break;
+
+        case DroidMessageType.TurnComplete:
+          console.log('\n\n--- Turn complete ---');
+          console.log(`Total text deltas received: ${deltaCount}`);
+          console.log(
+            interrupted
+              ? 'Session was interrupted successfully.'
+              : 'Session completed without interruption.'
+          );
+          if (msg.tokenUsage) {
+            console.log(
+              `Tokens — input: ${msg.tokenUsage.inputTokens}, ` +
+                `output: ${msg.tokenUsage.outputTokens}`
+            );
+          }
+          break;
+      }
+    }
+  } finally {
+    await session.close();
+    console.log('\nSession closed.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});