@factory/droid-sdk 0.2.0 → 0.3.0

package/examples/permission-handler.ts

@@ -1,98 +1,40 @@
 /**
  * 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 { mkdtemp, readFile, 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 });
-  }
+  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 });
 }
-
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});

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

@@ -12,7 +12,7 @@
 
 import assert from 'node:assert/strict';
 
-import { run } from '../src/index.js';
+import { run } from '@factory/droid-sdk';
 
 async function main(): Promise<void> {
   const prompt =

package/examples/run.ts

@@ -9,7 +9,7 @@
  *   npx tsx examples/run.ts "What is 2 + 2?"
  */
 
-import { run } from '../src/index.js';
+import { run } from '@factory/droid-sdk';
 
 async function main(): Promise<void> {
   const text = process.argv.slice(2).join(' ') || 'What is 2 + 2?';

package/examples/sdk-mcp-tool.ts

@@ -1,13 +1,13 @@
-import { z } from 'zod';
-
 import {
+  DroidMessageType,
   ToolConfirmationOutcome,
   createSession,
   createSdkMcpServer,
   tool,
-} from '../src/index.js';
+} from '@factory/droid-sdk';
+import { z } from 'zod';
 
-const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid';
+const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid-dev';
 
 const sdkTools = createSdkMcpServer({
   name: 'sdk-tools',
@@ -29,10 +29,14 @@ const session = await createSession({
 });
 
 try {
-  const result = await session.send(
+  for await (const msg of session.stream(
     'Use the favorite_number tool for Ada and tell me the answer.'
-  );
-  console.log(result.text);
+  )) {
+    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

@@ -1,10 +1,5 @@
 /**
- * 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.
+ * Spec mode: approve and hand off implementation to a new session.
  *
  * Usage:
  *   npx tsx examples/spec-mode-new-session.ts
@@ -15,107 +10,51 @@ 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;
-      },
-    });
+  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
+      );
 
-    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 (canExitSpec) {
+        return ToolConfirmationOutcome.ProceedNewSessionHigh;
       }
-    }
-
-    if (toolError) {
-      throw new Error(
-        `Tool failed during spec-mode implementation: ${toolError}`
-      );
-    }
+      return onlyCreatesFile
+        ? ToolConfirmationOutcome.ProceedOnce
+        : ToolConfirmationOutcome.Cancel;
+    },
+  });
 
-    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)}`
-      );
+  try {
+    for await (const _msg of session.stream(
+      `Plan then create ${outputPath} containing "Hello from Droid".`
+    )) {
+      // Consume the stream until the handoff implementation finishes.
     }
-
-    console.log(`\nVerified ${outputPath}.`);
   } finally {
-    await rm(tempDir, { recursive: true, force: true });
+    await session.close();
   }
-}
 
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
+  console.log(await readFile(outputPath, 'utf8'));
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}

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

@@ -1,133 +1,71 @@
 /**
  * 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 { 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.';
+  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)
+      );
 
-  console.log('=== Spec Mode: Same Session ===\n');
+      return canExitSpec ||
+        onlyCreatesFile ||
+        onlyEditsTempFile ||
+        onlyRunsTempCommand
+        ? ToolConfirmationOutcome.ProceedOnce
+        : ToolConfirmationOutcome.Cancel;
+    },
+  });
 
   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}`
-      );
+    for await (const _msg of session.stream(
+      `Plan then create ${outputPath} containing "Hello from Droid".`
+    )) {
+      // Consume the stream until implementation finishes.
     }
-
-    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 });
+    await session.close();
   }
-}
 
-main().catch((err: unknown) => {
-  console.error('Error:', err);
-  process.exit(1);
-});
+  console.log(await readFile(outputPath, 'utf8'));
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}

package/examples/structured-output.ts

@@ -6,27 +6,32 @@
  *
  * 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'],
     },
   };
 
@@ -37,12 +42,13 @@ async function main(): Promise<void> {
     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');
 }