@factory/droid-sdk 0.6.0 → 0.7.0

package/examples/browser/daemon-lifecycle.ts

@@ -0,0 +1,95 @@
+/**
+ * Forks, compacts, and rewinds a daemon session.
+ *
+ * Daemon operations return a new session ID. The source session stays usable,
+ * and the successor must be resumed explicitly.
+ *
+ * Usage:
+ *   npm run build
+ *   FACTORY_API_KEY=... DROID_SDK_EXAMPLE_CWD=/repo npm run serve:browser-example
+ *   open http://127.0.0.1:8420/?example=daemon-lifecycle
+ */
+
+import {
+  connectToDaemon,
+  DroidMessageType,
+  type ConnectedDroidSession,
+} from '@factory/droid-sdk';
+
+const { daemonUrl, apiKey, cwd } = (
+  globalThis as typeof globalThis & {
+    __DROID_SDK_EXAMPLE_CONFIG__: {
+      daemonUrl: string;
+      apiKey: string;
+      cwd: string;
+    };
+  }
+).__DROID_SDK_EXAMPLE_CONFIG__;
+if (!apiKey || !cwd) {
+  throw new Error('Set FACTORY_API_KEY and DROID_SDK_EXAMPLE_CWD.');
+}
+
+const droid = await connectToDaemon({
+  url: daemonUrl,
+  auth: { apiKey },
+});
+
+async function send(
+  session: ConnectedDroidSession,
+  prompt: string
+): Promise<string> {
+  let messageId: string | undefined;
+
+  for await (const message of session.stream(prompt)) {
+    if (
+      message.type === DroidMessageType.User &&
+      message.message.visibility !== 'llm_only'
+    ) {
+      messageId ??= message.message.id;
+    }
+    if (message.type === DroidMessageType.Assistant) {
+      console.log(message.text);
+    }
+  }
+
+  if (!messageId) throw new Error('The turn produced no user message ID.');
+  return messageId;
+}
+
+const sessions: ConnectedDroidSession[] = [];
+
+try {
+  const source = await droid.sessions.create({ cwd });
+  sessions.push(source);
+
+  await send(source, 'Remember this phrase exactly: mango sunrise');
+  const secondTurn = await send(
+    source,
+    'Now forget it and remember: cobalt harbor'
+  );
+
+  const { newSessionId: forkedId } = await source.fork();
+  const forked = await droid.sessions.resume(forkedId);
+  sessions.push(forked);
+  console.log(`Forked session: ${forked.id}`);
+
+  const { newSessionId: compactedId } = await source.compact();
+  const compacted = await droid.sessions.resume(compactedId);
+  sessions.push(compacted);
+  console.log(`Compacted session: ${compacted.id}`);
+
+  const { newSessionId: rewoundId } = await source.rewind({
+    messageId: secondTurn,
+    filesToRestore: [],
+    filesToDelete: [],
+    forkTitle: 'Before the second phrase',
+  });
+  const rewound = await droid.sessions.resume(rewoundId);
+  sessions.push(rewound);
+  console.log(`Rewound session: ${rewound.id}`);
+
+  await send(source, 'Say "source still works" and nothing else.');
+} finally {
+  await Promise.allSettled(sessions.map((session) => session.close()));
+  droid.disconnect();
+}

package/examples/browser/daemon-multi-session.ts

