@bhargavvc/sdd-cc 1.30.1 → 1.42.3

package/sdk/src/session-runner.ts

@@ -0,0 +1,327 @@
+/**
+ * Session runner — orchestrates Agent SDK query() calls for plan execution.
+ *
+ * Takes a parsed plan, builds the executor prompt, configures query() options,
+ * processes the message stream, and extracts results into a typed PlanResult.
+ */
+
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import type { SDKMessage, SDKResultMessage, SDKResultSuccess, SDKResultError } from '@anthropic-ai/claude-agent-sdk';
+import type { ParsedPlan, PlanResult, SessionOptions, SessionUsage, SDDCostUpdateEvent, PhaseStepType } from './types.js';
+import { SDDEventType, PhaseType } from './types.js';
+import type { SDDConfig } from './config.js';
+import { buildExecutorPrompt, parseAgentTools, DEFAULT_ALLOWED_TOOLS } from './prompt-builder.js';
+import type { SDDEventStream, EventStreamContext } from './event-stream.js';
+import { getToolsForPhase } from './tool-scoping.js';
+import { detectRuntime } from './query/helpers.js';
+import { resolveRuntimeTierDefault } from './model-catalog.js';
+
+// ─── Model resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve model identifier from options or config profile.
+ *
+ * Priority: explicit model option > config model_profile > default.
+ *
+ * Runtime-aware (#2832): the profile -> Claude-id map only applies when the
+ * project is targeting the Claude runtime. For Codex, Gemini, OpenCode, etc.,
+ * forcing a Claude model id (e.g. 'claude-sonnet-4-6') silently routes the
+ * autonomous run through the Claude path, which is wrong for those runtimes.
+ * In those cases — and whenever `resolve_model_ids: "omit"` is set — leave
+ * `model` unset so the runtime falls back to its configured default.
+ */
+function resolveModel(options?: SessionOptions, config?: SDDConfig): string | undefined {
+  if (options?.model) return options.model;
+
+  // Honor the explicit "don't resolve model ids" config knob (#2652, #2832).
+  // Mirrors `query/config-query.ts` resolve_model_ids === 'omit' branch.
+  if ((config as Record<string, unknown> | undefined)?.resolve_model_ids === 'omit') {
+    return undefined;
+  }
+
+  // Profile -> Claude id map. Applies only on the Claude runtime.
+  // Use `detectRuntime` so `SDD_RUNTIME` env precedence is honored — a Codex
+  // run with a Claude-shaped config must NOT be silently routed to Claude.
+  const runtime = detectRuntime({
+    runtime: (config as Record<string, unknown> | undefined)?.runtime,
+  });
+  if (runtime !== 'claude') {
+    // Non-Claude runtimes: never inject a Claude id from the profile map.
+    return undefined;
+  }
+
+  if (config?.model_profile) {
+    const profile = String(config.model_profile).toLowerCase();
+    if (profile === 'inherit') return undefined;
+    const tier = profile === 'quality' ? 'opus'
+      : (profile === 'budget' || profile === 'speed') ? 'haiku'
+      : (profile === 'balanced' || profile === 'adaptive') ? 'sonnet'
+      : null;
+    if (!tier) return config.model_profile;
+    return resolveRuntimeTierDefault('claude', tier)?.model;
+  }
+
+  return undefined; // Let SDK use its default
+}
+
+// ─── Session runner ──────────────────────────────────────────────────────────
+
+/**
+ * Run a plan execution session via the Agent SDK query() function.
+ *
+ * Builds the executor prompt from the parsed plan, configures query() with
+ * appropriate permissions, tool restrictions, and budget limits, then iterates
+ * the message stream to extract the result.
+ *
+ * @param plan - Parsed plan structure
+ * @param config - SDD project configuration
+ * @param options - Session overrides (maxTurns, budget, model, etc.)
+ * @param agentDef - Raw agent definition content (optional, for tool/role extraction)
+ * @returns Typed PlanResult with cost, duration, success/error status
+ */
+export async function runPlanSession(
+  plan: ParsedPlan,
+  config: SDDConfig,
+  options?: SessionOptions,
+  agentDef?: string,
+  eventStream?: SDDEventStream,
+  streamContext?: EventStreamContext,
+  phaseDir?: string,
+): Promise<PlanResult> {
+  // Build the executor prompt
+  const executorPrompt = buildExecutorPrompt(plan, { agentDef, phaseDir });
+
+  // Resolve allowed tools — from agent definition or defaults
+  const allowedTools = options?.allowedTools ??
+    (agentDef ? parseAgentTools(agentDef) : DEFAULT_ALLOWED_TOOLS);
+
+  // Resolve model
+  const model = resolveModel(options, config);
+
+  // Configure query options
+  const maxTurns = options?.maxTurns ?? 50;
+  const maxBudgetUsd = options?.maxBudgetUsd ?? 5.0;
+  const cwd = options?.cwd ?? process.cwd();
+
+  const queryStream = query({
+    prompt: `Execute this plan:\n\n${plan.objective || 'Execute the plan tasks below.'}`,
+    options: {
+      systemPrompt: {
+        type: 'preset',
+        preset: 'claude_code',
+        append: executorPrompt,
+      },
+      settingSources: ['project'],
+      allowedTools,
+      permissionMode: 'bypassPermissions',
+      allowDangerouslySkipPermissions: true,
+      maxTurns,
+      maxBudgetUsd,
+      cwd,
+      ...(model ? { model } : {}),
+    },
+  });
+
+  return processQueryStream(queryStream, eventStream, streamContext);
+}
+
+// ─── Result extraction ───────────────────────────────────────────────────────
+
+function isResultMessage(msg: SDKMessage): msg is SDKResultMessage {
+  return msg.type === 'result';
+}
+
+function isSuccessResult(msg: SDKResultMessage): msg is SDKResultSuccess {
+  return msg.subtype === 'success';
+}
+
+function isErrorResult(msg: SDKResultMessage): msg is SDKResultError {
+  return msg.subtype !== 'success';
+}
+
+function emptyUsage(): SessionUsage {
+  return {
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheReadInputTokens: 0,
+    cacheCreationInputTokens: 0,
+  };
+}
+
+function extractUsage(msg: SDKResultMessage): SessionUsage {
+  const u = msg.usage;
+  return {
+    inputTokens: u.input_tokens ?? 0,
+    outputTokens: u.output_tokens ?? 0,
+    cacheReadInputTokens: u.cache_read_input_tokens ?? 0,
+    cacheCreationInputTokens: u.cache_creation_input_tokens ?? 0,
+  };
+}
+
+function extractResult(msg: SDKResultMessage): PlanResult {
+  const base = {
+    sessionId: msg.session_id,
+    totalCostUsd: msg.total_cost_usd,
+    durationMs: msg.duration_ms,
+    usage: extractUsage(msg),
+    numTurns: msg.num_turns,
+  };
+
+  if (isSuccessResult(msg)) {
+    return {
+      ...base,
+      success: true,
+    };
+  }
+
+  // Error result
+  const errorMsg = msg as SDKResultError;
+  return {
+    ...base,
+    success: false,
+    error: {
+      subtype: errorMsg.subtype,
+      messages: errorMsg.errors ?? [],
+    },
+  };
+}
+
+// ─── Shared stream processing ────────────────────────────────────────────────
+
+/**
+ * Process a query() message stream, emit events, and extract the result.
+ * Shared between runPlanSession and runPhaseStepSession to avoid duplication.
+ */
+async function processQueryStream(
+  queryStream: AsyncIterable<SDKMessage>,
+  eventStream?: SDDEventStream,
+  streamContext?: EventStreamContext,
+): Promise<PlanResult> {
+  let resultMessage: SDKResultMessage | undefined;
+
+  try {
+    for await (const message of queryStream) {
+      if (eventStream) {
+        eventStream.mapAndEmit(message, streamContext ?? {});
+      }
+      if (isResultMessage(message)) {
+        resultMessage = message;
+      }
+    }
+  } catch (err) {
+    return {
+      success: false,
+      sessionId: '',
+      totalCostUsd: 0,
+      durationMs: 0,
+      usage: emptyUsage(),
+      numTurns: 0,
+      error: {
+        subtype: 'error_during_execution',
+        messages: [err instanceof Error ? err.message : String(err)],
+      },
+    };
+  }
+
+  if (!resultMessage) {
+    return {
+      success: false,
+      sessionId: '',
+      totalCostUsd: 0,
+      durationMs: 0,
+      usage: emptyUsage(),
+      numTurns: 0,
+      error: {
+        subtype: 'error_during_execution',
+        messages: ['No result message received from query stream'],
+      },
+    };
+  }
+
+  const result = extractResult(resultMessage);
+
+  if (eventStream) {
+    const cost = eventStream.getCost();
+    eventStream.emitEvent({
+      type: SDDEventType.CostUpdate,
+      timestamp: new Date().toISOString(),
+      sessionId: resultMessage.session_id,
+      phase: streamContext?.phase,
+      planName: streamContext?.planName,
+      sessionCostUsd: result.totalCostUsd,
+      cumulativeCostUsd: cost.cumulative,
+    } as SDDCostUpdateEvent);
+  }
+
+  return result;
+}
+
+// ─── Phase step session runner ───────────────────────────────────────────────
+
+/**
+ * Map PhaseStepType to PhaseType for tool scoping.
+ * PhaseStepType includes 'advance' which has no session-level equivalent.
+ */
+function stepTypeToPhaseType(step: PhaseStepType): PhaseType {
+  const mapping: Record<string, PhaseType> = {
+    discuss: PhaseType.Discuss,
+    research: PhaseType.Research,
+    plan: PhaseType.Plan,
+    plan_check: PhaseType.Verify,
+    execute: PhaseType.Execute,
+    verify: PhaseType.Verify,
+  };
+  return mapping[step] ?? PhaseType.Execute;
+}
+
+/**
+ * Run a phase step session via the Agent SDK query() function.
+ *
+ * Unlike runPlanSession which takes a ParsedPlan, this accepts a raw prompt
+ * string and a phase step type. The prompt becomes the system prompt append,
+ * and tools are scoped by phase type.
+ *
+ * @param prompt - Raw prompt string to append to the system prompt
+ * @param phaseStep - Phase step type (determines tool scoping)
+ * @param config - SDD project configuration
+ * @param options - Session overrides (maxTurns, budget, model, etc.)
+ * @param eventStream - Optional event stream for observability
+ * @param streamContext - Optional context for event tagging
+ * @returns Typed PlanResult with cost, duration, success/error status
+ */
+export async function runPhaseStepSession(
+  prompt: string,
+  phaseStep: PhaseStepType,
+  config: SDDConfig,
+  options?: SessionOptions,
+  eventStream?: SDDEventStream,
+  streamContext?: EventStreamContext,
+): Promise<PlanResult> {
+  const phaseType = stepTypeToPhaseType(phaseStep);
+  const allowedTools = options?.allowedTools ?? getToolsForPhase(phaseType);
+  const model = resolveModel(options, config);
+  const maxTurns = options?.maxTurns ?? 50;
+  const maxBudgetUsd = options?.maxBudgetUsd ?? 5.0;
+  const cwd = options?.cwd ?? process.cwd();
+
+  const queryStream = query({
+    prompt: `Execute this phase step: ${phaseStep}`,
+    options: {
+      systemPrompt: {
+        type: 'preset',
+        preset: 'claude_code',
+        append: prompt,
+      },
+      settingSources: ['project'],
+      allowedTools,
+      permissionMode: 'bypassPermissions',
+      allowDangerouslySkipPermissions: true,
+      maxTurns,
+      maxBudgetUsd,
+      cwd,
+      ...(model ? { model } : {}),
+    },
+  });
+
+  return processQueryStream(queryStream, eventStream, streamContext);
+}

package/sdk/src/tool-scoping.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from 'vitest';
+import { getToolsForPhase, PHASE_AGENT_MAP, PHASE_DEFAULT_TOOLS } from './tool-scoping.js';
+import { PhaseType } from './types.js';
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('getToolsForPhase', () => {
+  describe('default tools per phase', () => {
+    it('research phase: read-only + web search, no Write/Edit', () => {
+      const tools = getToolsForPhase(PhaseType.Research);
+      expect(tools).toContain('Read');
+      expect(tools).toContain('Grep');
+      expect(tools).toContain('Glob');
+      expect(tools).toContain('Bash');
+      expect(tools).toContain('WebSearch');
+      expect(tools).not.toContain('Write');
+      expect(tools).not.toContain('Edit');
+    });
+
+    it('execute phase: full read/write', () => {
+      const tools = getToolsForPhase(PhaseType.Execute);
+      expect(tools).toContain('Read');
+      expect(tools).toContain('Write');
+      expect(tools).toContain('Edit');
+      expect(tools).toContain('Bash');
+      expect(tools).toContain('Grep');
+      expect(tools).toContain('Glob');
+    });
+
+    it('verify phase: read-only, no Write/Edit', () => {
+      const tools = getToolsForPhase(PhaseType.Verify);
+      expect(tools).toContain('Read');
+      expect(tools).toContain('Bash');
+      expect(tools).toContain('Grep');
+      expect(tools).toContain('Glob');
+      expect(tools).not.toContain('Write');
+      expect(tools).not.toContain('Edit');
+    });
+
+    it('discuss phase: read-only, no Write/Edit', () => {
+      const tools = getToolsForPhase(PhaseType.Discuss);
+      expect(tools).toContain('Read');
+      expect(tools).toContain('Bash');
+      expect(tools).toContain('Grep');
+      expect(tools).toContain('Glob');
+      expect(tools).not.toContain('Write');
+      expect(tools).not.toContain('Edit');
+    });
+
+    it('plan phase: read/write + web, has Write but no Edit', () => {
+      const tools = getToolsForPhase(PhaseType.Plan);
+      expect(tools).toContain('Read');
+      expect(tools).toContain('Write');
+      expect(tools).toContain('Bash');
+      expect(tools).toContain('Glob');
+      expect(tools).toContain('Grep');
+      expect(tools).toContain('WebFetch');
+    });
+  });
+
+  describe('returns copies, not references', () => {
+    it('mutating returned array does not affect future calls', () => {
+      const tools1 = getToolsForPhase(PhaseType.Execute);
+      tools1.push('CustomTool');
+      const tools2 = getToolsForPhase(PhaseType.Execute);
+      expect(tools2).not.toContain('CustomTool');
+    });
+  });
+
+  describe('agent definition override', () => {
+    it('parses tools from agent def frontmatter when provided', () => {
+      const agentDef = `---
+name: test-agent
+tools: Bash, Grep, CustomTool
+---
+
+<role>Test agent</role>`;
+
+      const tools = getToolsForPhase(PhaseType.Execute, agentDef);
+      expect(tools).toEqual(['Bash', 'Grep', 'CustomTool']);
+    });
+
+    it('falls back to defaults when agent def has no tools line', () => {
+      const agentDef = `---
+name: test-agent
+---
+
+<role>Test agent</role>`;
+
+      const tools = getToolsForPhase(PhaseType.Execute, agentDef);
+      // parseAgentTools returns DEFAULT_ALLOWED_TOOLS when no tools: line found
+      expect(tools).toEqual(['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob']);
+    });
+
+    it('falls back to defaults when agent def has no frontmatter', () => {
+      const agentDef = '<role>Test agent with no frontmatter</role>';
+
+      const tools = getToolsForPhase(PhaseType.Research, agentDef);
+      // parseAgentTools returns DEFAULT_ALLOWED_TOOLS for no frontmatter
+      expect(tools).toEqual(['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob']);
+    });
+  });
+
+  describe('R015 compliance', () => {
+    it('research has no Write or Edit on source', () => {
+      const tools = getToolsForPhase(PhaseType.Research);
+      expect(tools).not.toContain('Write');
+      expect(tools).not.toContain('Edit');
+    });
+
+    it('execute has Write and Edit for source modification', () => {
+      const tools = getToolsForPhase(PhaseType.Execute);
+      expect(tools).toContain('Write');
+      expect(tools).toContain('Edit');
+    });
+
+    it('verify has no Write or Edit (read-only verification)', () => {
+      const tools = getToolsForPhase(PhaseType.Verify);
+      expect(tools).not.toContain('Write');
+      expect(tools).not.toContain('Edit');
+    });
+  });
+});
+
+describe('PHASE_AGENT_MAP', () => {
+  it('maps all phase types', () => {
+    for (const phase of Object.values(PhaseType)) {
+      expect(phase in PHASE_AGENT_MAP).toBe(true);
+    }
+  });
+
+  it('execute maps to sdd-executor.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Execute]).toBe('sdd-executor.md');
+  });
+
+  it('research maps to sdd-phase-researcher.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Research]).toBe('sdd-phase-researcher.md');
+  });
+
+  it('plan maps to sdd-planner.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Plan]).toBe('sdd-planner.md');
+  });
+
+  it('verify maps to sdd-verifier.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Verify]).toBe('sdd-verifier.md');
+  });
+
+  it('discuss maps to null (no dedicated agent)', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Discuss]).toBeNull();
+  });
+});
+
+describe('PHASE_DEFAULT_TOOLS', () => {
+  it('covers all phase types', () => {
+    for (const phase of Object.values(PhaseType)) {
+      expect(PHASE_DEFAULT_TOOLS[phase]).toBeDefined();
+      expect(PHASE_DEFAULT_TOOLS[phase].length).toBeGreaterThan(0);
+    }
+  });
+});

