@factory/droid-sdk 0.1.3 → 0.2.0

package/docs/examples/init-metadata.md

@@ -0,0 +1,79 @@
+# Example: initialization metadata
+
+Use this when you need the raw initialization payload, early session IDs, or model/settings metadata.
+
+## What this example shows
+
+- reading `query().sessionId` and `query().initResult`
+- waiting for `query().initialized`
+- reading `session.initResult` from `createSession()` and `resumeSession()`
+
+## Key snippet: inspect a query before and after initialization
+
+```ts
+const stream = query({
+  prompt: 'Reply with "ready" and nothing else.',
+  cwd: process.cwd(),
+});
+
+console.log(stream.sessionId);
+console.log(stream.initResult);
+
+const initialized = await stream.initialized;
+console.log(initialized.sessionId);
+console.log(initialized.settings.modelId);
+```
+
+Before initialization completes, `sessionId` and `initResult` are `null`.
+
+## Key snippet: read metadata from sessions
+
+```ts
+const session = await createSession({ cwd: process.cwd() });
+const resumed = await resumeSession(session.sessionId, { cwd: process.cwd() });
+
+console.log(session.initResult.settings.modelId);
+console.log(resumed.initResult.cwd);
+```
+
+## Full script
+
+```ts
+import { createSession, query, resumeSession } from '@factory/droid-sdk';
+
+async function main(): Promise<void> {
+  const stream = query({
+    prompt: 'Reply with "ready" and nothing else.',
+    cwd: process.cwd(),
+  });
+
+  console.log(stream.sessionId);
+  console.log(stream.initResult);
+
+  const initialized = await stream.initialized;
+  console.log(initialized.sessionId);
+  console.log(initialized.settings.modelId);
+
+  stream.abort();
+
+  const session = await createSession({ cwd: process.cwd() });
+  let resumed: Awaited<ReturnType<typeof resumeSession>> | null = null;
+
+  try {
+    resumed = await resumeSession(session.sessionId, {
+      cwd: process.cwd(),
+    });
+
+    console.log(session.initResult.settings.modelId);
+    console.log(resumed.initResult.cwd);
+  } finally {
+    await resumed?.close();
+    await session.close();
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```

package/docs/examples/list-sessions.md

@@ -0,0 +1,64 @@
+# Example: list saved sessions
+
+Use `listSessions()` when you need recent Droid session history without launching a subprocess.
+
+## What this example shows
+
+- listing recent sessions for the current project
+- listing recent sessions across all projects
+- formatting returned `SessionMetadata`
+
+## Key snippet: project-scoped listing
+
+```ts
+const currentProject = await listSessions({ numSessions: 10 });
+```
+
+## Key snippet: cross-project listing
+
+```ts
+const allSessions = await listSessions({
+  fetchOutsideCWD: true,
+  numSessions: 5,
+});
+```
+
+This helper reads local session files directly and returns `SessionMetadata[]`.
+
+## Full script
+
+```ts
+import { listSessions } from '@factory/droid-sdk';
+
+function formatDate(date: Date): string {
+  return date.toISOString().replace('T', ' ').slice(0, 19);
+}
+
+async function main(): Promise<void> {
+  const currentProject = await listSessions({ numSessions: 10 });
+
+  for (const session of currentProject) {
+    const title = session.sessionTitle ?? session.title ?? '(untitled)';
+    console.log(
+      `[${session.id.slice(0, 8)}] ${formatDate(session.modifiedTime)} ${session.messageCount} msgs — ${title}`
+    );
+  }
+
+  const allSessions = await listSessions({
+    fetchOutsideCWD: true,
+    numSessions: 5,
+  });
+
+  for (const session of allSessions) {
+    const title = session.sessionTitle ?? session.title ?? '(untitled)';
+    console.log(
+      `[${session.id.slice(0, 8)}] ${formatDate(session.modifiedTime)} — ${title}`
+    );
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```

package/docs/examples/multi-turn-session.md

