@factory/droid-sdk 0.6.0 → 0.8.0

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

@@ -0,0 +1,119 @@
+/**
+ * Spec mode: approve and implement in the same session.
+ *
+ * Approving the spec with `ProceedOnce` keeps implementation in the session
+ * that planned it. The example prints its session id and reports that no
+ * handoff occurred, which is what distinguishes its output from
+ * spec-mode-new-session.ts.
+ *
+ * A handoff would announce itself on the notification envelope: `params.sessionId`
+ * on incoming notifications would stop 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-same-session.ts
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+  type ClientPermissionHandler,
+  DroidInteractionMode,
+  DroidMessageType,
+  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;
+
+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
+    );
+
+  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.Spec,
+    specModeReasoningEffort: ReasoningEffort.High,
+    permissionHandler: handlePermissionRequest,
+  });
+
+  // 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 message of session.stream(
+      `Plan then create ${outputPath} containing "Hello from Droid".`
+    )) {
+      if (message.type === DroidMessageType.Result && !message.success) {
+        throw new Error(
+          message.error?.message ?? `Turn ended: ${message.subtype}`
+        );
+      }
+    }
+  } 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 });
+}
+
+// A foreign session id is only a proxy for a handoff, so warn rather than
+// fail: it may mean `ProceedOnce` handed implementation off, or merely that
+// some unrelated session-scoped notification arrived during the run.
+if (handoffSessionId !== null) {
+  console.warn(
+    `Observed a notification scoped to a different session (${String(handoffSessionId)}). ` +
+      'That may mean implementation was handed off, or that unrelated ' +
+      'session-scoped activity occurred during this run.'
+  );
+}

package/examples/node/structured-output.ts

@@ -0,0 +1,96 @@
+/**
+ * Structured output example.
+ *
+ * Passes a JSON schema via `outputFormat` and reads the parsed object back
+ * from `result.structuredOutput`.
+ *
+ * Usage:
+ *   npx tsx examples/node/structured-output.ts
+ */
+
+import { OutputFormatType, run } from '@factory/droid-sdk/node';
+
+interface CodeReview {
+  summary: string;
+  findings: Array<{
+    line: number;
+    severity: 'low' | 'medium' | 'high';
+    message: string;
+  }>;
+}
+
+function isCodeReview(value: unknown): value is CodeReview {
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    !('summary' in value) ||
+    typeof value.summary !== 'string' ||
+    !('findings' in value) ||
+    !Array.isArray(value.findings)
+  ) {
+    return false;
+  }
+
+  return value.findings.every(
+    (finding) =>
+      finding !== null &&
+      typeof finding === 'object' &&
+      'line' in finding &&
+      typeof finding.line === 'number' &&
+      'severity' in finding &&
+      ['low', 'medium', 'high'].includes(String(finding.severity)) &&
+      'message' in finding &&
+      typeof finding.message === 'string'
+  );
+}
+
+const result = await run(
+  `Review this code for correctness issues:
+
+function getDisplayName(user) {
+  return user.profile.name.trim();
+}`,
+  {
+    outputFormat: {
+      type: OutputFormatType.JsonSchema,
+      schema: {
+        type: 'object',
+        properties: {
+          summary: { type: 'string' },
+          findings: {
+            type: 'array',
+            items: {
+              type: 'object',
+              properties: {
+                line: { type: 'number' },
+                severity: {
+                  type: 'string',
+                  enum: ['low', 'medium', 'high'],
+                },
+                message: { type: 'string' },
+              },
+              required: ['line', 'severity', 'message'],
+            },
+          },
+        },
+        required: ['summary', 'findings'],
+        additionalProperties: false,
+      },
+    },
+  }
+);
+
+if (!result.success) {
+  const detail =
+    result.structuredOutputError?.message ??
+    result.error?.message ??
+    'Unknown error';
+  throw new Error(`run() failed (${result.subtype}): ${detail}`);
+}
+
+// The SDK returns `unknown`; validate it before reading fields.
+if (!isCodeReview(result.structuredOutput)) {
+  throw new Error('run() returned an unexpected structured output shape.');
+}
+
+console.log(JSON.stringify(result.structuredOutput, null, 2));

package/examples/node/tool-controls.ts

@@ -0,0 +1,26 @@
+/**
+ * Tool controls example.
+ *
+ * Disables tools at session creation, then inspects availability.
+ *
+ * Usage:
+ *   npx tsx examples/node/tool-controls.ts
+ */
+
+import { createSession } from '@factory/droid-sdk/node';
+
+const session = await createSession({
+  disabledToolIds: ['Execute'],
+});
+
+try {
+  const tools = await session.listTools();
+
+  for (const tool of tools) {
+    if (['Read', 'Grep', 'Execute'].includes(tool.id)) {
+      console.log(`${tool.id}: ${String(tool.allowed)}`);
+    }
+  }
+} finally {
+  await session.close();
+}

package/examples/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@factory/droid-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "private": false,
   "description": "TypeScript SDK for the Factory Droid CLI",
   "keywords": [
@@ -12,32 +12,34 @@
     "sdk"
   ],
   "license": "Apache-2.0",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
       },
       "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
       }
     },
-    "./protocol": {
+    "./node": {
       "import": {
-        "types": "./dist/protocol/index.d.ts",
-        "default": "./dist/protocol/index.js"
+        "types": "./dist/node.d.mts",
+        "default": "./dist/node.mjs"
       },
       "require": {
-        "types": "./dist/protocol/index.d.cts",
-        "default": "./dist/protocol/index.cjs"
+        "types": "./dist/node.d.ts",
+        "default": "./dist/node.js"
       }
     }
   },
+  "browser": {
+    "ws": false
+  },
   "files": [
     "dist",
     "docs",
@@ -45,18 +47,6 @@
     "README.md",
     "LICENSE"
   ],
-  "scripts": {
-    "build": "tsup",
-    "prepack": "npm run build",
-    "typecheck": "tsc --noEmit",
-    "typecheck:examples": "tsc --noEmit -p tsconfig.examples.json",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
-    "lint": "eslint src/ tests/ examples/",
-    "fix": "eslint --fix src/ tests/ examples/",
-    "format": "prettier --write .",
-    "format:check": "prettier --check ."
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Factory-AI/droid-sdk-typescript.git"
@@ -66,26 +56,14 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "uuid": "^11.1.0",
+    "@opentelemetry/api": "^1.9.0",
+    "eventemitter3": "^5.0.1",
+    "fast-deep-equal": "^3.1.3",
+    "isows": "^1.0.7",
+    "uuid": "^9.0.0",
     "ws": "^8.21.0",
     "zod": "^3.24.0"
   },
-  "devDependencies": {
-    "@eslint/js": "^9.39.4",
-    "@types/node": "^22.15.0",
-    "@types/uuid": "^10.0.0",
-    "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "^3.1.0",
-    "eslint": "^9.24.0",
-    "eslint-import-resolver-typescript": "^4.4.4",
-    "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-unused-imports": "^4.4.1",
-    "prettier": "^3.8.1",
-    "tsup": "^8.4.0",
-    "typescript": "^5.8.0",
-    "typescript-eslint": "^8.57.2",
-    "vitest": "^3.1.0"
-  },
   "homepage": "https://github.com/Factory-AI/droid-sdk-typescript#readme",
   "bugs": {
     "url": "https://github.com/Factory-AI/droid-sdk-typescript/issues"