@factory/droid-sdk 0.6.0 → 0.8.0

package/examples/node/permission-handler.ts

@@ -0,0 +1,60 @@
+/**
+ * Permission handler example.
+ *
+ * Usage:
+ *   npx tsx examples/node/permission-handler.ts
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  AutonomyLevel,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  run,
+} from '@factory/droid-sdk/node';
+
+const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-permission-'));
+const outputPath = join(tempDir, 'hello.txt');
+
+try {
+  let handledPermission = false;
+  const result = await run(
+    `Create ${outputPath} with the text "Hello, World!"`,
+    {
+      autonomyLevel: AutonomyLevel.Off,
+      permissionHandler({ toolUses, options }) {
+        handledPermission = true;
+        const onlyCreatesExpectedFile =
+          toolUses.length > 0 &&
+          toolUses.every(
+            (item) =>
+              item.details.type === ToolConfirmationType.Create &&
+              item.details.filePath === outputPath
+          );
+
+        const desired = onlyCreatesExpectedFile
+          ? ToolConfirmationOutcome.ProceedOnce
+          : ToolConfirmationOutcome.Cancel;
+
+        const offered = options.find((option) => option.value === desired);
+        if (!offered) throw new Error(`Outcome not offered: ${desired}`);
+
+        return desired;
+      },
+    }
+  );
+
+  if (!result.success) {
+    throw new Error(result.error?.message ?? 'The turn was interrupted.');
+  }
+  if (!handledPermission) {
+    throw new Error('The turn finished without requesting permission.');
+  }
+
+  console.log(await readFile(outputPath, 'utf8'));
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}

package/examples/node/rename-session.ts

@@ -0,0 +1,33 @@
+/**
+ * Rename session example.
+ *
+ * Sessions get an auto-generated title from their first prompt.
+ * `rename()` overrides it, which is what a host app calls when the user
+ * edits a conversation title.
+ *
+ * Usage:
+ *   npx tsx examples/node/rename-session.ts
+ */
+
+import { DroidMessageType, createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+try {
+  // A session needs at least one turn before it has a title to replace.
+  for await (const message of session.stream('Reply with exactly: OK')) {
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
+  }
+
+  await session.rename({
+    title: 'Quarterly report analysis',
+  });
+
+  console.log(`renamed session: ${session.id}`);
+} finally {
+  await session.close();
+}

package/examples/node/result-metadata.ts

@@ -0,0 +1,43 @@
+/**
+ * DroidResult metadata example.
+ *
+ * Prints the metadata `run()` returns alongside the response text.
+ *
+ * Usage:
+ *   npx tsx examples/node/result-metadata.ts
+ *   npx tsx examples/node/result-metadata.ts "Reply with metadata details."
+ */
+
+import { run } from '@factory/droid-sdk/node';
+
+const result = await run(
+  process.argv.slice(2).join(' ') ||
+    'Reply with "Metadata OK" and nothing else.'
+);
+
+console.log(result.text);
+console.log(`\nsession:  ${result.sessionId}`);
+console.log(`duration: ${result.durationMs}ms`);
+console.log(`turns:    ${result.turnCount}`);
+console.log(`success:  ${String(result.success)}`);
+console.log(`interrupted: ${String(result.interrupted)}`);
+console.log(`messages: ${result.messages.length}`);
+
+if (result.error) {
+  console.log(`error:    ${result.error.message}`);
+}
+
+if (result.tokenUsage) {
+  console.log(
+    `turn tokens: ${result.tokenUsage.inputTokens} in, ${result.tokenUsage.outputTokens} out`
+  );
+  console.log(
+    `turn cache:  ${result.tokenUsage.cacheReadTokens} read, ${result.tokenUsage.cacheCreationTokens} created`
+  );
+}
+
+if (!result.success) {
+  throw new Error(
+    result.error?.message ?? `The turn failed (${result.subtype}).`
+  );
+}

package/examples/node/resume-session.ts

@@ -0,0 +1,41 @@
+/**
+ * Resume session example.
+ *
+ * Loads a saved session and sends a follow-up prompt with its existing
+ * conversation, working directory, and settings.
+ *
+ * Usage:
+ *   npx tsx examples/node/resume-session.ts session-id
+ */
+
+import { DroidMessageType, resumeSession } from '@factory/droid-sdk/node';
+
+const sessionId = process.argv[2];
+if (!sessionId) {
+  throw new Error('Pass a session ID. Use listSessions() to find one.');
+}
+
+const session = await resumeSession(sessionId);
+
+try {
+  console.log(`cwd: ${String(session.cwd)}`);
+  console.log(`model: ${session.settings.modelId}`);
+
+  let assistantText = '';
+  for await (const message of session.stream(
+    'Continue from the last conversation.'
+  )) {
+    if (message.type === DroidMessageType.Assistant) {
+      assistantText += message.text;
+      console.log(message.text);
+    }
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
+  }
+  if (!assistantText) throw new Error('The turn produced no assistant text.');
+} finally {
+  await session.close();
+}

package/examples/node/rewind-session.ts

@@ -0,0 +1,79 @@
+/**
+ * Rewind session example.
+ *
+ * Runs a turn, inspects the files available at that point, then rewinds into a
+ * replacement session handle and continues from there.
+ *
+ * Usage:
+ *   npx tsx examples/node/rewind-session.ts
+ */
+
+import { DroidMessageType, createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+async function ask(
+  activeSession: Awaited<ReturnType<typeof createSession>>,
+  prompt: string
+): Promise<{ messageId: string; text: string }> {
+  let messageId: string | undefined;
+  let text = '';
+
+  for await (const message of activeSession.stream(prompt)) {
+    if (
+      message.type === DroidMessageType.User &&
+      message.message.visibility !== 'llm_only'
+    ) {
+      messageId ??= message.message.id;
+    }
+    if (message.type === DroidMessageType.Assistant) {
+      text += message.text;
+      console.log(message.text);
+    }
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
+  }
+
+  if (!messageId) throw new Error('The turn produced no user message ID.');
+  if (!text.trim()) throw new Error('The turn produced no assistant output.');
+  return { messageId, text };
+}
+
+try {
+  await ask(session, 'Remember this phrase exactly: mango sunrise');
+  const { messageId: secondTurn } = await ask(
+    session,
+    'Now forget it and remember: cobalt harbor'
+  );
+
+  const { availableFiles, createdFiles } = await session.getRewindInfo({
+    messageId: secondTurn,
+  });
+  console.log(
+    `rewind would restore ${availableFiles.length} file(s) ` +
+      `and delete ${createdFiles.length}`
+  );
+
+  const { session: successor } = await session.rewind({
+    messageId: secondTurn,
+    filesToRestore: availableFiles,
+    filesToDelete: createdFiles,
+    forkTitle: 'Before the second phrase',
+  });
+
+  try {
+    // `session` is now a retired wrapper. Its persisted ID can still be passed
+    // to resumeSession() later if the pre-rewind history is needed again.
+    console.log(`rewound into session: ${successor.id}`);
+
+    await ask(successor, 'What phrase did I ask you to remember?');
+  } finally {
+    await successor.close();
+  }
+} finally {
+  // Closes the active source, or does nothing if it was retired.
+  await session.close();
+}

package/examples/node/run.ts

@@ -0,0 +1,32 @@
+/**
+ * One-shot `run()` example.
+ *
+ * Sends a single prompt and prints the aggregated result. `run()` closes the
+ * underlying session for you.
+ *
+ * Usage:
+ *   npx tsx examples/node/run.ts
+ *   npx tsx examples/node/run.ts "What is 2 + 2?"
+ */
+
+import { run } from '@factory/droid-sdk/node';
+
+const result = await run(process.argv.slice(2).join(' ') || 'What is 2 + 2?');
+
+if (!result.success) {
+  throw new Error(
+    result.error?.message ?? `The turn failed (${result.subtype}).`
+  );
+}
+if (!result.text.trim()) {
+  throw new Error('The turn produced no assistant output.');
+}
+
+console.log(result.text);
+console.log(`\nmessages: ${result.messages.length}`);
+
+if (result.tokenUsage) {
+  console.log(
+    `tokens: ${result.tokenUsage.inputTokens} in, ${result.tokenUsage.outputTokens} out`
+  );
+}

package/examples/node/sdk-mcp-tool.ts

@@ -0,0 +1,56 @@
+/**
+ * SDK MCP tool example.
+ *
+ * Defines an in-process tool with `createSdkMcpServer` + `tool` and exposes it
+ * to Droid, then asks Droid to call it.
+ *
+ * Usage:
+ *   npx tsx examples/node/sdk-mcp-tool.ts
+ */
+
+import { z } from 'zod';
+
+import {
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  createSession,
+  createSdkMcpServer,
+  tool,
+} from '@factory/droid-sdk/node';
+
+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({
+  mcpServers: [sdkTools],
+  permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
+});
+
+try {
+  for await (const message of session.stream(
+    'Use the favorite_number tool for Ada and tell me the answer.'
+  )) {
+    if (message.type === DroidMessageType.ToolCall) {
+      console.log(`[tool call] ${message.name}`);
+    }
+    if (message.type === DroidMessageType.Assistant) {
+      console.log(message.text);
+    }
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
+  }
+} finally {
+  await session.close();
+}

package/examples/node/session-settings.ts

@@ -0,0 +1,35 @@
+/**
+ * Session settings example.
+ *
+ * Reads settings from a live session, updates them, and changes between Auto
+ * and Spec modes.
+ *
+ * Usage:
+ *   npx tsx examples/node/session-settings.ts
+ */
+
+import { AutonomyLevel, createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession({ autonomyLevel: AutonomyLevel.Low });
+
+function printSettings(label: string): void {
+  const { modelId, interactionMode, autonomyLevel } = session.settings;
+  console.log(`${label}: ${modelId}, ${interactionMode}, ${autonomyLevel}`);
+}
+
+try {
+  printSettings('created with');
+
+  await session.updateSettings({
+    autonomyLevel: AutonomyLevel.High,
+  });
+  printSettings('updated to  ');
+
+  await session.enterSpecMode();
+  printSettings('entered Spec');
+
+  await session.exitSpecMode();
+  printSettings('exited Spec ');
+} finally {
+  await session.close();
+}

package/examples/node/session-stream.ts

@@ -0,0 +1,59 @@
+/**
+ * Session streaming example.
+ *
+ * Sends a prompt with `session.stream()` and handles every message type
+ * emitted by a default (non-partial) stream.
+ *
+ * Usage:
+ *   npx tsx examples/node/session-stream.ts
+ *   npx tsx examples/node/session-stream.ts "What files are here?"
+ */
+
+import { DroidMessageType, createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+try {
+  const prompt = process.argv[2] ?? 'What files are in the current directory?';
+
+  for await (const msg of session.stream(prompt)) {
+    switch (msg.type) {
+      case DroidMessageType.Assistant:
+        process.stdout.write(msg.text);
+        break;
+
+      case DroidMessageType.User:
+        console.log('\n[user message accepted]');
+        break;
+
+      case DroidMessageType.ToolCall:
+        console.log(`\n[tool] ${msg.name}`);
+        break;
+
+      case DroidMessageType.ToolResult:
+        console.log(`[tool result] ${msg.isError ? 'error' : 'ok'}`);
+        break;
+
+      case DroidMessageType.Hook:
+        console.log(`\n[hook] ${msg.hookId}: ${msg.status}`);
+        break;
+
+      case DroidMessageType.Error:
+        console.error(`\n[error] ${msg.message}`);
+        break;
+
+      case DroidMessageType.Result:
+        if (!msg.success) {
+          throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+        }
+        if (msg.tokenUsage) {
+          console.log(
+            `\n\ntokens: ${msg.tokenUsage.inputTokens} in, ${msg.tokenUsage.outputTokens} out`
+          );
+        }
+        break;
+    }
+  }
+} finally {
+  await session.close();
+}

package/examples/node/skills.ts

@@ -0,0 +1,24 @@
+/**
+ * Skills example.
+ *
+ * Lists the skills available to a Node session.
+ *
+ * Usage:
+ *   npx tsx examples/node/skills.ts
+ */
+
+import { createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+try {
+  const { skills } = await session.listSkills();
+
+  for (const skill of skills) {
+    console.log(
+      `${skill.name}: ${skill.enabled === false ? 'disabled' : 'enabled'}`
+    );
+  }
+} finally {
+  await session.close();
+}

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

@@ -0,0 +1,120 @@
+/**
+ * Spec mode: approve and hand off implementation to a new session.
+ *
+ * Approving the spec with `ProceedNewSessionHigh` moves implementation into a
+ * fresh session. The example prints the planning session's own id alongside the
+ * id of the session that actually implemented the spec, so the handoff is
+ * visible in the output; see spec-mode-same-session.ts for the in-place
+ * variant, which reports no handoff.
+ *
+ * The handed-off session announces itself only on the notification envelope:
+ * once implementation moves, `params.sessionId` on incoming notifications stops
+ * matching `session.id`. The typed message stream carries no session id per
+ * message, so the example subscribes with `session.onNotification()` and
+ * validates each envelope with `SessionNotificationSchema`.
+ *
+ * Usage:
+ *   npx tsx examples/node/spec-mode-new-session.ts
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  type ClientPermissionHandler,
+  DroidInteractionMode,
+  DroidMessageType,
+  ReasoningEffort,
+  SessionNotificationSchema,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  createSession,
+} from '@factory/droid-sdk/node';
+
+const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-spec-'));
+const outputPath = join(tempDir, 'hello.txt');
+
+let handoffSessionId: string | null = null;
+
+const handlePermissionRequest: ClientPermissionHandler = ({
+  toolUses,
+  options,
+}) => {
+  const exitsSpecMode =
+    toolUses.length > 0 &&
+    toolUses.every(
+      (toolUse) => toolUse.details.type === ToolConfirmationType.ExitSpecMode
+    );
+  const createsExpectedFile =
+    toolUses.length > 0 &&
+    toolUses.every(
+      (toolUse) =>
+        toolUse.details.type === ToolConfirmationType.Create &&
+        toolUse.details.filePath === outputPath
+    );
+
+  let outcome = ToolConfirmationOutcome.Cancel;
+  if (exitsSpecMode) {
+    outcome = ToolConfirmationOutcome.ProceedNewSessionHigh;
+  } else if (createsExpectedFile) {
+    outcome = ToolConfirmationOutcome.ProceedOnce;
+  }
+  if (!options.some((option) => option.value === outcome)) {
+    throw new Error(`Outcome not offered: ${outcome}`);
+  }
+  return outcome;
+};
+
+try {
+  const session = await createSession({
+    interactionMode: DroidInteractionMode.Spec,
+    specModeReasoningEffort: ReasoningEffort.High,
+    permissionHandler: handlePermissionRequest,
+  });
+
+  // The typed message stream carries no per-message session id, and the
+  // precise handoff signal the SDK uses internally is not part of the public
+  // surface, so a foreign envelope session id is the available proxy. It is
+  // only a proxy: any notification scoped to another session also trips it.
+  const unsubscribe = session.onNotification((notification) => {
+    const parsed = SessionNotificationSchema.safeParse(notification);
+    if (!parsed.success) return;
+    const envelopeSessionId = parsed.data.params.sessionId;
+    if (envelopeSessionId !== undefined && envelopeSessionId !== session.id) {
+      handoffSessionId = envelopeSessionId;
+    }
+  });
+
+  try {
+    for await (const message of session.stream(
+      `Plan then create ${outputPath} containing "Hello from Droid".`
+    )) {
+      if (message.type === DroidMessageType.Result && !message.success) {
+        throw new Error(
+          message.error?.message ?? `Turn ended: ${message.subtype}`
+        );
+      }
+    }
+  } finally {
+    unsubscribe();
+    await session.close();
+  }
+
+  console.log(`planning session:       ${session.id}`);
+  console.log(
+    `implementing session:   ${handoffSessionId ?? '<same session>'}`
+  );
+  console.log(await readFile(outputPath, 'utf8'));
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}
+
+// Without a distinct implementing session this run is indistinguishable from
+// the same-session variant, so the handoff this example demonstrates did not
+// happen.
+if (handoffSessionId === null) {
+  throw new Error(
+    'Spec approval with ProceedNewSessionHigh did not hand off to a new session.'
+  );
+}