@@ -0,0 +1,66 @@
+/**
+ * Creates two sessions concurrently over one 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=... DROID_SDK_EXAMPLE_CWD=/repo npm run serve:browser-example
+ *   open http://127.0.0.1:8420/?example=daemon-multi-session
+ *
+ * Never commit a real API key or deploy it in browser code.
+ */
+
+import {
+  connectToDaemon,
+  DroidMessageType,
+  type ConnectedDroidSession,
+} from '@factory/droid-sdk';
+
+const { daemonUrl, apiKey, cwd } = (
+  globalThis as typeof globalThis & {
+    __DROID_SDK_EXAMPLE_CONFIG__: {
+      daemonUrl: string;
+      apiKey: string;
+      cwd: string;
+    };
+  }
+).__DROID_SDK_EXAMPLE_CONFIG__;
+if (!apiKey || !cwd) {
+  throw new Error('Set FACTORY_API_KEY and DROID_SDK_EXAMPLE_CWD.');
+}
+
+const droid = await connectToDaemon({
+  url: daemonUrl,
+  auth: { apiKey },
+});
+
+async function runTurn(
+  session: ConnectedDroidSession,
+  label: string,
+  prompt: string
+): Promise<void> {
+  for await (const message of session.stream(prompt)) {
+    if (message.type === DroidMessageType.Assistant) {
+      console.log(`${label}: ${message.text}`);
+    }
+  }
+}
+
+const sessions: ConnectedDroidSession[] = [];
+try {
+  const first = await droid.sessions.create({ cwd });
+  sessions.push(first);
+  const second = await droid.sessions.create({ cwd });
+  sessions.push(second);
+
+  console.log(`First session:  ${first.id}`);
+  console.log(`Second session: ${second.id}`);
+
+  await Promise.all([
+    runTurn(first, 'First', 'Say "one" and nothing else.'),
+    runTurn(second, 'Second', 'Say "two" and nothing else.'),
+  ]);
+} finally {
+  await Promise.allSettled(sessions.map((session) => session.close()));
+  droid.disconnect();
+}

package/examples/browser/daemon-session.ts

@@ -0,0 +1,73 @@
+/**
+ * Daemon connection from a browser: run a turn and approve its tool use.
+ *
+ * Waits for the turn to end rather than for the permission request, since a
+ * turn can finish without asking.
+ *
+ * Runs in a real browser (no `process`, no Node builtins). From a source
+ * checkout of this repository:
+ *   npm run build
+ *   FACTORY_API_KEY=... DROID_SDK_EXAMPLE_CWD=/repo npm run serve:browser-example
+ *   open http://127.0.0.1:8420/?example=daemon-session
+ *
+ * Notes:
+ * - If your page is served over https://, the browser will block ws:// URLs as
+ *   mixed content. Use wss:// (or serve the page over http:// for localhost).
+ * - Never commit a real API key or deploy it in browser code.
+ */
+
+import {
+  AutonomyLevel,
+  connectToDaemon,
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  type ConnectedDroidSession,
+} from '@factory/droid-sdk';
+
+const { daemonUrl, apiKey, cwd } = (
+  globalThis as typeof globalThis & {
+    __DROID_SDK_EXAMPLE_CONFIG__: {
+      daemonUrl: string;
+      apiKey: string;
+      cwd: string;
+    };
+  }
+).__DROID_SDK_EXAMPLE_CONFIG__;
+if (!apiKey || !cwd) {
+  throw new Error('Set FACTORY_API_KEY and DROID_SDK_EXAMPLE_CWD.');
+}
+
+const droid = await connectToDaemon({
+  url: daemonUrl,
+  auth: { apiKey },
+});
+
+let approvedPermission = false;
+let session: ConnectedDroidSession | undefined;
+
+try {
+  session = await droid.sessions.create({
+    cwd,
+    // Off ensures even low-risk commands exercise the permission handler.
+    autonomyLevel: AutonomyLevel.Off,
+    permissionHandler: () => {
+      approvedPermission = true;
+      return ToolConfirmationOutcome.ProceedOnce;
+    },
+  });
+
+  for await (const message of session.stream(
+    'Run `echo hello from the browser example` and show me the output.'
+  )) {
+    if (message.type === DroidMessageType.Assistant) {
+      console.log(message.text);
+    }
+  }
+
+  if (!approvedPermission) {
+    throw new Error('Turn finished without requesting permission.');
+  }
+} finally {
+  await Promise.allSettled(session ? [session.close()] : []);
+  droid.disconnect();
+}

