@factory/droid-sdk 0.7.0 → 0.9.0

package/examples/browser/daemon-model-discovery.ts

@@ -0,0 +1,47 @@
+/**
+ * Lists canonical model metadata through a daemon connection.
+ *
+ * Runs in a real browser (no `process`, no Node builtins). From a source
+ * checkout of this repository:
+ *   npm run build
+ *   FACTORY_API_KEY=... npm run serve:browser-example
+ *   open http://127.0.0.1:8420/?example=daemon-model-discovery
+ *
+ * Never commit a real API key or deploy it in browser code.
+ */
+
+import { connectToDaemon } from '@factory/droid-sdk';
+
+const { daemonUrl, apiKey } = (
+  globalThis as typeof globalThis & {
+    __DROID_SDK_EXAMPLE_CONFIG__: {
+      daemonUrl: string;
+      apiKey: string;
+    };
+  }
+).__DROID_SDK_EXAMPLE_CONFIG__;
+if (!apiKey) {
+  throw new Error('Set FACTORY_API_KEY.');
+}
+
+const droid = await connectToDaemon({
+  url: daemonUrl,
+  auth: { apiKey },
+});
+
+try {
+  const models = await droid.models.list({ includeDisabled: true });
+
+  for (const model of models) {
+    const status = model.disabled
+      ? `disabled: ${model.disabledReason}`
+      : 'available';
+    console.log(
+      `${model.displayName} (${model.id})\n` +
+        `  status: ${status}\n` +
+        `  reasoning: ${model.supportedReasoningEfforts.join(', ')}`
+    );
+  }
+} finally {
+  droid.disconnect();
+}

package/examples/browser/index.html

@@ -36,7 +36,8 @@
       <code>DROID_SDK_EXAMPLE_CWD</code> before starting the server, then pick
       one with <code>?example=daemon-session</code> (default),
       <code>?example=daemon-multi-session</code>,
-      <code>?example=daemon-lifecycle</code>, or
+      <code>?example=daemon-lifecycle</code>,
+      <code>?example=daemon-model-discovery</code>, or
       <code>?example=list-sessions</code>.
     </p>
 

package/examples/browser/list-sessions.ts