@@ -0,0 +1,77 @@
+# Example: multi-turn session
+
+Use `createSession()` when you want conversation state to persist across turns.
+
+## What this example shows
+
+- creating a persistent session
+- streaming one turn with `session.stream()`
+- collecting a later turn with `session.send()`
+- closing the session cleanly
+
+## Key snippet: create the session
+
+```ts
+const session = await createSession({ cwd: process.cwd() });
+```
+
+Create the session once and reuse it across prompts.
+
+## Key snippet: stream a turn
+
+```ts
+import { DroidMessageType } from '@factory/droid-sdk';
+
+for await (const msg of session.stream(
+  'List the TypeScript files in this project'
+)) {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
+    process.stdout.write(msg.text);
+  }
+}
+```
+
+Use `stream()` when you want incremental output.
+
+## Key snippet: collect a full response
+
+```ts
+const result = await session.send('Summarize the project in one sentence');
+console.log(result.text);
+```
+
+Use `send()` when you want the SDK to aggregate the turn for you.
+
+## Full script
+
+```ts
+import { createSession, DroidMessageType } from '@factory/droid-sdk';
+
+async function main(): Promise<void> {
+  const session = await createSession({ cwd: process.cwd() });
+
+  console.log(`Session created: ${session.sessionId}\n`);
+
+  try {
+    for await (const msg of session.stream(
+      'List the TypeScript files in this project'
+    )) {
+      if (msg.type === DroidMessageType.AssistantTextDelta) {
+        process.stdout.write(msg.text);
+      }
+    }
+
+    console.log('\n');
+
+    const result = await session.send('Summarize the project in one sentence');
+    console.log(result.text);
+  } finally {
+    await session.close();
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```

package/docs/examples/one-shot-query.md

@@ -0,0 +1,73 @@
+# Example: one-shot query
+
+Use this when you want a single prompt and want to stream output as it arrives.
+
+## What this example shows
+
+- starting a one-shot request with `query()`
+- streaming assistant text incrementally
+- observing tool activity and turn completion
+
+## Key snippet: create the stream
+
+```ts
+const stream = query({
+  prompt: 'List all TypeScript files in this project',
+  cwd: process.cwd(),
+});
+```
+
+- `prompt` is the first user message
+- `cwd` is the directory Droid should operate in
+
+## Key snippet: consume streamed messages
+
+```ts
+import { DroidMessageType } from '@factory/droid-sdk';
+
+for await (const msg of stream) {
+  if (msg.type === DroidMessageType.AssistantTextDelta) {
+    process.stdout.write(msg.text);
+  }
+}
+```
+
+- `assistant_text_delta` gives you streaming text output
+- you can also handle `tool_use`, `tool_result`, and `turn_complete`
+
+## Full script
+
+```ts
+import { DroidMessageType, query } from '@factory/droid-sdk';
+
+async function main(): Promise<void> {
+  const prompt = process.argv[2] ?? 'What files are in the current directory?';
+
+  const stream = query({
+    prompt,
+    cwd: process.cwd(),
+  });
+
+  for await (const msg of stream) {
+    switch (msg.type) {
+      case DroidMessageType.AssistantTextDelta:
+        process.stdout.write(msg.text);
+        break;
+      case DroidMessageType.ToolUse:
+        console.log(`\n[Tool] ${msg.toolName}`);
+        break;
+      case DroidMessageType.ToolResult:
+        console.log(`[Tool Result] ${msg.isError ? 'Error' : 'OK'}`);
+        break;
+      case DroidMessageType.TurnComplete:
+        console.log('\n\n--- Turn complete ---');
+        break;
+    }
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```

package/docs/examples/permission-handler.md

