@factory/droid-sdk 0.6.0 → 0.8.0

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

@@ -0,0 +1,87 @@
+/**
+ * Auto to Spec to implementation example.
+ *
+ * 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
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  type ClientPermissionHandler,
+  DroidInteractionMode,
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  createSession,
+} from '@factory/droid-sdk/node';
+
+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({
+    interactionMode: DroidInteractionMode.Auto,
+    permissionHandler: handlePermissionRequest,
+  });
+
+  try {
+    await session.enterSpecMode();
+
+    for await (const message of session.stream(
+      `Create ${outputPath} containing "hello".`
+    )) {
+      if (message.type === DroidMessageType.Result && !message.success) {
+        throw new Error(
+          message.error?.message ?? `Turn ended: ${message.subtype}`
+        );
+      }
+    }
+  } finally {
+    await session.close();
+  }
+
+  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

@@ -0,0 +1,56 @@
+/**
+ * Fork session example.
+ *
+ * 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
+ */
+
+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;
+    }
+    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 {
+  await streamText(session, 'Remember this phrase exactly: mango sunrise');
+
+  const fork = await session.fork();
+
+  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}`);
+
+    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

@@ -0,0 +1,94 @@
+/**
+ * Hook execution example.
+ *
+ * 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
+ */
+
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  DroidMessageType,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  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;
+const expectedCommand = 'echo hello';
+
+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({ 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 message of session.stream(
+      `Run the shell command \`${expectedCommand}\` using the Execute tool.`
+    )) {
+      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();
+  }
+} finally {
+  await rm(projectDir, { recursive: true, force: true });
+}
+
+if (hookCount === 0) {
+  throw new Error('The PreToolUse hook did not run.');
+}

package/examples/node/image-attachment.ts

@@ -0,0 +1,41 @@
+/**
+ * Image attachment example.
+ *
+ * Attaches a base64 image to a prompt via `images`, so the model can see it.
+ * `run()` and `session.stream()` both accept the same `images` option.
+ *
+ * Usage:
+ *   npx tsx examples/node/image-attachment.ts
+ */
+
+import { run } from '@factory/droid-sdk/node';
+
+/** A 120x120 PNG: one purple square centered on white. */
+const PURPLE_SQUARE_PNG =
+  'iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAIAAAC2BqGFAAAAzElEQVR42u3QAQ0A' +
+  'MAgEsZeOvLkCFyQLvZyCprVSEIAGLdCgQQs0aIEGDVqgQQs0aNACDVqgQYMWaNAC' +
+  'DRq0QIMW6GPQlffdoEGDBg0aNGjQoEGDBg0aNGjQoEGDBg0aNGjQoEGDBg0aNGjQ' +
+  'oEGDBg0aNGjQoEGDBg0aNGjQoEGDBg0aNGjQoEGDBg0aNGjQoEGDBg0aNGjQoEGD' +
+  'Bg0aNGjQoEGDFmjQAg0atECDFmjQoAUatECDBi3QoAUaNGiBBi3QoEELNGiBBn2g' +
+  'AU2hHmFuN1AZAAAAAElFTkSuQmCC';
+
+const result = await run(
+  'What single shape and color is in this image? Answer in five words or fewer.',
+  {
+    images: [
+      {
+        type: 'base64',
+        data: PURPLE_SQUARE_PNG,
+        mediaType: 'image/png',
+      },
+    ],
+  }
+);
+
+if (!result.success) {
+  throw new Error(
+    result.error?.message ?? `Image description failed (${result.subtype}).`
+  );
+}
+
+console.log(result.text);

package/examples/node/init-metadata.ts

