@factory/droid-sdk 0.1.3 → 0.2.0

package/examples/structured-output.ts

@@ -0,0 +1,53 @@
+/**
+ * Structured output example.
+ *
+ * Runs a prompt with the actual Droid CLI and requests a JSON object
+ * matching the provided schema.
+ *
+ * Usage:
+ *   npx tsx examples/structured-output.ts
+ *   npx tsx examples/structured-output.ts "Return a TypeScript pioneer"
+ */
+
+import assert from 'node:assert/strict';
+
+import { OutputFormatType, run } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const prompt =
+    process.argv.slice(2).join(' ') ||
+    'Return exactly this person: name Ada Lovelace, language TypeScript.';
+
+  const outputFormat = {
+    type: OutputFormatType.JsonSchema,
+    schema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        language: { type: 'string' },
+      },
+      required: ['name', 'language'],
+    },
+  };
+
+  console.log(`Sending prompt: "${prompt}"\n`);
+
+  const result = await run(prompt, {
+    cwd: process.cwd(),
+    outputFormat,
+  });
+
+  assert.ok(result.structuredOutput, 'Expected structuredOutput to be set');
+  assert.equal(typeof result.structuredOutput['name'], 'string');
+  assert.equal(typeof result.structuredOutput['language'], 'string');
+
+  console.log('=== Structured output ===');
+  console.log(JSON.stringify(result.structuredOutput, null, 2));
+
+  console.log('\nStructured output example passed');
+}
+
+main().catch((error: unknown) => {
+  console.error('Structured output example failed:', error);
+  process.exit(1);
+});

package/examples/test-compact.ts

