@factory/droid-sdk 0.9.1 → 0.10.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/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/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.10.0",
   "private": false,
   "description": "TypeScript SDK for the Factory Droid CLI",
   "keywords": [
@@ -59,6 +59,7 @@
     "eventemitter3": "^5.0.1",
     "fast-deep-equal": "^3.1.3",
     "isows": "^1.0.7",
+    "libsodium-wrappers-sumo": "^0.8.4",
     "uuid": "^9.0.0",
     "ws": "^8.21.0",
     "zod": "^3.24.0"