@factory/droid-sdk 0.1.4 → 0.2.0

package/examples/list-sessions.ts

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ *
+ * 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`);
+
+  // Default call: scopes to process.cwd().
+  const currentProject = await listSessions({ numSessions: 10 });
+
+  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}`);
+    }
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/multi-turn-session.ts

@@ -0,0 +1,67 @@
+/**
+ * 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');
+
+    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');
+      }
+    }
+
+    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');
+      }
+    }
+
+    console.log('=== Turn 3 (non-streaming) ===');
+    console.log('Prompt: "Summarize the project in one sentence"\n');
+
+    const result = await session.send('Summarize the project in one sentence');
+
+    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.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/permission-handler.ts

@@ -0,0 +1,98 @@
+/**
+ * Permission handler example.
+ *
+ * Demonstrates using `query()` with a custom `permissionHandler` that
+ * logs tool confirmation details, approves only one expected file creation,
+ * and cancels any unexpected tool request.
+ *
+ * Usage:
+ *   npx tsx examples/permission-handler.ts
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  DroidMessageType,
+  query,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  type RequestPermissionRequestParams,
+} from '../src/index.js';
+
+function permissionHandler(
+  allowedFilePath: string,
+  params: RequestPermissionRequestParams
+): ToolConfirmationOutcome {
+  for (const item of params.toolUses) {
+    console.log(`\n[Permission] Tool: ${item.toolUse.name}`);
+    console.log(`  Type: ${item.confirmationType}`);
+    console.log(`  Input: ${JSON.stringify(item.toolUse.input, null, 2)}`);
+  }
+
+  const onlyAllowedCreate = params.toolUses.every(
+    (item) =>
+      item.details.type === ToolConfirmationType.Create &&
+      item.details.filePath === allowedFilePath
+  );
+
+  if (!onlyAllowedCreate) {
+    console.log('  → Cancelling unexpected tool request\n');
+    return ToolConfirmationOutcome.Cancel;
+  }
+
+  console.log('  → Approving expected file creation with ProceedOnce\n');
+  return ToolConfirmationOutcome.ProceedOnce;
+}
+
+async function main(): Promise<void> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-permission-'));
+  const outputPath = join(tempDir, 'hello.txt');
+  const prompt =
+    process.argv[2] ??
+    `Create a file called ${outputPath} with the text 'Hello, World!'`;
+
+  try {
+    console.log(`Sending prompt: "${prompt}"\n`);
+
+    const stream = query({
+      prompt,
+      cwd: process.cwd(),
+      permissionHandler: (params) => permissionHandler(outputPath, params),
+    });
+
+    for await (const msg of stream) {
+      switch (msg.type) {
+        case DroidMessageType.AssistantTextDelta:
+          process.stdout.write(msg.text);
+          break;
+
+        case DroidMessageType.ToolUse:
+          console.log(`\n[Tool Use] ${msg.toolName}`);
+          break;
+
+        case DroidMessageType.ToolResult:
+          console.log(`[Tool Result] ${msg.isError ? 'Error' : 'Success'}`);
+          break;
+
+        case DroidMessageType.TurnComplete:
+          console.log('\n\n--- Turn complete ---');
+          if (msg.tokenUsage) {
+            console.log(
+              `Tokens — input: ${msg.tokenUsage.inputTokens}, ` +
+                `output: ${msg.tokenUsage.outputTokens}`
+            );
+          }
+          break;
+      }
+    }
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/result-metadata.ts

@@ -0,0 +1,62 @@
+/**
+ * DroidResult metadata example.
+ *
+ * Runs a prompt with the actual Droid CLI and prints the aggregated `run()`
+ * result metadata: sessionId, durationMs, turnCount, success, error, and token
+ * usage.
+ *
+ * Usage:
+ *   npx tsx examples/result-metadata.ts
+ *   npx tsx examples/result-metadata.ts "Reply with metadata details."
+ */
+
+import assert from 'node:assert/strict';
+
+import { run } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const prompt =
+    process.argv.slice(2).join(' ') ||
+    'Reply with "Metadata OK" and nothing else.';
+
+  console.log(`Sending prompt: "${prompt}"\n`);
+
+  const result = await run(prompt, {
+    cwd: process.cwd(),
+  });
+
+  assert.equal(typeof result.sessionId, 'string');
+  assert.ok(result.sessionId.length > 0);
+  assert.equal(typeof result.durationMs, 'number');
+  assert.ok(result.durationMs >= 0);
+  assert.equal(typeof result.turnCount, 'number');
+  assert.ok(result.turnCount >= 1);
+  assert.equal(typeof result.success, 'boolean');
+  assert.ok(Array.isArray(result.messages));
+
+  console.log('=== Result ===');
+  console.log(result.text);
+
+  console.log('\n=== Metadata ===');
+  console.log(`Session ID: ${result.sessionId}`);
+  console.log(`Duration: ${result.durationMs}ms`);
+  console.log(`Turn count: ${result.turnCount}`);
+  console.log(`Success: ${String(result.success)}`);
+  console.log(`Messages received: ${result.messages.length}`);
+
+  if (result.error) {
+    console.log(`Error: ${result.error.message}`);
+  }
+
+  if (result.tokenUsage) {
+    console.log(
+      `Tokens — input: ${result.tokenUsage.inputTokens}, ` +
+        `output: ${result.tokenUsage.outputTokens}`
+    );
+  }
+}
+
+main().catch((error: unknown) => {
+  console.error('Error:', error);
+  process.exit(1);
+});