@@ -0,0 +1,24 @@
+/**
+ * Initialization metadata example.
+ *
+ * Reads direct metadata from a freshly created session: session ID, working
+ * directory, model, and settings.
+ *
+ * Usage:
+ *   npx tsx examples/node/init-metadata.ts
+ */
+
+import { createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+try {
+  const { settings } = session;
+  console.log(`session:          ${session.id}`);
+  console.log(`cwd:              ${String(session.cwd)}`);
+  console.log(`model:            ${String(settings.modelId)}`);
+  console.log(`interaction mode: ${String(settings.interactionMode)}`);
+  console.log(`autonomy level:   ${String(settings.autonomyLevel)}`);
+} finally {
+  await session.close();
+}

package/examples/node/interrupt-session.ts

@@ -0,0 +1,55 @@
+/**
+ * Interrupt a running turn.
+ *
+ * Calls `session.interrupt()` partway through streaming. Unlike
+ * abort-session-stream.ts, this stops the turn server-side and leaves the
+ * session usable for another prompt.
+ *
+ * Usage:
+ *   npx tsx examples/node/interrupt-session.ts
+ */
+
+import {
+  type DroidResultMessage,
+  createSession,
+  DroidMessageType,
+} from '@factory/droid-sdk/node';
+
+const session = await createSession();
+let deltaCount = 0;
+let result: DroidResultMessage | undefined;
+
+try {
+  for await (const msg of session.stream('Write a long history of computing.', {
+    includePartialMessages: true,
+  })) {
+    if (msg.type === DroidMessageType.Result) {
+      result = msg;
+      if (!msg.success && !msg.interrupted) {
+        throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+      }
+    }
+
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      process.stdout.write(msg.text);
+      deltaCount++;
+
+      if (deltaCount === 5) {
+        await session.interrupt();
+      }
+    }
+  }
+
+  if (!result) {
+    throw new Error('The stream ended without a result.');
+  }
+  if (result.interrupted) {
+    console.log('\nTurn was interrupted.');
+  } else if (deltaCount >= 5) {
+    console.log('\nThe turn completed before the interrupt took effect.');
+  } else {
+    console.log('\nThe turn completed before an interrupt was requested.');
+  }
+} finally {
+  await session.close();
+}

package/examples/node/list-sessions.ts

@@ -0,0 +1,20 @@
+/**
+ * List saved sessions example.
+ *
+ * Reads the droid sessions stored on disk for the current project.
+ *
+ * Usage:
+ *   npx tsx examples/node/list-sessions.ts
+ */
+
+import { listSessions } from '@factory/droid-sdk/node';
+
+const sessions = await listSessions({ limit: 5 });
+
+if (sessions.length === 0) {
+  console.log('No sessions found for this project.');
+}
+
+for (const session of sessions) {
+  console.log(`${session.id}: ${session.title || '(untitled)'}`);
+}

package/examples/node/model-discovery.ts

