@factory/droid-sdk 0.2.0 → 0.4.0

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

@@ -1,73 +0,0 @@
-# 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

@@ -1,102 +0,0 @@
-# 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

@@ -1,52 +0,0 @@
-# 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

@@ -1,101 +0,0 @@
-# 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

@@ -1,90 +0,0 @@
-# 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);
-});
-```