package/examples/browser/index.html

@@ -0,0 +1,68 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Droid SDK browser examples</title>
+    <style>
+      body {
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        margin: 2rem;
+        line-height: 1.5;
+      }
+      pre {
+        background: #f4f4f5;
+        padding: 0.75rem;
+        overflow-x: auto;
+        white-space: pre-wrap;
+      }
+      #error:empty {
+        display: none;
+      }
+      #error {
+        background: #fee2e2;
+        padding: 0.75rem;
+        white-space: pre-wrap;
+      }
+    </style>
+  </head>
+  <body>
+    <h1>Droid SDK browser examples</h1>
+    <p>
+      Served by <code>npm run serve:browser-example</code>. The example module
+      is bundled for the browser on each request, so a reload picks up edits.
+    </p>
+    <p>
+      Set <code>FACTORY_API_KEY</code> and
+      <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=list-sessions</code>.
+    </p>
+
+    <div id="error"></div>
+    <div id="output"></div>
+
+    <script>
+      globalThis.__DROID_SDK_EXAMPLE_CONFIG__ =
+        __INJECTED_DROID_SDK_EXAMPLE_CONFIG__;
+    </script>
+    <script type="module">
+      // Surface load-time failures (for example a missing config value, which
+      // throws during module evaluation) instead of leaving a blank page.
+      const errorBox = document.querySelector('#error');
+      const showError = (err) => {
+        errorBox.textContent = String(
+          (err && (err.stack || err.message)) || err
+        );
+      };
+      window.addEventListener('error', (e) => showError(e.error ?? e.message));
+      window.addEventListener('unhandledrejection', (e) => showError(e.reason));
+
+      const params = new URLSearchParams(location.search);
+      const example = params.get('example') ?? 'daemon-session';
+
+      import(`./${example}.js${location.search}`).catch(showError);
+    </script>
+  </body>
+</html>

package/examples/browser/list-sessions.ts

@@ -0,0 +1,52 @@
+/**
+ * Lists recent daemon sessions and their messages.
+ *
+ * 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=list-sessions
+ *
+ * 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 sessions = await droid.sessions.list({ limit: 10 });
+
+  if (sessions.length === 0) {
+    console.log('No sessions found.');
+  }
+
+  for (const session of sessions) {
+    const messages = await droid.sessions.getMessages(session.id, {
+      limit: 20,
+    });
+
+    console.log(
+      session.id,
+      session.title ?? '(untitled)',
+      `${messages.length} messages`
+    );
+  }
+} finally {
+  droid.disconnect();
+}

package/examples/{abort-session-stream.ts → node/abort-session-stream.ts}

@@ -1,16 +1,16 @@
 /**
  * Abort a running turn with AbortController.
  *
+ * Passing an `abortSignal` to `session.stream()` makes the stream throw when
+ * the signal fires. See interrupt-session.ts for the server-side equivalent.
+ *
  * Usage:
- *   npx tsx examples/abort-session-stream.ts
+ *   npx tsx examples/node/abort-session-stream.ts
  */
 
-import { createSession } from '@factory/droid-sdk';
+import { createSession } from '@factory/droid-sdk/node';
 
-const session = await createSession({
-  apiKey: process.env.FACTORY_API_KEY!,
-  cwd: process.cwd(),
-});
+const session = await createSession();
 const controller = new AbortController();
 const timeout = setTimeout(
   () => controller.abort(new Error('Stopped by AbortController')),
@@ -20,11 +20,9 @@ const timeout = setTimeout(
 try {
   for await (const _msg of session.stream(
     'Write a long explanation of how compilers work.',
-    {
-      abortSignal: controller.signal,
-    }
+    { abortSignal: controller.signal }
   )) {
-    void _msg;
+    // Consume the stream until the abort signal cuts it short.
   }
 } catch (error) {
   console.log(error instanceof Error ? error.message : String(error));

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

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * Usage:
+ *   npx tsx examples/node/ask-user-elicitation.ts
+ */
+
+import { run } from '@factory/droid-sdk/node';
+
+const { text } = 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) {
+        console.log(`[asked] ${question.question}`);
+        console.log(`[options] ${question.options.join(', ')}`);
+      }
+
+      // 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) => ({
+          index: question.index,
+          question: question.question,
+          answer: question.options[0] ?? 'no preference',
+        })),
+      };
+    },
+  }
+);
+
+console.log(`\n${text}`);