@@ -37,9 +37,7 @@ try {
   }
 
   for (const session of sessions) {
-    const messages = await droid.sessions.getMessages(session.id, {
-      limit: 20,
-    });
+    const messages = await session.getMessages({ limit: 20 });
 
     console.log(
       session.id,

package/examples/node/abort-session-stream.ts

@@ -24,7 +24,9 @@ try {
   )) {
     // Consume the stream until the abort signal cuts it short.
   }
+  console.log('The turn completed before the abort signal fired.');
 } catch (error) {
+  if (!controller.signal.aborted) throw error;
   console.log(error instanceof Error ? error.message : String(error));
 } finally {
   clearTimeout(timeout);

package/examples/node/ask-user-elicitation.ts

@@ -1,8 +1,8 @@
 /**
  * AskUser elicitation example.
  *
- * When Droid needs input mid-turn it sends an `askUser` request. `askUserHandler`
- * answers it programmatically; without a handler the request goes unanswered.
+ * When Droid needs input mid-turn, `askUserHandler` answers it. Without a
+ * handler, the request is declined.
  *
  * Usage:
  *   npx tsx examples/node/ask-user-elicitation.ts
@@ -10,11 +10,11 @@
 
 import { run } from '@factory/droid-sdk/node';
 
-const { text } = await run(
+const result = await run(
   'Use the AskUser tool to ask me which color I prefer, then reply with the color I picked.',
   {
-    askUserHandler(params) {
-      for (const question of params.questions) {
+    askUserHandler({ questions }) {
+      for (const question of questions) {
         console.log(`[asked] ${question.question}`);
         console.log(`[options] ${question.options.join(', ')}`);
       }
@@ -22,7 +22,7 @@ const { text } = await run(
       // Answer every question with its first option. A real integration would
       // prompt the user; returning `cancelled: true` declines instead.
       return {
-        answers: params.questions.map((question) => ({
+        answers: questions.map((question) => ({
           index: question.index,
           question: question.question,
           answer: question.options[0] ?? 'no preference',
@@ -32,4 +32,8 @@ const { text } = await run(
   }
 );
 
-console.log(`\n${text}`);
+if (!result.success) {
+  throw new Error(result.error?.message ?? 'The turn was interrupted.');
+}
+
+console.log(`\n${result.text}`);

package/examples/node/compact-session.ts

@@ -10,6 +10,25 @@
 
 import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
 
+async function streamText(
+  activeSession: Awaited<ReturnType<typeof createSession>>,
+  prompt: string
+): Promise<string> {
+  let text = '';
+  for await (const msg of activeSession.stream(prompt)) {
+    if (msg.type === DroidMessageType.Assistant) {
+      text += msg.text;
+    }
+    if (msg.type === DroidMessageType.Result && !msg.success) {
+      throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+    }
+  }
+  if (!text.trim()) {
+    throw new Error('The turn produced no assistant output.');
+  }
+  return text;
+}
+
 const session = await createSession();
 
 try {
@@ -18,30 +37,26 @@ try {
     'Say "two" and nothing else',
     'Say "three" and nothing else',
   ]) {
-    for await (const msg of session.stream(prompt)) {
-      if (msg.type === DroidMessageType.Assistant) {
-        console.log(msg.text);
-      }
-    }
+    console.log(await streamText(session, prompt));
   }
 
   const { session: compacted, removedCount } = await session.compact();
 
-  // `session` is now a retired wrapper. Its persisted ID can still be passed
-  // to resumeSession() later if the uncompacted history is needed again.
-  console.log(`\noriginal session: ${session.id}`);
-  console.log(`compacted into:   ${compacted.id}`);
-  console.log(`messages removed: ${removedCount}`);
+  try {
+    // `session` is now a retired wrapper. Its persisted ID can still be passed
+    // to resumeSession() later if the uncompacted history is needed again.
+    console.log(`\noriginal session: ${session.id}`);
+    console.log(`compacted into:   ${compacted.id}`);
+    console.log(`messages removed: ${removedCount}`);
 
-  for await (const msg of compacted.stream(
-    'Which numbers did I ask you to say?'
-  )) {
-    if (msg.type === DroidMessageType.Assistant) {
-      console.log(`continued:        ${msg.text}`);
-    }
+    const continued = await streamText(
+      compacted,
+      'Which numbers did I ask you to say?'
+    );
+    console.log(`continued:        ${continued}`);
+  } finally {
+    await compacted.close();
   }
-
-  await compacted.close();
 } finally {
   // Closes the active source, or does nothing if it was retired.
   await session.close();

package/examples/node/custom-system-prompt.ts

@@ -0,0 +1,35 @@
+/**
+ * Custom system prompt example.
+ *
+ * Usage:
+ *   npx tsx examples/node/custom-system-prompt.ts
+ */
+
+import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
+
+const session = await createSession({
+  systemPrompt: {
+    type: 'preset',
+    preset: 'droid',
+    append: 'Keep answers concise and cite relevant files.',
+  },
+});
+
+try {
+  let text = '';
+  for await (const message of session.stream(
+    'Summarize the main entry points in this project.'
+  )) {
+    if (message.type === DroidMessageType.Assistant) {
+      text += message.text;
+    }
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
+  }
+  console.log(text);
+} finally {
+  await session.close();
+}

package/examples/node/document-input.ts

@@ -0,0 +1,58 @@
+/**
+ * Document input example.
+ *
+ * Attaches plain text or a base64 PDF through `files`. With no path, it uses
+ * an embedded text document so the example runs as-is.
+ *
+ * Usage:
+ *   npx tsx examples/node/document-input.ts
+ *   npx tsx examples/node/document-input.ts ./report.txt
+ *   npx tsx examples/node/document-input.ts ./report.pdf
+ */
+
+import { readFile } from 'node:fs/promises';
+import { basename, extname } from 'node:path';
+
+import { run, type DocumentSource } from '@factory/droid-sdk/node';
+
+const inputPath = process.argv[2];
+let document: DocumentSource;
+
+if (!inputPath) {
+  document = {
+    type: 'text',
+    mediaType: 'text/plain',
+    data: [
+      'Release: 2.4.0',
+      'Status: Ready',
+      'Main change: Added document input to the TypeScript SDK guide.',
+    ].join('\n'),
+    name: 'release-notes.txt',
+  };
+} else if (extname(inputPath).toLowerCase() === '.pdf') {
+  document = {
+    type: 'base64',
+    mediaType: 'application/pdf',
+    data: (await readFile(inputPath)).toString('base64'),
+    name: basename(inputPath),
+  };
+} else {
+  document = {
+    type: 'text',
+    mediaType: 'text/plain',
+    data: await readFile(inputPath, 'utf8'),
+    name: basename(inputPath),
+  };
+}
+
+const result = await run('Summarize this document in one sentence.', {
+  files: [document],
+});
+
+if (!result.success) {
+  throw new Error(
+    result.error?.message ?? `Document summary failed (${result.subtype}).`
+  );
+}
+
+console.log(result.text);

package/examples/node/enter-spec-mode.ts

@@ -1,13 +1,8 @@
 /**
- * Enter spec mode on a live session.
+ * Auto to Spec to implementation example.
  *
- * The other spec-mode examples start the session in spec mode. This one starts
- * in the default mode and switches mid-session with `enterSpecMode()`, which is
- * what a host app does when the user toggles spec mode on an open conversation.
- *
- * The switch is observable in the confirmations Droid asks for: it proposes a
- * plan (`ExitSpecMode`) before touching the filesystem, instead of going
- * straight to `Create`.
+ * Switches an Auto session to Spec mode, approves the plan, then allows the
+ * planned file creation in the same session.
  *
  * Usage:
  *   npx tsx examples/node/enter-spec-mode.ts
@@ -18,6 +13,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import {
+  type ClientPermissionHandler,
+  DroidInteractionMode,
+  DroidMessageType,
   ToolConfirmationOutcome,
   ToolConfirmationType,
   createSession,
@@ -26,41 +24,64 @@ import {
 const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-enter-spec-'));
 const outputPath = join(tempDir, 'hello.txt');
 
+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
+    );
+
+  if (exitsSpecMode) {
+    for (const toolUse of toolUses) {
+      if (toolUse.details.type === ToolConfirmationType.ExitSpecMode) {
+        console.log(toolUse.details.plan);
+      }
+    }
+  }
+
+  const outcome =
+    exitsSpecMode || createsExpectedFile
+      ? ToolConfirmationOutcome.ProceedOnce
+      : ToolConfirmationOutcome.Cancel;
+  if (!options.some((option) => option.value === outcome)) {
+    throw new Error(`Outcome not offered: ${outcome}`);
+  }
+  return outcome;
+};
+
 try {
   const session = await createSession({
-    permissionHandler(params) {
-      for (const toolUse of params.toolUses) {
-        const label =
-          toolUse.details.type === ToolConfirmationType.ExitSpecMode
-            ? 'plan proposed'
-            : 'implementing';
-        console.log(`[${label}] ${toolUse.details.type}`);
-      }
-      // Approving ExitSpecMode accepts the plan and lets implementation run.
-      return ToolConfirmationOutcome.ProceedOnce;
-    },
+    interactionMode: DroidInteractionMode.Auto,
+    permissionHandler: handlePermissionRequest,
   });
 
   try {
-    console.log(
-      `mode at creation: ${String(session.settings.interactionMode)}`
-    );
-
     await session.enterSpecMode();
-    console.log('switched to spec mode\n');
 
-    for await (const _msg of session.stream(
+    for await (const message of session.stream(
       `Create ${outputPath} containing "hello".`
     )) {
-      // Consume the stream until the plan is approved and implemented.
+      if (message.type === DroidMessageType.Result && !message.success) {
+        throw new Error(
+          message.error?.message ?? `Turn ended: ${message.subtype}`
+        );
+      }
     }
   } finally {
     await session.close();
   }
 
-  console.log(
-    `\nfile contents: ${JSON.stringify(await readFile(outputPath, 'utf8'))}`
-  );
+  console.log(await readFile(outputPath, 'utf8'));
 } finally {
   await rm(tempDir, { recursive: true, force: true });
 }

package/examples/node/external-mcp.ts

@@ -0,0 +1,45 @@
+/**
+ * External MCP server example.
+ *
+ * Connects an HTTP MCP server to one Node session, then lists its status and
+ * discovered tools.
+ *
+ * Usage:
+ *   MCP_SERVER_URL=https://example.com/mcp \
+ *     npx tsx examples/node/external-mcp.ts
+ */
+
+import { createSession } from '@factory/droid-sdk/node';
+
+const url = process.env.MCP_SERVER_URL;
+if (!url) {
+  throw new Error('Set MCP_SERVER_URL to an HTTP MCP endpoint.');
+}
+
+const token = process.env.MCP_SERVER_TOKEN;
+const session = await createSession({
+  mcpServers: [
+    {
+      name: 'external',
+      type: 'http',
+      url,
+      headers: token
+        ? [{ name: 'Authorization', value: `Bearer ${token}` }]
+        : [],
+    },
+  ],
+});
+
+try {
+  const { servers } = await session.listMcpServers();
+  const tools = await session.listMcpTools();
+  const server = servers.find((item) => item.name === 'external');
+
+  console.log(`status: ${server?.status ?? 'unknown'}`);
+
+  for (const tool of tools.filter((item) => item.serverName === 'external')) {
+    console.log(tool.name);
+  }
+} finally {
+  await session.close();
+}

package/examples/node/fork-session.ts

@@ -1,8 +1,8 @@
 /**
  * Fork session example.
  *
- * Establishes context in one session, forks it with `fork()`, then
- * uses the returned fork handle and confirms the copied context carried over.
+ * Establishes context in one session, forks it with `fork()`, then uses the
+ * returned fork handle to show the copied context.
  *
  * Usage:
  *   npx tsx examples/node/fork-session.ts
@@ -19,6 +19,12 @@ async function streamText(
     if (msg.type === DroidMessageType.Assistant) {
       text += msg.text;
     }
+    if (msg.type === DroidMessageType.Result && !msg.success) {
+      throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+    }
+  }
+  if (!text.trim()) {
+    throw new Error('The turn produced no assistant output.');
   }
   return text;
 }
@@ -30,15 +36,20 @@ try {
 
   const fork = await session.fork();
 
-  // `session` is now a retired wrapper. Its persisted ID can still be passed
-  // to resumeSession() later if the original branch is needed again.
-  console.log(`original session: ${session.id}`);
-  console.log(`forked session:   ${fork.id}`);
-  console.log(
-    `fork recalls:     ${await streamText(fork, 'What phrase did I ask you to remember?')}`
-  );
+  try {
+    // `session` is now a retired wrapper. Its persisted ID can still be passed
+    // to resumeSession() later if the original branch is needed again.
+    console.log(`original session: ${session.id}`);
+    console.log(`forked session:   ${fork.id}`);
 
-  await fork.close();
+    const recalled = await streamText(
+      fork,
+      'What phrase did I ask you to remember?'
+    );
+    console.log(`fork recalls:     ${recalled}`);
+  } finally {
+    await fork.close();
+  }
 } finally {
   // Closes the active source, or does nothing if it was retired.
   await session.close();

package/examples/node/hook-execution.ts

@@ -1,23 +1,9 @@
 /**
  * Hook execution example.
  *
- * Registers a PreToolUse hook for the `Execute` tool and prints the hook
- * lifecycle messages that arrive in the session stream.
- *
- * The hook lives in a throwaway project directory (`<tempdir>/.factory/hooks.json`)
- * that is passed as the session `cwd` and deleted afterwards, so running this
- * example never writes to your own `~/.factory` configuration. It does not
- * isolate you from it: hook lists are concatenated across settings levels
- * rather than replaced, so your own user-level `PreToolUse` hooks are appended
- * to the one below and fire during this run whenever their matcher matches.
- *
- * `hooksDisabled` resolves first-defined-wins across settings levels, so the
- * config below sets it explicitly rather than leaving it absent. An absent
- * value would inherit a global `"hooksDisabled": true` from `~/.factory` and
- * the hook would never run.
- *
- * See https://docs.factory.ai/cli/configuration/hooks-guide for the `/hooks`
- * slash command, the other events, and security guidance.
+ * Creates a temporary project with a PreToolUse hook and prints its stream
+ * events.
+ * User-level hooks still apply to the temporary project.
  *
  * Usage:
  *   npx tsx examples/node/hook-execution.ts
@@ -30,6 +16,7 @@ import { join } from 'node:path';
 import {
   DroidMessageType,
   ToolConfirmationOutcome,
+  ToolConfirmationType,
   createSession,
 } from '@factory/droid-sdk/node';
 
@@ -46,6 +33,7 @@ const hookSettings = {
 const projectDir = await mkdtemp(join(tmpdir(), 'droid-sdk-hook-project-'));
 
 let hookCount = 0;
+const expectedCommand = 'echo hello';
 
 try {
   await mkdir(join(projectDir, '.factory'), { recursive: true });
@@ -56,25 +44,43 @@ try {
 
   const session = await createSession({
     cwd: projectDir,
-    permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
+    permissionHandler({ toolUses, options }) {
+      const approvesExpectedCommand =
+        toolUses.length === 1 &&
+        toolUses[0].details.type === ToolConfirmationType.Execute &&
+        toolUses[0].details.fullCommand === expectedCommand;
+      const desired = approvesExpectedCommand
+        ? ToolConfirmationOutcome.ProceedOnce
+        : ToolConfirmationOutcome.Cancel;
+
+      if (!options.some((option) => option.value === desired)) {
+        throw new Error(`Outcome not offered: ${desired}`);
+      }
+      return desired;
+    },
   });
 
   try {
-    for await (const msg of session.stream(
-      'Run the shell command `echo hello` using the Execute tool.'
+    for await (const message of session.stream(
+      `Run the shell command \`${expectedCommand}\` using the Execute tool.`
     )) {
-      if (msg.type !== DroidMessageType.Hook) {
-        continue;
-      }
-
-      hookCount++;
-      if (msg.status === 'started') {
-        console.log(`[hook started] ${msg.eventName}: ${msg.command}`);
-      } else {
-        console.log(
-          `[hook ${msg.status}] exit code ${String(msg.exitCode)}: ${(msg.stdout ?? '').trim()}`
+      if (message.type === DroidMessageType.Result && !message.success) {
+        throw new Error(
+          message.error?.message ?? `Turn ended: ${message.subtype}`
         );
       }
+      if (message.type === DroidMessageType.Hook) {
+        hookCount++;
+        if (message.status === 'started') {
+          console.log(
+            `[hook started] ${message.eventName}: ${message.command}`
+          );
+        } else {
+          console.log(
+            `[hook ${message.status}] exit code ${String(message.exitCode)}: ${(message.stdout ?? '').trim()}`
+          );
+        }
+      }
     }
   } finally {
     await session.close();
@@ -83,12 +89,6 @@ try {
   await rm(projectDir, { recursive: true, force: true });
 }
 
-// A silent zero-hook run would look identical to a passing one, so fail loudly.
 if (hookCount === 0) {
-  throw new Error(
-    'No hook messages arrived: the registered PreToolUse hook never ran. ' +
-      'The most likely cause is that the droid answered this turn without ' +
-      'calling the Execute tool, so the `Execute` matcher never fired. ' +
-      'Re-run, or widen the matcher to the tool the droid actually used.'
-  );
+  throw new Error('The PreToolUse hook did not run.');
 }

package/examples/node/image-attachment.ts

@@ -19,7 +19,7 @@ const PURPLE_SQUARE_PNG =
   'Bg0aNGjQoEGDFmjQAg0atECDFmjQoAUatECDBi3QoAUaNGiBBi3QoEELNGiBBn2g' +
   'AU2hHmFuN1AZAAAAAElFTkSuQmCC';
 
-const { text } = await run(
+const result = await run(
   'What single shape and color is in this image? Answer in five words or fewer.',
   {
     images: [
@@ -32,4 +32,10 @@ const { text } = await run(
   }
 );
 
-console.log(text);
+if (!result.success) {
+  throw new Error(
+    result.error?.message ?? `Image description failed (${result.subtype}).`
+  );
+}
+
+console.log(result.text);