feat: daemon SDK MVP — connectDaemon, DaemonConnection, DaemonSession

docs/sdk-usage-guide.md

@@ -6,12 +6,13 @@
 npm install @factory/droid-sdk
 ```
 
-Requires Node.js 18+ and the `droid` CLI on your PATH.
+Requires Node.js 18+ and the `droid` CLI on your PATH. This guide covers **exec mode** (`run()`, `createSession()`), which spawns a subprocess per session. For WebSocket-based daemon mode with concurrent sessions, see the [Daemon Usage Guide](./daemon-usage-guide.md).
 
 ```ts
 import { run } from '@factory/droid-sdk';
 
 const result = await run('What files are in this directory?', {
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
 });
 console.log(result.text);
@@ -26,7 +27,10 @@ Send a prompt, get a result, done. The session is created and closed automatical
 ```ts
 import { run } from '@factory/droid-sdk';
 
-const result = await run('What is 2 + 2?', { cwd: process.cwd() });
+const result = await run('What is 2 + 2?', {
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 console.log(result.text);
 ```
 
@@ -38,6 +42,7 @@ Force the response to match a JSON schema. The validated object is available on
 import { OutputFormatType, run } from '@factory/droid-sdk';
 
 const result = await run('Pick a number between 1 and 42.', {
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   outputFormat: {
     type: OutputFormatType.JsonSchema,
@@ -57,16 +62,19 @@ console.log((result.structuredOutput as { number: number }).number);
 Create a session once, then call `stream()` multiple times. Context is preserved across turns.
 
 ```ts
-import { createSession } from '@factory/droid-sdk';
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 for await (const msg of session.stream('Remember the word "mango".')) {
   // consume first turn
 }
 
 for await (const msg of session.stream('What word did I say?')) {
-  if (msg.type === 'assistant') console.log(msg.text);
+  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
 }
 
 await session.close();
@@ -77,12 +85,14 @@ await session.close();
 Reconnect to a previously created session by its ID.
 
 ```ts
-import { resumeSession } from '@factory/droid-sdk';
+import { resumeSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await resumeSession('existing-session-id');
+const session = await resumeSession('existing-session-id', {
+  apiKey: process.env.FACTORY_API_KEY!,
+});
 
 for await (const msg of session.stream('Continue where we left off.')) {
-  if (msg.type === 'assistant') console.log(msg.text);
+  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
 }
 
 await session.close();
@@ -95,7 +105,10 @@ await session.close();
 ```ts
 import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 for await (const msg of session.stream(
   'List files in the current directory.'
@@ -126,7 +139,10 @@ Enable `includePartialMessages` to get token-by-token deltas, thinking blocks, a
 ```ts
 import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 for await (const msg of session.stream('Explain recursion.', {
   includePartialMessages: true,
@@ -144,19 +160,25 @@ await session.close();
 Use `session.interrupt()` to stop the current turn server-side, or pass an `AbortSignal` to cancel from the client.
 
 ```ts
-import { createSession } from '@factory/droid-sdk';
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
 // Interrupt after receiving some output
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 for await (const msg of session.stream('Write a long essay.')) {
-  if (msg.type === 'assistant') {
+  if (msg.type === DroidMessageType.Assistant) {
     await session.interrupt();
   }
 }
 await session.close();
 
 // Or cancel with AbortSignal
-const session2 = await createSession({ cwd: process.cwd() });
+const session2 = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 const controller = new AbortController();
 setTimeout(() => controller.abort(), 2000);
 
@@ -179,6 +201,7 @@ Define custom tools that Droid can call during a session. Tools are served via a
 import {
   createSession,
   createSdkMcpServer,
+  DroidMessageType,
   tool,
   ToolConfirmationOutcome,
 } from '@factory/droid-sdk';
@@ -199,13 +222,14 @@ const server = createSdkMcpServer({
 });
 
 const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   mcpServers: [server],
   permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
 });
 
 for await (const msg of session.stream('Look up Alice.')) {
-  if (msg.type === 'assistant') console.log(msg.text);
+  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
 }
 
 await session.close();
@@ -219,6 +243,7 @@ Control what Droid can do without asking for permission. Set at session creation
 import { createSession, AutonomyLevel } from '@factory/droid-sdk';
 
 const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   autonomyLevel: AutonomyLevel.High, // Off | Low | Medium | High
 });
@@ -236,6 +261,7 @@ Restrict which tools Droid can use. Accepts tool IDs like `'Read'`, `'Execute'`,
 import { createSession } from '@factory/droid-sdk';
 
 const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   enabledToolIds: ['Read', 'Grep'],
   disabledToolIds: ['Execute'],
@@ -258,6 +284,7 @@ import {
 } from '@factory/droid-sdk';
 
 await run('Create hello.txt with "Hello, World!"', {
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   permissionHandler(params) {
     const safe = params.toolUses.every(
@@ -283,6 +310,7 @@ import {
 } from '@factory/droid-sdk';
 
 const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   interactionMode: DroidInteractionMode.Spec,
   permissionHandler(params) {
@@ -306,9 +334,12 @@ Send images or documents alongside your prompt. Images must be base64-encoded.
 
 ```ts
 import { readFileSync } from 'node:fs';
-import { createSession } from '@factory/droid-sdk';
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 for await (const msg of session.stream('Describe this image.', {
   images: [
@@ -319,7 +350,7 @@ for await (const msg of session.stream('Describe this image.', {
     },
   ],
 })) {
-  if (msg.type === 'assistant') console.log(msg.text);
+  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
 }
 
 await session.close();
@@ -330,17 +361,26 @@ await session.close();
 Create a copy of the current session with all context preserved. Useful for branching a conversation.
 
 ```ts
-import { createSession, resumeSession } from '@factory/droid-sdk';
+import {
+  createSession,
+  DroidMessageType,
+  resumeSession,
+} from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 for await (const msg of session.stream('Remember: the password is "banana".')) {
 }
 
 const { newSessionId } = await session.forkSession();
-const fork = await resumeSession(newSessionId);
+const fork = await resumeSession(newSessionId, {
+  apiKey: process.env.FACTORY_API_KEY!,
+});
 
 for await (const msg of fork.stream('What is the password?')) {
-  if (msg.type === 'assistant') console.log(msg.text);
+  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
 }
 
 await fork.close();
@@ -354,7 +394,10 @@ Summarize and remove old messages to free up context window space.
 ```ts
 import { createSession } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 // ... after many turns ...
 const result = await session.compactSession();
@@ -376,7 +419,10 @@ import {
   AutonomyLevel,
 } from '@factory/droid-sdk';
 
-const transport = new ProcessTransport({ cwd: process.cwd() });
+const transport = new ProcessTransport({
+  cwd: process.cwd(),
+  env: { FACTORY_API_KEY: process.env.FACTORY_API_KEY! },
+});
 await transport.connect();
 const client = new DroidClient({ transport });
 
@@ -423,6 +469,7 @@ Choose which model to use and how much reasoning effort to apply. Configurable a
 import { createSession, ReasoningEffort } from '@factory/droid-sdk';
 
 const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   modelId: 'claude-sonnet-4-20250514',
   reasoningEffort: ReasoningEffort.High,
@@ -443,7 +490,10 @@ Observe file hooks (pre/post tool execution hooks) as they run during a session.
 ```ts
 import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 for await (const msg of session.stream('Create a new file.')) {
   if (msg.type === DroidMessageType.Hook) {
@@ -463,9 +513,10 @@ await session.close();
 Programmatically answer questions that Droid asks the user during execution.
 
 ```ts
-import { createSession } from '@factory/droid-sdk';
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
 const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
   cwd: process.cwd(),
   askUserHandler(params) {
     return {
@@ -480,7 +531,7 @@ const session = await createSession({
 });
 
 for await (const msg of session.stream('Help me set up this project.')) {
-  if (msg.type === 'assistant') console.log(msg.text);
+  if (msg.type === DroidMessageType.Assistant) console.log(msg.text);
 }
 
 await session.close();
@@ -493,7 +544,10 @@ Add, remove, toggle, and list MCP servers at runtime within an active session.
 ```ts
 import { createSession, McpServerType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 await session.addMcpServer({
   name: 'my-server',
@@ -514,7 +568,10 @@ Query current context window usage to understand how much capacity remains.
 ```ts
 import { createSession } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 for await (const msg of session.stream('Hello')) {
 }
 
@@ -533,7 +590,10 @@ Monitor token consumption in real-time via stream events, or read the final tota
 ```ts
 import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 for await (const msg of session.stream('Summarize this project.', {
   includePartialMessages: true,
@@ -558,7 +618,10 @@ List all available skills in the current session.
 ```ts
 import { createSession } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 const { skills } = await session.listSkills();
 
 for (const skill of skills) {
@@ -575,7 +638,10 @@ Subscribe to raw protocol notifications for custom event handling beyond the str
 ```ts
 import { createSession, SessionNotificationType } from '@factory/droid-sdk';
 
-const session = await createSession({ cwd: process.cwd() });
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+});
 
 const unsubscribe = session.onNotification(
   (notification) => {
@@ -604,7 +670,9 @@ import {
 } from '@factory/droid-sdk';
 
 try {
-  const session = await resumeSession('nonexistent-id');
+  const session = await resumeSession('nonexistent-id', {
+    apiKey: process.env.FACTORY_API_KEY!,
+  });
 } catch (error) {
   if (error instanceof SessionNotFoundError) {
     console.log(`Session not found: ${error.sessionId}`);
@@ -634,6 +702,7 @@ The package also exports its full Zod schema surface from `src/schemas/index.ts`
 
 | Field                     | Type                     | Description                                                 |
 | :------------------------ | :----------------------- | :---------------------------------------------------------- |
+| `apiKey`                  | `string`                 | **Required.** Factory API key for authentication            |
 | `cwd`                     | `string`                 | Working directory for the session                           |
 | `machineId`               | `string`                 | Machine identifier for initialization                       |
 | `modelId`                 | `string`                 | LLM model identifier                                        |
@@ -646,6 +715,7 @@ The package also exports its full Zod schema surface from `src/schemas/index.ts`
 | `enabledToolIds`          | `string[]`               | Tool allowlist                                              |
 | `disabledToolIds`         | `string[]`               | Tool denylist                                               |
 | `tags`                    | `SessionTag[]`           | Session tags for categorization                             |
+| `sessionSource`           | `SessionSource`          | Attribution metadata (e.g., integration origin)             |
 | `permissionHandler`       | `PermissionHandler`      | Tool confirmation callback                                  |
 | `askUserHandler`          | `AskUserHandler`         | Structured user-input callback                              |
 | `execPath`                | `string`                 | Path to `droid` executable (default: `"droid"`)             |