package/examples/node/compact-session.ts

@@ -0,0 +1,48 @@
+/**
+ * Compact session example.
+ *
+ * Builds up history over a few turns, then calls `compact()` to
+ * summarize it into a new session.
+ *
+ * Usage:
+ *   npx tsx examples/node/compact-session.ts
+ */
+
+import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+try {
+  for (const prompt of [
+    'Say "one" and nothing else',
+    '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);
+      }
+    }
+  }
+
+  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}`);
+
+  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}`);
+    }
+  }
+
+  await compacted.close();
+} finally {
+  // Closes the active source, or does nothing if it was retired.
+  await session.close();
+}

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

@@ -0,0 +1,66 @@
+/**
+ * Enter spec mode on a live session.
+ *
+ * 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`.
+ *
+ * Usage:
+ *   npx tsx examples/node/enter-spec-mode.ts
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  createSession,
+} from '@factory/droid-sdk/node';
+
+const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-enter-spec-'));
+const outputPath = join(tempDir, 'hello.txt');
+
+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;
+    },
+  });
+
+  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(
+      `Create ${outputPath} containing "hello".`
+    )) {
+      // Consume the stream until the plan is approved and implemented.
+    }
+  } finally {
+    await session.close();
+  }
+
+  console.log(
+    `\nfile contents: ${JSON.stringify(await readFile(outputPath, 'utf8'))}`
+  );
+} finally {
+  await rm(tempDir, { recursive: true, force: true });
+}

package/examples/node/fork-session.ts

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ *
+ * Usage:
+ *   npx tsx examples/node/fork-session.ts
+ */
+
+import { DroidMessageType, createSession } from '@factory/droid-sdk/node';
+
+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.Assistant) {
+      text += msg.text;
+    }
+  }
+  return text;
+}
+
+const session = await createSession();
+
+try {
+  await streamText(session, 'Remember this phrase exactly: mango sunrise');
+
+  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?')}`
+  );
+
+  await fork.close();
+} finally {
+  // Closes the active source, or does nothing if it was retired.
+  await session.close();
+}

package/examples/node/hook-execution.ts

@@ -0,0 +1,94 @@
+/**
+ * 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.
+ *
+ * Usage:
+ *   npx tsx examples/node/hook-execution.ts
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  createSession,
+} from '@factory/droid-sdk/node';
+
+const hookSettings = {
+  hooksDisabled: false,
+  PreToolUse: [
+    {
+      matcher: 'Execute',
+      hooks: [{ type: 'command', command: 'echo hook-from-sdk-example' }],
+    },
+  ],
+};
+
+const projectDir = await mkdtemp(join(tmpdir(), 'droid-sdk-hook-project-'));
+
+let hookCount = 0;
+
+try {
+  await mkdir(join(projectDir, '.factory'), { recursive: true });
+  await writeFile(
+    join(projectDir, '.factory', 'hooks.json'),
+    JSON.stringify(hookSettings, null, 2)
+  );
+
+  const session = await createSession({
+    cwd: projectDir,
+    permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
+  });
+
+  try {
+    for await (const msg of session.stream(
+      'Run the shell command `echo hello` 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()}`
+        );
+      }
+    }
+  } finally {
+    await session.close();
+  }
+} finally {
+  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.'
+  );
+}