@@ -0,0 +1,102 @@
+# Example: permission handler
+
+Use a `permissionHandler` when your app needs to inspect or approve tool calls.
+
+## What this example shows
+
+- receiving tool confirmation requests
+- inspecting `params.toolUses`
+- approving each request with `ToolConfirmationOutcome.ProceedOnce`
+
+## Key snippet: define the handler
+
+```ts
+function permissionHandler(
+  allowedFilePath: string,
+  params: RequestPermissionRequestParams
+): ToolConfirmationOutcome {
+  const onlyAllowedCreate = params.toolUses.every(
+    (item) =>
+      item.details.type === ToolConfirmationType.Create &&
+      item.details.filePath === allowedFilePath
+  );
+
+  return onlyAllowedCreate
+    ? ToolConfirmationOutcome.ProceedOnce
+    : ToolConfirmationOutcome.Cancel;
+}
+```
+
+- `params.toolUses` describes the pending tool calls
+- `ProceedOnce` approves the current request only
+
+## Key snippet: pass the handler to `query()`
+
+```ts
+const stream = query({
+  prompt: `Create a file called ${outputPath} with the text 'Hello, World!'`,
+  cwd: process.cwd(),
+  permissionHandler: (params) => permissionHandler(outputPath, params),
+});
+```
+
+## Full script
+
+```ts
+import {
+  DroidMessageType,
+  query,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+  type RequestPermissionRequestParams,
+} from '@factory/droid-sdk';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+function permissionHandler(
+  allowedFilePath: string,
+  params: RequestPermissionRequestParams
+): ToolConfirmationOutcome {
+  for (const item of params.toolUses) {
+    console.log(`\n[Permission] Tool: ${item.toolUse.name}`);
+    console.log(`Type: ${item.confirmationType}`);
+  }
+
+  const onlyAllowedCreate = params.toolUses.every(
+    (item) =>
+      item.details.type === ToolConfirmationType.Create &&
+      item.details.filePath === allowedFilePath
+  );
+
+  return onlyAllowedCreate
+    ? ToolConfirmationOutcome.ProceedOnce
+    : ToolConfirmationOutcome.Cancel;
+}
+
+async function main(): Promise<void> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-permission-'));
+  const outputPath = join(tempDir, 'hello.txt');
+
+  try {
+    const stream = query({
+      prompt: `Create a file called ${outputPath} with the text 'Hello, World!'`,
+      cwd: process.cwd(),
+      permissionHandler: (params) => permissionHandler(outputPath, params),
+    });
+
+    for await (const msg of stream) {
+      if (msg.type === DroidMessageType.AssistantTextDelta) {
+        process.stdout.write(msg.text);
+      }
+    }
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```

package/docs/examples/run.md

@@ -0,0 +1,52 @@
+# Example: one-shot run
+
+Use this when you want a single prompt and only need the final aggregated
+result.
+
+## What this example shows
+
+- sending a one-shot request with `run()`
+- reading the final assistant text
+- inspecting collected messages and token usage
+
+## Key snippet
+
+```ts
+const result = await run('What files are in the current directory?', {
+  cwd: process.cwd(),
+});
+
+console.log(result.text);
+```
+
+`run()` creates a temporary session, sends the prompt, returns a
+`DroidResult`, and closes the session automatically.
+
+## Full script
+
+```ts
+import { run } from '@factory/droid-sdk';
+
+async function main(): Promise<void> {
+  const text = process.argv.slice(2).join(' ') || 'What is 2 + 2?';
+
+  const result = await run(text, {
+    cwd: process.cwd(),
+  });
+
+  console.log(result.text);
+  console.log(`Messages received: ${result.messages.length}`);
+
+  if (result.tokenUsage) {
+    console.log(
+      `Tokens — input: ${result.tokenUsage.inputTokens}, ` +
+        `output: ${result.tokenUsage.outputTokens}`
+    );
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```

package/docs/examples/spec-mode.md

