@factory/droid-sdk 0.9.1 → 0.11.0

package/examples/node/custom-model-editing-disposable.ts

@@ -0,0 +1,171 @@
+/**
+ * Review the complete custom-model edit flow against the isolated daemon
+ * started by custom-model-editing-disposable.sh. No provider call is made.
+ *
+ * From the repository root:
+ *   bash packages/droid-sdk-ext/examples/node/custom-model-editing-disposable.sh
+ */
+import assert from 'node:assert/strict';
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { connectToDaemon } from '@factory/droid-sdk';
+
+const home = process.env.BYOK_REPRO_HOME;
+if (
+  !home ||
+  home !== process.env.HOME ||
+  home !== process.env.FACTORY_HOME_OVERRIDE ||
+  process.env.FACTORY_AIRGAP_ENABLED !== 'true' ||
+  !existsSync(join(home, '.byok-review-scratch'))
+) {
+  throw new Error('Run this example through its disposable daemon script.');
+}
+
+const url = process.env.DROID_DAEMON_URL;
+const apiKey = process.env.FACTORY_API_KEY;
+if (!url?.startsWith('ws://127.0.0.1:') || !apiKey) {
+  throw new Error('Expected the isolated loopback daemon and test auth key.');
+}
+
+const settingsPath = join(home, '.factory-dev', 'settings.json');
+if (existsSync(settingsPath)) {
+  throw new Error('Refusing to edit a pre-existing settings file.');
+}
+
+const model = 'review-synthetic-model';
+const byokKey = `review-${randomBytes(16).toString('hex')}`;
+
+function assertStored(displayName: string): void {
+  const raw: unknown = JSON.parse(readFileSync(settingsPath, 'utf8'));
+  assert.ok(raw && typeof raw === 'object' && 'customModels' in raw);
+  const models = raw.customModels;
+  assert.ok(Array.isArray(models) && models.length === 1);
+  const stored: unknown = models[0];
+  assert.ok(stored && typeof stored === 'object');
+  assert.ok(
+    'apiKey' in stored && stored.apiKey === byokKey,
+    'The synthetic BYOK key was not retained on disk.'
+  );
+  assert.ok(
+    'displayName' in stored && stored.displayName === displayName,
+    'The model name did not persist.'
+  );
+  assert.ok(
+    'useInRouter' in stored && stored.useInRouter === true,
+    'The JSON-authored router opt-in did not persist.'
+  );
+}
+
+function assertRpcError(error: unknown, code: number, reason?: string): void {
+  if (!(error instanceof Error && 'error' in error)) {
+    throw new Error('Expected a structured daemon RPC error.');
+  }
+  const rpcError = error.error;
+  if (!(rpcError && typeof rpcError === 'object' && 'code' in rpcError)) {
+    throw new Error('Expected a structured daemon RPC error.');
+  }
+  assert.ok(rpcError.code === code, 'Unexpected daemon RPC error code.');
+  if (reason !== undefined) {
+    assert.ok('data' in rpcError, 'Expected a structured conflict reason.');
+    const data = rpcError.data;
+    assert.ok(
+      data &&
+        typeof data === 'object' &&
+        'reason' in data &&
+        data.reason === reason,
+      'Unexpected daemon conflict reason.'
+    );
+  }
+}
+
+const droid = await connectToDaemon({ url, auth: { apiKey } });
+try {
+  const empty = await droid.customModels.listWithRevision();
+  assert.ok(empty.revision && empty.models.length === 0);
+
+  await droid.customModels.upsert({
+    model,
+    provider: 'anthropic',
+    expectedRevision: empty.revision,
+    configuration: {
+      model,
+      provider: 'anthropic',
+      baseUrl: 'https://example.invalid/anthropic',
+      displayName: 'Created',
+      apiKey: byokKey,
+      useInRouter: true,
+    },
+  });
+  assertStored('Created');
+  console.log('PASS: complete create persisted in the isolated settings file');
+
+  const opening = await droid.customModels.listWithRevision();
+  const row = opening.models[0];
+  assert.ok(opening.revision && row?.editableConfig);
+  assert.ok(row.isValid && row.hasApiKey);
+  assert.ok(!Object.hasOwn(row.editableConfig, 'apiKey'));
+  assert.ok(!JSON.stringify(opening).includes(byokKey));
+  assert.deepEqual(row.redactedSecrets, [['apiKey']]);
+  assert.ok(row.editableConfig.useInRouter === true);
+
+  await droid.customModels.upsert({
+    rawIndex: row.rawIndex,
+    expectedModel: row.model,
+    model: row.model,
+    provider: row.provider,
+    expectedRevision: opening.revision,
+    configuration: { ...row.editableConfig, displayName: 'Edited' },
+    preservedSecrets: row.redactedSecrets,
+  });
+  assertStored('Edited');
+  console.log('PASS: redacted edit retained the synthetic credential');
+
+  const current = await droid.customModels.listWithRevision();
+  assert.ok(current.revision && current.revision !== opening.revision);
+  assert.ok(current.models[0]?.editableConfig);
+
+  let staleRejected = false;
+  try {
+    await droid.customModels.upsert({
+      rawIndex: row.rawIndex,
+      expectedModel: row.model,
+      model: row.model,
+      provider: row.provider,
+      expectedRevision: opening.revision,
+      configuration: { ...row.editableConfig, displayName: 'Stale overwrite' },
+      preservedSecrets: row.redactedSecrets,
+    });
+  } catch (error) {
+    assertRpcError(error, -32006, 'stale_revision');
+    staleRejected = true;
+  }
+  assert.ok(staleRejected, 'The stale write unexpectedly succeeded.');
+  assertStored('Edited');
+  console.log('PASS: stale edit returned CONFLICT and changed nothing');
+
+  let invalidRejected = false;
+  try {
+    await droid.customModels.upsert({
+      rawIndex: row.rawIndex,
+      expectedModel: row.model,
+      model: row.model,
+      provider: row.provider,
+      expectedRevision: current.revision,
+      configuration: {
+        ...current.models[0].editableConfig,
+        unexpectedField: 'not supported',
+      },
+      preservedSecrets: current.models[0].redactedSecrets,
+    });
+  } catch (error) {
+    assertRpcError(error, -32602);
+    invalidRejected = true;
+  }
+  assert.ok(invalidRejected, 'The invalid edit unexpectedly succeeded.');
+  assertStored('Edited');
+  console.log('PASS: invalid complete edit returned INVALID_PARAMS');
+} finally {
+  droid.disconnect();
+}

