@factory/droid-sdk 0.7.0 → 0.8.0

package/docs/typescript-sdk-reference.md

@@ -1,30 +1,31 @@
 # Factory TypeScript SDK
 
-The Factory TypeScript SDK lets applications run Droid, continue conversations,
-stream work, control tools, and connect to a running Droid daemon.
+Use the Factory TypeScript SDK to run Droid from Node.js.
 
 The public npm package is `@factory/droid-sdk`.
 
-This page is the single user-facing SDK guide. The package's exported
-TypeScript declarations remain authoritative for its compile-time API surface.
+This guide covers the high-level public API. The package's exported TypeScript
+declarations define the complete compile-time API.
 
 ## Overview
 
-The SDK has two main runtimes.
+Import the SDK from `@factory/droid-sdk/node`. It starts a Droid CLI subprocess
+and provides session management, streaming, local session discovery, and
+in-process MCP tool APIs.
 
-| Runtime | Import                    | Use it for                                                      |
-| ------- | ------------------------- | --------------------------------------------------------------- |
-| Node    | `@factory/droid-sdk/node` | Scripts, CI, local tools, and apps that can start the Droid CLI |
-| Daemon  | `@factory/droid-sdk`      | Browser or Node apps that connect to an existing Droid daemon   |
+### Choose an API
 
-The Node runtime starts a Droid subprocess for you. The daemon runtime connects
-to a daemon over WebSocket and can manage several sessions through one
-connection.
+| Goal                                    | API               |
+| --------------------------------------- | ----------------- |
+| Run one prompt and get the final result | `run()`           |
+| Keep context across prompts             | `createSession()` |
+| Continue a saved session                | `resumeSession()` |
+| Find saved sessions                     | `listSessions()`  |
 
-The root import is browser-safe. The `/node` import adds subprocess,
-filesystem, local session discovery, and SDK MCP tool APIs.
+Start with `run()` for one prompt. Use a session when later prompts need the
+same conversation history.
 
-## Requirements and installation
+## Install and authenticate
 
 Install the package:
 
@@ -34,9 +35,8 @@ npm install @factory/droid-sdk
 
 The SDK requires Node.js 18 or later.
 
-By default, Node session APIs start the `droid` CLI from `PATH`. You can provide
-a different executable with `execPath`. Supplying a custom `transport` bypasses
-subprocess creation and this requirement.
+By default, the SDK starts the `droid` CLI from `PATH`. Pass `execPath` to use a
+different `droid` executable.
 
 Set an API key:
 
@@ -44,42 +44,30 @@ Set an API key:
 export FACTORY_API_KEY="your-key"
 ```
 
-You can also pass `apiKey` directly when creating a Node session.
-
-### Browser security
-
-The daemon client currently authenticates with a Factory API key. Use browser
-examples only in trusted local tools. Do not ship a Factory API key in a public
-website, commit it to source control, or put it in a URL.
-
-An HTTPS page must connect with `wss://`. Local pages served over HTTP can use
-`ws://`.
+The SDK reads `FACTORY_API_KEY` from the process environment by default. You
+can also pass `apiKey` to `run()`, `createSession()`, or `resumeSession()`.
 
 ## Quick start
 
 ### Run one prompt
 
-**Runtime: Node**
-
 ```ts
 import { run } from '@factory/droid-sdk/node';
 
 const result = await run('Summarize this repository.');
 
 if (!result.success) {
-  throw new Error(result.error?.message ?? 'The run did not complete.');
+  throw new Error(result.error?.message ?? `Run failed: ${result.subtype}`);
 }
 
 console.log(result.text);
 ```
 
-`run()` creates a session, waits for its final result, and closes the session.
-Use it for one-shot work.
+`run()` creates a session, consumes its complete message stream, returns the
+terminal `DroidResult`, and closes the session.
 
 ### Continue a conversation
 
-**Runtime: Node**
-
 ```ts
 import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
 
@@ -102,169 +90,353 @@ try {
 }
 ```
 