@@ -0,0 +1,101 @@
+# Example: spec mode approval flow
+
+Use spec mode when you want Droid to propose a plan first and only implement after approval.
+
+## What this example shows
+
+- starting a query in `DroidInteractionMode.Spec`
+- detecting an `ExitSpecMode` confirmation request
+- choosing whether implementation stays in the same session or moves to a new one
+
+## Key snippet: start in spec mode
+
+```ts
+const stream = query({
+  prompt,
+  cwd: process.cwd(),
+  interactionMode: DroidInteractionMode.Spec,
+  specModeReasoningEffort: ReasoningEffort.High,
+  permissionHandler(params) {
+    return ToolConfirmationOutcome.ProceedOnce;
+  },
+});
+```
+
+## Key snippet: detect the spec approval request
+
+```ts
+const exitSpec = params.toolUses.find(
+  (t) => t.confirmationType === ToolConfirmationType.ExitSpecMode
+);
+```
+
+Choose the outcome you want:
+
+- `ToolConfirmationOutcome.ProceedOnce` keeps implementation in the same session
+- `ToolConfirmationOutcome.ProceedNewSessionHigh` hands implementation to a new session
+
+## Full script
+
+```ts
+import {
+  DroidMessageType,
+  DroidInteractionMode,
+  query,
+  ReasoningEffort,
+  ToolConfirmationOutcome,
+  ToolConfirmationType,
+} from '@factory/droid-sdk';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+async function main(): Promise<void> {
+  const tempDir = await mkdtemp(join(tmpdir(), 'droid-sdk-spec-'));
+  const outputPath = join(tempDir, 'hello-from-droid.txt');
+  const prompt =
+    `Plan how to create a small ${outputPath} file containing the text ` +
+    '"Hello from Droid". Keep the plan short and concrete.';
+
+  try {
+    const stream = query({
+      prompt,
+      cwd: process.cwd(),
+      interactionMode: DroidInteractionMode.Spec,
+      specModeReasoningEffort: ReasoningEffort.High,
+      permissionHandler(params) {
+        const exitSpec = params.toolUses.find(
+          (item) => item.details.type === ToolConfirmationType.ExitSpecMode
+        );
+
+        if (exitSpec) {
+          return ToolConfirmationOutcome.ProceedOnce;
+        }
+
+        const onlyAllowedCreate = params.toolUses.every(
+          (item) =>
+            item.details.type === ToolConfirmationType.Create &&
+            item.details.filePath === outputPath
+        );
+
+        return onlyAllowedCreate
+          ? ToolConfirmationOutcome.ProceedOnce
+          : ToolConfirmationOutcome.Cancel;
+      },
+    });
+
+    for await (const msg of stream) {
+      if (msg.type === DroidMessageType.AssistantTextDelta) {
+        process.stdout.write(msg.text);
+      }
+    }
+  } finally {
+    await rm(tempDir, { recursive: true, force: true });
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```

package/docs/examples/tool-controls.md

@@ -0,0 +1,90 @@
+# Example: tool controls
+
+Use this when you want to programmatically shape which built-in exec tools are available.
+
+## What this example shows
+
+- setting initial tool overrides
+- inspecting the current tool catalog with `listTools()`
+- updating tool overrides later with `updateSettings()`
+
+## Key snippet: set tool overrides at session creation
+
+```ts
+const session = await createSession({
+  cwd: process.cwd(),
+  enabledToolIds: ['Read', 'Glob', 'Grep'],
+  disabledToolIds: ['Execute'],
+});
+```
+
+## Key snippet: inspect tool state
+
+```ts
+const result = await session.listTools();
+console.log(result.tools);
+```
+
+## Key snippet: update tool state later
+
+```ts
+await session.updateSettings({
+  disabledToolIds: ['Read', 'Execute'],
+});
+```
+
+## Full script
+
+```ts
+import { createSession, type ExecToolInfo } from '@factory/droid-sdk';
+
+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 {
+    const initial = await session.listTools();
+    const initialRead = initial.tools.find((tool) => tool.llmId === 'Read');
+    const initialExecute = initial.tools.find(
+      (tool) => tool.llmId === 'Execute'
+    );
+
+    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'
+    );
+
+    printToolState('Read', updatedRead);
+    printToolState('Execute', updatedExecute);
+  } finally {
+    await session.close();
+  }
+}
+
+main().catch((err: unknown) => {
+  console.error('Error:', err);
+  process.exit(1);
+});
+```