@factory/droid-sdk 0.1.4 → 0.3.0

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

@@ -0,0 +1,43 @@
+/**
+ * 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 npx tsx examples/droid-dev-structured-output.ts
+ */
+
+import { run } from '@factory/droid-sdk';
+import { z } from 'zod';
+
+const PersonSchema = z.object({
+  name: z.literal('Ada Lovelace'),
+  language: z.literal('TypeScript'),
+  score: z.number(),
+});
+
+async function main(): Promise<void> {
+  const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid';
+
+  const result = await run(
+    [
+      'Return a structured object for Ada Lovelace.',
+      'Use name "Ada Lovelace", language "TypeScript", and score 99.',
+      'Return only valid JSON and do not include markdown fences.',
+    ].join(' '),
+    {
+      execPath,
+      cwd: process.cwd(),
+    }
+  );
+
+  const parsed = PersonSchema.parse(JSON.parse(result.text));
+
+  console.log(`droid executable: ${execPath}`);
+  console.log('structured output:', JSON.stringify(parsed, null, 2));
+  console.log(`messages received: ${result.messages.length}`);
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});

package/examples/fork-session.ts

@@ -0,0 +1,61 @@
+/**
+ * Fork session example.
+ *
+ * Demonstrates:
+ * - creating a session and establishing some context
+ * - calling `forkSession()` to get a new server-side session ID
+ * - resuming the fork and continuing from the copied context
+ *
+ * Usage:
+ *   npx tsx examples/fork-session.ts
+ */
+
+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() });
+  let fork: Awaited<ReturnType<typeof resumeSession>> | null = null;
+
+  try {
+    console.log(`Original session: ${session.sessionId}\n`);
+    await streamText(session, 'Remember this phrase exactly: mango sunrise');
+
+    const { newSessionId } = await session.forkSession();
+    console.log(`Forked session:   ${newSessionId}\n`);
+
+    fork = await resumeSession(newSessionId);
+
+    const result = await streamText(
+      fork,
+      'What phrase did I ask you to remember?'
+    );
+    console.log('Fork response:');
+    console.log(result);
+  } finally {
+    await fork?.close();
+    await session.close();
+    console.log('\nBoth sessions closed.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

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

@@ -0,0 +1,19 @@
+/**
+ * Initialization metadata example.
+ *
+ * Usage:
+ *   npx tsx examples/init-metadata.ts
+ */
+
+import { createSession, resumeSession } from '@factory/droid-sdk';
+
+const session = await createSession({ cwd: process.cwd() });
+const resumed = await resumeSession(session.sessionId);
+
+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)}`);
+
+await resumed.close();
+await session.close();

package/examples/interrupt-session.ts

@@ -0,0 +1,32 @@
+/**
+ * Interrupt a running turn.
+ *
+ * Usage:
+ *   npx tsx examples/interrupt-session.ts
+ */
+
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
+
+const session = await createSession({ cwd: process.cwd() });
+let deltaCount = 0;
+
+try {
+  for await (const msg of session.stream(
+    'Write a long history of computing.'
+  )) {
+    if (msg.type !== DroidMessageType.AssistantTextDelta) {
+      continue;
+    }
+
+    process.stdout.write(msg.text);
+    deltaCount++;
+
+    if (deltaCount === 5) {
+      await session.interrupt();
+    }
+  }
+
+  console.log('\nInterrupted turn.');
+} finally {
+  await session.close();
+}

package/examples/list-sessions.ts

@@ -0,0 +1,19 @@
+/**
+ * List saved sessions example.
+ *
+ * Usage:
+ *   npx tsx examples/list-sessions.ts
+ */
+
+import { listSessions } from '@factory/droid-sdk';
+
+const sessions = await listSessions({ numSessions: 5 });
+
+for (const session of sessions) {
+  const title = session.sessionTitle ?? session.title ?? '(untitled)';
+  console.log(`${session.id}: ${title}`);
+}
+
+if (sessions.length === 0) {
+  console.log('No sessions found for this project.');
+}

package/examples/multi-turn-session.ts

@@ -0,0 +1,35 @@
+/**
+ * Multi-turn session example.
+ *
+ * Usage:
+ *   npx tsx examples/multi-turn-session.ts
+ */
+
+import { DroidMessageType, createSession } 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;
+}
+
+const session = await createSession({ cwd: process.cwd() });
+
+try {
+  console.log(`Session: ${session.sessionId}\n`);
+
+  const first = await streamText(session, 'What is this project?');
+  console.log(first);
+
+  const second = await streamText(session, 'What should I test first?');
+  console.log('\n', second);
+} finally {
+  await session.close();
+}

package/examples/permission-handler.ts

@@ -0,0 +1,40 @@
+/**
+ * Permission handler example.
+ *
+ * Usage:
+ *   npx tsx examples/permission-handler.ts
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  run,
+} from '@factory/droid-sdk';
+
+const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-permission-'));
+const outputPath = join(tempDir, 'hello.txt');
+
+try {
+  await run(`Create ${outputPath} with the text "Hello, World!"`, {
+    cwd: process.cwd(),
+    permissionHandler(params) {
+      const onlyCreatesExpectedFile = params.toolUses.every(
+        (item) =>
+          item.details.type === ToolConfirmationType.Create &&
+          item.details.filePath === outputPath
+      );
+
+      return onlyCreatesExpectedFile
+        ? ToolConfirmationOutcome.ProceedOnce
+        : ToolConfirmationOutcome.Cancel;
+    },
+  });
+
+  console.log(await readFile(outputPath, 'utf8'));
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}

package/examples/readme-structured-output.ts

@@ -0,0 +1,25 @@
+import { OutputFormatType, run } from '@factory/droid-sdk';
+
+type FavoriteNumber = { favoriteNumber: number };
+
+const result = await run('Pick a favorite number between 1 and 42.', {
+  cwd: process.cwd(),
+  outputFormat: {
+    type: OutputFormatType.JsonSchema,
+    schema: {
+      type: 'object',
+      properties: {
+        favoriteNumber: {
+          type: 'number',
+          minimum: 1,
+          maximum: 42,
+        },
+      },
+      required: ['favoriteNumber'],
+    },
+  },
+});
+
+console.log(
+  (result.structuredOutput as FavoriteNumber | undefined)?.favoriteNumber
+);

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 '@factory/droid-sdk';
+
+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 '@factory/droid-sdk';
+
+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,42 @@
+import {
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  createSession,
+  createSdkMcpServer,
+  tool,
+} from '@factory/droid-sdk';
+import { z } from 'zod';
+
+const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid-dev';
+
+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 {
+  for await (const msg of session.stream(
+    'Use the favorite_number tool for Ada and tell me the answer.'
+  )) {
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      process.stdout.write(msg.text);
+    }
+  }
+  console.log();
+} finally {
+  await session.close();
+}

package/examples/session-stream.ts

@@ -0,0 +1,54 @@
+/**
+ * Simple session streaming example.
+ *
+ * Demonstrates using `session.stream()` to send a prompt, streaming
+ * full assistant/tool messages, and handling the final `result`.
+ *
+ * Usage:
+ *   npx tsx examples/session-stream.ts
+ */
+
+import { DroidMessageType, createSession } from '@factory/droid-sdk';
+
+async function main(): Promise<void> {
+  const prompt = process.argv[2] ?? 'What files are in the current directory?';
+
+  console.log(`Sending prompt: "${prompt}"\n`);
+
+  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] ${msg.toolUse.name}`);
+          break;
+
+        case DroidMessageType.ToolResult:
+          console.log(`[Tool Result] ${msg.isError ? 'Error' : 'OK'}`);
+          break;
+
+        case DroidMessageType.Result:
+          console.log('\n\n--- Turn complete ---');
+          if (msg.tokenUsage) {
+            console.log(
+              `Tokens — input: ${msg.tokenUsage.inputTokens}, ` +
+                `output: ${msg.tokenUsage.outputTokens}`
+            );
+          }
+          break;
+      }
+    }
+  } finally {
+    await session.close();
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

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

@@ -0,0 +1,60 @@
+/**
+ * Spec mode: approve and hand off implementation to a new session.
+ *
+ * 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 {
+  DroidInteractionMode,
+  ReasoningEffort,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  createSession,
+} from '@factory/droid-sdk';
+
+const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-spec-'));
+const outputPath = join(tempDir, 'hello.txt');
+
+try {
+  const session = await createSession({
+    cwd: process.cwd(),
+    interactionMode: DroidInteractionMode.Spec,
+    specModeReasoningEffort: ReasoningEffort.High,
+    permissionHandler(params) {
+      const canExitSpec = params.toolUses.some(
+        (item) => item.details.type === ToolConfirmationType.ExitSpecMode
+      );
+      const onlyCreatesFile = params.toolUses.every(
+        (item) =>
+          item.details.type === ToolConfirmationType.Create &&
+          item.details.filePath === outputPath
+      );
+
+      if (canExitSpec) {
+        return ToolConfirmationOutcome.ProceedNewSessionHigh;
+      }
+      return onlyCreatesFile
+        ? ToolConfirmationOutcome.ProceedOnce
+        : ToolConfirmationOutcome.Cancel;
+    },
+  });
+
+  try {
+    for await (const _msg of session.stream(
+      `Plan then create ${outputPath} containing "Hello from Droid".`
+    )) {
+      // Consume the stream until the handoff implementation finishes.
+    }
+  } finally {
+    await session.close();
+  }
+
+  console.log(await readFile(outputPath, 'utf8'));
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}

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

@@ -0,0 +1,71 @@
+/**
+ * Spec mode: approve and implement in the same session.
+ *
+ * Usage:
+ *   npx tsx examples/spec-mode-same-session.ts
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  DroidInteractionMode,
+  ReasoningEffort,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  createSession,
+} from '@factory/droid-sdk';
+
+const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-spec-'));
+const outputPath = join(tempDir, 'hello.txt');
+
+try {
+  const session = await createSession({
+    cwd: process.cwd(),
+    interactionMode: DroidInteractionMode.Spec,
+    specModeReasoningEffort: ReasoningEffort.High,
+    permissionHandler(params) {
+      const canExitSpec = params.toolUses.some(
+        (item) => item.details.type === ToolConfirmationType.ExitSpecMode
+      );
+      const onlyCreatesFile = params.toolUses.every(
+        (item) =>
+          item.details.type === ToolConfirmationType.Create &&
+          item.details.filePath === outputPath
+      );
+      const onlyEditsTempFile = params.toolUses.every(
+        (item) =>
+          item.details.type === ToolConfirmationType.ApplyPatch &&
+          item.details.filePath === outputPath
+      );
+      const onlyRunsTempCommand = params.toolUses.every(
+        (item) =>
+          item.details.type === ToolConfirmationType.Execute &&
+          item.details.fullCommand.includes(outputPath) &&
+          item.details.fullCommand.includes(tempDir)
+      );
+
+      return canExitSpec ||
+        onlyCreatesFile ||
+        onlyEditsTempFile ||
+        onlyRunsTempCommand
+        ? ToolConfirmationOutcome.ProceedOnce
+        : ToolConfirmationOutcome.Cancel;
+    },
+  });
+
+  try {
+    for await (const _msg of session.stream(
+      `Plan then create ${outputPath} containing "Hello from Droid".`
+    )) {
+      // Consume the stream until implementation finishes.
+    }
+  } finally {
+    await session.close();
+  }
+
+  console.log(await readFile(outputPath, 'utf8'));
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}