@factory/droid-sdk 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @factory/droid-sdk
 
-TypeScript SDK for the [Factory](https://factory.ai) Droid CLI. Provides a high-level API for interacting with Droid as a subprocess, with streaming message support, multi-turn sessions, spec mode, tool controls, initialization metadata, session forking, session discovery, and tool permission handling.
+TypeScript SDK for the [Factory](https://factory.ai) Droid CLI. Provides a high-level API for interacting with Droid as a subprocess, with one-shot prompts, streaming messages, multi-turn sessions, structured output, SDK-backed MCP tools, spec mode, tool controls, initialization metadata, session forking, session discovery, and tool permission handling.
 
 ## Requirements
 
@@ -15,26 +15,71 @@ npm install @factory/droid-sdk
 
 ## Quick Start
 
-Send a one-shot prompt and stream the response:
+Send a one-shot prompt and get the aggregated result:
 
 ```ts
-import { DroidMessageType, query } from '@factory/droid-sdk';
+import { run } from '@factory/droid-sdk';
 
-const stream = query({
-  prompt: 'What files are in the current directory?',
+const result = await run('What files are in the current directory?', {
   cwd: '/my/project',
 });
 
-for await (const msg of stream) {
-  if (msg.type === DroidMessageType.AssistantTextDelta) {
-    process.stdout.write(msg.text);
-  }
-  if (msg.type === DroidMessageType.TurnComplete) {
-    console.log('\nDone!');
+console.log(result.text);
+```
+
+Create a session when you want to stream one or more turns:
+
+```ts
+import { DroidMessageType, createSession } from '@factory/droid-sdk';
+
+const session = await createSession({ cwd: '/my/project' });
+
+try {
+  for await (const msg of session.stream(
+    'What files are in the current directory?'
+  )) {
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      process.stdout.write(msg.text);
+    }
+    if (msg.type === DroidMessageType.Result) {
+      console.log('\nDone!');
+    }
   }
+} finally {
+  await session.close();
 }
 ```
 
+## Structured Output
+
+Request a JSON object that matches a JSON Schema:
+
+```ts
+import { OutputFormatType, run } from '@factory/droid-sdk';
+
+const result = await run('Pick a favorite number between 1 and 42.', {
+  cwd: '/my/project',
+  outputFormat: {
+    type: OutputFormatType.JsonSchema,
+    schema: {
+      type: 'object',
+      properties: {
+        favoriteNumber: {
+          type: 'number',
+          minimum: 1,
+          maximum: 42,
+        },
+      },
+      required: ['favoriteNumber'],
+    },
+  },
+});
+
+console.log(result.structuredOutput?.favoriteNumber);
+```
+
+Structured output is available on `run()` and `session.stream(prompt, options)` through the `outputFormat` message option. `run()` parses the final object into `result.structuredOutput`; streaming callers can read and parse the final assistant message themselves.
+
 ## Multi-Turn Sessions
 
 Use `createSession()` for persistent conversations with multiple turns:
@@ -43,6 +88,7 @@ Use `createSession()` for persistent conversations with multiple turns:
 import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
 const session = await createSession({ cwd: '/my/project' });
+console.log(session.sessionId);
 
 // Streaming turn
 for await (const msg of session.stream('List all TypeScript files')) {
@@ -51,50 +97,88 @@ for await (const msg of session.stream('List all TypeScript files')) {
   }
 }
 
-// Non-streaming turn
-const result = await session.send('Summarize the project');
-console.log(result.text);
+// Later turns use the same streaming API
+for await (const msg of session.stream('Summarize the project')) {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
+    process.stdout.write(msg.text);
+  }
+}
 
 await session.close();
 ```
 
-Resume an existing session by ID:
+Use `session.sessionId` to persist the session ID, then resume it later:
 
 ```ts
 import { resumeSession } from '@factory/droid-sdk';
 
-const session = await resumeSession('session-id-here');
-const result = await session.send('Continue where we left off');
-console.log(result.text);
+const session = await resumeSession(savedSessionId);
+for await (const msg of session.stream('Continue where we left off')) {
+  // Handle streamed DroidMessage events.
+}
 await session.close();
 ```
 
 The returned `DroidSession` also exposes `session.initResult`, which contains the raw `initialize_session` or `load_session` result returned by the JSON-RPC server.
 
-## Initialization Metadata
+## SDK-backed MCP Tools
 
-Inspect the raw initialization metadata from `query()`, `createSession()`, and `resumeSession()`:
+Expose in-process TypeScript tools to Droid through MCP:
 
 ```ts
-import { createSession, query, resumeSession } from '@factory/droid-sdk';
+import { z } from 'zod';
 
-const stream = query({
-  prompt: 'Reply with "ready" and nothing else.',
+import {
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  createSession,
+  createSdkMcpServer,
+  tool,
+} from '@factory/droid-sdk';
+
+const sdkTools = createSdkMcpServer({
+  name: 'sdk-tools',
+  tools: [
+    tool(
+      'favorite_number',
+      'Returns a favorite number for a person',
+      { name: z.string() },
+      ({ name }) => `${name}'s favorite number is 42.`
+    ),
+  ],
+});
+
+const session = await createSession({
   cwd: '/my/project',
+  mcpServers: [sdkTools],
+  permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
 });
 
-console.log(stream.sessionId); // null before initialization
-console.log(stream.initResult); // null before initialization
+for await (const msg of session.stream(
+  'Use the favorite_number tool for Ada and tell me the answer.'
+)) {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
+    process.stdout.write(msg.text);
+  }
+}
+
+await session.close();
+```
+
+`createSdkMcpServer()` is managed by the SDK session lifecycle. Use `tool()` with a Zod object shape for typed tool input validation.
 
-const initialized = await stream.initialized;
-console.log(initialized.sessionId);
-console.log(initialized.settings.modelId);
-stream.abort();
+## Initialization Metadata
+
+Inspect the raw initialization metadata from `createSession()` and `resumeSession()`:
+
+```ts
+import { createSession, resumeSession } from '@factory/droid-sdk';
 
 const session = await createSession({ cwd: '/my/project' });
+console.log(session.sessionId);
 console.log(session.initResult.settings.modelId);
 
-const resumed = await resumeSession(session.sessionId, { cwd: '/my/project' });
+const resumed = await resumeSession(session.sessionId);
 console.log(resumed.initResult.cwd);
 
 await resumed.close();
@@ -107,6 +191,7 @@ Start a session directly in spec mode, or enter spec mode later on an existing s
 
 ```ts
 import {
+  DroidMessageType,
   createSession,
   DroidInteractionMode,
   ReasoningEffort,
@@ -119,8 +204,13 @@ const session = await createSession({
   specModeModelId: 'claude-sonnet-4-20250514',
 });
 
-const plan = await session.send('Draft a plan for adding integration tests');
-console.log(plan.text);
+for await (const msg of session.stream(
+  'Draft a plan for adding integration tests'
+)) {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
+    process.stdout.write(msg.text);
+  }
+}
 
 await session.enterSpecMode({
   specModeReasoningEffort: ReasoningEffort.High,
@@ -164,17 +254,28 @@ await session.close();
 Fork the current server-side session and continue from the new session ID:
 
 ```ts
-import { createSession, resumeSession } from '@factory/droid-sdk';
+import {
+  DroidMessageType,
+  createSession,
+  resumeSession,
+} from '@factory/droid-sdk';
 
 const session = await createSession({ cwd: '/my/project' });
 
-await session.send('Remember this phrase: mango sunrise');
+for await (const _msg of session.stream(
+  'Remember this phrase: mango sunrise'
+)) {
+  // Consume the turn.
+}
 
 const { newSessionId } = await session.forkSession();
-const fork = await resumeSession(newSessionId, { cwd: '/my/project' });
+const fork = await resumeSession(newSessionId);
 
-const result = await fork.send('What phrase did I ask you to remember?');
-console.log(result.text);
+for await (const msg of fork.stream('What phrase did I ask you to remember?')) {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
+    process.stdout.write(msg.text);
+  }
+}
 
 await fork.close();
 await session.close();
@@ -226,12 +327,11 @@ Handle tool confirmation requests with a custom permission handler:
 ```ts
 import {
   DroidMessageType,
-  query,
+  createSession,
   ToolConfirmationOutcome,
 } from '@factory/droid-sdk';
 
-const stream = query({
-  prompt: 'Create a hello.txt file',
+const session = await createSession({
   cwd: '/my/project',
   permissionHandler(params) {
     console.log('Tool permission requested:', params);
@@ -239,10 +339,14 @@ const stream = query({
   },
 });
 
-for await (const msg of stream) {
-  if (msg.type === DroidMessageType.AssistantTextDelta) {
-    process.stdout.write(msg.text);
+try {
+  for await (const msg of session.stream('Create a hello.txt file')) {
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      process.stdout.write(msg.text);
+    }
   }
+} finally {
+  await session.close();
 }
 ```
 
@@ -252,48 +356,46 @@ for await (const msg of stream) {
 
 | Function                      | Description                                                      |
 | ----------------------------- | ---------------------------------------------------------------- |
-| `query(options)`              | One-shot prompt → async generator of `DroidMessage` events       |
+| `run(prompt, options?)`       | One-shot prompt → aggregated `DroidResult`                       |
 | `createSession(options?)`     | Create a new multi-turn session → `DroidSession`                 |
 | `resumeSession(id, options?)` | Resume an existing session → `DroidSession`                      |
 | `listSessions(options?)`      | List droid sessions saved on disk → `Promise<SessionMetadata[]>` |
-
-### `query(options): DroidQuery`
-
-Returns an async generator that yields `DroidMessage` events. The returned `DroidQuery` object also exposes:
-
-- **`interrupt()`** — gracefully interrupt the agent's current turn
-- **`abort()`** — forcefully kill the subprocess
-- **`sessionId`** — the session ID (available after initialization)
-- **`initResult`** — cached `initialize_session` result, or `null` before initialization
-- **`initialized`** — promise that resolves with the `initialize_session` result
-
-`query(options)` also accepts an `abortSignal` for external cancellation.
+| `createSdkMcpServer(options)` | Create an SDK-managed MCP server for in-process tools            |
+| `tool(...)`                   | Define a typed SDK-backed MCP tool                               |
 
 ### `DroidSession`
 
 Returned by `createSession()` and `resumeSession()`. Key methods:
 
-- **`stream(text, options?)`** — send a message, returns async generator of `DroidMessage`
-- **`send(text, options?)`** — send a message, returns aggregated `DroidResult`
+- **`stream(prompt, options?)`** — stream `DroidMessage` events for one turn
 - **`interrupt()`** — interrupt the current turn
 - **`close()`** — close the session and release resources
 - **`updateSettings(params)`** — update model, autonomy level, etc.
 - **`enterSpecMode(params?)`** — switch the current session into spec mode
 - **`forkSession()`** — create a forked server-side session and return its new session ID
+- **`compactSession(params?)`** — compact session history and return the new session ID
+- **`getContextStats()`** — read current context window utilization
 - **`addMcpServer(params)`** / **`removeMcpServer(params)`** / **`toggleMcpServer(params)`** — manage MCP servers
 - **`listMcpServers()`** / **`listMcpTools()`** / **`authenticateMcpServer(params)`** — inspect and authenticate MCP servers
 - **`listTools(params?)`** — inspect the exec tool catalog and current allow/deny state
 - **`renameSession(params)`** — rename the current session
+- **`getRewindInfo(params)`** / **`executeRewind(params)`** — inspect and execute file rewind operations
 - **`sessionId`** — the session ID
 - **`initResult`** — cached `initialize_session` or `load_session` result
 
 ### `DroidResult`
 
-Returned by `session.send()`:
+Returned by `run()`:
 
+- **`sessionId`** — session that produced the result
 - **`text`** — concatenated assistant response text
 - **`messages`** — all `DroidMessage` objects from the turn
 - **`tokenUsage`** — final token usage, or `null`
+- **`durationMs`** — wall-clock time spent consuming the turn
+- **`turnCount`** — number of completed turns observed while consuming the stream
+- **`error`** — first Droid error event from the turn, or `null`
+- **`structuredOutput`** — parsed structured JSON object, or `null`
+- **`success`** — `true` when no Droid error event was emitted
 
 ### `DroidMessage` Types
 
@@ -307,29 +409,45 @@ if (msg.type === DroidMessageType.AssistantTextDelta) {
 }
 ```
 
-| Type                    | Description                             |
-| ----------------------- | --------------------------------------- |
-| `assistant_text_delta`  | Streaming text token from the assistant |
-| `thinking_text_delta`   | Streaming reasoning/thinking token      |
-| `tool_use`              | Tool invocation by the assistant        |
-| `tool_result`           | Result from a tool execution            |
-| `tool_progress`         | Progress update during tool execution   |
-| `working_state_changed` | Agent working state transition          |
-| `token_usage_update`    | Updated token usage counters            |
-| `create_message`        | Full assistant message created          |
-| `turn_complete`         | Sentinel: agent turn finished           |
-| `session_title_updated` | Session title changed                   |
-| `mcp_status_changed`    | MCP server status changed               |
-| `mcp_auth_required`     | MCP authentication required             |
-| `mcp_auth_completed`    | MCP authentication completed            |
-| `error`                 | Error event from the process            |
+| Type                       | Description                                     |
+| -------------------------- | ----------------------------------------------- |
+| `assistant`                | Complete assistant message                      |
+| `user`                     | Complete user message                           |
+| `assistant_text_delta`     | Streaming text token from the assistant         |
+| `assistant_text_complete`  | End of an assistant text block                  |
+| `thinking_text_delta`      | Streaming reasoning/thinking token              |
+| `thinking_text_complete`   | End of a thinking block                         |
+| `tool_call`                | Tool invocation by the assistant                |
+| `tool_call_delta`          | Streaming tool call input                       |
+| `tool_result`              | Result from a tool execution                    |
+| `tool_progress`            | Progress update during tool execution           |
+| `hook`                     | File hook execution event (started or finished) |
+| `working_state_changed`    | Agent working state transition                  |
+| `token_usage_update`       | Updated token usage counters                    |
+| `result`                   | End-of-turn sentinel with aggregated metadata   |
+| `session_title_updated`    | Session title changed                           |
+| `settings_updated`         | Session settings changed                        |
+| `permission_resolved`      | Tool permission request resolved                |
+| `mcp_status_changed`       | MCP server status changed                       |
+| `mcp_auth_required`        | MCP authentication required                     |
+| `mcp_auth_completed`       | MCP authentication completed                    |
+| `error`                    | Error event from the process                    |
+| `mission_state_changed`    | Mission state changed                           |
+| `mission_features_changed` | Mission features changed                        |
+| `mission_progress_entry`   | Mission progress log changed                    |
+| `mission_heartbeat`        | Mission heartbeat                               |
+| `mission_worker_started`   | Mission worker started                          |
+| `mission_worker_completed` | Mission worker completed                        |
 
 ### Options
 
-`QueryOptions` and `CreateSessionOptions` accept:
+Session creation options used by `run()` and `createSession()` include:
 
-- **`prompt`** — the user prompt (query only)
 - **`cwd`** — working directory for the session
+- **`execPath`** — path to `droid` executable (default: `"droid"`)
+- **`execArgs`** — extra CLI arguments for the spawned droid process
+- **`env`** — environment variables for the spawned process
+- **`transport`** — provide a custom transport instead of spawning a process
 - **`modelId`** — LLM model identifier
 - **`autonomyLevel`** — `AutonomyLevel` enum value
 - **`interactionMode`** — `DroidInteractionMode` enum value
@@ -342,12 +460,19 @@ if (msg.type === DroidMessageType.AssistantTextDelta) {
 - **`permissionHandler`** — callback for tool confirmations
 - **`askUserHandler`** — callback for interactive questions
 - **`abortSignal`** — standard `AbortSignal` for cancellation
-- **`execPath`** — path to `droid` executable (default: `"droid"`)
-- **`transport`** — provide a custom transport instead of spawning a process
+
+`resumeSession()` accepts the process, transport, handler, `mcpServers`, and `abortSignal` options needed to reconnect to an existing session, but does not accept new-session-only options such as `modelId` or `interactionMode`. `cwd` is intentionally not accepted on resume: the persisted session's working directory is always used. To run in a different directory, create a new session or fork the existing one.
+
+Message APIs (`run()` and `session.stream()`) also accept:
+
+- **`images`** — base64 image attachments
+- **`files`** — document/file attachments
+- **`outputFormat`** — structured output request, currently `OutputFormatType.JsonSchema`
+- **`abortSignal`** — standard `AbortSignal` for turn cancellation
 
 ### `DroidClient`
 
-Low-level JSON-RPC client for advanced use. Provides typed methods for the underlying protocol operations, including `listTools()` and `renameSession()`. Most users should prefer `query()` and `createSession()`.
+Low-level JSON-RPC client for advanced use. Provides typed methods for the underlying protocol operations, including `listTools()`, `renameSession()`, `getRewindInfo()`, and `executeRewind()`. Most users should prefer `run()` and `createSession()`.
 
 ### Error Types
 
@@ -364,10 +489,15 @@ Low-level JSON-RPC client for advanced use. Provides typed methods for the under
 
 See the [`examples/`](./examples) directory for runnable examples:
 
-- **[`simple-query.ts`](./examples/simple-query.ts)** — one-shot query with streaming output
+- **[`session-stream.ts`](./examples/session-stream.ts)** — session streaming output
+- **[`run.ts`](./examples/run.ts)** — one-shot prompt with aggregated result
 - **[`multi-turn-session.ts`](./examples/multi-turn-session.ts)** — multi-turn session lifecycle
 - **[`abort-session-stream.ts`](./examples/abort-session-stream.ts)** — cancel an in-flight streaming session turn with `AbortSignal`
-- **[`init-metadata.ts`](./examples/init-metadata.ts)** — read initialization and load metadata from query/session APIs
+- **[`interrupt-session.ts`](./examples/interrupt-session.ts)** — interrupt a running session turn
+- **[`init-metadata.ts`](./examples/init-metadata.ts)** — read initialization and load metadata from session APIs
+- **[`result-metadata.ts`](./examples/result-metadata.ts)** — inspect `DroidResult` metadata from `run()`
+- **[`structured-output.ts`](./examples/structured-output.ts)** — request and parse structured output
+- **[`droid-dev-structured-output.ts`](./examples/droid-dev-structured-output.ts)** — structured output smoke test with configurable Droid executable
 - **[`permission-handler.ts`](./examples/permission-handler.ts)** — custom permission handling
 - **[`spec-mode-same-session.ts`](./examples/spec-mode-same-session.ts)** — approve a spec and continue in the same session
 - **[`spec-mode-new-session.ts`](./examples/spec-mode-new-session.ts)** — approve a spec and hand off implementation to a new session
@@ -375,6 +505,8 @@ See the [`examples/`](./examples) directory for runnable examples:
 - **[`sdk-mcp-tool.ts`](./examples/sdk-mcp-tool.ts)** — expose SDK-defined tools to Droid through MCP
 - **[`fork-session.ts`](./examples/fork-session.ts)** — fork a session and continue from the new session ID
 - **[`list-sessions.ts`](./examples/list-sessions.ts)** — discover droid sessions saved on disk
+- **[`test-compact.ts`](./examples/test-compact.ts)** — compact session history
+- **[`test-rewind.ts`](./examples/test-rewind.ts)** — use low-level rewind APIs
 
 ## License