package/examples/node/custom-model-editing.ts

@@ -0,0 +1,55 @@
+/**
+ * Read a custom-model edit snapshot, or explicitly rename one model.
+ *
+ * Set DROID_DAEMON_URL and FACTORY_API_KEY for an existing daemon.
+ * Read-only: npx tsx examples/node/custom-model-editing.ts
+ * Rename: npx tsx examples/node/custom-model-editing.ts <raw-index> <display-name>
+ */
+
+import { connectToDaemon } from '@factory/droid-sdk';
+
+const url = process.env.DROID_DAEMON_URL;
+const apiKey = process.env.FACTORY_API_KEY;
+if (!url || !apiKey) {
+  throw new Error('Set DROID_DAEMON_URL and FACTORY_API_KEY.');
+}
+
+const [rawIndexText, displayName] = process.argv.slice(2);
+const rawIndex = rawIndexText === undefined ? undefined : Number(rawIndexText);
+if (
+  rawIndex !== undefined &&
+  (!Number.isInteger(rawIndex) || rawIndex < 0 || displayName === undefined)
+) {
+  throw new Error(
+    'Pass a non-negative raw index and a display name to rename.'
+  );
+}
+
+const droid = await connectToDaemon({ url, auth: { apiKey } });
+try {
+  // list() remains the array-only display API. Editors need this snapshot.
+  const snapshot = await droid.customModels.listWithRevision();
+  console.log(`Found ${snapshot.models.length} personal custom models.`);
+  if (rawIndex !== undefined) {
+    const model = snapshot.models.find((entry) => entry.rawIndex === rawIndex);
+    if (!snapshot.revision || !model?.editableConfig) {
+      throw new Error(
+        'Model is missing or the daemon does not support full editing.'
+      );
+    }
+    await droid.customModels.upsert({
+      rawIndex: model.rawIndex,
+      expectedModel: model.model,
+      expectedRevision: snapshot.revision,
+      model: model.model,
+      provider: model.provider,
+      configuration: { ...model.editableConfig, displayName },
+      preservedSecrets: model.redactedSecrets,
+    });
+    console.log(
+      'Model renamed. Reload the snapshot before the next edit or delete.'
+    );
+  }
+} finally {
+  droid.disconnect();
+}

