@factory/droid-sdk 0.7.0 → 0.8.0

package/examples/node/interrupt-session.ts

@@ -9,28 +9,47 @@
  *   npx tsx examples/node/interrupt-session.ts
  */
 
-import { createSession, DroidMessageType } from '@factory/droid-sdk/node';
+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.AssistantTextDelta) {
-      continue;
+    if (msg.type === DroidMessageType.Result) {
+      result = msg;
+      if (!msg.success && !msg.interrupted) {
+        throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+      }
     }
 
-    process.stdout.write(msg.text);
-    deltaCount++;
+    if (msg.type === DroidMessageType.AssistantTextDelta) {
+      process.stdout.write(msg.text);
+      deltaCount++;
 
-    if (deltaCount === 5) {
-      await session.interrupt();
+      if (deltaCount === 5) {
+        await session.interrupt();
+      }
     }
   }
 
-  console.log('\nInterrupted turn.');
+  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/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

@@ -19,7 +19,11 @@ 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) throw new Error('The turn produced no assistant text.');
   return text;
 }
 

package/examples/node/observability.ts

@@ -2,14 +2,7 @@
  * 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.
+ * `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.
@@ -60,10 +53,6 @@ const observability: DroidObservability = {
 
 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;
 
@@ -71,13 +60,11 @@ try {
   for await (const msg of session.stream(
     'Reply with the single word: ready.'
   )) {
-    if (msg.type === DroidMessageType.Assistant) {
-      console.log(`[assistant] ${msg.text}`);
+    if (msg.type === DroidMessageType.Result && !msg.success) {
+      throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
     }
   }
-  // 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.
+  // Measure before close(), which emits another request log.
   turnLogCount = logCount - logCountBeforeTurn;
 } finally {
   await session.close();

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();
+}

package/examples/node/permission-handler.ts

@@ -25,19 +25,24 @@ try {
     `Create ${outputPath} with the text "Hello, World!"`,
     {
       autonomyLevel: AutonomyLevel.Off,
-      permissionHandler(params) {
+      permissionHandler({ toolUses, options }) {
         handledPermission = true;
         const onlyCreatesExpectedFile =
-          params.toolUses.length > 0 &&
-          params.toolUses.every(
+          toolUses.length > 0 &&
+          toolUses.every(
             (item) =>
               item.details.type === ToolConfirmationType.Create &&
               item.details.filePath === outputPath
           );
 
-        return onlyCreatesExpectedFile
+        const desired = onlyCreatesExpectedFile
           ? ToolConfirmationOutcome.ProceedOnce
           : ToolConfirmationOutcome.Cancel;
+
+        const offered = options.find((option) => option.value === desired);
+        if (!offered) throw new Error(`Outcome not offered: ${desired}`);
+
+        return desired;
       },
     }
   );

package/examples/node/rename-session.ts

@@ -9,14 +9,18 @@
  *   npx tsx examples/node/rename-session.ts
  */
 
-import { createSession } from '@factory/droid-sdk/node';
+import { DroidMessageType, 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.
+  for await (const message of session.stream('Reply with exactly: OK')) {
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
   }
 
   await session.rename({

package/examples/node/result-metadata.ts

@@ -29,6 +29,15 @@ if (result.error) {
 
 if (result.tokenUsage) {
   console.log(
-    `tokens:   ${result.tokenUsage.inputTokens} in, ${result.tokenUsage.outputTokens} out`
+    `turn tokens: ${result.tokenUsage.inputTokens} in, ${result.tokenUsage.outputTokens} out`
+  );
+  console.log(
+    `turn cache:  ${result.tokenUsage.cacheReadTokens} read, ${result.tokenUsage.cacheCreationTokens} created`
+  );
+}
+
+if (!result.success) {
+  throw new Error(
+    result.error?.message ?? `The turn failed (${result.subtype}).`
   );
 }

package/examples/node/resume-session.ts

@@ -0,0 +1,41 @@
+/**
+ * Resume session example.
+ *
+ * Loads a saved session and sends a follow-up prompt with its existing
+ * conversation, working directory, and settings.
+ *
+ * Usage:
+ *   npx tsx examples/node/resume-session.ts session-id
+ */
+
+import { DroidMessageType, resumeSession } from '@factory/droid-sdk/node';
+
+const sessionId = process.argv[2];
+if (!sessionId) {
+  throw new Error('Pass a session ID. Use listSessions() to find one.');
+}
+
+const session = await resumeSession(sessionId);
+
+try {
+  console.log(`cwd: ${String(session.cwd)}`);
+  console.log(`model: ${session.settings.modelId}`);
+
+  let assistantText = '';
+  for await (const message of session.stream(
+    'Continue from the last conversation.'
+  )) {
+    if (message.type === DroidMessageType.Assistant) {
+      assistantText += message.text;
+      console.log(message.text);
+    }
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
+  }
+  if (!assistantText) throw new Error('The turn produced no assistant text.');
+} finally {
+  await session.close();
+}

package/examples/node/rewind-session.ts

@@ -15,8 +15,9 @@ const session = await createSession();
 async function ask(
   activeSession: Awaited<ReturnType<typeof createSession>>,
   prompt: string
-): Promise<string> {
+): Promise<{ messageId: string; text: string }> {
   let messageId: string | undefined;
+  let text = '';
 
   for await (const message of activeSession.stream(prompt)) {
     if (
@@ -26,17 +27,24 @@ async function ask(
       messageId ??= message.message.id;
     }
     if (message.type === DroidMessageType.Assistant) {
+      text += message.text;
       console.log(message.text);
     }
+    if (message.type === DroidMessageType.Result && !message.success) {
+      throw new Error(
+        message.error?.message ?? `Turn ended: ${message.subtype}`
+      );
+    }
   }
 
   if (!messageId) throw new Error('The turn produced no user message ID.');
-  return messageId;
+  if (!text.trim()) throw new Error('The turn produced no assistant output.');
+  return { messageId, text };
 }
 
 try {
   await ask(session, 'Remember this phrase exactly: mango sunrise');
-  const secondTurn = await ask(
+  const { messageId: secondTurn } = await ask(
     session,
     'Now forget it and remember: cobalt harbor'
   );
@@ -56,13 +64,15 @@ try {
     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?');
+  try {
+    // `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 successor.close();
+    await ask(successor, 'What phrase did I ask you to remember?');
+  } finally {
+    await successor.close();
+  }
 } finally {
   // Closes the active source, or does nothing if it was retired.
   await session.close();

package/examples/node/run.ts

@@ -11,15 +11,22 @@
 
 import { run } from '@factory/droid-sdk/node';
 
-const { text, messages, tokenUsage } = await run(
-  process.argv.slice(2).join(' ') || 'What is 2 + 2?'
-);
+const result = await run(process.argv.slice(2).join(' ') || 'What is 2 + 2?');
 
-console.log(text);
-console.log(`\nmessages: ${messages.length}`);
+if (!result.success) {
+  throw new Error(
+    result.error?.message ?? `The turn failed (${result.subtype}).`
+  );
+}
+if (!result.text.trim()) {
+  throw new Error('The turn produced no assistant output.');
+}
+
+console.log(result.text);
+console.log(`\nmessages: ${result.messages.length}`);
 
-if (tokenUsage) {
+if (result.tokenUsage) {
   console.log(
-    `tokens: ${tokenUsage.inputTokens} in, ${tokenUsage.outputTokens} out`
+    `tokens: ${result.tokenUsage.inputTokens} in, ${result.tokenUsage.outputTokens} out`
   );
 }

package/examples/node/sdk-mcp-tool.ts

@@ -32,21 +32,23 @@ const sdkTools = createSdkMcpServer({
 
 const session = await createSession({
   mcpServers: [sdkTools],
-  // 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(
+  for await (const message of session.stream(
     'Use the favorite_number tool for Ada and tell me the answer.'
   )) {
-    if (msg.type === DroidMessageType.ToolCall) {
-      console.log(`[tool call] ${msg.name}`);
+    if (message.type === DroidMessageType.ToolCall) {
+      console.log(`[tool call] ${message.name}`);
     }
-    if (msg.type === DroidMessageType.Assistant) {
-      console.log(msg.text);
+    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 {

package/examples/node/session-settings.ts

@@ -1,18 +1,14 @@
 /**
  * Session settings example.
  *
- * Reads settings from a live session, updates them with `updateSettings()`,
- * and reads the updated values back.
+ * Reads settings from a live session, updates them, and changes between Auto
+ * and Spec modes.
  *
  * Usage:
  *   npx tsx examples/node/session-settings.ts
  */
 
-import {
-  AutonomyLevel,
-  DroidInteractionMode,
-  createSession,
-} from '@factory/droid-sdk/node';
+import { AutonomyLevel, createSession } from '@factory/droid-sdk/node';
 
 const session = await createSession({ autonomyLevel: AutonomyLevel.Low });
 
@@ -25,11 +21,15 @@ try {
   printSettings('created with');
 
   await session.updateSettings({
-    interactionMode: DroidInteractionMode.Spec,
     autonomyLevel: AutonomyLevel.High,
   });
-
   printSettings('updated to  ');
+
+  await session.enterSpecMode();
+  printSettings('entered Spec');
+
+  await session.exitSpecMode();
+  printSettings('exited Spec ');
 } finally {
   await session.close();
 }

package/examples/node/session-stream.ts

@@ -1,8 +1,8 @@
 /**
  * Session streaming example.
  *
- * Sends a prompt with `session.stream()` and handles each message type:
- * assistant text, tool calls, tool results, and the final result.
+ * Sends a prompt with `session.stream()` and handles every message type
+ * emitted by a default (non-partial) stream.
  *
  * Usage:
  *   npx tsx examples/node/session-stream.ts
@@ -22,6 +22,10 @@ try {
         process.stdout.write(msg.text);
         break;
 
+      case DroidMessageType.User:
+        console.log('\n[user message accepted]');
+        break;
+
       case DroidMessageType.ToolCall:
         console.log(`\n[tool] ${msg.name}`);
         break;
@@ -30,7 +34,18 @@ try {
         console.log(`[tool result] ${msg.isError ? 'error' : 'ok'}`);
         break;
 
+      case DroidMessageType.Hook:
+        console.log(`\n[hook] ${msg.hookId}: ${msg.status}`);
+        break;
+
+      case DroidMessageType.Error:
+        console.error(`\n[error] ${msg.message}`);
+        break;
+
       case DroidMessageType.Result:
+        if (!msg.success) {
+          throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+        }
         if (msg.tokenUsage) {
           console.log(
             `\n\ntokens: ${msg.tokenUsage.inputTokens} in, ${msg.tokenUsage.outputTokens} out`

package/examples/node/skills.ts

@@ -0,0 +1,24 @@
+/**
+ * Skills example.
+ *
+ * Lists the skills available to a Node session.
+ *
+ * Usage:
+ *   npx tsx examples/node/skills.ts
+ */
+
+import { createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession();
+
+try {
+  const { skills } = await session.listSkills();
+
+  for (const skill of skills) {
+    console.log(
+      `${skill.name}: ${skill.enabled === false ? 'disabled' : 'enabled'}`
+    );
+  }
+} finally {
+  await session.close();
+}

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

@@ -22,7 +22,9 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import {
+  type ClientPermissionHandler,
   DroidInteractionMode,
+  DroidMessageType,
   ReasoningEffort,
   SessionNotificationSchema,
   ToolConfirmationOutcome,
@@ -35,18 +37,40 @@ const outputPath = join(tempDir, 'hello.txt');
 
 let handoffSessionId: string | null = null;
 
+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
+    );
+
+  let outcome = ToolConfirmationOutcome.Cancel;
+  if (exitsSpecMode) {
+    outcome = ToolConfirmationOutcome.ProceedNewSessionHigh;
+  } else if (createsExpectedFile) {
+    outcome = ToolConfirmationOutcome.ProceedOnce;
+  }
+  if (!options.some((option) => option.value === outcome)) {
+    throw new Error(`Outcome not offered: ${outcome}`);
+  }
+  return outcome;
+};
+
 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;
-    },
+    permissionHandler: handlePermissionRequest,
   });
 
   // The typed message stream carries no per-message session id, and the
@@ -63,10 +87,14 @@ try {
   });
 
   try {
-    for await (const _msg of session.stream(
+    for await (const message of session.stream(
       `Plan then create ${outputPath} containing "Hello from Droid".`
     )) {
-      // Consume the stream until the handoff implementation finishes.
+      if (message.type === DroidMessageType.Result && !message.success) {
+        throw new Error(
+          message.error?.message ?? `Turn ended: ${message.subtype}`
+        );
+      }
     }
   } finally {
     unsubscribe();