@factory/droid-sdk 0.2.0 → 0.4.0

package/examples/structured-output.ts

@@ -6,43 +6,50 @@
  *
  * Usage:
  *   npx tsx examples/structured-output.ts
- *   npx tsx examples/structured-output.ts "Return a TypeScript pioneer"
+ *   npx tsx examples/structured-output.ts "Pick a favorite number between 1 and 42"
  */
 
 import assert from 'node:assert/strict';
 
-import { OutputFormatType, run } from '../src/index.js';
+import { OutputFormatType, run } from '@factory/droid-sdk';
+
+type FavoriteNumber = { favoriteNumber: number };
 
 async function main(): Promise<void> {
   const prompt =
     process.argv.slice(2).join(' ') ||
-    'Return exactly this person: name Ada Lovelace, language TypeScript.';
+    'Pick a favorite number between 1 and 42.';
 
   const outputFormat = {
     type: OutputFormatType.JsonSchema,
     schema: {
       type: 'object',
       properties: {
-        name: { type: 'string' },
-        language: { type: 'string' },
+        favoriteNumber: {
+          type: 'number',
+          minimum: 1,
+          maximum: 42,
+        },
       },
-      required: ['name', 'language'],
+      required: ['favoriteNumber'],
     },
   };
 
   console.log(`Sending prompt: "${prompt}"\n`);
 
   const result = await run(prompt, {
+    apiKey: process.env.FACTORY_API_KEY!,
     cwd: process.cwd(),
     outputFormat,
   });
 
-  assert.ok(result.structuredOutput, 'Expected structuredOutput to be set');
-  assert.equal(typeof result.structuredOutput['name'], 'string');
-  assert.equal(typeof result.structuredOutput['language'], 'string');
+  const structuredOutput = result.structuredOutput as FavoriteNumber | null;
+
+  assert.ok(structuredOutput, 'Expected structuredOutput to be set');
+  assert.equal(typeof structuredOutput.favoriteNumber, 'number');
 
   console.log('=== Structured output ===');
-  console.log(JSON.stringify(result.structuredOutput, null, 2));
+  console.log(JSON.stringify(structuredOutput, null, 2));
 
   console.log('\nStructured output example passed');
 }

package/examples/test-compact.ts

@@ -10,10 +10,13 @@
  *   npx tsx examples/test-compact.ts
  */
 