package/examples/run.ts

@@ -0,0 +1,38 @@
+/**
+ * Manual smoke test for the one-shot `run()` API.
+ *
+ * Sends a single prompt, prints the aggregated result, and exits after the
+ * underlying session has been closed by `run()`.
+ *
+ * Usage:
+ *   npx tsx examples/run.ts
+ *   npx tsx examples/run.ts "What is 2 + 2?"
+ */
+
+import { run } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const text = process.argv.slice(2).join(' ') || 'What is 2 + 2?';
+
+  console.log(`Sending prompt: "${text}"\n`);
+
+  const result = await run(text, {
+    cwd: process.cwd(),
+  });
+
+  console.log('=== Result ===');
+  console.log(result.text);
+  console.log(`Messages received: ${result.messages.length}`);
+
+  if (result.tokenUsage) {
+    console.log(
+      `Tokens — input: ${result.tokenUsage.inputTokens}, ` +
+        `output: ${result.tokenUsage.outputTokens}`
+    );
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/sdk-mcp-tool.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+
+import {
+  ToolConfirmationOutcome,
+  createSession,
+  createSdkMcpServer,
+  tool,
+} from '../src/index.js';
+
+const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid';
+
+const sdkTools = createSdkMcpServer({
+  name: 'sdk-tools',
+  tools: [
+    tool(
+      'favorite_number',
+      'Returns a favorite number for a person',
+      { name: z.string() },
+      ({ name }) => `${name}'s favorite number is 42.`
+    ),
+  ],
+});
+
+const session = await createSession({
+  execPath,
+  mcpServers: [sdkTools],
+  cwd: process.cwd(),
+  permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
+});
+
+try {
+  const result = await session.send(
+    'Use the favorite_number tool for Ada and tell me the answer.'
+  );
+  console.log(result.text);
+} finally {
+  await session.close();
+}

package/examples/simple-query.ts

@@ -0,0 +1,53 @@
+/**
+ * Simple one-shot query example.
+ *
+ * Demonstrates using `query()` to send a single prompt, streaming
+ * `AssistantTextDelta` messages to stdout, and handling `TurnComplete`.
+ *
+ * Usage:
+ *   npx tsx examples/simple-query.ts
+ */
+
+import { DroidMessageType, query } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const prompt = process.argv[2] ?? 'What files are in the current directory?';
+
+  console.log(`Sending prompt: "${prompt}"\n`);
+
+  const stream = query({
+    prompt,
+    cwd: process.cwd(),
+  });
+
+  for await (const msg of stream) {
+    switch (msg.type) {
+      case DroidMessageType.AssistantTextDelta:
+        process.stdout.write(msg.text);
+        break;
+
+      case DroidMessageType.ToolUse:
+        console.log(`\n[Tool] ${msg.toolName}`);
+        break;
+
+      case DroidMessageType.ToolResult:
+        console.log(`[Tool Result] ${msg.isError ? 'Error' : 'OK'}`);
+        break;
+
+      case DroidMessageType.TurnComplete:
+        console.log('\n\n--- Turn complete ---');
+        if (msg.tokenUsage) {
+          console.log(
+            `Tokens — input: ${msg.tokenUsage.inputTokens}, ` +
+              `output: ${msg.tokenUsage.outputTokens}`
+          );
+        }
+        break;
+    }
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/spec-mode-new-session.ts

@@ -0,0 +1,121 @@
+/**
+ * Spec mode: approve and hand off to a new session.
+ *
+ * The agent drafts a plan in spec mode. On approval with
+ * ProceedNewSessionHigh, the server automatically creates a
+ * fresh session and implements the plan. The results stream
+ * back through the same query — no manual session creation needed.
+ *
+ * Usage:
+ *   npx tsx examples/spec-mode-new-session.ts
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  DroidMessageType,
+  DroidInteractionMode,
+  query,
+  ReasoningEffort,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+} from '../src/index.js';
+
+const EXPECTED_CONTENT = 'Hello from Droid';
+
+async function main(): Promise<void> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-spec-'));
+  const outputPath = join(tempDir, 'hello-from-droid.txt');
+  const prompt =
+    `Plan how to create a small ${outputPath} file containing the text ` +
+    '"Hello from Droid". Keep the plan short and concrete.';
+
+  console.log('=== Spec Mode: New Session Handoff ===\n');
+
+  try {
+    let toolError: string | null = null;
+
+    const stream = query({
+      prompt,
+      cwd: process.cwd(),
+      interactionMode: DroidInteractionMode.Spec,
+      specModeReasoningEffort: ReasoningEffort.High,
+      permissionHandler(params) {
+        const exitSpec = params.toolUses.find(
+          (item) => item.details.type === ToolConfirmationType.ExitSpecMode
+        );
+
+        if (exitSpec?.details.type === ToolConfirmationType.ExitSpecMode) {
+          console.log(
+            '\n--- Plan received, approving with new session handoff ---'
+          );
+          console.log(exitSpec.details.plan);
+          console.log('---\n');
+
+          // The server creates a fresh session and implements the plan.
+          // Results continue streaming through this same query.
+          return ToolConfirmationOutcome.ProceedNewSessionHigh;
+        }
+
+        const onlyAllowedCreate = params.toolUses.every(
+          (item) =>
+            item.details.type === ToolConfirmationType.Create &&
+            item.details.filePath === outputPath
+        );
+
+        return onlyAllowedCreate
+          ? ToolConfirmationOutcome.ProceedOnce
+          : ToolConfirmationOutcome.Cancel;
+      },
+    });
+
+    for await (const msg of stream) {
+      switch (msg.type) {
+        case DroidMessageType.AssistantTextDelta:
+          process.stdout.write(msg.text);
+          break;
+        case DroidMessageType.ToolUse:
+          console.log(`\n[Tool] ${msg.toolName}`);
+          break;
+        case DroidMessageType.ToolResult:
+          if (msg.isError) {
+            toolError = JSON.stringify(msg.content);
+          }
+          console.log(`[Tool Result] ${msg.isError ? 'Error' : 'OK'}`);
+          break;
+        case DroidMessageType.TurnComplete:
+          console.log('\n\n--- Turn complete ---');
+          if (msg.tokenUsage) {
+            console.log(
+              `Tokens — input: ${msg.tokenUsage.inputTokens}, output: ${msg.tokenUsage.outputTokens}`
+            );
+          }
+          break;
+      }
+    }
+
+    if (toolError) {
+      throw new Error(
+        `Tool failed during spec-mode implementation: ${toolError}`
+      );
+    }
+
+    const content = await readFile(outputPath, 'utf8');
+    if (content.trim() !== EXPECTED_CONTENT) {
+      throw new Error(
+        `Expected ${outputPath} to contain ${JSON.stringify(EXPECTED_CONTENT)}, got ${JSON.stringify(content)}`
+      );
+    }
+
+    console.log(`\nVerified ${outputPath}.`);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/spec-mode-same-session.ts

@@ -0,0 +1,133 @@
+/**
+ * Spec mode: approve and implement in the same session.
+ *
+ * The agent drafts a plan in spec mode, then implements it
+ * in the same query stream after approval.
+ *
+ * Usage:
+ *   npx tsx examples/spec-mode-same-session.ts
+ */
+
+import { mkdtemp, rm } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  DroidMessageType,
+  DroidInteractionMode,
+  query,
+  ReasoningEffort,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+} from '../src/index.js';
+
+const EXPECTED_CONTENT = 'Hello from Droid';
+
+async function main(): Promise<void> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-spec-'));
+  const outputPath = join(tempDir, 'hello-from-droid.txt');
+  const prompt =
+    `Plan how to create a small ${outputPath} file containing the text ` +
+    '"Hello from Droid". Keep the plan short and concrete.';
+
+  console.log('=== Spec Mode: Same Session ===\n');
+
+  try {
+    let toolError: string | null = null;
+
+    const stream = query({
+      prompt,
+      cwd: process.cwd(),
+      interactionMode: DroidInteractionMode.Spec,
+      specModeReasoningEffort: ReasoningEffort.High,
+      permissionHandler(params) {
+        const exitSpec = params.toolUses.find(
+          (item) => item.details.type === ToolConfirmationType.ExitSpecMode
+        );
+
+        if (exitSpec?.details.type === ToolConfirmationType.ExitSpecMode) {
+          console.log('\n--- Plan received, approving in same session ---');
+          console.log(exitSpec.details.plan);
+          console.log('---\n');
+          return ToolConfirmationOutcome.ProceedOnce;
+        }
+
+        const onlyAllowedCreate = params.toolUses.every(
+          (item) =>
+            item.details.type === ToolConfirmationType.Create &&
+            item.details.filePath === outputPath
+        );
+        const onlyAllowedApplyPatch = params.toolUses.every(
+          (item) =>
+            item.details.type === ToolConfirmationType.ApplyPatch &&
+            item.details.filePath === outputPath
+        );
+        const onlyAllowedExecute = params.toolUses.every((item) => {
+          if (item.details.type !== ToolConfirmationType.Execute) {
+            return false;
+          }
+
+          const command = item.details.fullCommand;
+          return (
+            command.includes(outputPath) &&
+            command.includes(tempDir) &&
+            !command.includes('sudo') &&
+            !command.includes('rm -rf /')
+          );
+        });
+
+        return onlyAllowedCreate || onlyAllowedApplyPatch || onlyAllowedExecute
+          ? ToolConfirmationOutcome.ProceedOnce
+          : ToolConfirmationOutcome.Cancel;
+      },
+    });
+
+    for await (const msg of stream) {
+      switch (msg.type) {
+        case DroidMessageType.AssistantTextDelta:
+          process.stdout.write(msg.text);
+          break;
+        case DroidMessageType.ToolUse:
+          console.log(`\n[Tool] ${msg.toolName}`);
+          break;
+        case DroidMessageType.ToolResult:
+          if (msg.isError) {
+            toolError = JSON.stringify(msg.content);
+          }
+          console.log(`[Tool Result] ${msg.isError ? 'Error' : 'OK'}`);
+          break;
+        case DroidMessageType.TurnComplete:
+          console.log('\n\n--- Turn complete ---');
+          if (msg.tokenUsage) {
+            console.log(
+              `Tokens — input: ${msg.tokenUsage.inputTokens}, output: ${msg.tokenUsage.outputTokens}`
+            );
+          }
+          break;
+      }
+    }
+
+    if (toolError) {
+      throw new Error(
+        `Tool failed during spec-mode implementation: ${toolError}`
+      );
+    }
+
+    const content = await readFile(outputPath, 'utf8');
+    if (content.trim() !== EXPECTED_CONTENT) {
+      throw new Error(
+        `Expected ${outputPath} to contain ${JSON.stringify(EXPECTED_CONTENT)}, got ${JSON.stringify(content)}`
+      );
+    }
+
+    console.log(`\nVerified ${outputPath}.`);
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});