@factory/droid-sdk 0.6.0 → 0.8.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-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/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,69 @@
+<!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>,
+      <code>?example=daemon-model-discovery</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,50 @@
+/**
+ * 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 session.getMessages({ limit: 20 });
+
+    console.log(
+      session.id,
+      session.title ?? '(untitled)',
+      `${messages.length} messages`
+    );
+  }
+} finally {
+  droid.disconnect();
+}

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

@@ -0,0 +1,34 @@
+/**
+ * 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/node/abort-session-stream.ts
+ */
+
+import { createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+const controller = new AbortController();
+const timeout = setTimeout(
+  () => controller.abort(new Error('Stopped by AbortController')),
+  1000
+);
+
+try {
+  for await (const _msg of session.stream(
+    'Write a long explanation of how compilers work.',
+    { abortSignal: controller.signal }
+  )) {
+    // 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);
+  await session.close();
+}

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

@@ -0,0 +1,39 @@
+/**
+ * AskUser elicitation example.
+ *
+ * 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
+ */
+
+import { run } from '@factory/droid-sdk/node';
+
+const result = await run(
+  'Use the AskUser tool to ask me which color I prefer, then reply with the color I picked.',
+  {
+    askUserHandler({ questions }) {
+      for (const question of 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: questions.map((question) => ({
+          index: question.index,
+          question: question.question,
+          answer: question.options[0] ?? 'no preference',
+        })),
+      };
+    },
+  }
+);
+
+if (!result.success) {
+  throw new Error(result.error?.message ?? 'The turn was interrupted.');
+}
+
+console.log(`\n${result.text}`);

package/examples/node/compact-session.ts

@@ -0,0 +1,63 @@
+/**
+ * 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';
+
+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 {
+  for (const prompt of [
+    'Say "one" and nothing else',
+    'Say "two" and nothing else',
+    'Say "three" and nothing else',
+  ]) {
+    console.log(await streamText(session, prompt));
+  }
+
+  const { session: compacted, removedCount } = await session.compact();
+
+  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}`);
+
+    const continued = await streamText(
+      compacted,
+      'Which numbers did I ask you to say?'
+    );
+    console.log(`continued:        ${continued}`);
+  } finally {
+    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);