-import { createSession, DroidMessageType } from '../src/index.js';
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
 async function main(): Promise<void> {
-  const session = await createSession({ cwd: process.cwd() });
+  const session = await createSession({
+    apiKey: process.env.FACTORY_API_KEY!,
+    cwd: process.cwd(),
+  });
   try {
     console.log(`Session created: ${session.sessionId}\n`);
 
@@ -27,11 +30,13 @@ async function main(): Promise<void> {
       console.log(`=== Turn ${i + 1} ===`);
       console.log(`Prompt: "${prompts[i]}"\n`);
 
-      for await (const msg of session.stream(prompts[i])) {
+      for await (const msg of session.stream(prompts[i], {
+        includePartialMessages: true,
+      })) {
         if (msg.type === DroidMessageType.AssistantTextDelta) {
           process.stdout.write(msg.text);
         }
-        if (msg.type === DroidMessageType.TurnComplete) {
+        if (msg.type === DroidMessageType.Result) {
           console.log('\n');
         }
       }

package/examples/test-rewind.ts

@@ -1,155 +1,87 @@
 /**
- * Rewind example (getRewindInfo + executeRewind).
- *
- * Demonstrates the low-level DroidClient API for rewind operations.
- * Uses explicit user message IDs so they can be referenced as rewind
- * targets — the snapshot system uses user message IDs as boundary
- * markers.
+ * Low-level rewind API example.
  *
  * Usage:
  *   npx tsx examples/test-rewind.ts
  */
 
-import crypto from 'node:crypto';
+import { randomUUID } from 'node:crypto';
 
 import {
-  DroidClient,
-  ProcessTransport,
   AutonomyLevel,
+  DroidClient,
   DroidWorkingState,
+  ProcessTransport,
   SessionNotificationType,
-  ToolConfirmationOutcome,
-} from '../src/index.js';
-
-function uuid(): string {
-  return crypto.randomUUID();
-}
-
-/**
- * Send a user message with an explicit messageId and wait for the
- * agent turn to complete by observing working-state notifications.
- */
-async function sendAndWait(
-  client: DroidClient,
-  text: string,
-  messageId: string
-): Promise<void> {
-  return new Promise<void>((resolve) => {
-    let wasActive = false;
-
-    const unsub = client.onNotification((notification) => {
-      const params = notification['params'] as
-        | Record<string, unknown>
-        | undefined;
-      const inner = params?.['notification'] as
-        | Record<string, unknown>
-        | undefined;
-      if (!inner) return;
+} from '@factory/droid-sdk';
+
+function waitForTurn(client: DroidClient): Promise<void> {
+  return new Promise((resolve) => {
+    let started = false;
+    const unsubscribe = client.onNotification((notification) => {
+      const params = notification['params'];
+      if (typeof params !== 'object' || params === null) {
+        return;
+      }
 
-      if (inner['type'] === SessionNotificationType.ASSISTANT_TEXT_DELTA) {
-        const delta = inner['textDelta'] as string | undefined;
-        if (delta) process.stdout.write(delta);
+      const event = (params as Record<string, unknown>)['notification'];
+      if (typeof event !== 'object' || event === null) {
+        return;
       }
 
       if (
-        inner['type'] === SessionNotificationType.DROID_WORKING_STATE_CHANGED
+        (event as Record<string, unknown>)['type'] !==
+        SessionNotificationType.DROID_WORKING_STATE_CHANGED
       ) {
-        const newState = inner['newState'] as string;
-        if (newState !== DroidWorkingState.Idle) {
-          wasActive = true;
-        }
-        if (newState === DroidWorkingState.Idle && wasActive) {
-          unsub();
-          resolve();
-        }
+        return;
       }
-    });
 
-    void client.addUserMessage({ text, messageId });
+      const newState = (event as Record<string, unknown>)['newState'];
+      started ||= newState !== DroidWorkingState.Idle;
+      if (started && newState === DroidWorkingState.Idle) {
+        unsubscribe();
+        resolve();
+      }
+    });
   });
 }
 
-async function main(): Promise<void> {
-  console.log('=== Creating session ===');
-  const transport = new ProcessTransport({ cwd: process.cwd() });
-  await transport.connect();
-  const client = new DroidClient({ transport });
+const transport = new ProcessTransport({ cwd: process.cwd() });
+await transport.connect();
+
+const client = new DroidClient({ transport });
 
-  const initResult = await client.initializeSession({
+try {
+  await client.initializeSession({
     machineId: 'default',
     cwd: process.cwd(),
     autonomyLevel: AutonomyLevel.High,
   });
-  console.log(`Session ID: ${initResult.sessionId}\n`);
-
-  client.setPermissionHandler(() => ToolConfirmationOutcome.ProceedOnce);
-
-  const userMsgId1 = uuid();
-  console.log(`=== Turn 1: "hello" (msgId: ${userMsgId1.slice(0, 12)}...) ===`);
-  await sendAndWait(client, 'Say "hello" and nothing else.', userMsgId1);
-  console.log('\n');
 
-  const userMsgId2 = uuid();
-  console.log(
-    `=== Turn 2: create file (msgId: ${userMsgId2.slice(0, 12)}...) ===`
-  );
-  await sendAndWait(
-    client,
-    'Create a file called /tmp/droid-sdk-rewind-test.txt with the content ' +
-      '"rewind test data". Do not explain, just create it.',
-    userMsgId2
-  );
-  console.log('\n');
+  const messageId = randomUUID();
+  const done = waitForTurn(client);
+  await client.addUserMessage({
+    messageId,
+    text: 'Say "hello" and nothing else.',
+  });
+  await done;
 
-  console.log(`=== getRewindInfo (msgId: ${userMsgId2.slice(0, 12)}...) ===`);
   try {
-    const rewindInfo = await client.getRewindInfo({ messageId: userMsgId2 });
-    console.log(
-      `  Available files to restore: ${rewindInfo.availableFiles.length}`
-    );
-    for (const f of rewindInfo.availableFiles) {
-      console.log(`    - ${f.filePath} (${f.size} bytes)`);
-    }
-    console.log(`  Created files to delete: ${rewindInfo.createdFiles.length}`);
-    for (const f of rewindInfo.createdFiles) {
-      console.log(`    - ${f.filePath}`);
-    }
-    console.log(`  Evicted files: ${rewindInfo.evictedFiles.length}`);
-  } catch (err) {
+    const rewindInfo = await client.getRewindInfo({ messageId });
     console.log(
-      `  Error (expected — server does not yet support this): ${err instanceof Error ? err.message : String(err)}`
+      `Files available to restore: ${rewindInfo.availableFiles.length}`
     );
-  }
-  console.log();
 
-  console.log(
-    `=== executeRewind (to msgId: ${userMsgId1.slice(0, 12)}...) ===`
-  );
-  try {
-    const rewindResult = await client.executeRewind({
-      messageId: userMsgId1,
+    const rewind = await client.executeRewind({
+      messageId,
       filesToRestore: [],
       filesToDelete: [],
-      forkTitle: 'Rewind to first hello',
+      forkTitle: 'Rewind example',
     });
-    console.log(`  New session ID: ${rewindResult.newSessionId}`);
-    console.log(`  Restored: ${rewindResult.restoredCount}`);
-    console.log(`  Deleted: ${rewindResult.deletedCount}`);
-    console.log(`  Failed restores: ${rewindResult.failedRestoreCount}`);
-    console.log(`  Failed deletes: ${rewindResult.failedDeleteCount}`);
-  } catch (err) {
-    console.log(
-      `  Error (expected — server does not yet support this): ${err instanceof Error ? err.message : String(err)}`
-    );
+    console.log(`Rewound into session: ${rewind.newSessionId}`);
+  } catch (error) {
+    console.log(`Rewind unavailable: ${String(error)}`);
   }
-  console.log();
-
-  console.log('=== Closing ===');
+} finally {
   await client.close();
-  console.log('Done.');
 }
-
-main().catch((err: unknown) => {
-  console.error('Fatal error:', err);
-  process.exit(1);
-});

package/examples/tool-controls.ts

@@ -1,69 +1,37 @@
 /**
  * Tool controls example.
  *
- * Demonstrates:
- * - configuring enabled and disabled tool IDs at session creation
- * - inspecting the current tool catalog with `listTools()`
- * - updating tool overrides with `updateSettings()`
- *
  * Usage:
  *   npx tsx examples/tool-controls.ts
  */
 
-import { createSession } from '../src/index.js';
-import type { ExecToolInfo } from '../src/index.js';
+import { createSession } from '@factory/droid-sdk';
 
-function printToolState(label: string, tool: ExecToolInfo | undefined): void {
-  if (!tool) {
-    console.log(`${label}: not present in tool catalog`);
-    return;
-  }
+const session = await createSession({
+  apiKey: process.env.FACTORY_API_KEY!,
+  cwd: process.cwd(),
+  enabledToolIds: ['Read', 'Grep'],
+  disabledToolIds: ['Execute'],
+});
 
+try {
+  const before = await session.listTools();
   console.log(
-    `${label}: defaultAllowed=${tool.defaultAllowed}, currentlyAllowed=${tool.currentlyAllowed}`
+    before.tools
+      .filter((tool) => ['Read', 'Execute'].includes(tool.llmId))
+      .map((tool) => `${tool.llmId}: ${String(tool.currentlyAllowed)}`)
+      .join('\n')
   );
-}
-
-async function main(): Promise<void> {
-  const session = await createSession({
-    cwd: process.cwd(),
-    enabledToolIds: ['Read', 'Glob', 'Grep'],
-    disabledToolIds: ['Execute'],
-  });
-
-  try {
-    console.log(`Session created: ${session.sessionId}\n`);
-
-    const initial = await session.listTools();
-    const initialRead = initial.tools.find((tool) => tool.llmId === 'Read');
-    const initialExecute = initial.tools.find(
-      (tool) => tool.llmId === 'Execute'
-    );
 
-    console.log('=== Initial tool state ===');
-    printToolState('Read', initialRead);
-    printToolState('Execute', initialExecute);
+  await session.updateSettings({ disabledToolIds: ['Read', 'Execute'] });
 
-    await session.updateSettings({
-      disabledToolIds: ['Read', 'Execute'],
-    });
-
-    const updated = await session.listTools();
-    const updatedRead = updated.tools.find((tool) => tool.llmId === 'Read');
-    const updatedExecute = updated.tools.find(
-      (tool) => tool.llmId === 'Execute'
-    );
-
-    console.log('\n=== Updated tool state ===');
-    printToolState('Read', updatedRead);
-    printToolState('Execute', updatedExecute);
-  } finally {
-    await session.close();
-    console.log('\nSession closed.');
-  }
+  const after = await session.listTools();
+  console.log(
+    after.tools
+      .filter((tool) => ['Read', 'Execute'].includes(tool.llmId))
+      .map((tool) => `${tool.llmId}: ${String(tool.currentlyAllowed)}`)
+      .join('\n')
+  );
+} finally {
+  await session.close();
 }
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factory/droid-sdk",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "private": false,
   "description": "TypeScript SDK for the Factory Droid CLI",
   "keywords": [
@@ -57,12 +57,14 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "uuid": "^11.1.0",
+    "ws": "^8.21.0",
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
     "@types/node": "^22.15.0",
     "@types/uuid": "^10.0.0",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^3.1.0",
     "eslint": "^9.24.0",
     "eslint-import-resolver-typescript": "^4.4.4",

package/docs/examples/init-metadata.md

@@ -1,79 +0,0 @@
-# Example: initialization metadata
-
-Use this when you need the raw initialization payload, early session IDs, or model/settings metadata.
-
-## What this example shows
-
-- reading `query().sessionId` and `query().initResult`
-- waiting for `query().initialized`
-- reading `session.initResult` from `createSession()` and `resumeSession()`
-
-## Key snippet: inspect a query before and after initialization
-
-```ts
-const stream = query({
-  prompt: 'Reply with "ready" and nothing else.',
-  cwd: process.cwd(),
-});
-
-console.log(stream.sessionId);
-console.log(stream.initResult);
-
-const initialized = await stream.initialized;
-console.log(initialized.sessionId);
-console.log(initialized.settings.modelId);
-```
-
-Before initialization completes, `sessionId` and `initResult` are `null`.
-
-## Key snippet: read metadata from sessions
-
-```ts
-const session = await createSession({ cwd: process.cwd() });
-const resumed = await resumeSession(session.sessionId, { cwd: process.cwd() });
-
-console.log(session.initResult.settings.modelId);
-console.log(resumed.initResult.cwd);
-```
-
-## Full script
-
-```ts
-import { createSession, query, resumeSession } from '@factory/droid-sdk';
-
-async function main(): Promise<void> {
-  const stream = query({
-    prompt: 'Reply with "ready" and nothing else.',
-    cwd: process.cwd(),
-  });
-
-  console.log(stream.sessionId);
-  console.log(stream.initResult);
-
-  const initialized = await stream.initialized;
-  console.log(initialized.sessionId);
-  console.log(initialized.settings.modelId);
-
-  stream.abort();
-
-  const session = await createSession({ cwd: process.cwd() });
-  let resumed: Awaited<ReturnType<typeof resumeSession>> | null = null;
-
-  try {
-    resumed = await resumeSession(session.sessionId, {
-      cwd: process.cwd(),
-    });
-
-    console.log(session.initResult.settings.modelId);
-    console.log(resumed.initResult.cwd);
-  } finally {
-    await resumed?.close();
-    await session.close();
-  }
-}
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
-```

package/docs/examples/list-sessions.md

@@ -1,64 +0,0 @@
-# Example: list saved sessions
-
-Use `listSessions()` when you need recent Droid session history without launching a subprocess.
-
-## What this example shows
-
-- listing recent sessions for the current project
-- listing recent sessions across all projects
-- formatting returned `SessionMetadata`
-
-## Key snippet: project-scoped listing
-
-```ts
-const currentProject = await listSessions({ numSessions: 10 });
-```
-
-## Key snippet: cross-project listing
-
-```ts
-const allSessions = await listSessions({
-  fetchOutsideCWD: true,
-  numSessions: 5,
-});
-```
-
-This helper reads local session files directly and returns `SessionMetadata[]`.
-
-## Full script
-
-```ts
-import { listSessions } from '@factory/droid-sdk';
-
-function formatDate(date: Date): string {
-  return date.toISOString().replace('T', ' ').slice(0, 19);
-}
-
-async function main(): Promise<void> {
-  const currentProject = await listSessions({ numSessions: 10 });
-
-  for (const session of currentProject) {
-    const title = session.sessionTitle ?? session.title ?? '(untitled)';
-    console.log(
-      `[${session.id.slice(0, 8)}] ${formatDate(session.modifiedTime)} ${session.messageCount} msgs — ${title}`
-    );
-  }
-
-  const allSessions = await listSessions({
-    fetchOutsideCWD: true,
-    numSessions: 5,
-  });
-
-  for (const session of allSessions) {
-    const title = session.sessionTitle ?? session.title ?? '(untitled)';
-    console.log(
-      `[${session.id.slice(0, 8)}] ${formatDate(session.modifiedTime)} — ${title}`
-    );
-  }
-}
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
-```

package/docs/examples/multi-turn-session.md

@@ -1,77 +0,0 @@
-# Example: multi-turn session
-
-Use `createSession()` when you want conversation state to persist across turns.
-
-## What this example shows
-
-- creating a persistent session
-- streaming one turn with `session.stream()`
-- collecting a later turn with `session.send()`
-- closing the session cleanly
-
-## Key snippet: create the session
-
-```ts
-const session = await createSession({ cwd: process.cwd() });
-```
-
-Create the session once and reuse it across prompts.
-
-## Key snippet: stream a turn
-
-```ts
-import { DroidMessageType } from '@factory/droid-sdk';
-
-for await (const msg of session.stream(
-  'List the TypeScript files in this project'
-)) {
-  if (msg.type === DroidMessageType.AssistantTextDelta) {
-    process.stdout.write(msg.text);
-  }
-}
-```
-
-Use `stream()` when you want incremental output.
-
-## Key snippet: collect a full response
-
-```ts
-const result = await session.send('Summarize the project in one sentence');
-console.log(result.text);
-```
-
-Use `send()` when you want the SDK to aggregate the turn for you.
-
-## Full script
-
-```ts
-import { createSession, DroidMessageType } from '@factory/droid-sdk';
-
-async function main(): Promise<void> {
-  const session = await createSession({ cwd: process.cwd() });
-
-  console.log(`Session created: ${session.sessionId}\n`);
-
-  try {
-    for await (const msg of session.stream(
-      'List the TypeScript files in this project'
-    )) {
-      if (msg.type === DroidMessageType.AssistantTextDelta) {
-        process.stdout.write(msg.text);
-      }
-    }
-
-    console.log('\n');
-
-    const result = await session.send('Summarize the project in one sentence');
-    console.log(result.text);
-  } finally {
-    await session.close();
-  }
-}
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
-```