@@ -0,0 +1,60 @@
+/**
+ * Compact session example.
+ *
+ * Demonstrates `session.compactSession()` to summarize and compact
+ * session history. Creates a session, sends several messages to build
+ * up conversation history, then compacts and verifies newSessionId
+ * and removedCount.
+ *
+ * Usage:
+ *   npx tsx examples/test-compact.ts
+ */
+
+import { createSession, DroidMessageType } from '../src/index.js';
+
+async function main(): Promise<void> {
+  const session = await createSession({ cwd: process.cwd() });
+  try {
+    console.log(`Session created: ${session.sessionId}\n`);
+
+    const prompts = [
+      'Say "one" and nothing else',
+      'Say "two" and nothing else',
+      'Say "three" and nothing else',
+    ];
+
+    for (let i = 0; i < prompts.length; i++) {
+      console.log(`=== Turn ${i + 1} ===`);
+      console.log(`Prompt: "${prompts[i]}"\n`);
+
+      for await (const msg of session.stream(prompts[i])) {
+        if (msg.type === DroidMessageType.AssistantTextDelta) {
+          process.stdout.write(msg.text);
+        }
+        if (msg.type === DroidMessageType.TurnComplete) {
+          console.log('\n');
+        }
+      }
+    }
+
+    console.log('=== Compacting session ===');
+    const compactResult = await session.compactSession({});
+    console.log(`Original session: ${session.sessionId}`);
+    console.log(`New session:      ${compactResult.newSessionId}`);
+    console.log(`Removed messages: ${compactResult.removedCount}`);
+
+    if (compactResult.newSessionId && compactResult.removedCount > 0) {
+      console.log('\nCompaction succeeded.');
+    } else {
+      console.log('\nCompaction returned unexpected results.');
+    }
+  } finally {
+    await session.close();
+    console.log('Session closed.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/examples/test-rewind.ts

@@ -0,0 +1,155 @@
+/**
+ * Rewind example (getRewindInfo + executeRewind).
+ *
+ * Demonstrates the low-level DroidClient API for rewind operations.
+ * Uses explicit user message IDs so they can be referenced as rewind
+ * targets — the snapshot system uses user message IDs as boundary
+ * markers.
+ *
+ * Usage:
+ *   npx tsx examples/test-rewind.ts
+ */
+
+import crypto from 'node:crypto';
+
+import {
+  DroidClient,
+  ProcessTransport,
+  AutonomyLevel,
+  DroidWorkingState,
+  SessionNotificationType,
+  ToolConfirmationOutcome,
+} from '../src/index.js';
+
+function uuid(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Send a user message with an explicit messageId and wait for the
+ * agent turn to complete by observing working-state notifications.
+ */
+async function sendAndWait(
+  client: DroidClient,
+  text: string,
+  messageId: string
+): Promise<void> {
+  return new Promise<void>((resolve) => {
+    let wasActive = false;
+
+    const unsub = client.onNotification((notification) => {
+      const params = notification['params'] as
+        | Record<string, unknown>
+        | undefined;
+      const inner = params?.['notification'] as
+        | Record<string, unknown>
+        | undefined;
+      if (!inner) return;
+
+      if (inner['type'] === SessionNotificationType.ASSISTANT_TEXT_DELTA) {
+        const delta = inner['textDelta'] as string | undefined;
+        if (delta) process.stdout.write(delta);
+      }
+
+      if (
+        inner['type'] === SessionNotificationType.DROID_WORKING_STATE_CHANGED
+      ) {
+        const newState = inner['newState'] as string;
+        if (newState !== DroidWorkingState.Idle) {
+          wasActive = true;
+        }
+        if (newState === DroidWorkingState.Idle && wasActive) {
+          unsub();
+          resolve();
+        }
+      }
+    });
+
+    void client.addUserMessage({ text, messageId });
+  });
+}
+
+async function main(): Promise<void> {
+  console.log('=== Creating session ===');
+  const transport = new ProcessTransport({ cwd: process.cwd() });
+  await transport.connect();
+  const client = new DroidClient({ transport });
+
+  const initResult = await client.initializeSession({
+    machineId: 'default',
+    cwd: process.cwd(),
+    autonomyLevel: AutonomyLevel.High,
+  });
+  console.log(`Session ID: ${initResult.sessionId}\n`);
+
+  client.setPermissionHandler(() => ToolConfirmationOutcome.ProceedOnce);
+
+  const userMsgId1 = uuid();
+  console.log(`=== Turn 1: "hello" (msgId: ${userMsgId1.slice(0, 12)}...) ===`);
+  await sendAndWait(client, 'Say "hello" and nothing else.', userMsgId1);
+  console.log('\n');
+
+  const userMsgId2 = uuid();
+  console.log(
+    `=== Turn 2: create file (msgId: ${userMsgId2.slice(0, 12)}...) ===`
+  );
+  await sendAndWait(
+    client,
+    'Create a file called /tmp/droid-sdk-rewind-test.txt with the content ' +
+      '"rewind test data". Do not explain, just create it.',
+    userMsgId2
+  );
+  console.log('\n');
+
+  console.log(`=== getRewindInfo (msgId: ${userMsgId2.slice(0, 12)}...) ===`);
+  try {
+    const rewindInfo = await client.getRewindInfo({ messageId: userMsgId2 });
+    console.log(
+      `  Available files to restore: ${rewindInfo.availableFiles.length}`
+    );
+    for (const f of rewindInfo.availableFiles) {
+      console.log(`    - ${f.filePath} (${f.size} bytes)`);
+    }
+    console.log(`  Created files to delete: ${rewindInfo.createdFiles.length}`);
+    for (const f of rewindInfo.createdFiles) {
+      console.log(`    - ${f.filePath}`);
+    }
+    console.log(`  Evicted files: ${rewindInfo.evictedFiles.length}`);
+  } catch (err) {
+    console.log(
+      `  Error (expected — server does not yet support this): ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  console.log();
+
+  console.log(
+    `=== executeRewind (to msgId: ${userMsgId1.slice(0, 12)}...) ===`
+  );
+  try {
+    const rewindResult = await client.executeRewind({
+      messageId: userMsgId1,
+      filesToRestore: [],
+      filesToDelete: [],
+      forkTitle: 'Rewind to first hello',
+    });
+    console.log(`  New session ID: ${rewindResult.newSessionId}`);
+    console.log(`  Restored: ${rewindResult.restoredCount}`);
+    console.log(`  Deleted: ${rewindResult.deletedCount}`);
+    console.log(`  Failed restores: ${rewindResult.failedRestoreCount}`);
+    console.log(`  Failed deletes: ${rewindResult.failedDeleteCount}`);
+  } catch (err) {
+    console.log(
+      `  Error (expected — server does not yet support this): ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  console.log();
+
+  console.log('=== Closing ===');
+  await client.close();
+  console.log('Done.');
+}
+
+main().catch((err: unknown) => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});

package/examples/tool-controls.ts

@@ -0,0 +1,69 @@
+/**
+ * Tool controls example.
+ *
+ * Demonstrates:
+ * - configuring enabled and disabled tool IDs at session creation
+ * - inspecting the current tool catalog with `listTools()`
+ * - updating tool overrides with `updateSettings()`
+ *
+ * Usage:
+ *   npx tsx examples/tool-controls.ts
+ */
+
+import { createSession } from '../src/index.js';
+import type { ExecToolInfo } from '../src/index.js';
+
+function printToolState(label: string, tool: ExecToolInfo | undefined): void {
+  if (!tool) {
+    console.log(`${label}: not present in tool catalog`);
+    return;
+  }
+
+  console.log(
+    `${label}: defaultAllowed=${tool.defaultAllowed}, currentlyAllowed=${tool.currentlyAllowed}`
+  );
+}
+
+async function main(): Promise<void> {
+  const session = await createSession({
+    cwd: process.cwd(),
+    enabledToolIds: ['Read', 'Glob', 'Grep'],
+    disabledToolIds: ['Execute'],
+  });
+
+  try {
+    console.log(`Session created: ${session.sessionId}\n`);
+
+    const initial = await session.listTools();
+    const initialRead = initial.tools.find((tool) => tool.llmId === 'Read');
+    const initialExecute = initial.tools.find(
+      (tool) => tool.llmId === 'Execute'
+    );
+
+    console.log('=== Initial tool state ===');
+    printToolState('Read', initialRead);
+    printToolState('Execute', initialExecute);
+
+    await session.updateSettings({
+      disabledToolIds: ['Read', 'Execute'],
+    });
+
+    const updated = await session.listTools();
+    const updatedRead = updated.tools.find((tool) => tool.llmId === 'Read');
+    const updatedExecute = updated.tools.find(
+      (tool) => tool.llmId === 'Execute'
+    );
+
+    console.log('\n=== Updated tool state ===');
+    printToolState('Read', updatedRead);
+    printToolState('Execute', updatedExecute);
+  } finally {
+    await session.close();
+    console.log('\nSession closed.');
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@factory/droid-sdk",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "private": false,
   "description": "TypeScript SDK for the Factory Droid CLI",
-  "keywords": ["factory", "droid", "cli", "ai", "agent", "sdk"],
+  "keywords": [
+    "factory",
+    "droid",
+    "cli",
+    "ai",
+    "agent",
+    "sdk"
+  ],
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -23,16 +30,22 @@
   },
   "files": [
     "dist",
+    "docs",
+    "examples",
     "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/",
-    "fix": "eslint --fix src/"
+    "lint": "eslint src/ tests/ examples/",
+    "fix": "eslint --fix src/ tests/ examples/",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "repository": {
     "type": "git",
@@ -42,6 +55,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "uuid": "^11.1.0",
     "zod": "^3.24.0"
   },
@@ -51,9 +65,17 @@
     "@types/uuid": "^10.0.0",
     "@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"
   }
 }