-Use a session when later prompts need context from earlier turns.
+In the above example, the second prompt uses context from the first turn.
+Remember to close sessions that your code creates.
+
+## Core concepts
+
+### Session
+
+A session holds conversation history, settings, and a working directory. Create
+one with `createSession()` or load a saved session with `resumeSession()`.
+
+### Turn
+
+A turn starts when you send one prompt with `session.stream()`. A session can
+run one turn at a time.
+
+### Stream message
+
+`session.stream()` returns an async iterable of complete messages. Narrow each
+message by its `type`. Messages can report user input, assistant output, tool
+activity, hooks, errors, and a terminal `DroidResult`.
+
+### Result
+
+A normally completed turn ends with a `DroidResult`. `run()` consumes the stream and returns that same result type. See [Streaming and results](#streaming-and-results) for result handling, errors, token usage, and cancellation.
 
-### Connect to a daemon
+### Ownership and cleanup
 
-**Runtime: Node or trusted local browser**
+Cleanup depends on how the session was created.
+
+| API               | Cleanup                          |
+| ----------------- | -------------------------------- |
+| `run()`           | Closes its session automatically |
+| `createSession()` | Call `await session.close()`     |
+| `resumeSession()` | Call `await session.close()`     |
+
+Use `finally` blocks so cleanup also runs after an error.
+
+## Models
+
+Model IDs are strings because availability depends on the account,
+organization policy, and daemon configuration. Omit `modelId` to use the Droid
+default.
+
+### Discover available models
+
+**Runtime: Node.js**
 
 ```ts
-import { connectToDaemon, DroidMessageType } from '@factory/droid-sdk';
+import { listModels } from '@factory/droid-sdk/node';
 
-async function runWithDaemon(apiKey: string, cwd: string) {
-  const droid = await connectToDaemon({
-    url: 'ws://127.0.0.1:37643',
-    auth: { apiKey },
-  });
+const models = await listModels();
+const catalog = await listModels({ includeDisabled: true });
+```
 
-  const session = await droid.sessions.create({ cwd });
+The Node helper starts a one-shot Droid process, requests the catalog without
+creating a session, and closes the process before returning.
 
-  try {
-    for await (const message of session.stream('Summarize this repository.')) {
-      if (message.type === DroidMessageType.Assistant) {
-        console.log(message.text);
-      }
+**Runtime: Daemon** (`droid` is a client returned by `connectToDaemon()`)
+
+```ts
+const models = await droid.models.list();
+const catalog = await droid.models.list({ includeDisabled: true });
+
+for (const model of models) {
+  console.log(model.id, model.supportedReasoningEfforts);
+}
+```
+
+`includeDisabled` defaults to `false`, so both APIs return only selectable
+models when options are omitted. When disabled models are requested, every
+disabled entry includes a `disabledReason` for display. Regular organization
+members cannot enable these models. An organization manager may be able to
+change the model policy or complete a required opt-in.
+
+Runnable examples:
+
+- Node: [`examples/node/model-discovery.ts`](../examples/node/model-discovery.ts)
+- Browser and daemon: [`examples/browser/daemon-model-discovery.ts`](../examples/browser/daemon-model-discovery.ts)
+
+Each available model includes:
+
+| Field                       | Meaning                                        |
+| --------------------------- | ---------------------------------------------- |
+| `id`                        | Value accepted by `modelId`                    |
+| `displayName`               | Full display name                              |
+| `shortDisplayName`          | Compact display name                           |
+| `modelProvider`             | Model provider                                 |
+| `supportedReasoningEfforts` | Reasoning levels accepted by the model         |
+| `defaultReasoningEffort`    | Reasoning level used when none is supplied     |
+| `isCustom`                  | Whether the model is user-configured           |
+| `disabled`                  | Whether policy prevents selecting the model    |
+| `disabledReason`            | Required explanation when `disabled` is `true` |
+| `noImageSupport`            | Whether image input is unavailable             |
+| `supportsImageGeneration`   | Whether the model can generate images          |
+| `kind`                      | Model or router classification, when present   |
+
+Other optional fields provide tier, token multiplier, and display badges.
+
+### Node and daemon discovery
+
+| Runtime | Discovery API         | Lifecycle                                |
+| ------- | --------------------- | ---------------------------------------- |
+| Node    | `listModels(options)` | Uses and closes a one-shot Droid process |
+| Daemon  | `droid.models.list()` | Reuses the connected daemon client       |
+
+Both APIs return the same `ModelInfo[]` type and include built-in models plus
+configured custom models.
+
+### Select a model
+
+Pass a configured model ID when creating a session or running one prompt.
+
+```ts
+import {
+  createSession,
+  DroidMessageType,
+  ReasoningEffort,
+} from '@factory/droid-sdk/node';
+
+const session = await createSession({
+  modelId: 'model-id',
+  reasoningEffort: ReasoningEffort.High,
+});
+
+try {
+  for await (const message of session.stream('Review this repository.')) {
+    if (message.type === DroidMessageType.Assistant) {
+      console.log(message.text);
     }
-  } finally {
-    await Promise.allSettled([session.close()]);
-    droid.disconnect();
   }
+} finally {
+  await session.close();
 }
 ```
 
-In browser code, obtain both arguments from trusted local configuration. This
-does not make an API key secret from browser JavaScript, so keep this pattern
-restricted to trusted local pages.
+For an existing session, call `updateSettings()`:
 
-## Core concepts
+```ts
+await session.updateSettings({
+  modelId: 'model-id',
+  reasoningEffort: ReasoningEffort.High,
+});
+```
 
-### Session
+Set `reasoningEffort` only to a level supported by the selected model. Omit it
+to use the model's configured default.
 
-A session holds conversation history, settings, and a working directory.
+Runnable example: [`examples/node/model-selection.ts`](../examples/node/model-selection.ts)
 
-Node sessions are created with `createSession()` or loaded with
-`resumeSession()`. Daemon sessions are created or resumed through
-`droid.sessions`.
+### Use Auto Router
 
-### Turn
+Set `modelId` to `"auto"` to let Factory choose a model for each turn.
 
-A turn starts when you send one prompt with `session.stream()`. A session can
-run one turn at a time. Different daemon sessions can run turns concurrently.
+```ts
+import { run } from '@factory/droid-sdk/node';
 
-### Stream message
+const result = await run('Find the cause of the failing tests.', {
+  modelId: 'auto',
+});
 
-`session.stream()` yields a discriminated message union. The default stream
-contains complete user, assistant, tool, hook, error, and result messages.
+if (!result.success) {
+  throw new Error(result.error?.message ?? `Run failed: ${result.subtype}`);
+}
 
-### Result
+console.log(result.text);
+```
 
-Every normally completed stream ends with a result message. A result reports
-success, interruption, or failure and includes final text, messages, duration,
-turn count, and token usage when available.
+The selected model can change between turns. Choose a fixed model ID when runs must use the same model.
 
-### Node and daemon lifecycle behavior
+### Choose a spec-mode model
 
-Node and daemon replacement operations intentionally behave differently.
+The primary model handles normal turns. The spec-mode model handles turns in
+spec mode.
 
-| Behavior                        | Node session                                               | Daemon session                 |
-| ------------------------------- | ---------------------------------------------------------- | ------------------------------ |
-| Successor response              | `fork`: handle; `compact`/`rewind`: outcome with `session` | Outcome with `newSessionId`    |
-| Source handle after replacement | Retired                                                    | Still usable                   |
-| Load successor                  | Automatic                                                  | Call `droid.sessions.resume()` |
+```ts
+import {
+  createSession,
+  DroidInteractionMode,
+  ReasoningEffort,
+} from '@factory/droid-sdk/node';
 
-See [Session lifecycle](#session-lifecycle) for examples.
+const session = await createSession({
+  modelId: 'auto',
+  interactionMode: DroidInteractionMode.Spec,
+  specModeModelId: 'model-id',
+  specModeReasoningEffort: ReasoningEffort.High,
+});
 
-## One-shot runs
+try {
+  for await (const _message of session.stream(
+    'Draft an implementation plan.'
+  )) {
+    // Consume messages.
+  }
+} finally {
+  await session.close();
+}
+```
 
-**Runtime: Node**
+You can also choose the model when entering spec mode:
 
 ```ts
-function run(prompt: string, options?: RunOptions): Promise<DroidResult>;
+await session.enterSpecMode({
+  specModeModelId: 'model-id',
+  specModeReasoningEffort: ReasoningEffort.High,
+});
 ```
 
-`run()` supports the same creation and message options as a Node session,
-except partial stream events.
+### Use a custom model
+
+Configure custom models in `~/.factory/settings.json`. See [Custom Models (BYOK)](https://docs.factory.ai/cli/byok/overview) for provider, credential, and model settings.
+
+After configuration, pass the custom model ID anywhere the SDK accepts `modelId`. The ID uses `custom:` followed by the configured `model` value.
 
 ```ts
-const result = await run('Review the authentication middleware.', {
-  cwd: '/path/to/repository',
-  modelId: 'model-id',
-  reasoningEffort: ReasoningEffort.High,
-  disabledToolIds: ['Execute'],
+import { run } from '@factory/droid-sdk/node';
+
+const result = await run('Summarize this repository.', {
+  modelId: 'custom:gpt-4o-mini',
 });
-```
 
-Common options:
-
-| Option                         | Purpose                                        |
-| ------------------------------ | ---------------------------------------------- |
-| `cwd`                          | Working directory. Defaults to `process.cwd()` |
-| `apiKey`                       | Factory API key. Defaults to `FACTORY_API_KEY` |
-| `modelId`                      | Model selection                                |
-| `reasoningEffort`              | Model reasoning level                          |
-| `autonomyLevel`                | Permission policy level                        |
-| `interactionMode`              | Auto, spec, or mission mode. AGI is deprecated |
-| `specModeModelId`              | Model used in spec mode                        |
-| `specModeReasoningEffort`      | Reasoning level used in spec mode              |
-| `disabledToolIds`              | Tools that Droid cannot use                    |
-| `autoRejectPermissionRequests` | Reject all permission requests automatically   |
-| `disableBuiltinSkills`         | Hide Factory-provided built-in skills          |
-| `permissionHandler`            | Handles permission requests                    |
-| `askUserHandler`               | Answers AskUser requests                       |
-| `tags`                         | Session attribution tags                       |
-| `sessionSource`                | Session source attribution                     |
-| `images`                       | Base64 image attachments                       |
-| `files`                        | Text or PDF attachments                        |
-| `outputFormat`                 | JSON schema for structured output              |
-| `abortSignal`                  | Cancels the run                                |
-| `mcpServers`                   | MCP servers available to the session           |
-| `observability`                | Logging, metrics, and trace integration        |
-| `execPath`                     | Droid executable path                          |
-| `execArgs`                     | Additional Droid process arguments             |
-| `env`                          | Additional Droid process environment variables |
-| `transport`                    | Custom string-framed transport                 |
+if (!result.success) {
+  throw new Error(result.error?.message ?? `Run failed: ${result.subtype}`);
+}
+
+console.log(result.text);
+```
 
 ## Sessions
 
-### Create a Node session
+Use a session when prompts need shared conversation history. A session owns its working directory, settings, and one active turn at a time.
+
+### Create and use a session
 
 ```ts
-import { createSession } from '@factory/droid-sdk/node';
+import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
 
 const session = await createSession({
   cwd: process.cwd(),
-  modelId: 'model-id',
 });
+
+async function send(prompt: string) {
+  for await (const message of session.stream(prompt)) {
+    if (message.type === DroidMessageType.Assistant) {
+      console.log(message.text);
+    }
+  }
+}
+
+try {
+  await send('What does this project do?');
+  await send('What should I test first?');
+} finally {
+  await session.close();
+}
+```
+
+The second turn uses context from the first. `cwd` defaults to `process.cwd()`. Model and reasoning defaults come from Droid settings.
+
+Runnable example:
+[`examples/node/multi-turn-session.ts`](../examples/node/multi-turn-session.ts)
+
+### Resume a saved session
+
+```ts
+import { DroidMessageType, resumeSession } from '@factory/droid-sdk/node';
+
+async function continueSession(sessionId: string) {
+  const session = await resumeSession(sessionId);
+
+  try {
+    for await (const message of session.stream(
+      'Continue from the last conversation.'
+    )) {
+      if (message.type === DroidMessageType.Assistant) {
+        console.log(message.text);
+      }
+    }
+  } finally {
+    await session.close();
+  }
+}
 ```
 
-When omitted, `cwd` defaults to `process.cwd()`. Model and reasoning defaults
-come from Droid settings.
+`resumeSession()` restores the saved conversation, working directory, and session settings. It does not accept `cwd`, `modelId`, or reasoning options.
+
+Resume options can provide new permission and AskUser handlers, disabled tools, MCP servers, an abort signal, and observability sinks.
+
+### Customize the system prompt
 
-### Resume a Node session
+Use `systemPrompt` to append instructions to Droid's effective built-in prompt
+or replace the behavioral prompt:
 
 ```ts
-import { resumeSession } from '@factory/droid-sdk/node';
+const appended = await createSession({
+  systemPrompt: {
+    type: 'preset',
+    preset: 'droid',
+    append: 'Prioritize security findings and cite relevant files.',
+  },
+});
 
-const session = await resumeSession('session-id');
+const replaced = await createSession({
+  systemPrompt: 'Act as a focused dependency-analysis agent.',
+});
 ```
 
-The saved session owns its working directory and settings. Resume options can
-change handlers, transports, disabled tools, MCP servers, and observability,
-but cannot replace saved model or working-directory settings.
+The Droid preset retains the prompt that the session would normally use,
+including specialized exec and mission prompts, and appends your instructions.
+A string replaces that behavioral prompt. Both forms retain the mandatory
+Droid identity block and required model/tool guidance.
+
+The option is available to `run()`, `createSession()`, and
+`droid.sessions.create()`. The prompt is fixed when the session is created.
+It is saved in the session settings file, restored by `resumeSession()` and
+`droid.sessions.resume()`, and inherited unchanged by forks.
+
+The prompt configuration is stored in the sibling session settings file, not
+serialized as a system event in the transcript JSONL. As with any instruction,
+the model can still repeat prompt text in its generated messages or thinking,
+which are part of the transcript. Treat both files as sensitive.
+
+Runnable example: [`examples/node/custom-system-prompt.ts`](../examples/node/custom-system-prompt.ts)
+
+### Read session state
 
-### Session state
+Each handle exposes its ID, current working directory, and current settings.
 
 ```ts
 console.log(session.id);
 console.log(session.cwd);
 console.log(session.settings.modelId);
+console.log(session.settings.reasoningEffort);
+console.log(session.settings.interactionMode);
 ```
 
-`settings` and `cwd` update when the running session reports changes.
+`settings` is read-only. The SDK updates `settings` and `cwd` when Droid reports a change.
 
-### Update settings
+Runnable example: [`examples/node/init-metadata.ts`](../examples/node/init-metadata.ts)
+
+### Update active-session settings
+
+Use `updateSettings()` for changes that should apply to later turns in the current session.
 
 ```ts
+import { AutonomyLevel, ReasoningEffort } from '@factory/droid-sdk/node';
+
 await session.updateSettings({
   modelId: 'model-id',
   reasoningEffort: ReasoningEffort.High,
@@ -273,32 +445,82 @@ await session.updateSettings({
 });
 ```
 
-Public settings include model, reasoning, interaction mode, autonomy, spec
-mode settings, tags, mission settings, compaction settings, and disabled tools.
+Updatable settings include:
+
+- model and reasoning effort
+- interaction mode and autonomy level
+- spec-mode model settings
+- tool availability overrides
+
+Interaction mode controls whether Droid operates normally in Auto mode or produces a read-only plan in Spec mode. Autonomy level controls which actions require approval while Droid is in Auto mode. Tool availability overrides can enable, disable, or restrict the tools available to the session.
+
+When only changing interaction modes, use `enterSpecMode()` and `exitSpecMode()` instead of setting `interactionMode` directly.
+
+The updated values are available through `session.settings`.
+
+Runnable example: [`examples/node/session-settings.ts`](../examples/node/session-settings.ts)
 
 ### Rename a session
 
+Use `rename()` after the first turn to replace the generated title.
+
 ```ts
 await session.rename({ title: 'Authentication review' });
 ```
 
-### Discover saved Node sessions
+Runnable example:
+[`examples/node/rename-session.ts`](../examples/node/rename-session.ts)
+
+### List saved sessions
+
+`listSessions()` reads local Droid session storage. It does not start Droid or
+call the Factory API.
+
+List sessions for the current working directory:
 
 ```ts
 import { listSessions } from '@factory/droid-sdk/node';
 
+const sessions = await listSessions({ limit: 10 });
+
+for (const session of sessions) {
+  console.log(session.id, session.title, session.modifiedTime);
+}
+```
+
+List sessions across all working directories:
+
+```ts
 const sessions = await listSessions({
-  cwd: process.cwd(),
+  fetchOutsideCWD: true,
   limit: 10,
 });
 ```
 
-`listSessions()` reads local session storage. It does not call the Factory REST
-API or a daemon.
+Results are sorted by `modifiedTime`, newest first. Each item includes its ID, title, owner, message count, creation time, modification time, and working directory when available.
+
+Runnable example: [`examples/node/list-sessions.ts`](../examples/node/list-sessions.ts)
+
+### What persists
+
+Droid saves the session data needed to continue later.
+
+| Restored from the saved session | Attach again when resuming |
+| ------------------------------- | -------------------------- |
+| Conversation history            | Permission handler         |
+| Working directory               | AskUser handler            |
+| Title                           | SDK MCP servers            |
+| Session settings                | Observability sinks        |
+|                                 | Abort signal               |
+
+Session settings include model, reasoning, Auto or Spec interaction mode, autonomy, spec-mode model settings, and tool availability overrides.
+
+Handlers, observability sinks, abort signals, and SDK MCP servers are runtime objects. Droid cannot serialize them with the session, so attach them again when calling `resumeSession()`. They do not need to be the same object instances or implementations used when the session was created.
 
-### Close a session
+### Close sessions safely
 
-Call `close()` in `finally` when your code owns a Node session.
+Call `close()` in `finally` when your code creates or resumes a session.
+Closing releases the subprocess, subscriptions, and SDK-owned MCP servers.
 
 ```ts
 const session = await createSession();
@@ -310,11 +532,13 @@ try {
 }
 ```
 
-## Streaming
+## Streaming and results
 
-### Complete messages
+Each call to `session.stream()` starts one turn and returns an async iterable.
+
+By default, it yields complete messages and ends with a terminal `DroidResult`.
 
-Complete messages are the default.
+### Complete messages
 
 ```ts
 for await (const message of session.stream('Find the failing test.')) {
@@ -342,12 +566,60 @@ Default message types:
 | `tool_result` | Complete tool result                 |
 | `hook`        | Hook execution                       |
 | `error`       | Runtime error event                  |
-| `result`      | Final turn result                    |
+| `result`      | Terminal `DroidResult`               |
+
+Runnable example: [`examples/node/session-stream.ts`](../examples/node/session-stream.ts)
+
+### Handle the result
+
+`DroidResult` is a discriminated union. Check `subtype` or `success` before using the response.
+
+```ts
+const result = await run('Run the test suite.');
+
+switch (result.subtype) {
+  case 'success':
+    console.log(result.text);
+    break;
+  case 'interrupted':
+    console.log('The run was interrupted.');
+    break;
+  case 'error_during_execution':
+  case 'error_structured_output':
+    console.error(
+      result.structuredOutputError?.message ??
+        result.error?.message ??
+        'Unknown error'
+    );
+    break;
+}
+```
+
+| Subtype                   | Meaning                                           |
+| ------------------------- | ------------------------------------------------- |
+| `success`                 | The turn completed successfully                   |
+| `interrupted`             | The turn was cancelled or permission declined     |
+| `error_during_execution`  | Droid could not complete the requested work       |
+| `error_structured_output` | Structured-output generation or validation failed |
+
+Every result includes:
+
+```ts
+console.log(result.sessionId);
+console.log(result.durationMs);
+console.log(result.turnCount);
+console.log(result.messages);
+console.log(result.text);
+console.log(result.tokenUsage);
+```
+
+`run()` returns the terminal result directly. When consuming `session.stream()`, handle the message whose type is `DroidMessageType.Result`.
+
+Runnable example: [`examples/node/result-metadata.ts`](../examples/node/result-metadata.ts)
 
 ### Partial events
 
-Use partial events only when the application needs live text, thinking, tool
-progress, usage, or state updates.
+Enable partial events only when the application needs live text, thinking, tool progress, token usage, or state updates.
 
 ```ts
 for await (const event of session.stream('Explain the test failure.', {
@@ -361,21 +633,152 @@ for await (const event of session.stream('Explain the test failure.', {
 
 Partial streams can also include thinking deltas, tool-call deltas, tool
 progress, token updates, permission results, settings changes, working-state
-changes, MCP status, and mission events.
+changes, and MCP status.
+
+Runnable example: [`examples/node/partial-stream.ts`](../examples/node/partial-stream.ts)
+
+### Token and context usage
+
+`DroidResult.tokenUsage` reports raw token counts for the current SDK turn and,
+when available, the Factory Service Credits (FSC) charged for that turn. One
+turn is one `run()` or `session.stream()` call. This is not the session's
+lifetime total.
+
+```ts
+if (result.tokenUsage) {
+  console.log(`input: ${result.tokenUsage.inputTokens}`);
+  console.log(`output: ${result.tokenUsage.outputTokens}`);
+  console.log(`cache read: ${result.tokenUsage.cacheReadTokens}`);
+  console.log(`cache created: ${result.tokenUsage.cacheCreationTokens}`);
+  if (result.tokenUsage.factoryCredits !== undefined) {
+    console.log(`Factory Service Credits: ${result.tokenUsage.factoryCredits}`);
+  }
+}
+```
+
+| Field                 | What it measures during the turn                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `inputTokens`         | Provider-reported input across model calls, which can include instructions, tools, conversation history, and the latest message |
+| `outputTokens`        | Output generated across model calls, not only the final visible response                                                        |
+| `cacheReadTokens`     | Input tokens reused from the prompt cache                                                                                       |
+| `cacheCreationTokens` | Input tokens written to the prompt cache                                                                                        |
+| `thinkingTokens`      | Reasoning tokens reported separately when available                                                                             |
+| `factoryCredits`      | Factory Service Credits charged, when available                                                                                 |
+
+One turn can make several model calls while Droid uses tools. Their usage is combined in the result, along with usage from delegated work. Earlier conversation can be counted again when it is included as input to a later turn. Cached input is also reported through the separate cache fields. `tokenUsage` is `null` when usage is unavailable.
+
+Partial streams can emit `DroidMessageType.TokenUsageUpdate`. Unlike the per-turn result, these events contain cumulative committed usage for the session.
+
+`getContextStats()` measures current context occupancy, not cumulative token usage:
+
+```ts
+const stats = await session.getContextStats();
+
+console.log(stats.used, stats.remaining, stats.limit, stats.accuracy);
+```
+
+| Field       | Meaning                                                                                               |
+| ----------- | ----------------------------------------------------------------------------------------------------- |
+| `used`      | Estimated tokens currently occupied by prompts, tools, instructions, and conversation history         |
+| `limit`     | Active model's maximum input window; unresolved model IDs fall back to the effective compaction limit |
+| `remaining` | `Math.max(0, limit - used)`                                                                           |
+| `accuracy`  | Currently `estimated`, because Droid approximates tokens from character counts                        |
+
+`remaining` estimates room in the model's input window. It does not
+necessarily mean tokens remaining before compaction. Droid can compact at a
+lower configured threshold, commonly 250,000 tokens, even when the active
+model's input window is larger.
+
+### Errors
+
+An error event and a thrown exception mean different things:
+
+- An `error` message reports a runtime problem during the turn. A terminal `DroidResult` normally follows and describes the final outcome.
+- A failed `DroidResult` means the stream completed, but the requested work or structured output failed.
+- A thrown exception means the SDK operation itself could not finish, such as an abort, connection failure, protocol error, or concurrent stream attempt.
+
+Handle stream exceptions around the iteration:
+
+```ts
+try {
+  for await (const message of session.stream('Run the tests.')) {
+    if (message.type === DroidMessageType.Error) {
+      console.error(message.message);
+    }
+  }
+} catch (error) {
+  console.error('The stream could not finish:', error);
+}
+```
+
+`run()` follows the same distinction: agent failures are returned as failed results, while setup, transport, protocol, and abort failures are thrown.
 
 ### Stream concurrency
 
 One session handle can have one active stream. Starting another active stream
 throws `ConcurrentStreamError`.
 
-Daemon sessions on the same connection may stream concurrently.
+### Cancellation and interruption
+
+Use an abort signal to cancel one turn:
+
+```ts
+const controller = new AbortController();
+
+setTimeout(
+  () => controller.abort(new Error('Timed out after 5 seconds')),
+  5_000
+);
+
+for await (const message of session.stream('Perform a long review.', {
+  abortSignal: controller.signal,
+})) {
+  // Handle messages.
+}
+```
+
+The stream interrupts the active turn and throws the abort reason.
+
+Use `session.interrupt()` when another part of the application needs to stop
+the active turn:
+
+```ts
+await session.interrupt();
+```
+
+The stream normally continues to a terminal result with subtype `interrupted`.
+The session remains available for later prompts.
+
+Breaking out of the stream also interrupts the active turn:
+
+```ts
+for await (const message of session.stream('Investigate every failing test.')) {
+  if (message.type === DroidMessageType.Assistant) {
+    console.log(message.text);
+
+    // Interrupt this turn instead of merely hiding its remaining output.
+    break;
+  }
+}
+```
+
+Breaking out of the loop before the turn finishes sends an interrupt request
+to Droid. This cancels the remaining model and tool work for that turn. The
+session remains open and can accept another prompt, but this loop does not
+receive the interrupted turn's terminal `DroidResult`.
+
+A session-level abort signal passed to `createSession()` closes the entire
+session when aborted.
 
-### Stop consuming a stream
+Runnable examples:
 
-Breaking out of a stream early interrupts the active server turn.
+- [`examples/node/abort-session-stream.ts`](../examples/node/abort-session-stream.ts)
+- [`examples/node/interrupt-session.ts`](../examples/node/interrupt-session.ts)
 
 ## Inputs and outputs
 
+Pass images, documents, or an output schema in the options for the turn that should use them. Both `run()` and `session.stream()` accept these options.
+
 ### Images
 
 ```ts
@@ -390,12 +793,14 @@ const result = await run('Describe this image.', {
 });
 ```
 
-Supported image types are JPEG, PNG, GIF, and WebP.
+`data` contains the base64-encoded image bytes. Supported media types are `image/jpeg`, `image/png`, `image/gif`, and `image/webp`.
+
+Runnable example: [`examples/node/image-attachment.ts`](../examples/node/image-attachment.ts)
 
 ### Documents
 
 ```ts
-for await (const _message of session.stream('Summarize this document.', {
+const result = await run('Summarize this document.', {
   files: [
     {
       type: 'text',
@@ -404,109 +809,69 @@ for await (const _message of session.stream('Summarize this document.', {
       name: 'report.txt',
     },
   ],
-})) {
-  // Consume messages.
-}
-```
-
-Document inputs support plain text and base64 PDF data.
-
-### Structured output
-
-Use structured output when another system needs a predictable result.
-
-```ts
-import { OutputFormatType, run } from '@factory/droid-sdk/node';
-
-const result = await run('Review this function for correctness issues.', {
-  outputFormat: {
-    type: OutputFormatType.JsonSchema,
-    schema: {
-      type: 'object',
-      properties: {
-        summary: { type: 'string' },
-        findings: {
-          type: 'array',
-          items: {
-            type: 'object',
-            properties: {
-              line: { type: 'number' },
-              severity: {
-                type: 'string',
-                enum: ['low', 'medium', 'high'],
-              },
-              message: { type: 'string' },
-            },
-            required: ['line', 'severity', 'message'],
-          },
-        },
-      },
-      required: ['summary', 'findings'],
-    },
-  },
 });
-
-if (!result.success) {
-  throw new Error(
-    result.structuredOutputError?.message ??
-      result.error?.message ??
-      'Structured output failed.'
-  );
-}
-
-console.log(result.structuredOutput);
 ```
 
-`structuredOutput` is typed as `unknown`. Validate or narrow it before passing
-it to another system. A successful result can omit structured output.
-
-### Result metadata
+Document inputs support:
 
-```ts
-console.log(result.sessionId);
-console.log(result.durationMs);
-console.log(result.turnCount);
-console.log(result.tokenUsage);
-console.log(result.messages);
-```
+| Source       | `type`   | `mediaType`       | `data`                        |
+| ------------ | -------- | ----------------- | ----------------------------- |
+| Plain text   | `text`   | `text/plain`      | The document text             |
+| PDF document | `base64` | `application/pdf` | Base64-encoded PDF file bytes |
 
-`tokenUsage` is `null` when usage is unavailable.
+`name` is optional for both forms. Attach content through `data`; a filesystem path by itself is not a document upload.
 
-## Cancellation and interruption
+Runnable example: [`examples/node/document-input.ts`](../examples/node/document-input.ts)
 
-### Abort one turn
+### Structured output
+
+Use `outputFormat` when another system needs a JSON object that follows a schema.
 
 ```ts
-const controller = new AbortController();
+import { OutputFormatType, run } from '@factory/droid-sdk/node';
 
-setTimeout(() => controller.abort(), 5_000);
+const result = await run('Return the repository name and test command.', {
+  outputFormat: {
+    type: OutputFormatType.JsonSchema,
+    schema: {
+      type: 'object',
+      properties: {
+        repository: { type: 'string' },
+        testCommand: { type: 'string' },
+      },
+      required: ['repository', 'testCommand'],
+      additionalProperties: false,
+    },
+  },
+});
 
-for await (const message of session.stream('Perform a long review.', {
-  abortSignal: controller.signal,
-})) {
-  // Handle messages.
+if (!result.success) {
+  throw new Error(
+    result.structuredOutputError?.message ??
+      result.error?.message ??
+      `Structured output failed (${result.subtype}).`
+  );
 }
-```
-
-The stream throws the abort reason after interrupting the active turn.
 
-### Interrupt and keep the session
+if (!result.structuredOutput) {
+  throw new Error('No structured output was returned.');
+}
 
-```ts
-await session.interrupt();
+console.log(JSON.stringify(result.structuredOutput, null, 2));
 ```
 
-`interrupt()` stops the active turn on the server. The stream continues to its
-terminal result, normally with subtype `interrupted`. The session remains
-usable for later prompts.
+Invalid or missing schema output normally produces a failed result with subtype `error_structured_output`; `structuredOutputError` contains the available validation details.
 
-A session-level abort signal passed to `createSession()` closes the whole
-session when aborted.
+`structuredOutput` is typed as `unknown`, because a JSON Schema does not provide a TypeScript runtime validator. Check that it is present and validate or narrow its shape before reading fields or passing it to another system. A successful result can still omit structured output, so do not use `result.success` as the only check.
+
+Runnable example: [`examples/node/structured-output.ts`](../examples/node/structured-output.ts)
 
 ## Permissions and user input
 
 ### Autonomy
 
+Autonomy controls which actions require approval in Auto mode.
+
 ```ts
 import { AutonomyLevel } from '@factory/droid-sdk/node';
 
@@ -515,11 +880,20 @@ const session = await createSession({
 });
 ```
 
-Levels are `Off`, `Low`, `Medium`, and `High`. When omitted, Droid settings
-choose the default.
+| Level    | Behavior                                |
+| -------- | --------------------------------------- |
+| `Off`    | Ask before every action                 |
+| `Low`    | Allow file edits and read-only commands |
+| `Medium` | Allow reversible commands               |
+| `High`   | Allow commands without approval prompts |
+
+When omitted, Droid uses the configured default. Autonomy does not select Auto or Spec mode; `interactionMode` does that.
 
 ### Permission handler
 
+Use `permissionHandler` to approve or reject requests that reach the client.
+The handler may be synchronous or asynchronous.
+
 ```ts
 import {
   ToolConfirmationOutcome,
@@ -528,32 +902,45 @@ import {
 
 const session = await createSession({
   autonomyLevel: AutonomyLevel.Off,
-  permissionHandler(request) {
-    const safe =
-      request.toolUses.length > 0 &&
-      request.toolUses.every(
-        (use) => use.details.type === ToolConfirmationType.Create
-      );
-
-    return safe
+  permissionHandler({ toolUses, options }) {
+    const createsOnly =
+      toolUses.length > 0 &&
+      toolUses.every((use) => use.details.type === ToolConfirmationType.Create);
+
+    const desired = createsOnly
       ? ToolConfirmationOutcome.ProceedOnce
       : ToolConfirmationOutcome.Cancel;
+
+    const offered = options.find((option) => option.value === desired);
+    if (!offered) throw new Error(`Outcome not offered: ${desired}`);
+
+    return desired;
   },
 });
 ```
 
-The handler must return an outcome supplied by the request. Invalid results and
-handler errors cancel the request.
+`toolUses` describes the pending actions. `options` contains the outcomes available for this request. Return one of those values. Common outcomes are:
+
+| Outcome         | Effect                                  |
+| --------------- | --------------------------------------- |
+| `ProceedOnce`   | Approve this request                    |
+| `ProceedAlways` | Approve and persist the applicable rule |
+| `Cancel`        | Reject the request                      |
 
-Without a handler, permission requests are cancelled.
+The available outcomes vary by request. Returning an unavailable value, throwing from the handler, or omitting the handler cancels the request.
+
+Runnable example:
+[`examples/node/permission-handler.ts`](../examples/node/permission-handler.ts)
 
 ### AskUser handler
 
+`askUserHandler` answers questions Droid asks during a turn. Connect it to a form, prompt, or other application UI.
+
 ```ts
 const result = await run('Ask me which environment to deploy.', {
-  askUserHandler(request) {
+  askUserHandler({ questions }) {
     return {
-      answers: request.questions.map((question) => ({
+      answers: questions.map((question) => ({
         index: question.index,
         question: question.question,
         answer: question.options[0] ?? 'none',
@@ -563,7 +950,7 @@ const result = await run('Ask me which environment to deploy.', {
 });
 ```
 
-To decline:
+Each answer must copy the question's `index` and `question`. To decline the questionnaire:
 
 ```ts
 return { cancelled: true, answers: [] };
@@ -571,16 +958,24 @@ return { cancelled: true, answers: [] };
 
 Without a handler, AskUser requests are declined.
 
-### Disable tools
+Runnable example:
+[`examples/node/ask-user-elicitation.ts`](../examples/node/ask-user-elicitation.ts)
+
+### Tool controls
+
+Disable tools when creating, resuming, or updating a session:
 
 ```ts
 const session = await createSession({
   disabledToolIds: ['Execute'],
 });
+
+await session.updateSettings({
+  disabledToolIds: ['Execute', 'Edit'],
+});
 ```
 
-Tool IDs are strings. Use `listTools()` to inspect the tools available to the
-current session.
+Tool IDs are strings. Use `listTools()` to inspect the tools available to the current session.
 
 ```ts
 const tools = await session.listTools();
@@ -593,27 +988,50 @@ for (const tool of tools) {
 The public SDK provides subtractive `disabledToolIds`. It does not expose a
 restrictive allowlist.
 
+Runnable example: [`examples/node/tool-controls.ts`](../examples/node/tool-controls.ts)
+
 ## Tools and extensions
 
+Use the extension that matches the job:
+
+| Extension            | Use it for                                       |
+| -------------------- | ------------------------------------------------ |
+| Skills               | Reusable instructions and supporting files       |
+| SDK MCP tools        | In-process TypeScript functions exposed to Droid |
+| External MCP servers | Tools provided by another process or service     |
+| Hooks                | Commands that run at defined lifecycle events    |
+
 ### Skills
 
+List the skills available to the session:
+
 ```ts
 const { skills } = await session.listSkills();
 
+for (const skill of skills) {
+  console.log(skill.name, skill.enabled);
+}
+```
+
+Enable or disable a skill at the user or project level:
+
+```ts
+import { SettingsLevel } from '@factory/droid-sdk/node';
+
 await session.setSkillDisabled({
   skillName: 'skill-name',
   disabled: true,
-  settingsLevel: 'project',
+  settingsLevel: SettingsLevel.Project,
 });
 ```
 
-Skills may come from project, personal, built-in, or automation settings.
+Skills can come from project, personal, built-in, or automation settings.
 
-### SDK MCP tools
+Runnable example: [`examples/node/skills.ts`](../examples/node/skills.ts)
 
-**Runtime: Node**
+### SDK MCP tools
 
-Use an SDK MCP server to define an in-process tool with a typed Zod input.
+Use `tool()` to define an in-process TypeScript function with a Zod input schema.
 
 ```ts
 import { z } from 'zod';
@@ -623,7 +1041,7 @@ import {
   tool,
 } from '@factory/droid-sdk/node';
 
-const tools = createSdkMcpServer({
+const server = createSdkMcpServer({
   name: 'review-tools',
   tools: [
     tool(
@@ -636,35 +1054,91 @@ const tools = createSdkMcpServer({
 });
 
 const session = await createSession({
-  mcpServers: [tools],
+  mcpServers: [server],
 });
+
+try {
+  for await (const _message of session.stream(
+    'Find the owner of src/index.ts.'
+  )) {
+    // Consume messages.
+  }
+} finally {
+  await session.close();
+}
 ```
 
-The SDK starts an authenticated loopback MCP server and closes it with the
-session.
+The SDK starts an authenticated loopback MCP server and closes it with the session.
+Tool calls still follow the session's autonomy and permission rules.
+Attach SDK MCP servers again when resuming a saved session because they are runtime objects, not persisted session data.
+
+Runnable example: [`examples/node/sdk-mcp-tool.ts`](../examples/node/sdk-mcp-tool.ts)
 
 ### External MCP servers
 
-Node sessions can add, remove, toggle, list, and authenticate MCP servers.
+Pass external MCP configuration when creating or resuming a session:
 
 ```ts
-await session.addMcpServer({
-  name: 'docs',
-  type: 'http',
-  url: 'https://example.com/mcp',
+const session = await createSession({
+  mcpServers: [
+    {
+      name: 'docs',
+      type: 'http',
+      url: 'https://example.com/mcp',
+      headers: [],
+    },
+  ],
 });
+```
+
+Supported session configuration:
+
+| Transport     | `type` field | Required configuration |
+| ------------- | ------------ | ---------------------- |
+| Local process | Omit         | `command` and `args`   |
+| HTTP          | `http`       | `url` and `headers`    |
+| SSE           | `sse`        | `url` and `headers`    |
+
+Inspect server status and discovered tools:
+
+```ts
+try {
+  const { servers, summary } = await session.listMcpServers();
+  const tools = await session.listMcpTools();
 
-const servers = await session.listMcpServers();
-const tools = await session.listMcpTools();
+  console.log(servers, summary, tools);
+} finally {
+  await session.close();
+}
 ```
 
-The daemon client exposes the complete MCP management API through `droid.mcp`.
+`addMcpServer()`, `removeMcpServer()`, and `toggleMcpServer()` change the user's Droid configuration.
+Use `authenticateMcpServer({ serverName })` when a server requires authentication.
+
+Runnable example: [`examples/node/external-mcp.ts`](../examples/node/external-mcp.ts)
 
 ### Hooks
 
-Hooks are configured in `.factory/hooks.json`. They can run before or after
-tools, when prompts are submitted, when notifications arrive, during
-compaction, and when sessions or subagents stop.
+Hooks run shell commands at defined lifecycle events.
+Configure them in `.factory/hooks.json`:
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Execute",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "echo before Execute"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Hooks can run before or after tools, when prompts are submitted, when notifications arrive, during compaction, and when sessions or subagents stop.
 
 Hook events are available in the stream:
 
@@ -676,32 +1150,17 @@ for await (const message of session.stream('Run the tests.')) {
 }
 ```
 
-The SDK exposes hook schemas and types, but does not provide a programmatic
-hook-registration API.
-
-### Raw notifications
-
-**Runtime: Node**
-
-```ts
-const unsubscribe = session.onNotification(
-  (notification) => console.log(notification),
-  { type: 'settings_updated' }
-);
-
-unsubscribe();
-```
+The SDK exposes hook schemas and stream events, but it does not provide a programmatic hook-registration API.
 
-Use raw notifications only when the typed stream does not expose the event you
-need.
+Runnable example: [`examples/node/hook-execution.ts`](../examples/node/hook-execution.ts)
 
 ## Session lifecycle
 
-### Node replacement handles
+### Replacement handles
 
-Node `fork()` returns a ready successor handle. `compact()` and `rewind()`
-return outcome objects containing a ready successor in `session`. Each
-operation retires its source wrapper.
+`fork()` returns a ready successor handle. `compact()` and `rewind()` return
+outcome objects containing a ready successor in `session`. Each operation
+retires its source wrapper.
 
 ```ts
 const forked = await session.fork();
@@ -727,362 +1186,159 @@ with `resumeSession(sourceId)`.
 
 Do not replace a session while it has an active stream.
 
-### Daemon replacement IDs
-
-Daemon operations return a new session ID. The source handle remains usable.
-
-```ts
-const { newSessionId } = await source.compact();
-const compacted = await droid.sessions.resume(newSessionId);
-```
-
-The same rule applies to `fork()` and `rewind()`.
-
-```ts
-const forkResult = await source.fork();
-const fork = await droid.sessions.resume(forkResult.newSessionId);
-
-const rewindResult = await source.rewind({
-  messageId,
-  filesToRestore,
-  filesToDelete,
-  forkTitle: 'Before the failed change',
-});
-const rewound = await droid.sessions.resume(rewindResult.newSessionId);
-```
-
-Daemon replacement locking is local to one client handle. Avoid replacing or
-streaming the same session through several daemon clients at once.
-
 ## Spec mode
 
-Create a session in spec mode:
+Spec mode lets Droid inspect the codebase and propose a plan without changing files. Start a session in Spec mode or switch an existing session with `enterSpecMode()`:
 
 ```ts
-import {
-  createSession,
-  DroidInteractionMode,
-  ReasoningEffort,
-} from '@factory/droid-sdk/node';
-
 const session = await createSession({
   interactionMode: DroidInteractionMode.Spec,
-  specModeReasoningEffort: ReasoningEffort.High,
 });
+
+// Or switch an existing Auto session.
+await session.enterSpecMode();
 ```
 
-Enter spec mode later:
+`enterSpecMode()` can also set the model used for planning:
 
 ```ts
 await session.enterSpecMode({
+  specModeModelId: 'model-id',
   specModeReasoningEffort: ReasoningEffort.High,
 });
 ```
 
-When Droid asks to leave spec mode, a permission handler can approve
-implementation in the same session or hand it to a new session.
+### Leave without approving a plan
 
-| Outcome                 | Behavior                                            |
-| ----------------------- | --------------------------------------------------- |
-| `ProceedOnce`           | Continue in the same session                        |
-| `ProceedNewSessionHigh` | Start implementation in a new high-autonomy session |
+Call `exitSpecMode()` to return the session to Auto mode without approving a plan or starting implementation:
 
-New-session handoff IDs currently require inspecting raw notifications.
+```ts
+await session.enterSpecMode();
 
-## Daemon and browser applications
+// Return to Auto mode without approving or implementing the plan.
+await session.exitSpecMode();
+```
 
-### Connect
+`exitSpecMode()` changes the interaction mode only. It does not select a `ToolConfirmationOutcome` or approve an `ExitSpecMode` permission request.
 
-```ts
-const droid = await connectToDaemon({
-  url: 'ws://127.0.0.1:37643',
-  auth: { apiKey },
-  permissionHandler,
-  askUserHandler,
-  onError(error) {
-    console.error(error);
-  },
-});
-```
+The method is available on Node `DroidSession` handles returned by `createSession()`, `resumeSession()`, and replacement operations such as `fork()`, `compact()`, and `rewind()`. Daemon clients continue to change the mode with `droid.sessions.updateSettings()`.
 
-Connection-level handlers become defaults for created and resumed sessions.
-Per-session handlers override them.
+### Approve a plan
 
-### Create and resume
+When the plan is ready, Droid sends an `ExitSpecMode` permission request. Its
+details contain the plan. Unlike calling `exitSpecMode()`, approving it with `ProceedOnce` accepts the completed plan, returns to Auto mode, and continues implementation in the same session:
 
 ```ts
-const created = await droid.sessions.create({
-  cwd: '/path/to/repository',
-});
-
-const resumed = await droid.sessions.resume('session-id');
-```
+import {
+  AutonomyLevel,
+  createSession,
+  DroidInteractionMode,
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+} from '@factory/droid-sdk/node';
 
-One `ConnectedDroid` can have one attached handle for each session ID.
+const session = await createSession({
+  interactionMode: DroidInteractionMode.Auto,
+  autonomyLevel: AutonomyLevel.Low,
+  permissionHandler({ toolUses }) {
+    const request = toolUses.find(
+      ({ details }) => details.type === ToolConfirmationType.ExitSpecMode
+    );
 
-### List and inspect history
+    if (request?.details.type === ToolConfirmationType.ExitSpecMode) {
+      console.log(request.details.plan);
 
-```ts
-const sessions = await droid.sessions.list({ limit: 20 });
+      return ToolConfirmationOutcome.ProceedOnce;
+    }
 
-const messages = await droid.sessions.getMessages(sessions[0].id, {
-  limit: 50,
+    return ToolConfirmationOutcome.Cancel;
+  },
 });
 
-const matches = await droid.sessions.search({
-  query: 'authentication failure',
-});
+try {
+  await session.enterSpecMode();
+
+  for await (const message of session.stream('Plan and update README.md.')) {
+    if (message.type === DroidMessageType.Result) {
+      console.log(message.subtype);
+    }
+  }
+} finally {
+  await session.close();
+}
 ```
 
-The daemon session resource also supports opened-session listing,
-archive/unarchive, rename, settings, context information, and queued-message
-operations.
+The handler can be asynchronous. An interactive application should display the plan and wait for the user's decision before returning.
 
-### Concurrent sessions
+Return `Cancel` to reject the plan. The turn ends with an `interrupted` result, and the session remains available for another prompt.
 
-Different daemon sessions can stream over one connection at the same time.
+Some `ExitSpecMode` requests offer `ProceedNewSession` variants. Return one of those offered values to hand implementation to a new session. Return only values present in the request's `options`.
 
-```ts
-await Promise.all([
-  consume(first.stream('Review the API.')),
-  consume(second.stream('Review the tests.')),
-]);
-```
+Runnable example:
+[`examples/node/enter-spec-mode.ts`](../examples/node/enter-spec-mode.ts)
 
-### Cleanup
-
-| Operation            | Daemon session | Local handle           | Connection |
-| -------------------- | -------------- | ---------------------- | ---------- |
-| `session.detach()`   | Keeps running  | Detached               | Retained   |
-| `session.close()`    | Ends           | Detached after success | Retained   |
-| `droid.disconnect()` | Keeps running  | All detached           | Destroyed  |
-
-Detached handles cannot be reused. Resume the session to obtain a new handle.
-
-### Stable daemon resources
-
-| Namespace      | Main methods                                                                                                                                                                                                                     |
-| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `sessions`     | `list`, `listOpened`, `create`, `resume`, `getMessages`, `search`, `archive`, `unarchive`, `rename`, `updateSettings`, `resolveQueuedMessage`, `killWorker`, `getRewindInfo`, `rewind`, `compact`, `fork`, `getContextBreakdown` |
-| `workspace`    | `changeDirectory`, `validateDirectory`, `checkTrust`, `trust`, `listFiles`, `searchFiles`, `getFileContent`                                                                                                                      |
-| `settings`     | `getDefaults`, `updateDefaults`                                                                                                                                                                                                  |
-| `customModels` | `list`, `upsert`, `delete`                                                                                                                                                                                                       |
-| `ssh`          | `installKey`                                                                                                                                                                                                                     |
-| `updates`      | `trigger`                                                                                                                                                                                                                        |
-| `relay`        | `start`, `stop`, `status`                                                                                                                                                                                                        |
-| `terminals`    | `create`, `write`, `resize`, `close`, `list`                                                                                                                                                                                     |
-| `mcp`          | `getConfig`, `updateConfig`, `addServer`, `removeServer`, `toggleServer`, authentication, registry, and tool methods                                                                                                             |
-| `skills`       | `list`, `setDisabled`                                                                                                                                                                                                            |
-| `commands`     | `list`                                                                                                                                                                                                                           |
-| `plugins`      | `listAvailable`, `listInstalled`, `install`, `uninstall`, `setEnabled`, `update`                                                                                                                                                 |
-| `marketplaces` | `list`, `add`, `remove`, `update`                                                                                                                                                                                                |
-| `automations`  | `list`, `run`, `pause`, `resume`, history, visual, create, update, rename, delete, fork, and config methods                                                                                                                      |
-| `git`          | `getDiff`, `listBranches`, `checkoutBranch`, `push`, `commit`, `createPullRequest`, `resolvePullRequestStatuses`                                                                                                                 |
-| `feedback`     | `submitBugReport`                                                                                                                                                                                                                |
-
-### Facade return shapes
-
-The namespaced daemon facade normalizes common collection results:
-
-- `sessions.list()` returns session summaries with `id`, `messageCount`, and
-  `modifiedTime`.
-- `sessions.getMessages()` returns the message array directly.
-- Collection methods such as `customModels.list()`, `terminals.list()`,
-  `mcp.listRegistry()`, `mcp.listTools()`, `commands.list()`, and the plugin,
-  marketplace, automation, and Software Factory list methods return arrays.
-- Methods whose protocol result includes additional metadata retain the result
-  object. This includes `sessions.search()`, `mcp.listServers()`, and
-  `skills.list()`.
-
-The low-level `DaemonClient` returns canonical protocol response types instead
-of these normalized facade shapes.
-
-## Observability
-
-**Runtime: Node**
+## Operations
+
+### Observability
 
 ```ts
-const session = await createSession({
+import { run } from '@factory/droid-sdk/node';
+
+const result = await run('Check the repository status.', {
   observability: {
     logger: {
       log(event) {
-        console.log(event.level, event.message);
-      },
-    },
-    metrics: {
-      record(event) {
-        console.log(event.name, event.value);
-      },
-    },
-    tracing: {
-      inject(carrier) {
-        carrier.traceparent = currentTraceparent;
+        console.log(event.level, event.name, event.attributes);
       },
     },
   },
 });
-```
-
-Observability sinks must not throw into SDK operations. The SDK avoids sending
-prompt text, message content, tool inputs, raw output, and stack traces through
-its observability contracts.
 
-## Advanced resources
-
-### Low-level daemon integration
-
-Most applications should use `connectToDaemon()`. The root entrypoint also
-exports `DaemonClient`, `DaemonSessionController`, `MultiSessionStateManager`,
-`MultiMissionStateManager`, `WebSocketDaemonTransport`, daemon events, and
-canonical protocol types for hosts that need custom connection or state
-ownership.
-
-Node-only IPC and in-process transports come from the `/node` entrypoint:
-
-```ts
-import { DaemonClient, MachineType } from '@factory/droid-sdk';
-import {
-  InProcessDaemonClientTransport,
-  type InProcessDaemonClientTransportOptions,
-  type InProcessMessageHandler,
-} from '@factory/droid-sdk/node';
-
-function createInProcessClient(
-  sendMessage: InProcessMessageHandler,
-  onMessage: NonNullable<InProcessDaemonClientTransportOptions['onMessage']>
-) {
-  const transport = new InProcessDaemonClientTransport({
-    sendMessage,
-    onMessage,
-  });
-
-  return new DaemonClient({
-    machineType: MachineType.Local,
-    transport,
-  });
+if (!result.success) {
+  throw new Error(result.error?.message ?? `Run failed: ${result.subtype}`);
 }
 ```
 
-The root also exports `WebSocketDaemonTransport`; the `/node` entrypoint exports
-`IpcDaemonClientTransport`.
-
-Hosts can inject daemon-core logging, metrics, tracing, and domain helpers once
-at startup:
-
-```ts
-import { configureDaemonCoreDeps } from '@factory/droid-sdk';
-
-configureDaemonCoreDeps({
-  logger: {
-    info: (message, metadata) => logger.info(message, metadata),
-    error: (message, metadata) => logger.error(message, metadata),
-  },
-});
-```
-
-Unspecified dependencies keep their standalone defaults.
-
-### Low-level Node integration
-
-Most Node applications should use `run()` or `DroidSession`. The `/node`
-entrypoint also exports `ProcessTransport` and `DroidClient` for direct
-JSON-RPC integrations.
-
-Low-level RPC methods return complete response envelopes. Read successful
-payloads from `response.result`. Direct permission and AskUser handlers receive
-complete request events, while high-level session handlers receive request
-parameters.
-
-`ProcessTransport` uses `droidExecPath` and `droidExecExtraArgs` for executable
-configuration. A custom `StringFramedDroidClientTransport` exchanges
-newline-delimited JSON-RPC strings and can replace subprocess transport
-entirely.
-
-### Context and token usage
-
-Read the current context-window estimate:
-
-```ts
-const stats = await session.getContextStats();
+Pass `logger`, `metrics`, or `tracing` sinks through `observability`.
+Sink methods must not throw.
+The SDK excludes prompts, messages, tool inputs, raw output, and stack traces from observability events.
+Process startup emits telemetry before the first turn, and `close()` emits a request log.
+To verify turn-specific logs, snapshot the count after creating the session and check it before closing.
 
-console.log(stats.used, stats.remaining, stats.limit, stats.accuracy);
-```
+Runnable example:
+[`examples/node/observability.ts`](../examples/node/observability.ts)
 
-Enable partial messages to receive live token updates:
+### Low-level APIs
 
-```ts
-for await (const message of session.stream('Summarize this repository.', {
-  includePartialMessages: true,
-})) {
-  if (message.type === DroidMessageType.TokenUsageUpdate) {
-    console.log(message.inputTokens, message.outputTokens);
-  }
-}
-```
+Use the high-level APIs unless your application owns the transport or protocol lifecycle.
 
-The final result's `tokenUsage` contains the last observed totals or `null`.
+| Need                         | Preferred API      | Low-level alternative |
+| ---------------------------- | ------------------ | --------------------- |
+| Run a session                | `createSession()`  | `DroidClient`         |
+| Consume typed session events | `session.stream()` | Raw notifications     |
 
-### Factory REST API
+The `/node` entrypoint exports `DroidClient` for direct JSON-RPC integrations.
+Low-level methods return response envelopes, so successful payloads are under `response.result`.
 
-The browser-safe root exports REST helpers for Factory computers, machine
-templates, metrics, dependency installation, and remote-session listing.
+Use `onNotification()` only when `session.stream()` does not expose the event you need:
 
 ```ts
-import { listComputers, listRemoteSessions } from '@factory/droid-sdk';
-
-const options = { apiKey: process.env.FACTORY_API_KEY! };
+const unsubscribe = session.onNotification(
+  (notification) => console.log(notification.type),
+  { type: 'settings_updated' }
+);
 
-const computers = await listComputers(options);
-const sessions = await listRemoteSessions(options);
+unsubscribe();
 ```
 
-REST calls use `https://api.factory.ai` by default. Pass `baseUrl` to target a
-different Factory API host.
-
-| Resource            | Functions                                                                                                                                       |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| Machine templates   | `listMachineTemplates`, `getMachineTemplate`                                                                                                    |
-| Computers           | `listComputers`, `getComputer`, `getComputerByName`, `createComputer`, `updateComputer`, `deleteComputer`, `restartComputer`, `refreshComputer` |
-| Computer operations | `getComputerMetrics`, `retryInstallDeps`                                                                                                        |
-| Remote sessions     | `listRemoteSessions`                                                                                                                            |
-
-### Unstable daemon resources
-
-APIs under `droid.unstable` may change between SDK releases.
-
-| Namespace         | Main methods or resources                                                 |
-| ----------------- | ------------------------------------------------------------------------- |
-| `crons`           | `list`, `create`, `update`, `delete`, `holdSession`, `resumeSession`      |
-| `missions`        | `inspectReadiness`, `acknowledgeReadinessWarning`                         |
-| `semanticDiff`    | `getCache`, `saveCache`, `generate`                                       |
-| `fileTransfers`   | `push`, `pull`                                                            |
-| `proxy`           | `getToken`                                                                |
-| `softwareFactory` | `workstreams`, `signals`, `changes`, `activities`, and `events` resources |
-
-Keep unstable API use behind an application-owned adapter.
-
-For example, create and manage a scheduled prompt through the unstable cron
-resource:
-
-```ts
-const cron = await droid.unstable.crons.create({
-  kind: 'root_prompt',
-  scope: { type: 'root' },
-  schedule: { expression: '0 * * * *', recurring: true },
-  payload: {
-    type: 'prompt',
-    prompt: 'Check repository health',
-    target: { type: 'new_session', cwd: '/workspace' },
-  },
-});
+## API reference
 
-await droid.unstable.crons.update(cron.id, { status: 'paused' });
-await droid.unstable.crons.delete(cron.id);
-```
+### Entrypoint
 
-## API reference
+Import functions, classes, enums, and types from `@factory/droid-sdk/node`.
 
-### Node functions
+### Functions
 
 | API                                  | Returns                      |
 | ------------------------------------ | ---------------------------- |
@@ -1090,37 +1346,52 @@ await droid.unstable.crons.delete(cron.id);
 | `createSession(options?)`            | `Promise<DroidSession>`      |
 | `resumeSession(sessionId, options?)` | `Promise<DroidSession>`      |
 | `listSessions(options?)`             | `Promise<SessionMetadata[]>` |
+| `listModels(options?)`               | `Promise<ModelInfo[]>`       |
 | `createSdkMcpServer(options)`        | `SdkMcpServer`               |
 | `tool(...)`                          | `DroidTool`                  |
 
 ### `DroidSession`
 
-| Member                    | Purpose                               |
-| ------------------------- | ------------------------------------- |
-| `id`                      | Session ID                            |
-| `cwd`                     | Live working directory                |
-| `settings`                | Live read-only settings               |
-| `stream()`                | Run one turn                          |
-| `interrupt()`             | Stop the active turn                  |
-| `updateSettings()`        | Update session settings               |
-| `enterSpecMode()`         | Change to spec mode                   |
-| `listTools()`             | List normalized tools                 |
-| `listSkills()`            | List skills                           |
-| `setSkillDisabled()`      | Enable or disable a skill             |
-| `addMcpServer()`          | Add an MCP server                     |
-| `removeMcpServer()`       | Remove an MCP server                  |
-| `toggleMcpServer()`       | Enable or disable an MCP server       |
-| `listMcpServers()`        | List MCP servers                      |
-| `listMcpTools()`          | List MCP tools                        |
-| `authenticateMcpServer()` | Start MCP authentication              |
-| `getContextStats()`       | Read context usage                    |
-| `getRewindInfo()`         | Inspect rewindable file changes       |
-| `rewind()`                | Create a rewound successor            |
-| `compact()`               | Create a compacted successor          |
-| `fork()`                  | Create a forked successor             |
-| `rename()`                | Change the session title              |
-| `onNotification()`        | Subscribe to raw notifications        |
-| `close()`                 | Close the session and owned resources |
+| Member                    | Purpose                                      |
+| ------------------------- | -------------------------------------------- |
+| `id`                      | Session ID                                   |
+| `cwd`                     | Live working directory                       |
+| `settings`                | Live read-only settings                      |
+| `stream()`                | Run one turn                                 |
+| `interrupt()`             | Stop the active turn                         |
+| `updateSettings()`        | Update session settings                      |
+| `enterSpecMode()`         | Change to spec mode                          |
+| `exitSpecMode()`          | Return to Auto mode without approving a plan |
+| `listTools()`             | List normalized tools                        |
+| `listSkills()`            | List skills                                  |
+| `setSkillDisabled()`      | Enable or disable a skill                    |
+| `addMcpServer()`          | Add an MCP server                            |
+| `removeMcpServer()`       | Remove an MCP server                         |
+| `toggleMcpServer()`       | Enable or disable an MCP server              |
+| `listMcpServers()`        | List MCP servers                             |
+| `listMcpTools()`          | List MCP tools                               |
+| `authenticateMcpServer()` | Start MCP authentication                     |
+| `getContextStats()`       | Read context usage                           |
+| `getRewindInfo()`         | Inspect rewindable file changes              |
+| `rewind()`                | Create a rewound successor                   |
+| `compact()`               | Create a compacted successor                 |
+| `fork()`                  | Create a forked successor                    |
+| `rename()`                | Change the session title                     |
+| `onNotification()`        | Subscribe to raw notifications               |
+| `close()`                 | Close the session and owned resources        |
+
+### Stream and model types
+
+| Type                 | Purpose                                           |
+| -------------------- | ------------------------------------------------- |
+| `DroidStreamMessage` | Complete messages returned by the default stream  |
+| `DroidStreamEvent`   | Complete messages plus partial events             |
+| `DroidResult`        | Terminal result returned by `run()`               |
+| `DroidMessageType`   | Runtime constants for narrowing stream messages   |
+| `TokenUsage`         | Token counts and optional Factory Service Credits |
+| `ModelInfo`          | Model catalog entry returned by discovery APIs    |
+
+`session.stream()` yields `DroidStreamMessage` by default and `DroidStreamEvent` when `includePartialMessages` is `true`.
 
 ### Result states
 
@@ -1131,130 +1402,36 @@ await droid.unstable.crons.delete(cron.id);
 | `error_during_execution`  | `false`   | `false`       | Runtime failure           |
 | `error_structured_output` | `false`   | `false`       | Structured-output failure |
 
-Common result fields:
-
-```ts
-{
-  type: 'result';
-  subtype:
-    | 'success'
-    | 'interrupted'
-    | 'error_during_execution'
-    | 'error_structured_output';
-  sessionId: string;
-  durationMs: number;
-  tokenUsage: TokenUsage | null;
-  messages: DroidStreamEvent[];
-  text: string;
-  turnCount: number;
-  success: boolean;
-  interrupted: boolean;
-  structuredOutput?: unknown;
-  structuredOutputError?: StructuredOutputError | null;
-  error: ErrorEvent | null;
-}
-```
+Every result includes `sessionId`, `durationMs`, `tokenUsage`, `messages`, `text`, and `turnCount`.
+Check `success` before using successful output.
 
 ### Main enums
 
 | Enum                   | Values                                                                           |
 | ---------------------- | -------------------------------------------------------------------------------- |
 | `AutonomyLevel`        | `Off`, `Low`, `Medium`, `High`                                                   |
-| `DroidInteractionMode` | `Auto`, `Spec`, `Mission`; `AGI` is deprecated                                   |
+| `DroidInteractionMode` | `Auto`, `Spec`                                                                   |
 | `ReasoningEffort`      | `None`, `Dynamic`, `Off`, `Minimal`, `Low`, `Medium`, `High`, `ExtraHigh`, `Max` |
 | `OutputFormatType`     | `JsonSchema`                                                                     |
 
-Model IDs and tool IDs are strings. Discover available models and tools at
-runtime instead of treating them as closed enums.
+Model IDs and tool IDs are strings rather than closed enums.
 
 ### Main errors
 
-Universal errors:
-
-| Error                      | Meaning                                       |
-| -------------------------- | --------------------------------------------- |
-| `ConcurrentStreamError`    | A session handle already has an active stream |
-| `SessionReplacedError`     | A Node source wrapper was replaced            |
-| `SessionReplacementError`  | Successor loading or rollback failed          |
-| `AbortError`               | A daemon operation was aborted                |
-| `ConnectionClosedError`    | Daemon connection closed                      |
-| `JsonRpcRequestError`      | Daemon JSON-RPC request failed                |
-| `RelayConnectionError`     | Relay connection failed                       |
-| `WebSocketConnectionError` | WebSocket connection failed                   |
-
-Node-only errors:
-
-| Error                    | Meaning                                      |
-| ------------------------ | -------------------------------------------- |
-| `DroidClientError`       | Base Node client error                       |
-| `ConnectionError`        | Droid process or transport connection failed |
-| `TimeoutError`           | A request timed out                          |
-| `ProtocolError`          | Protocol or API response failed              |
-| `SessionError`           | Base session error                           |
-| `SessionNotFoundError`   | Saved session was not found                  |
-| `InvalidSessionCwdError` | Saved working directory is invalid           |
-| `ProcessExitError`       | Droid subprocess exited unexpectedly         |
-
-### Custom transports
-
-**Runtime: Node, advanced**
-
-```ts
-interface StringFramedDroidClientTransport {
-  isConnected: boolean;
-  send(message: string): Promise<void>;
-  onMessage(handler: (message: string) => void): void;
-  onError(handler: (error: Error) => void): void;
-  close(): Promise<void>;
-}
-```
-
-Pass a ready transport through `run()`, `createSession()`, or
-`resumeSession()`. A custom transport bypasses subprocess creation and the
-Node API-key requirement.
-
-## Errors and limitations
-
-### Handle results explicitly
-
-```ts
-const result = await run('Run the test suite.');
-
-switch (result.subtype) {
-  case 'success':
-    console.log(result.text);
-    break;
-  case 'interrupted':
-    console.log('The run was interrupted.');
-    break;
-  case 'error_during_execution':
-  case 'error_structured_output':
-    console.error(
-      result.structuredOutputError?.message ??
-        result.error?.message ??
-        'Unknown error'
-    );
-    break;
-}
-```
-
-### Known limitations
+| Error                     | Meaning                                       |
+| ------------------------- | --------------------------------------------- |
+| `ConcurrentStreamError`   | A session handle already has an active stream |
+| `SessionReplacedError`    | A source wrapper was replaced                 |
+| `SessionReplacementError` | Successor loading or rollback failed          |
+| `DroidClientError`        | Base client error                             |
+| `ConnectionError`         | Droid process connection failed               |
+| `TimeoutError`            | A request timed out                           |
+| `ProtocolError`           | Protocol or API response failed               |
+| `SessionError`            | Base session error                            |
+| `SessionNotFoundError`    | Saved session was not found                   |
+| `InvalidSessionCwdError`  | Saved working directory is invalid            |
+| `ProcessExitError`        | Droid subprocess exited unexpectedly          |
+
+## Known limitations
 
-- Daemon replacement locking does not coordinate separate clients.
-- Browser daemon authentication currently requires an API key.
 - New-session spec handoff IDs require raw notification inspection.
-- REST remote-session support currently provides listing only.
-
-## Runnable examples
-
-The package includes runnable examples for one-shot runs, streaming, sessions,
-permissions, AskUser, attachments, structured output, MCP tools, hooks,
-observability, spec mode, replacement lifecycle, daemon sessions, concurrent
-browser sessions, and daemon lifecycle operations.
-
-All examples are under:
-
-```text
-examples/node/
-examples/browser/
-```