package/examples/node/hook-execution.ts

@@ -45,10 +45,11 @@ try {
   const session = await createSession({
     cwd: projectDir,
     permissionHandler({ toolUses, options }) {
+      const [toolUse] = toolUses;
       const approvesExpectedCommand =
         toolUses.length === 1 &&
-        toolUses[0].details.type === ToolConfirmationType.Execute &&
-        toolUses[0].details.fullCommand === expectedCommand;
+        toolUse?.details.type === ToolConfirmationType.Execute &&
+        toolUse.details.fullCommand === expectedCommand;
       const desired = approvesExpectedCommand
         ? ToolConfirmationOutcome.ProceedOnce
         : ToolConfirmationOutcome.Cancel;

package/examples/node/rest-api.ts

@@ -0,0 +1,55 @@
+/**
+ * Factory REST API example.
+ *
+ * Lists the Computers and remote sessions an API key can see, using the
+ * client generated from the public Factory API spec.
+ *
+ * These operations take `{ client }` from `createFactoryClient({ apiKey, baseUrl })`
+ * and resolve `{ data, error }`. The root `@factory/droid-sdk` REST helpers
+ * take `{ apiKey, baseUrl }` and resolve the response body. Several names
+ * exist on both with different contracts, so a file that imports both should
+ * alias the shared names or import this entry under a namespace. A root
+ * options object cannot be passed here: generated operations require a
+ * `client` created with `createFactoryClient`.
+ *
+ * Usage:
+ *   FACTORY_API_KEY=... npx tsx examples/node/rest-api.ts [baseUrl]
+ */
+
+import {
+  createFactoryClient,
+  listComputers,
+  listSessions,
+} from '@factory/droid-sdk/api';
+
+const apiKey = process.env.FACTORY_API_KEY;
+if (!apiKey) {
+  throw new Error('Set FACTORY_API_KEY.');
+}
+
+const client = createFactoryClient({
+  apiKey,
+  baseUrl: process.argv[2],
+});
+
+const computers = await listComputers({ client });
+if (computers.error !== undefined) {
+  throw new Error(
+    `Listing Computers failed: ${JSON.stringify(computers.error)}`
+  );
+}
+console.log(`Computers (${computers.data.computers.length}):`);
+for (const computer of computers.data.computers) {
+  console.log(`  ${computer.id}  ${computer.name}  ${computer.status ?? ''}`);
+}
+
+const sessions = await listSessions({ client, query: { limit: 5 } });
+if (sessions.error !== undefined) {
+  throw new Error(`Listing sessions failed: ${JSON.stringify(sessions.error)}`);
+}
+console.log(`Recent sessions (${sessions.data.sessions.length}):`);
+for (const session of sessions.data.sessions) {
+  console.log(
+    `  ${session.sessionId}  ${session.status}  ${session.messageCount} messages`
+  );
+}

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

@@ -1,8 +1,8 @@
 /**
  * SDK MCP tool example.
  *
- * Defines an in-process tool with `createSdkMcpServer` + `tool` and exposes it
- * to Droid, then asks Droid to call it.
+ * Defines an in-process read-only tool with `createSdkMcpServer` + `tool` and
+ * exposes it to Droid, then asks Droid to call it.
  *
  * Usage:
  *   npx tsx examples/node/sdk-mcp-tool.ts
@@ -25,7 +25,9 @@ const sdkTools = createSdkMcpServer({
       'favorite_number',
       'Returns a favorite number for a person',
       { name: z.string() },
-      ({ name }) => `${name}'s favorite number is 42.`
+      ({ name }) => `${name}'s favorite number is 42.`,
+      // Read-only tools run without a permission prompt.
+      { annotations: { readOnlyHint: true } }
     ),
   ],
 });

package/examples/node/start-workstream.ts

@@ -0,0 +1,76 @@
+/**
+ * Start a workstream on a running daemon and leave it running.
+ *
+ * The orchestrator plans the goal and runs agents in the daemon, which keeps
+ * the workstream going after this script exits. Without an `askUserHandler`,
+ * any question the orchestrator asks is declined (see ask-user-elicitation.ts).
+ * An agent's questions and permission prompts are answered only by a client
+ * that attaches that agent with handlers (`droid.sessions.resume(agentId, ...)`).
+ *
+ * Set DROID_DAEMON_URL and FACTORY_API_KEY for an existing daemon whose account
+ * has access to workstreams. Set WORKSTREAM_COMPUTER_ID to let agents also run
+ * on that computer instead of only on this daemon's machine.
+ * Usage: npx tsx examples/node/start-workstream.ts "<goal>" [cwd]
+ */
+
+import {
+  AutonomyLevel,
+  DroidMessageType,
+  ReasoningEffort,
+  WorkstreamMachineTargetKind,
+  connectToDaemon,
+} from '@factory/droid-sdk';
+
+const url = process.env.DROID_DAEMON_URL;
+const apiKey = process.env.FACTORY_API_KEY;
+const computerId = process.env.WORKSTREAM_COMPUTER_ID;
+if (!url || !apiKey) {
+  throw new Error('Set DROID_DAEMON_URL and FACTORY_API_KEY.');
+}
+
+const [goal, cwd = process.cwd()] = process.argv.slice(2);
+if (!goal) {
+  throw new Error('Pass the workstream goal as the first argument.');
+}
+
+const droid = await connectToDaemon({ url, auth: { apiKey } });
+try {
+  // Agents on another machine reach this daemon through its relay.
+  if (computerId) await droid.relay.start();
+  const orchestrator = await droid.unstable.workstreams.start({
+    cwd,
+    title: goal.slice(0, 80),
+    // Agents inherit the orchestrator's autonomy; below High they stop to ask.
+    autonomyLevel: AutonomyLevel.High,
+    agentReasoningEffort: ReasoningEffort.High,
+    ...(computerId
+      ? {
+          machines: [
+            {
+              label: 'remote',
+              target: {
+                kind: WorkstreamMachineTargetKind.Computer,
+                computerId,
+              },
+            },
+          ],
+          defaultMachineLabel: 'remote',
+        }
+      : {}),
+  });
+  console.log(`Workstream ${orchestrator.id} started.`);
+
+  for await (const msg of orchestrator.stream(goal)) {
+    if (msg.type === DroidMessageType.Assistant) {
+      process.stdout.write(msg.text);
+    } else if (msg.type === DroidMessageType.Result && !msg.success) {
+      throw new Error(msg.error?.message ?? `Turn ended: ${msg.subtype}`);
+    }
+  }
+
+  // Detach, not close: closing would end the workstream in the daemon.
+  await orchestrator.detach();
+  console.log(`\nWorkstream ${orchestrator.id} keeps running in the daemon.`);
+} finally {
+  droid.disconnect();
+}

package/examples/node/tool-controls.ts

@@ -1,7 +1,7 @@
 /**
  * Tool controls example.
  *
- * Disables tools at session creation, then inspects availability.
+ * Disables tools at session creation, then inspects availability and schemas.
  *
  * Usage:
  *   npx tsx examples/node/tool-controls.ts
@@ -14,12 +14,14 @@ const session = await createSession({
 });
 
 try {
-  const tools = await session.listTools();
+  const tools = await session.listTools({
+    includeSchemas: true,
+    toolIds: ['Read', 'Grep', 'Execute'],
+  });
 
   for (const tool of tools) {
-    if (['Read', 'Grep', 'Execute'].includes(tool.id)) {
-      console.log(`${tool.id}: ${String(tool.allowed)}`);
-    }
+    console.log(`${tool.id}: ${String(tool.allowed)}`);
+    console.log(JSON.stringify(tool.schemas, null, 2));
   }
 } finally {
   await session.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factory/droid-sdk",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "private": false,
   "description": "TypeScript SDK for the Factory Droid CLI",
   "keywords": [
@@ -35,6 +35,16 @@
         "types": "./dist/node.d.ts",
         "default": "./dist/node.js"
       }
+    },
+    "./api": {
+      "import": {
+        "types": "./dist/api.d.mts",
+        "default": "./dist/api.mjs"
+      },
+      "require": {
+        "types": "./dist/api.d.ts",
+        "default": "./dist/api.js"
+      }
     }
   },
   "browser": {
@@ -54,12 +64,13 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@opentelemetry/api": "^1.9.0",
     "eventemitter3": "^5.0.1",
     "fast-deep-equal": "^3.1.3",
     "isows": "^1.0.7",
-    "uuid": "^9.0.0",
+    "libsodium-wrappers-sumo": "^0.8.4",
+    "uuid": "^11.1.1",
     "ws": "^8.21.0",
     "zod": "^3.24.0"
   },