package/sdk/src/tool-scoping.ts

@@ -0,0 +1,61 @@
+/**
+ * Tool scoping — maps phase types to allowed tool sets.
+ *
+ * Per R015, different phases get different tool access:
+ * - Research: read-only + web search (no Write/Edit on source)
+ * - Execute: full read/write
+ * - Verify: read-only (no Write/Edit)
+ * - Discuss: read-only
+ * - Plan: read/write + web (for creating plan files)
+ */
+
+import { PhaseType } from './types.js';
+import { parseAgentTools } from './prompt-builder.js';
+
+// ─── Phase default tool sets ─────────────────────────────────────────────────
+
+const PHASE_DEFAULT_TOOLS: Record<PhaseType, string[]> = {
+  [PhaseType.Research]: ['Read', 'Grep', 'Glob', 'Bash', 'WebSearch'],
+  [PhaseType.Execute]: ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'],
+  [PhaseType.Verify]: ['Read', 'Bash', 'Grep', 'Glob'],
+  [PhaseType.Discuss]: ['Read', 'Bash', 'Grep', 'Glob'],
+  [PhaseType.Plan]: ['Read', 'Write', 'Bash', 'Glob', 'Grep', 'WebFetch'],
+  [PhaseType.Repair]: ['Read', 'Write', 'Edit', 'Bash', 'Grep', 'Glob'],
+};
+
+// ─── Phase → agent definition filename ──────────────────────────────────────
+
+/**
+ * Maps each phase type to its corresponding agent definition filename.
+ * Discuss has no dedicated agent — it runs in the main conversation.
+ */
+export const PHASE_AGENT_MAP: Record<PhaseType, string | null> = {
+  [PhaseType.Execute]: 'sdd-executor.md',
+  [PhaseType.Research]: 'sdd-phase-researcher.md',
+  [PhaseType.Plan]: 'sdd-planner.md',
+  [PhaseType.Verify]: 'sdd-verifier.md',
+  [PhaseType.Discuss]: null,
+  [PhaseType.Repair]: null,
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Get the allowed tools for a phase type.
+ *
+ * If an agent definition string is provided, tools are parsed from its
+ * frontmatter (reusing parseAgentTools from prompt-builder). Otherwise,
+ * returns the hardcoded phase defaults per R015.
+ *
+ * @param phaseType - The phase being executed
+ * @param agentDef - Optional raw agent .md file content to parse tools from
+ * @returns Array of allowed tool names
+ */
+export function getToolsForPhase(phaseType: PhaseType, agentDef?: string): string[] {
+  if (agentDef) {
+    return parseAgentTools(agentDef);
+  }
+  return [...PHASE_DEFAULT_TOOLS[phaseType]];
+}
+
+export { PHASE_DEFAULT_TOOLS };