@factory/droid-sdk 0.6.0 → 0.7.0

package/examples/node/image-attachment.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 { text } = 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',
+      },
+    ],
+  }
+);
+
+console.log(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/{interrupt-session.ts → node/interrupt-session.ts}

@@ -1,16 +1,17 @@
 /**
  * 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/interrupt-session.ts
+ *   npx tsx examples/node/interrupt-session.ts
  */
 
-import { createSession, DroidMessageType } from '@factory/droid-sdk';
+import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
 
-const session = await createSession({
-  apiKey: process.env.FACTORY_API_KEY!,
-  cwd: process.cwd(),
-});
+const session = await createSession();
 let deltaCount = 0;
 
 try {

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/multi-turn-session.ts

@@ -0,0 +1,33 @@
+/**
+ * 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;
+    }
+  }
+  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,88 @@
+/**
+ * Observability example.
+ *
+ * Passes a `DroidObservability` bundle (logger, metrics, tracing) to
+ * `createSession()`, which wires it into both the spawned droid process
+ * transport and the client. Spawning the process records a spawn-latency
+ * metric and a log; every outgoing request asks the tracing sink to inject
+ * trace context into the request's `_meta`.
+ *
+ * The example then runs one real conversational turn through
+ * `session.stream()` so the sinks observe request/response traffic from actual
+ * work rather than only process startup.
+ *
+ * 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 });
+
+// Snapshot before the turn. Spawning the process alone emits a log, so a
+// total-count assertion would pass having observed only startup. Logs are also
+// the only turn-scoped signal here: the SDK's sole metric is spawn latency,
+// recorded before the turn begins, so metrics cannot witness turn traffic.
+const logCountBeforeTurn = logCount;
+let turnLogCount = 0;
+
+try {
+  for await (const msg of session.stream(
+    'Reply with the single word: ready.'
+  )) {
+    if (msg.type === DroidMessageType.Assistant) {
+      console.log(`[assistant] ${msg.text}`);
+    }
+  }
+  // Measure before teardown: `session.close()` sends a `close_session` request,
+  // which is itself logged, so counting after the `finally` would always find
+  // at least one log regardless of what the turn did.
+  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/permission-handler.ts

@@ -0,0 +1,55 @@
+/**
+ * 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(params) {
+        handledPermission = true;
+        const onlyCreatesExpectedFile =
+          params.toolUses.length > 0 &&
+          params.toolUses.every(
+            (item) =>
+              item.details.type === ToolConfirmationType.Create &&
+              item.details.filePath === outputPath
+          );
+
+        return onlyCreatesExpectedFile
+          ? ToolConfirmationOutcome.ProceedOnce
+          : ToolConfirmationOutcome.Cancel;
+      },
+    }
+  );
+
+  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,29 @@
+/**
+ * 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 { 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 _msg of session.stream('Reply with exactly: OK')) {
+    // Consume the stream so the turn completes.
+  }
+
+  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,34 @@
+/**
+ * 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(
+    `tokens:   ${result.tokenUsage.inputTokens} in, ${result.tokenUsage.outputTokens} out`
+  );
+}

package/examples/node/rewind-session.ts

@@ -0,0 +1,69 @@
+/**
+ * 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<string> {
+  let messageId: string | undefined;
+
+  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) {
+      console.log(message.text);
+    }
+  }
+
+  if (!messageId) throw new Error('The turn produced no user message ID.');
+  return messageId;
+}
+
+try {
+  await ask(session, 'Remember this phrase exactly: mango sunrise');
+  const 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',
+  });
+
+  // `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?');
+
+  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,25 @@
+/**
+ * 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 { text, messages, tokenUsage } = await run(
+  process.argv.slice(2).join(' ') || 'What is 2 + 2?'
+);
+
+console.log(text);
+console.log(`\nmessages: ${messages.length}`);
+
+if (tokenUsage) {
+  console.log(
+    `tokens: ${tokenUsage.inputTokens} in, ${tokenUsage.outputTokens} out`
+  );
+}

package/examples/{sdk-mcp-tool.ts → node/sdk-mcp-tool.ts}

@@ -1,13 +1,22 @@
+/**
+ * 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';
-import { z } from 'zod';
-
-const execPath = process.env['DROID_EXEC_PATH'] ?? 'droid-dev';
+} from '@factory/droid-sdk/node';
 
 const sdkTools = createSdkMcpServer({
   name: 'sdk-tools',
@@ -22,23 +31,24 @@ const sdkTools = createSdkMcpServer({
 });
 
 const session = await createSession({
-  apiKey: process.env.FACTORY_API_KEY!,
-  execPath,
   mcpServers: [sdkTools],
-  cwd: process.cwd(),
+  // Not the focus of this example, but required: without a handler every
+  // permission request resolves to Cancel, so a tool needing approval would
+  // never run.
   permissionHandler: () => ToolConfirmationOutcome.ProceedOnce,
 });
 
 try {
   for await (const msg of session.stream(
-    'Use the favorite_number tool for Ada and tell me the answer.',
-    { includePartialMessages: true }
+    'Use the favorite_number tool for Ada and tell me the answer.'
   )) {
-    if (msg.type === DroidMessageType.AssistantTextDelta) {
-      process.stdout.write(msg.text);
+    if (msg.type === DroidMessageType.ToolCall) {
+      console.log(`[tool call] ${msg.name}`);
+    }
+    if (msg.type === DroidMessageType.Assistant) {
+      console.log(msg.text);
     }
   }
-  console.log();
 } 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 with `updateSettings()`,
+ * and reads the updated values back.
+ *
+ * Usage:
+ *   npx tsx examples/node/session-settings.ts
+ */
+
+import {
+  AutonomyLevel,
+  DroidInteractionMode,
+  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({
+    interactionMode: DroidInteractionMode.Spec,
+    autonomyLevel: AutonomyLevel.High,
+  });
+
+  printSettings('updated to  ');
+} finally {
+  await session.close();
+}

package/examples/node/session-stream.ts

@@ -0,0 +1,44 @@
+/**
+ * Session streaming example.
+ *
+ * Sends a prompt with `session.stream()` and handles each message type:
+ * assistant text, tool calls, tool results, and the final result.
+ *
+ * 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.ToolCall:
+        console.log(`\n[tool] ${msg.name}`);
+        break;
+
+      case DroidMessageType.ToolResult:
+        console.log(`[tool result] ${msg.isError ? 'error' : 'ok'}`);
+        break;
+
+      case DroidMessageType.Result:
+        if (msg.tokenUsage) {
+          console.log(
+            `\n\ntokens: ${msg.tokenUsage.inputTokens} in, ${msg.tokenUsage.outputTokens} out`
+          );
+        }
+        break;
+    }
+  }
+} finally {
+  await session.close();
+}

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

@@ -0,0 +1,92 @@
+/**
+ * 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 {
+  DroidInteractionMode,
+  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;
+
+try {
+  const session = await createSession({
+    interactionMode: DroidInteractionMode.Spec,
+    specModeReasoningEffort: ReasoningEffort.High,
+    permissionHandler(params) {
+      const canExitSpec = params.toolUses.some(
+        (item) => item.details.type === ToolConfirmationType.ExitSpecMode
+      );
+      return canExitSpec
+        ? ToolConfirmationOutcome.ProceedNewSessionHigh
+        : ToolConfirmationOutcome.ProceedOnce;
+    },
+  });
+
+  // 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 _msg of session.stream(
+      `Plan then create ${outputPath} containing "Hello from Droid".`
+    )) {
+      // Consume the stream until the handoff implementation finishes.
+    }
+  } 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.'
+  );
+}