gsd-remix 1.0.0

package/sdk/src/session-runner.test.ts

@@ -0,0 +1,98 @@
+/**
+ * Unit tests for session-runner.ts
+ *
+ * Regression test for #2194: runPhaseStepSession was passing the full prompt
+ * string as both the user-visible prompt: message and systemPrompt.append,
+ * doubling the token cost on every phase step invocation.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { PhaseStepType } from './types.js';
+import { CONFIG_DEFAULTS } from './config.js';
+import type { GSDConfig } from './config.js';
+
+// ─── Mock the Agent SDK ───────────────────────────────────────────────────────
+
+// Capture the query call options so we can assert on them without making real API calls.
+const mockQueryCalls: Array<{ prompt: string; options: Record<string, unknown> }> = [];
+
+vi.mock('@anthropic-ai/claude-agent-sdk', () => {
+  async function* fakeQueryStream() {
+    // Yield a minimal success result message so processQueryStream completes.
+    yield {
+      type: 'result',
+      subtype: 'success',
+      session_id: 'test-session',
+      total_cost_usd: 0,
+      duration_ms: 1,
+      num_turns: 1,
+      usage: {
+        input_tokens: 10,
+        output_tokens: 5,
+        cache_read_input_tokens: 0,
+        cache_creation_input_tokens: 0,
+      },
+    };
+  }
+
+  return {
+    query: vi.fn((args: { prompt: string; options: Record<string, unknown> }) => {
+      mockQueryCalls.push({ prompt: args.prompt, options: args.options });
+      return fakeQueryStream();
+    }),
+  };
+});
+
+// ─── Import SUT after mock is hoisted ────────────────────────────────────────
+
+import { runPhaseStepSession } from './session-runner.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeConfig(overrides: Partial<GSDConfig> = {}): GSDConfig {
+  return { ...CONFIG_DEFAULTS, ...overrides };
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('runPhaseStepSession', () => {
+  beforeEach(() => {
+    mockQueryCalls.length = 0;
+  });
+
+  it('does not duplicate the prompt in both the user message and systemPrompt.append', async () => {
+    const fullPrompt = 'You are a researcher. Investigate the topic thoroughly.\n\n## Context\nDetailed instructions here...';
+
+    await runPhaseStepSession(fullPrompt, PhaseStepType.Research, makeConfig());
+
+    expect(mockQueryCalls).toHaveLength(1);
+
+    const call = mockQueryCalls[0];
+    const appendValue = (call.options.systemPrompt as { append?: string })?.append;
+
+    // The full prompt must appear in systemPrompt.append (that is its correct location).
+    expect(appendValue).toBe(fullPrompt);
+
+    // The user-visible prompt: must NOT be the full prompt — it should be a short directive.
+    expect(call.prompt).not.toBe(fullPrompt);
+    expect(call.prompt.length).toBeLessThan(fullPrompt.length);
+  });
+
+  it('passes the full prompt in systemPrompt.append', async () => {
+    const fullPrompt = 'Complex multi-line\nprompt with $VARIABLES and $(command) patterns.';
+
+    await runPhaseStepSession(fullPrompt, PhaseStepType.Execute, makeConfig());
+
+    const call = mockQueryCalls[0];
+    const appendValue = (call.options.systemPrompt as { append?: string })?.append;
+
+    expect(appendValue).toBe(fullPrompt);
+  });
+
+  it('returns a successful PlanResult', async () => {
+    const result = await runPhaseStepSession('Test prompt', PhaseStepType.Verify, makeConfig());
+
+    expect(result.success).toBe(true);
+    expect(result.sessionId).toBe('test-session');
+  });
+});

package/sdk/src/session-runner.ts

@@ -0,0 +1,299 @@
+/**
+ * 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, GSDCostUpdateEvent, PhaseStepType } from './types.js';
+import { GSDEventType, PhaseType } from './types.js';
+import type { GSDConfig } from './config.js';
+import { buildExecutorPrompt, parseAgentTools, DEFAULT_ALLOWED_TOOLS } from './prompt-builder.js';
+import type { GSDEventStream, EventStreamContext } from './event-stream.js';
+import { getToolsForPhase } from './tool-scoping.js';
+
+// ─── Model resolution ────────────────────────────────────────────────────────
+
+/**
+ * Resolve model identifier from options or config profile.
+ *
+ * Priority: explicit model option > config model_profile > default.
+ */
+function resolveModel(options?: SessionOptions, config?: GSDConfig): string | undefined {
+  if (options?.model) return options.model;
+
+  // Map model_profile names to model IDs
+  if (config?.model_profile) {
+    const profileMap: Record<string, string> = {
+      balanced: 'claude-sonnet-4-6',
+      quality: 'claude-opus-4-6',
+      speed: 'claude-haiku-4-5',
+    };
+    return profileMap[config.model_profile] ?? config.model_profile;
+  }
+
+  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 - GSD 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: GSDConfig,
+  options?: SessionOptions,
+  agentDef?: string,
+  eventStream?: GSDEventStream,
+  streamContext?: EventStreamContext,
+): Promise<PlanResult> {
+  // Build the executor prompt
+  const executorPrompt = buildExecutorPrompt(plan, agentDef);
+
+  // 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?: GSDEventStream,
+  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: GSDEventType.CostUpdate,
+      timestamp: new Date().toISOString(),
+      sessionId: resultMessage.session_id,
+      phase: streamContext?.phase,
+      planName: streamContext?.planName,
+      sessionCostUsd: result.totalCostUsd,
+      cumulativeCostUsd: cost.cumulative,
+    } as GSDCostUpdateEvent);
+  }
+
+  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 - GSD 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: GSDConfig,
+  options?: SessionOptions,
+  eventStream?: GSDEventStream,
+  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 gsd-executor.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Execute]).toBe('gsd-executor.md');
+  });
+
+  it('research maps to gsd-phase-researcher.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Research]).toBe('gsd-phase-researcher.md');
+  });
+
+  it('plan maps to gsd-planner.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Plan]).toBe('gsd-planner.md');
+  });
+
+  it('verify maps to gsd-verifier.md', () => {
+    expect(PHASE_AGENT_MAP[PhaseType.Verify]).toBe('gsd-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]: 'gsd-executor.md',
+  [PhaseType.Research]: 'gsd-phase-researcher.md',
+  [PhaseType.Plan]: 'gsd-planner.md',
+  [PhaseType.Verify]: 'gsd-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 };