@factory/droid-sdk 0.6.0 → 0.7.0

package/examples/daemon-multi-session.ts

@@ -1,67 +0,0 @@
-/**
- * Manual smoke test for the daemon SDK — multiple concurrent sessions.
- *
- * Spawns a local daemon, creates two sessions in separate /tmp directories,
- * and runs them concurrently over a single WebSocket connection.
- *
- * Usage:
- *   npx tsx examples/daemon-multi-session.ts
- */
-
-import { connectDaemon, DroidMessageType } from '@factory/droid-sdk';
-
-async function main(): Promise<void> {
-  console.log('Connecting to local daemon...\n');
-  const daemon = await connectDaemon({ apiKey: process.env.FACTORY_API_KEY! });
-  console.log('Connected!\n');
-
-  const frontend = await daemon.createSession({
-    cwd: '/tmp/daemon-test-frontend',
-  });
-  const backend = await daemon.createSession({
-    cwd: '/tmp/daemon-test-backend',
-  });
-
-  console.log('Two sessions created. Running concurrently...\n');
-
-  await Promise.all([
-    (async () => {
-      for await (const msg of frontend.stream(
-        'Create a file called hello.md with a short greeting message. Just a few lines.'
-      )) {
-        if (msg.type === DroidMessageType.Assistant) {
-          process.stdout.write(`[frontend] ${msg.text}\n`);
-        } else if (msg.type === DroidMessageType.ToolCall) {
-          console.log(`[frontend] [tool] ${msg.toolUse.name}`);
-        } else if (msg.type === DroidMessageType.Result) {
-          console.log(`[frontend] Done in ${msg.durationMs}ms`);
-        }
-      }
-      await frontend.close();
-    })(),
-    (async () => {
-      for await (const msg of backend.stream(
-        'Create a file called notes.md with 3 random fun facts. Keep it short.'
-      )) {
-        if (msg.type === DroidMessageType.Assistant) {
-          process.stdout.write(`[backend] ${msg.text}\n`);
-        } else if (msg.type === DroidMessageType.ToolCall) {
-          console.log(`[backend] [tool] ${msg.toolUse.name}`);
-        } else if (msg.type === DroidMessageType.Result) {
-          console.log(`[backend] Done in ${msg.durationMs}ms`);
-        }
-      }
-      await backend.close();
-    })(),
-  ]);
-
-  await daemon.close();
-  console.log(
-    '\nDone. Check /tmp/daemon-test-frontend/hello.md and /tmp/daemon-test-backend/notes.md'
-  );
-}
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});

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

@@ -1,44 +0,0 @@
-/**
- * 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(' '),
-    {
-      apiKey: process.env.FACTORY_API_KEY!,
-      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

@@ -1,68 +0,0 @@
-/**
- * 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, {
-    includePartialMessages: true,
-  })) {
-    if (msg.type === DroidMessageType.AssistantTextDelta) {
-      text += msg.text;
-    }
-  }
-  return text;
-}
-
-async function main(): Promise<void> {
-  const session = await createSession({
-    apiKey: process.env.FACTORY_API_KEY!,
-    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, {
-      apiKey: process.env.FACTORY_API_KEY!,
-    });
-
-    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

@@ -1,68 +0,0 @@
-/**
- * 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 apiKey = process.env.FACTORY_API_KEY;
-  if (!apiKey) {
-    console.error('Set FACTORY_API_KEY environment variable.');
-    process.exit(1);
-  }
-
-  const session = await createSession({ apiKey, 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,24 +0,0 @@
-/**
- * Initialization metadata example.
- *
- * Usage:
- *   npx tsx examples/init-metadata.ts
- */
-
-import { createSession, resumeSession } from '@factory/droid-sdk';
-
-const session = await createSession({
-  apiKey: process.env.FACTORY_API_KEY!,
-  cwd: process.cwd(),
-});
-const resumed = await resumeSession(session.sessionId, {
-  apiKey: process.env.FACTORY_API_KEY!,
-});
-
-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/list-sessions.ts

@@ -1,19 +0,0 @@
-/**
- * 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

@@ -1,40 +0,0 @@
-/**
- * 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, {
-    includePartialMessages: true,
-  })) {
-    if (msg.type === DroidMessageType.AssistantTextDelta) {
-      text += msg.text;
-    }
-  }
-  return text;
-}
-
-const session = await createSession({
-  apiKey: process.env.FACTORY_API_KEY!,
-  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

@@ -1,41 +0,0 @@
-/**
- * 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!"`, {
-    apiKey: process.env.FACTORY_API_KEY!,
-    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

@@ -1,26 +0,0 @@
-import { OutputFormatType, run } from '@factory/droid-sdk';
-
-type FavoriteNumber = { favoriteNumber: number };
-
-const result = await run('Pick a favorite number between 1 and 42.', {
-  apiKey: process.env.FACTORY_API_KEY!,
-  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

@@ -1,63 +0,0 @@
-/**
- * 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, {
-    apiKey: process.env.FACTORY_API_KEY!,
-    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

@@ -1,39 +0,0 @@
-/**
- * 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, {
-    apiKey: process.env.FACTORY_API_KEY!,
-    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/session-stream.ts

@@ -1,57 +0,0 @@
-/**
- * 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({
-    apiKey: process.env.FACTORY_API_KEY!,
-    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

@@ -1,61 +0,0 @@
-/**
- * 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({
-    apiKey: process.env.FACTORY_API_KEY!,
-    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

@@ -1,72 +0,0 @@
-/**
- * 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({
-    apiKey: process.env.FACTORY_API_KEY!,
-    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 });
-}