@@ -0,0 +1,28 @@
+/**
+ * Node model discovery example.
+ *
+ * Lists the models available to the current account and organization.
+ *
+ * Usage:
+ *   FACTORY_API_KEY=... npx tsx examples/node/model-discovery.ts
+ */
+
+import { listModels } from '@factory/droid-sdk/node';
+
+const apiKey = process.env.FACTORY_API_KEY;
+if (!apiKey) {
+  throw new Error('Set FACTORY_API_KEY.');
+}
+
+const models = await listModels({ apiKey, 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(', ')}`
+  );
+}

package/examples/node/model-selection.ts

@@ -0,0 +1,35 @@
+/**
+ * Model selection example.
+ *
+ * Runs one turn with a configured model ID.
+ *
+ * Usage:
+ *   FACTORY_API_KEY=... npx tsx examples/node/model-selection.ts model-id
+ */
+
+import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
+
+const modelId = process.argv[2];
+if (!modelId) {
+  throw new Error('Pass a configured model ID.');
+}
+
+const session = await createSession({
+  cwd: process.cwd(),
+  modelId,
+});
+
+try {
+  for await (const message of session.stream('Summarize this repository.')) {
+    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/multi-turn-session.ts

@@ -0,0 +1,37 @@
+/**
+ * Multi-turn session example.
+ *
+ * Sends two prompts over one session so the second turn can build on the
+ * context established by the first.
+ *
+ * Usage:
+ *   npx tsx examples/node/multi-turn-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;
+    }
+    if (msg.type === DroidMessageType.Result && !msg.success) {
+      throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+    }
+  }
+  if (!text) throw new Error('The turn produced no assistant text.');
+  return text;
+}
+
+const session = await createSession();
+
+try {
+  console.log(await streamText(session, 'What is this project?'));
+  console.log(`\n${await streamText(session, 'What should I test first?')}`);
+} finally {
+  await session.close();
+}

package/examples/node/observability.ts

@@ -0,0 +1,75 @@
+/**
+ * Observability example.
+ *
+ * Passes a `DroidObservability` bundle (logger, metrics, tracing) to
+ * `createSession()`, then runs one turn so the sinks observe real traffic.
+ *
+ * Sinks only ever receive structured, privacy-safe values — never raw
+ * stdout/stderr or message content.
+ *
+ * Usage:
+ *   npx tsx examples/node/observability.ts
+ */
+
+import {
+  DroidMessageType,
+  createSession,
+  type DroidLogEvent,
+  type DroidMetricEvent,
+  type DroidObservability,
+  type DroidTraceContextCarrier,
+} from '@factory/droid-sdk/node';
+
+let logCount = 0;
+
+const observability: DroidObservability = {
+  logger: {
+    log(event: DroidLogEvent): void {
+      logCount++;
+      console.log(
+        `[log:${event.level}] ${event.name} — ${event.message}`,
+        event.attributes ?? {}
+      );
+    },
+  },
+  metrics: {
+    record(event: DroidMetricEvent): void {
+      console.log(
+        `[metric] ${event.name}=${event.value}${event.unit} (${event.kind})`,
+        event.attributes ?? {}
+      );
+    },
+  },
+  tracing: {
+    inject(carrier: DroidTraceContextCarrier): void {
+      // Populate the carrier from your tracer's active span. The SDK copies
+      // traceparent/tracestate into each request's `_meta`.
+      carrier.traceparent =
+        '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+      carrier.tracestate = 'factory=1';
+    },
+  },
+};
+
+const session = await createSession({ observability });
+
+const logCountBeforeTurn = logCount;
+let turnLogCount = 0;
+
+try {
+  for await (const msg of session.stream(
+    'Reply with the single word: ready.'
+  )) {
+    if (msg.type === DroidMessageType.Result && !msg.success) {
+      throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+    }
+  }
+  // Measure before close(), which emits another request log.
+  turnLogCount = logCount - logCountBeforeTurn;
+} finally {
+  await session.close();
+}
+
+if (turnLogCount === 0) {
+  throw new Error('Observability sinks saw no logged requests for the turn.');
+}

package/examples/node/partial-stream.ts

@@ -0,0 +1,56 @@
+/**
+ * Partial stream example.
+ *
+ * Prints assistant text as it arrives, tool progress, and cumulative session
+ * token updates.
+ *
+ * Usage:
+ *   npx tsx examples/node/partial-stream.ts
+ *   npx tsx examples/node/partial-stream.ts "Explain this repository."
+ */
+
+import { DroidMessageType, createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+try {
+  const prompt =
+    process.argv.slice(2).join(' ') || 'Explain this repository briefly.';
+  let sawSuccessfulResult = false;
+
+  for await (const event of session.stream(prompt, {
+    includePartialMessages: true,
+  })) {
+    switch (event.type) {
+      case DroidMessageType.AssistantTextDelta:
+        process.stdout.write(event.text);
+        break;
+
+      case DroidMessageType.ToolProgress:
+        console.log(`\n[tool progress] ${event.toolUseId}`);
+        break;
+
+      case DroidMessageType.TokenUsageUpdate:
+        console.log(
+          `\n[session tokens] ${event.inputTokens} in, ${event.outputTokens} out`
+        );
+        break;
+
+      case DroidMessageType.Result:
+        if (!event.success) {
+          throw new Error(
+            event.error?.message ?? `Turn ended: ${event.subtype}`
+          );
+        }
+        sawSuccessfulResult = true;
+        console.log(`\n[result] ${event.subtype}`);
+        break;
+    }
+  }
+
+  if (!sawSuccessfulResult) {
+    throw new Error('The stream ended without a successful result.');
+  }
+} finally {
+  await session.close();
+}