@factory/droid-sdk 0.2.0 → 0.3.0

package/examples/abort-session-stream.ts

@@ -1,67 +1,31 @@
 /**
- * Manual smoke test for cancelling `session.stream(..., { abortSignal })`.
- *
- * Starts a long-running streaming turn, aborts it after a short delay, then
- * verifies the stream rejects with the abort reason.
+ * Abort a running turn with AbortController.
  *
  * Usage:
  *   npx tsx examples/abort-session-stream.ts
- *   npx tsx examples/abort-session-stream.ts 3000
  */
 
-import { createSession, DroidMessageType } from '../src/index.js';
-
-async function main(): Promise<void> {
-  const abortAfterMs = Number(process.argv[2] ?? 2000);
-  if (!Number.isFinite(abortAfterMs) || abortAfterMs <= 0) {
-    throw new Error('Abort delay must be a positive number of milliseconds.');
-  }
-
-  const controller = new AbortController();
-  const session = await createSession({ cwd: process.cwd() });
-  let textDeltaCount = 0;
-  let receivedText = '';
-
-  const timeout = setTimeout(() => {
-    controller.abort(new Error(`Aborted after ${abortAfterMs}ms`));
-  }, abortAfterMs);
+import { createSession } from '@factory/droid-sdk';
 
-  try {
-    console.log(`Session created: ${session.sessionId}`);
-    console.log(`Aborting after ${abortAfterMs}ms\n`);
+const session = await createSession({ cwd: process.cwd() });
+const controller = new AbortController();
+const timeout = setTimeout(
+  () => controller.abort(new Error('Stopped by AbortController')),
+  1000
+);
 
-    const prompt =
-      'Write a long, detailed explanation of how compilers work, including ' +
-      'lexing, parsing, semantic analysis, optimization, and code generation.';
-
-    for await (const message of session.stream(prompt, {
+try {
+  for await (const _msg of session.stream(
+    'Write a long explanation of how compilers work.',
+    {
       abortSignal: controller.signal,
-    })) {
-      if (message.type === DroidMessageType.AssistantTextDelta) {
-        textDeltaCount++;
-        receivedText += message.text;
-        process.stdout.write(message.text);
-      }
-    }
-
-    throw new Error('Expected stream to abort, but it completed normally.');
-  } catch (error) {
-    if (error instanceof Error && error.message.includes('Aborted after')) {
-      console.log('\n\n=== Abort confirmed ===');
-      console.log(`Received text deltas before abort: ${textDeltaCount}`);
-      console.log(`Received characters before abort: ${receivedText.length}`);
-      return;
     }
-
-    throw error;
-  } finally {
-    clearTimeout(timeout);
-    await session.close();
-    console.log('Session closed.');
+  )) {
+    void _msg;
   }
+} catch (error) {
+  console.log(error instanceof Error ? error.message : String(error));
+} finally {
+  clearTimeout(timeout);
+  await session.close();
 }
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});

package/examples/droid-dev-structured-output.ts

@@ -1,15 +1,14 @@
 /**
- * One-off integration smoke test for JSON output against droid-dev.
+ * One-off integration smoke test for JSON output against Droid.
  *
  * Usage:
  *   npx tsx examples/droid-dev-structured-output.ts
- *   DROID_EXEC_PATH=/path/to/droid-dev npx tsx examples/droid-dev-structured-output.ts
+ *   DROID_EXEC_PATH=/path/to/droid npx tsx examples/droid-dev-structured-output.ts
  */
 
+import { run } from '@factory/droid-sdk';
 import { z } from 'zod';
 
-import { run } from '../src/index.js';
-
 const PersonSchema = z.object({
   name: z.literal('Ada Lovelace'),
   language: z.literal('TypeScript'),
@@ -17,7 +16,7 @@ const PersonSchema = z.object({
 });
 
 async function main(): Promise<void> {
-  const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid-dev';
+  const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid';
 
   const result = await run(
     [

package/examples/fork-session.ts

@@ -10,7 +10,24 @@
  *   npx tsx examples/fork-session.ts
  */
 
-import { createSession, resumeSession } from '../src/index.js';
+import {
+  DroidMessageType,
+  createSession,
+  resumeSession,
+} from '@factory/droid-sdk';
+
+async function streamText(
+  session: Awaited<ReturnType<typeof createSession>>,
+  prompt: string
+): Promise<string> {
+  let text = '';
+  for await (const msg of session.stream(prompt)) {
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      text += msg.text;
+    }
+  }
+  return text;
+}
 
 async function main(): Promise<void> {
   const session = await createSession({ cwd: process.cwd() });
@@ -18,17 +35,19 @@ async function main(): Promise<void> {
 
   try {
     console.log(`Original session: ${session.sessionId}\n`);
-
-    await session.send('Remember this phrase exactly: mango sunrise');
+    await streamText(session, 'Remember this phrase exactly: mango sunrise');
 
     const { newSessionId } = await session.forkSession();
     console.log(`Forked session:   ${newSessionId}\n`);
 
-    fork = await resumeSession(newSessionId, { cwd: process.cwd() });
+    fork = await resumeSession(newSessionId);
 
-    const result = await fork.send('What phrase did I ask you to remember?');
+    const result = await streamText(
+      fork,
+      'What phrase did I ask you to remember?'
+    );
     console.log('Fork response:');
-    console.log(result.text);
+    console.log(result);
   } finally {
     await fork?.close();
     await session.close();

package/examples/hook-execution.ts

@@ -0,0 +1,62 @@
+/**
+ * Hook execution streaming example.
+ *
+ * Demonstrates how to handle hook execution messages in a session stream.
+ *
+ * Usage:
+ *   npx tsx examples/hook-execution.ts
+ */
+
+import { DroidMessageType, createSession } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const prompt = 'Run a simple shell command using Execute tool.';
+
+  console.log(`Sending prompt: "${prompt}"\n`);
+
+  // Note: To actually see hooks, you need to have hooks configured in your droid settings.
+  const session = await createSession({ cwd: process.cwd() });
+
+  try {
+    for await (const msg of session.stream(prompt)) {
+      switch (msg.type) {
+        case DroidMessageType.Assistant:
+          process.stdout.write(msg.text);
+          break;
+
+        case DroidMessageType.ToolCall:
+          console.log(`\n[Tool Call] ${msg.toolUse.name} (${msg.toolUse.id})`);
+          break;
+
+        case DroidMessageType.Hook:
+          if (msg.status === 'started') {
+            console.log(
+              `  [Hook Started] ID: ${msg.hookId}, Event: ${msg.eventName}, Command: ${msg.command}`
+            );
+          } else {
+            console.log(
+              `  [Hook ${msg.status}] ID: ${msg.hookId}, Exit Code: ${msg.exitCode}`
+            );
+            if (msg.stdout) console.log(`    stdout: ${msg.stdout.trim()}`);
+            if (msg.stderr) console.log(`    stderr: ${msg.stderr.trim()}`);
+          }
+          break;
+
+        case DroidMessageType.ToolResult:
+          console.log(`[Tool Result] ${msg.isError ? 'Error' : 'OK'}`);
+          break;
+
+        case DroidMessageType.Result:
+          console.log('\n\n--- Turn complete ---');
+          break;
+      }
+    }
+  } finally {
+    await session.close();
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/init-metadata.ts

@@ -1,76 +1,19 @@
 /**
  * Initialization metadata example.
  *
- * Demonstrates:
- * - `query().sessionId`, `query().initResult`, and `query().initialized`
- * - `session.initResult` from `createSession()`
- * - `resumed.initResult` from `resumeSession()`
- *
  * Usage:
  *   npx tsx examples/init-metadata.ts
  */
 
-import {
-  createSession,
-  DroidMessageType,
-  query,
-  resumeSession,
-} from '../src/index.js';
-
-async function main(): Promise<void> {
-  const stream = query({
-    prompt: 'Reply with "ready" and nothing else.',
-    cwd: process.cwd(),
-  });
-
-  console.log('=== query() metadata ===');
-  console.log(`Before initialization: sessionId=${String(stream.sessionId)}`);
-  console.log(`Before initialization: initResult=${String(stream.initResult)}`);
-
-  const initialized = await stream.initialized;
-  console.log(`After initialization: sessionId=${initialized.sessionId}`);
-  console.log(`Model: ${String(initialized.settings.modelId)}`);
-  console.log(
-    `Cached initResult matches initialized: ${String(stream.initResult === initialized)}`
-  );
-
-  let text = '';
-  for await (const msg of stream) {
-    if (msg.type === DroidMessageType.AssistantTextDelta) {
-      text += msg.text;
-    }
-  }
-  console.log(`Response: ${JSON.stringify(text.trim())}\n`);
-
-  console.log('=== createSession() / resumeSession() metadata ===');
-  const session = await createSession({ cwd: process.cwd() });
-  let resumed: Awaited<ReturnType<typeof resumeSession>> | null = null;
-
-  try {
-    console.log(`Created session: ${session.sessionId}`);
-    console.log(
-      `createSession().initResult.settings.modelId=${String(session.initResult.settings.modelId)}`
-    );
+import { createSession, resumeSession } from '@factory/droid-sdk';
 
-    resumed = await resumeSession(session.sessionId, {
-      cwd: process.cwd(),
-    });
+const session = await createSession({ cwd: process.cwd() });
+const resumed = await resumeSession(session.sessionId);
 
-    console.log(`Resumed session: ${resumed.sessionId}`);
-    console.log(
-      `resumeSession().initResult.cwd=${String(resumed.initResult.cwd)}`
-    );
-    console.log(
-      `resumeSession().initResult.availableModels=${String(resumed.initResult.availableModels?.length ?? 0)}`
-    );
-  } finally {
-    await resumed?.close();
-    await session.close();
-    console.log('\nSessions closed.');
-  }
-}
+console.log(`created session: ${session.sessionId}`);
+console.log(`resumed session: ${resumed.sessionId}`);
+console.log(`created model: ${String(session.initResult.settings.modelId)}`);
+console.log(`resumed cwd: ${String(resumed.initResult.cwd)}`);
 
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
+await resumed.close();
+await session.close();

package/examples/interrupt-session.ts

@@ -1,67 +1,32 @@
 /**
- * Interrupt session example.
- *
- * Demonstrates using `session.interrupt()` to stop the agent mid-turn.
- * Starts a streaming turn with a long-running prompt, waits for a few
- * `AssistantTextDelta` messages, then sends an interrupt and continues
- * consuming the stream until `TurnComplete`.
+ * Interrupt a running turn.
  *
  * Usage:
  *   npx tsx examples/interrupt-session.ts
  */
 
-import { createSession, DroidMessageType } from '../src/index.js';
-
-async function main(): Promise<void> {
-  const session = await createSession({ cwd: process.cwd() });
-  try {
-    console.log(`Session created: ${session.sessionId}\n`);
-
-    const prompt =
-      'Write a detailed essay about the history of computing, from the ' +
-      'earliest mechanical calculators to modern quantum computers.';
-    console.log(`Prompt: "${prompt}"\n`);
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
 
-    let deltaCount = 0;
-    let interrupted = false;
+const session = await createSession({ cwd: process.cwd() });
+let deltaCount = 0;
 
-    for await (const msg of session.stream(prompt)) {
-      switch (msg.type) {
-        case DroidMessageType.AssistantTextDelta:
-          deltaCount++;
-          process.stdout.write(msg.text);
+try {
+  for await (const msg of session.stream(
+    'Write a long history of computing.'
+  )) {
+    if (msg.type !== DroidMessageType.AssistantTextDelta) {
+      continue;
+    }
 
-          if (deltaCount === 5 && !interrupted) {
-            interrupted = true;
-            console.log('\n\n>>> Sending interrupt after 5 text deltas...\n');
-            await session.interrupt();
-          }
-          break;
+    process.stdout.write(msg.text);
+    deltaCount++;
 
-        case DroidMessageType.TurnComplete:
-          console.log('\n\n--- Turn complete ---');
-          console.log(`Total text deltas received: ${deltaCount}`);
-          console.log(
-            interrupted
-              ? 'Session was interrupted successfully.'
-              : 'Session completed without interruption.'
-          );
-          if (msg.tokenUsage) {
-            console.log(
-              `Tokens — input: ${msg.tokenUsage.inputTokens}, ` +
-                `output: ${msg.tokenUsage.outputTokens}`
-            );
-          }
-          break;
-      }
+    if (deltaCount === 5) {
+      await session.interrupt();
     }
-  } finally {
-    await session.close();
-    console.log('\nSession closed.');
   }
-}
 
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
+  console.log('\nInterrupted turn.');
+} finally {
+  await session.close();
+}

package/examples/list-sessions.ts

@@ -1,65 +1,19 @@
 /**
- * List sessions example.
- *
- * Demonstrates:
- * - scanning ~/.factory/sessions/ for saved droid sessions
- * - filtering by current working directory
- * - including sessions from other projects with a cap
- *
- * This helper reads the local filesystem directly — no droid process is
- * spawned — so it's safe to call even when no droid is running.
+ * List saved sessions example.
  *
  * Usage:
  *   npx tsx examples/list-sessions.ts
  */
 
-import { listSessions } from '../src/index.js';
-
-function formatDate(date: Date): string {
-  return date.toISOString().replace('T', ' ').slice(0, 19);
-}
-
-async function main(): Promise<void> {
-  console.log(`=== Sessions for ${process.cwd()} ===\n`);
+import { listSessions } from '@factory/droid-sdk';
 
-  // Default call: scopes to process.cwd().
-  const currentProject = await listSessions({ numSessions: 10 });
+const sessions = await listSessions({ numSessions: 5 });
 
-  if (currentProject.length === 0) {
-    console.log('(no sessions recorded for this directory yet)');
-  } else {
-    console.log(`10 most recent for this project:\n`);
-    for (const session of currentProject) {
-      const fav = session.isFavorite ? '*' : ' ';
-      const title = session.sessionTitle ?? session.title ?? '(untitled)';
-      console.log(
-        `  ${fav} [${session.id.slice(0, 8)}] ${formatDate(session.modifiedTime)} ${session.messageCount} msgs — ${title}`
-      );
-    }
-  }
-
-  console.log('\n=== 5 most recent sessions across all projects ===\n');
-
-  const allSessions = await listSessions({
-    fetchOutsideCWD: true,
-    numSessions: 5,
-  });
-
-  if (allSessions.length === 0) {
-    console.log('(no sessions found)');
-  } else {
-    for (const session of allSessions) {
-      const title = session.sessionTitle ?? session.title ?? '(untitled)';
-      const cwd = session.cwd ?? '(no cwd)';
-      console.log(
-        `  [${session.id.slice(0, 8)}] ${formatDate(session.modifiedTime)} — ${title}`
-      );
-      console.log(`      cwd: ${cwd}`);
-    }
-  }
+for (const session of sessions) {
+  const title = session.sessionTitle ?? session.title ?? '(untitled)';
+  console.log(`${session.id}: ${title}`);
 }
 
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
+if (sessions.length === 0) {
+  console.log('No sessions found for this project.');
+}

package/examples/multi-turn-session.ts

@@ -1,67 +1,35 @@
 /**
  * Multi-turn session example.
  *
- * Demonstrates `createSession()` for a persistent session, multiple
- * `stream()` calls for streaming turns, `send()` for a non-streaming
- * turn, and `close()` for cleanup.
- *
  * Usage:
  *   npx tsx examples/multi-turn-session.ts
  */
 
-import { createSession, DroidMessageType } from '../src/index.js';
-
-async function main(): Promise<void> {
-  const session = await createSession({ cwd: process.cwd() });
-  try {
-    console.log(`Session created: ${session.sessionId}\n`);
-
-    console.log('=== Turn 1 (streaming) ===');
-    console.log('Prompt: "List the TypeScript files in this project"\n');
+import { DroidMessageType, createSession } 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);
-      }
-      if (msg.type === DroidMessageType.TurnComplete) {
-        console.log('\n');
-      }
+async function streamText(
+  session: Awaited<ReturnType<typeof createSession>>,
+  prompt: string
+): Promise<string> {
+  let text = '';
+  for await (const msg of session.stream(prompt)) {
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      text += msg.text;
     }
+  }
+  return text;
+}
 
-    console.log('=== Turn 2 (streaming) ===');
-    console.log('Prompt: "How many lines of code total?"\n');
-
-    for await (const msg of session.stream('How many lines of code total?')) {
-      if (msg.type === DroidMessageType.AssistantTextDelta) {
-        process.stdout.write(msg.text);
-      }
-      if (msg.type === DroidMessageType.TurnComplete) {
-        console.log('\n');
-      }
-    }
+const session = await createSession({ cwd: process.cwd() });
 
-    console.log('=== Turn 3 (non-streaming) ===');
-    console.log('Prompt: "Summarize the project in one sentence"\n');
+try {
+  console.log(`Session: ${session.sessionId}\n`);
 
-    const result = await session.send('Summarize the project in one sentence');
+  const first = await streamText(session, 'What is this project?');
+  console.log(first);
 
-    console.log('Response:', result.text);
-    console.log(`Messages received: ${result.messages.length}`);
-    if (result.tokenUsage) {
-      console.log(
-        `Tokens — input: ${result.tokenUsage.inputTokens}, ` +
-          `output: ${result.tokenUsage.outputTokens}`
-      );
-    }
-  } finally {
-    await session.close();
-    console.log('\nSession closed.');
-  }
+  const second = await streamText(session, 'What should I test first?');
+  console.log('\n', second);
+} finally {
+  await session.close();
 }
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});