@factory/droid-sdk 0.1.3 → 0.2.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, 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 streaming message support, multi-turn sessions, spec mode, tool controls, initialization metadata, session forking, session discovery, and tool permission handling.
 
 ## Requirements
 
@@ -18,19 +18,19 @@ npm install @factory/droid-sdk
 Send a one-shot prompt and stream the response:
 
 ```ts
-import { query } from "@factory/droid-sdk";
+import { DroidMessageType, query } from '@factory/droid-sdk';
 
 const stream = query({
-  prompt: "What files are in the current directory?",
-  cwd: "/my/project",
+  prompt: 'What files are in the current directory?',
+  cwd: '/my/project',
 });
 
 for await (const msg of stream) {
-  if (msg.type === "assistant_text_delta") {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
     process.stdout.write(msg.text);
   }
-  if (msg.type === "turn_complete") {
-    console.log("\nDone!");
+  if (msg.type === DroidMessageType.TurnComplete) {
+    console.log('\nDone!');
   }
 }
 ```
@@ -40,19 +40,19 @@ for await (const msg of stream) {
 Use `createSession()` for persistent conversations with multiple turns:
 
 ```ts
-import { createSession } from "@factory/droid-sdk";
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: "/my/project" });
+const session = await createSession({ cwd: '/my/project' });
 
 // Streaming turn
-for await (const msg of session.stream("List all TypeScript files")) {
-  if (msg.type === "assistant_text_delta") {
+for await (const msg of session.stream('List all TypeScript files')) {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
     process.stdout.write(msg.text);
   }
 }
 
 // Non-streaming turn
-const result = await session.send("Summarize the project");
+const result = await session.send('Summarize the project');
 console.log(result.text);
 
 await session.close();
@@ -61,32 +61,186 @@ await session.close();
 Resume an existing session by ID:
 
 ```ts
-import { resumeSession } from "@factory/droid-sdk";
+import { resumeSession } from '@factory/droid-sdk';
 
-const session = await resumeSession("session-id-here");
-const result = await session.send("Continue where we left off");
+const session = await resumeSession('session-id-here');
+const result = await session.send('Continue where we left off');
 console.log(result.text);
 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
+
+Inspect the raw initialization metadata from `query()`, `createSession()`, and `resumeSession()`:
+
+```ts
+import { createSession, query, resumeSession } from '@factory/droid-sdk';
+
+const stream = query({
+  prompt: 'Reply with "ready" and nothing else.',
+  cwd: '/my/project',
+});
+
+console.log(stream.sessionId); // null before initialization
+console.log(stream.initResult); // null before initialization
+
+const initialized = await stream.initialized;
+console.log(initialized.sessionId);
+console.log(initialized.settings.modelId);
+stream.abort();
+
+const session = await createSession({ cwd: '/my/project' });
+console.log(session.initResult.settings.modelId);
+
+const resumed = await resumeSession(session.sessionId, { cwd: '/my/project' });
+console.log(resumed.initResult.cwd);
+
+await resumed.close();
+await session.close();
+```
+
+## Spec Mode
+
+Start a session directly in spec mode, or enter spec mode later on an existing session:
+
+```ts
+import {
+  createSession,
+  DroidInteractionMode,
+  ReasoningEffort,
+} from '@factory/droid-sdk';
+
+const session = await createSession({
+  cwd: '/my/project',
+  interactionMode: DroidInteractionMode.Spec,
+  specModeReasoningEffort: ReasoningEffort.High,
+  specModeModelId: 'claude-sonnet-4-20250514',
+});
+
+const plan = await session.send('Draft a plan for adding integration tests');
+console.log(plan.text);
+
+await session.enterSpecMode({
+  specModeReasoningEffort: ReasoningEffort.High,
+});
+
+await session.close();
+```
+
+When handling spec-mode approval, you can approve implementation in the same session with `ToolConfirmationOutcome.ProceedOnce`, or hand off to a fresh session with `ToolConfirmationOutcome.ProceedNewSessionHigh`.
+
+## Tool Controls
+
+Control which exec tools are available at session start, inspect the current tool catalog, and update tool overrides later:
+
+```ts
+import { createSession } from '@factory/droid-sdk';
+
+const session = await createSession({
+  cwd: '/my/project',
+  enabledToolIds: ['Read'],
+  disabledToolIds: ['Execute'],
+});
+
+const { tools } = await session.listTools();
+console.log(
+  tools.map((tool) => ({
+    id: tool.llmId,
+    allowed: tool.currentlyAllowed,
+  }))
+);
+
+await session.updateSettings({
+  disabledToolIds: ['Read', 'Execute'],
+});
+
+await session.close();
+```
+
+## Forking Sessions
+
+Fork the current server-side session and continue from the new session ID:
+
+```ts
+import { createSession, resumeSession } from '@factory/droid-sdk';
+
+const session = await createSession({ cwd: '/my/project' });
+
+await session.send('Remember this phrase: mango sunrise');
+
+const { newSessionId } = await session.forkSession();
+const fork = await resumeSession(newSessionId, { cwd: '/my/project' });
+
+const result = await fork.send('What phrase did I ask you to remember?');
+console.log(result.text);
+
+await fork.close();
+await session.close();
+```
+
+## Listing Sessions
+
+Discover droid sessions saved on disk (mirrors the CLI's `/sessions` command). Reads `~/.factory/sessions/` directly — no droid process is spawned, so this works even when no session is running:
+
+```ts
+import { listSessions } from '@factory/droid-sdk';
+
+// Sessions for the current project (cwd defaults to process.cwd())
+const current = await listSessions();
+
+// 10 most recent sessions in the current project
+const recent = await listSessions({ numSessions: 10 });
+
+// Every session on disk, most recent first
+const all = await listSessions({ fetchOutsideCWD: true });
+
+// 10 most recent sessions across all projects
+const recentAcrossProjects = await listSessions({
+  fetchOutsideCWD: true,
+  numSessions: 10,
+});
+
+// Sessions for a specific other project
+const other = await listSessions({ cwd: '/Users/me/other-repo' });
+
+for (const s of current) {
+  console.log(`[${s.id}] ${s.title} (${s.messageCount} msgs)`);
+}
+```
+
+Each `SessionMetadata` record includes `id`, `title`, `sessionTitle`, `owner`, `messageCount`, `modifiedTime`, `createdTime`, `isFavorite`, `cwd`, `decompSessionType`, and `decompMissionId`. Archived sessions (those with an `archivedAt` in their settings file) are excluded automatically. Results are sorted by `modifiedTime` descending.
+
+`ListSessionsOptions`:
+
+- **`cwd`** — working directory to scope the listing to (default `process.cwd()`). Ignored when `fetchOutsideCWD` is `true`.
+- **`fetchOutsideCWD`** — return sessions from every working directory on disk (default `false`)
+- **`numSessions`** — cap on total sessions returned
+- **`sessionsDir`** — override the sessions root (default `~/.factory/sessions/`)
+
 ## Permission Handling
 
 Handle tool confirmation requests with a custom permission handler:
 
 ```ts
-import { query, ToolConfirmationOutcome } from "@factory/droid-sdk";
+import {
+  DroidMessageType,
+  query,
+  ToolConfirmationOutcome,
+} from '@factory/droid-sdk';
 
 const stream = query({
-  prompt: "Create a hello.txt file",
-  cwd: "/my/project",
+  prompt: 'Create a hello.txt file',
+  cwd: '/my/project',
   permissionHandler(params) {
-    console.log("Tool permission requested:", params);
+    console.log('Tool permission requested:', params);
     return ToolConfirmationOutcome.ProceedOnce;
   },
 });
 
 for await (const msg of stream) {
-  if (msg.type === "assistant_text_delta") {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
     process.stdout.write(msg.text);
   }
 }
@@ -96,11 +250,12 @@ for await (const msg of stream) {
 
 ### Top-Level Functions
 
-| Function | Description |
-|---|---|
-| `query(options)` | One-shot prompt → async generator of `DroidMessage` events |
-| `createSession(options?)` | Create a new multi-turn session → `DroidSession` |
-| `resumeSession(id, options?)` | Resume an existing session → `DroidSession` |
+| Function                      | Description                                                      |
+| ----------------------------- | ---------------------------------------------------------------- |
+| `query(options)`              | One-shot prompt → async generator of `DroidMessage` events       |
+| `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`
 
@@ -109,6 +264,10 @@ Returns an async generator that yields `DroidMessage` events. The returned `Droi
 - **`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.
 
 ### `DroidSession`
 
@@ -119,8 +278,14 @@ Returned by `createSession()` and `resumeSession()`. Key methods:
 - **`interrupt()`** — interrupt the current turn
 - **`close()`** — close the session and release resources
 - **`updateSettings(params)`** — update model, autonomy level, etc.
-- **`addMcpServer(params)`** / **`removeMcpServer(params)`** — manage MCP servers
+- **`enterSpecMode(params?)`** — switch the current session into spec mode
+- **`forkSession()`** — create a forked server-side session and return its new session ID
+- **`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
 - **`sessionId`** — the session ID
+- **`initResult`** — cached `initialize_session` or `load_session` result
 
 ### `DroidResult`
 
@@ -134,18 +299,30 @@ Returned by `session.send()`:
 
 All messages have a discriminated `type` field:
 
-| 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 |
-| `error` | Error event from the process |
+```ts
+import { DroidMessageType } from '@factory/droid-sdk';
+
+if (msg.type === DroidMessageType.AssistantTextDelta) {
+  process.stdout.write(msg.text);
+}
+```
+
+| 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            |
 
 ### Options
 
@@ -155,26 +332,33 @@ All messages have a discriminated `type` field:
 - **`cwd`** — working directory for the session
 - **`modelId`** — LLM model identifier
 - **`autonomyLevel`** — `AutonomyLevel` enum value
+- **`interactionMode`** — `DroidInteractionMode` enum value
 - **`reasoningEffort`** — `ReasoningEffort` enum value
+- **`specModeModelId`** — override model used in spec mode
+- **`specModeReasoningEffort`** — override reasoning level used in spec mode
+- **`mcpServers`** — initial MCP server configurations, including SDK-backed MCP servers from `createSdkMcpServer()`
+- **`enabledToolIds`** — explicit exec tool allowlist
+- **`disabledToolIds`** — explicit exec tool denylist
 - **`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
 
 ### `DroidClient`
 
-Low-level JSON-RPC client for advanced use. Provides typed methods for all 19 protocol operations. 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()` and `renameSession()`. Most users should prefer `query()` and `createSession()`.
 
 ### Error Types
 
-| Error | Description |
-|---|---|
-| `ConnectionError` | Failed to connect to the droid process |
-| `ProtocolError` | JSON-RPC protocol error |
-| `SessionError` | Base session error |
-| `SessionNotFoundError` | Session ID not found |
-| `TimeoutError` | Request timed out |
-| `ProcessExitError` | Droid subprocess exited unexpectedly |
+| Error                  | Description                            |
+| ---------------------- | -------------------------------------- |
+| `ConnectionError`      | Failed to connect to the droid process |
+| `ProtocolError`        | JSON-RPC protocol error                |
+| `SessionError`         | Base session error                     |
+| `SessionNotFoundError` | Session ID not found                   |
+| `TimeoutError`         | Request timed out                      |
+| `ProcessExitError`     | Droid subprocess exited unexpectedly   |
 
 ## Examples
 
@@ -182,7 +366,15 @@ See the [`examples/`](./examples) directory for runnable examples:
 
 - **[`simple-query.ts`](./examples/simple-query.ts)** — one-shot query with streaming output
 - **[`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
 - **[`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
+- **[`tool-controls.ts`](./examples/tool-controls.ts)** — configure allow/deny lists and inspect tool availability
+- **[`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
 
 ## License