@bhargavvc/sdd-cc 1.35.0 → 1.42.3

package/sdk/src/sdd-transport.ts

@@ -0,0 +1,117 @@
+import type { QueryResult } from './query/utils.js';
+import type { QueryRegistry } from './query/registry.js';
+import type { TransportMode } from './sdd-transport-policy.js';
+import { toFailureSignal } from './query-failure-classification.js';
+import { SDDToolsError } from './sdd-tools-error.js';
+
+export interface TransportRequest {
+  legacyCommand: string;
+  legacyArgs: string[];
+  registryCommand: string;
+  registryArgs: string[];
+  mode: TransportMode;
+  projectDir: string;
+  workstream?: string;
+}
+
+export interface TransportAdapters {
+  dispatchNative: (request: TransportRequest) => Promise<QueryResult>;
+  execSubprocessJson: (legacyCommand: string, legacyArgs: string[]) => Promise<unknown>;
+  execSubprocessRaw: (legacyCommand: string, legacyArgs: string[]) => Promise<string>;
+  formatNativeRaw?: (registryCommand: string, data: unknown) => string;
+}
+
+export interface TransportPolicyLike {
+  preferNative: boolean;
+  allowFallbackToSubprocess: boolean;
+}
+
+export interface TransportDecision {
+  dispatchMode: 'native' | 'subprocess';
+  reason?: 'workstream_forced' | 'native_not_preferred' | 'native_unregistered' | 'native_failure_fallback';
+}
+
+export class SDDTransport {
+  constructor(
+    private readonly registry: QueryRegistry,
+    private readonly adapters: TransportAdapters,
+  ) {}
+
+  async run(
+    request: TransportRequest,
+    policy: TransportPolicyLike,
+    onDecision?: (decision: TransportDecision) => void,
+  ): Promise<unknown> {
+    const useNative = this.shouldUseNative(request, policy);
+    if (useNative) {
+      try {
+        const native = await this.adapters.dispatchNative(request);
+        onDecision?.({ dispatchMode: 'native' });
+        return this.projectNativeOutput(request, native.data);
+      } catch (error) {
+        if (this.shouldRethrowNativeError(error, policy)) throw error;
+        onDecision?.({ dispatchMode: 'subprocess', reason: 'native_failure_fallback' });
+      }
+    } else {
+      const reason = this.subprocessReason(request, policy);
+      if (!policy.allowFallbackToSubprocess && reason === 'native_unregistered') {
+        throw SDDToolsError.failure(
+          `Subprocess fallback disabled: command '${request.registryCommand}' cannot run without native dispatch`,
+          request.legacyCommand,
+          request.legacyArgs,
+          null,
+        );
+      }
+      onDecision?.({ dispatchMode: 'subprocess', reason });
+    }
+
+    return this.dispatchSubprocess(request);
+  }
+
+  private shouldUseNative(request: TransportRequest, policy: TransportPolicyLike): boolean {
+    const forceSubprocess = Boolean(request.workstream);
+    return !forceSubprocess && policy.preferNative && this.registry.has(request.registryCommand);
+  }
+
+  private subprocessReason(request: TransportRequest, policy: TransportPolicyLike): TransportDecision['reason'] {
+    if (request.workstream) return 'workstream_forced';
+    if (!policy.preferNative) return 'native_not_preferred';
+    if (!this.registry.has(request.registryCommand)) return 'native_unregistered';
+
+    throw new Error(
+      `Unexpected subprocess reason state for command '${request.registryCommand}' with preferNative=${String(policy.preferNative)} and workstream=${String(request.workstream)}`,
+    );
+  }
+
+  private shouldRethrowNativeError(error: unknown, policy: TransportPolicyLike): boolean {
+    if (!policy.allowFallbackToSubprocess) return true;
+    // Do not subprocess-fallback after a timed-out native dispatch:
+    // the timeout does not cancel the native handler, so falling through
+    // would run the same command twice (double-execution race).
+    return toFailureSignal(error).kind === 'timeout';
+  }
+
+  private dispatchSubprocess(request: TransportRequest): Promise<unknown> {
+    if (request.mode === 'raw') {
+      return this.adapters.execSubprocessRaw(request.legacyCommand, request.legacyArgs);
+    }
+    return this.adapters.execSubprocessJson(request.legacyCommand, request.legacyArgs);
+  }
+
+  private projectNativeOutput(request: TransportRequest, data: unknown): unknown {
+    if (request.mode === 'raw') {
+      if (this.adapters.formatNativeRaw) {
+        return this.adapters.formatNativeRaw(request.registryCommand, data).trim();
+      }
+      return this.toRaw(data);
+    }
+    return data;
+  }
+
+  private toRaw(data: unknown): string {
+    if (typeof data === 'string') return data.trim();
+    const json = JSON.stringify(data, null, 2);
+    if (json == null) return '';
+    return json.trim();
+  }
+}

package/sdk/src/sdk-package-compatibility.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it, vi } from 'vitest';
+import { join } from 'node:path';
+
+import {
+  BUNDLED_CORE_CJS_PATH,
+  BUNDLED_SDD_AGENTS_DIR,
+  BUNDLED_SDD_TEMPLATES_DIR,
+  BUNDLED_SDD_TOOLS_PATH,
+  loadLegacyCoreConfig,
+  probeLegacySdkAsset,
+  resolveBundledAgentsDir,
+  resolveBundledTemplatesDir,
+  resolveSddToolsPath,
+  resolveLegacyInstallDir,
+  resolveLegacyUserProfilePath,
+  resolveLegacyTemplatesDir,
+  resolveLegacyWorkflowsDir,
+} from './sdk-package-compatibility.js';
+import { SDDError } from './errors.js';
+
+describe('SDK Package Seam Module', () => {
+  const projectDir = '/work/project';
+  const homeDir = '/users/tester';
+
+  it('resolves legacy install-relative directories through one seam', () => {
+    expect(resolveLegacyInstallDir(homeDir)).toBe(join(homeDir, '.claude', 'sdd'));
+    expect(resolveLegacyTemplatesDir(homeDir)).toBe(join(homeDir, '.claude', 'sdd', 'templates'));
+    expect(resolveLegacyWorkflowsDir(homeDir)).toBe(join(homeDir, '.claude', 'sdd', 'workflows'));
+    expect(resolveLegacyUserProfilePath(homeDir)).toBe(join(homeDir, '.claude', 'sdd', 'USER-PROFILE.md'));
+    expect(resolveBundledTemplatesDir()).toBe(BUNDLED_SDD_TEMPLATES_DIR);
+    expect(resolveBundledAgentsDir()).toBe(BUNDLED_SDD_AGENTS_DIR);
+  });
+
+  it('probes legacy sdd-tools locations in bundled -> project -> home order', () => {
+    const resolution = probeLegacySdkAsset('sdd-tools', projectDir, {
+      homeDir,
+      existsSync: path => path === join(projectDir, '.claude', 'sdd', 'bin', 'sdd-tools.cjs'),
+    });
+
+    expect(resolution.probes).toEqual([
+      BUNDLED_SDD_TOOLS_PATH,
+      join(projectDir, '.claude', 'sdd', 'bin', 'sdd-tools.cjs'),
+      join(homeDir, '.claude', 'sdd', 'bin', 'sdd-tools.cjs'),
+    ]);
+    expect(resolution.path).toBe(join(projectDir, '.claude', 'sdd', 'bin', 'sdd-tools.cjs'));
+    expect(resolution.fallbackPath).toBe(join(homeDir, '.claude', 'sdd', 'bin', 'sdd-tools.cjs'));
+  });
+
+  it('returns concrete fallback sdd-tools path when no legacy probe exists', () => {
+    const path = resolveSddToolsPath(projectDir, {
+      homeDir,
+      existsSync: () => false,
+    });
+
+    expect(path).toBe(join(homeDir, '.claude', 'sdd', 'bin', 'sdd-tools.cjs'));
+  });
+
+  it('loads legacy core.cjs through one compatibility adapter', () => {
+    const loadConfig = vi.fn((cwd: string) => ({ cwd, source: 'legacy-core' }));
+    const requireFn = vi.fn(() => ({ loadConfig }));
+    const createRequire = vi.fn(() => requireFn as unknown as NodeJS.Require);
+
+    const result = loadLegacyCoreConfig(projectDir, {
+      homeDir,
+      existsSync: path => path === BUNDLED_CORE_CJS_PATH,
+      createRequire,
+    });
+
+    expect(createRequire).toHaveBeenCalledOnce();
+    expect(requireFn).toHaveBeenCalledWith(BUNDLED_CORE_CJS_PATH);
+    expect(loadConfig).toHaveBeenCalledWith(projectDir);
+    expect(result).toEqual({ cwd: projectDir, source: 'legacy-core' });
+  });
+
+  it('reports checked core.cjs probes when legacy asset missing', () => {
+    expect(() => loadLegacyCoreConfig(projectDir, {
+      homeDir,
+      existsSync: () => false,
+    })).toThrow(SDDError);
+
+    try {
+      loadLegacyCoreConfig(projectDir, {
+        homeDir,
+        existsSync: () => false,
+      });
+      expect.fail('expected SDDError');
+    } catch (error) {
+      expect(error).toBeInstanceOf(SDDError);
+      const message = (error as Error).message;
+      expect(message).toContain('state load: sdd/bin/lib/core.cjs not found.');
+      expect(message).toContain('Checked:');
+      expect(message).toContain(BUNDLED_CORE_CJS_PATH);
+      expect(message).toContain(join(projectDir, '.claude', 'sdd', 'bin', 'lib', 'core.cjs'));
+      expect(message).toContain(join(homeDir, '.claude', 'sdd', 'bin', 'lib', 'core.cjs'));
+    }
+  });
+});

package/sdk/src/sdk-package-compatibility.ts

@@ -0,0 +1,141 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { SDDError, ErrorClassification } from './errors.js';
+
+export type LegacySdkAsset = 'sdd-tools' | 'core-cjs';
+
+export interface LegacySdkAssetResolution {
+  asset: LegacySdkAsset;
+  path: string | null;
+  fallbackPath: string;
+  probes: string[];
+}
+
+interface LegacySdkCompatibilityDeps {
+  existsSync?: (path: string) => boolean;
+  homeDir?: string;
+  createRequire?: typeof createRequire;
+}
+
+export const BUNDLED_SDD_TOOLS_PATH = fileURLToPath(
+  new URL('../../sdd/bin/sdd-tools.cjs', import.meta.url),
+);
+
+export const BUNDLED_CORE_CJS_PATH = fileURLToPath(
+  new URL('../../sdd/bin/lib/core.cjs', import.meta.url),
+);
+
+export const BUNDLED_SDD_TEMPLATES_DIR = fileURLToPath(
+  new URL('../../sdd/templates', import.meta.url),
+);
+
+export const BUNDLED_SDD_AGENTS_DIR = fileURLToPath(
+  new URL('../../agents', import.meta.url),
+);
+
+const LEGACY_ASSET_SUBPATH: Record<LegacySdkAsset, string> = {
+  'sdd-tools': 'sdd-tools.cjs',
+  'core-cjs': join('lib', 'core.cjs'),
+};
+
+const BUNDLED_LEGACY_ASSET_PATH: Record<LegacySdkAsset, string> = {
+  'sdd-tools': BUNDLED_SDD_TOOLS_PATH,
+  'core-cjs': BUNDLED_CORE_CJS_PATH,
+};
+
+export function resolveLegacyInstallDir(homeDir: string = homedir()): string {
+  return join(homeDir, '.claude', 'sdd');
+}
+
+export function resolveLegacyTemplatesDir(homeDir: string = homedir()): string {
+  return join(resolveLegacyInstallDir(homeDir), 'templates');
+}
+
+export function resolveLegacyWorkflowsDir(homeDir: string = homedir()): string {
+  return join(resolveLegacyInstallDir(homeDir), 'workflows');
+}
+
+export function resolveLegacyUserProfilePath(homeDir: string = homedir()): string {
+  return join(resolveLegacyInstallDir(homeDir), 'USER-PROFILE.md');
+}
+
+export function resolveLegacySkillsDir(homeDir: string = homedir()): string {
+  return join(resolveLegacyInstallDir(homeDir), 'skills');
+}
+
+export function resolveBundledTemplatesDir(): string {
+  return BUNDLED_SDD_TEMPLATES_DIR;
+}
+
+export function resolveBundledAgentsDir(): string {
+  return BUNDLED_SDD_AGENTS_DIR;
+}
+
+function legacyAssetProbes(asset: LegacySdkAsset, projectDir: string, homeDir: string): string[] {
+  const suffix = LEGACY_ASSET_SUBPATH[asset];
+  return [
+    BUNDLED_LEGACY_ASSET_PATH[asset],
+    join(projectDir, '.claude', 'sdd', 'bin', suffix),
+    join(homeDir, '.claude', 'sdd', 'bin', suffix),
+  ];
+}
+
+export function probeLegacySdkAsset(
+  asset: LegacySdkAsset,
+  projectDir: string,
+  deps: LegacySdkCompatibilityDeps = {},
+): LegacySdkAssetResolution {
+  const pathExists = deps.existsSync ?? existsSync;
+  const probes = legacyAssetProbes(asset, projectDir, deps.homeDir ?? homedir());
+  return {
+    asset,
+    path: probes.find(candidate => pathExists(candidate)) ?? null,
+    fallbackPath: probes[probes.length - 1]!,
+    probes,
+  };
+}
+
+/**
+ * Resolve the legacy `sdd-tools.cjs` executable path through the SDK Package Seam Module.
+ *
+ * Preserves historical behavior: if no probe exists, return the final fallback path so
+ * downstream subprocess errors still show a concrete location.
+ */
+export function resolveSddToolsPath(projectDir: string, deps: LegacySdkCompatibilityDeps = {}): string {
+  const resolution = probeLegacySdkAsset('sdd-tools', projectDir, deps);
+  return resolution.path ?? resolution.fallbackPath;
+}
+
+function missingLegacyCoreMessage(resolution: LegacySdkAssetResolution): string {
+  return [
+    'state load: sdd/bin/lib/core.cjs not found.',
+    `Checked: ${resolution.probes.join(', ')}`,
+    'Install SDD (e.g. npm i -g @bhargavvc/sdd-cc) or clone with sdd next to the SDK.',
+  ].join(' ');
+}
+
+/**
+ * Load `loadConfig(cwd)` from the legacy CJS install through one compatibility seam.
+ */
+export function loadLegacyCoreConfig(projectDir: string, deps: LegacySdkCompatibilityDeps = {}): Record<string, unknown> {
+  const resolution = probeLegacySdkAsset('core-cjs', projectDir, deps);
+  if (!resolution.path) {
+    throw new SDDError(
+      missingLegacyCoreMessage(resolution),
+      ErrorClassification.Blocked,
+    );
+  }
+
+  const req = (deps.createRequire ?? createRequire)(import.meta.url);
+  const mod = req(resolution.path) as Partial<{ loadConfig: (cwd: string) => Record<string, unknown> }>;
+  if (typeof mod.loadConfig !== 'function') {
+    throw new SDDError(
+      `state load: invalid core.cjs at ${resolution.path} (missing loadConfig(cwd)).`,
+      ErrorClassification.Blocked,
+    );
+  }
+  return mod.loadConfig(projectDir);
+}

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

@@ -0,0 +1,164 @@
+/**
+ * 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 { SDDConfig } 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<SDDConfig> = {}): SDDConfig {
+  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');
+  });
+
+  // ─── #2832: runtime-aware model resolution ─────────────────────────────────
+  // Issue: with `runtime: codex` and `model_profile: balanced`, resolveModel
+  // mapped balanced -> 'claude-sonnet-4-6' and forced the Codex run through
+  // a Claude model. For non-Claude runtimes the SDK must NOT inject a Claude
+  // model id; it should leave model unset (or honor explicit overrides) and
+  // let the runtime use its configured default.
+  describe('resolveModel runtime awareness (#2832)', () => {
+    it('does NOT pass a Claude profile model id when runtime is codex', async () => {
+      await runPhaseStepSession(
+        'prompt',
+        PhaseStepType.Execute,
+        makeConfig({ runtime: 'codex', model_profile: 'balanced' } as Partial<SDDConfig>),
+      );
+      const opts = mockQueryCalls[0].options as { model?: string };
+      expect(opts.model).toBeUndefined();
+    });
+
+    it('does NOT pass a Claude profile model id when resolve_model_ids is "omit"', async () => {
+      await runPhaseStepSession(
+        'prompt',
+        PhaseStepType.Execute,
+        makeConfig({ resolve_model_ids: 'omit', model_profile: 'balanced' } as Partial<SDDConfig>),
+      );
+      const opts = mockQueryCalls[0].options as { model?: string };
+      expect(opts.model).toBeUndefined();
+    });
+
+    it('still maps profile -> Claude id when runtime is claude (no regression)', async () => {
+      await runPhaseStepSession(
+        'prompt',
+        PhaseStepType.Execute,
+        makeConfig({ runtime: 'claude', model_profile: 'balanced' } as Partial<SDDConfig>),
+      );
+      const opts = mockQueryCalls[0].options as { model?: string };
+      expect(opts.model).toBe('claude-sonnet-4-6');
+    });
+
+    it('respects SDD_RUNTIME env precedence over config (no Claude id when env=codex)', async () => {
+      const prev = process.env.SDD_RUNTIME;
+      process.env.SDD_RUNTIME = 'codex';
+      try {
+        await runPhaseStepSession(
+          'prompt',
+          PhaseStepType.Execute,
+          makeConfig({ model_profile: 'balanced' } as Partial<SDDConfig>),
+        );
+        const opts = mockQueryCalls[0].options as { model?: string };
+        expect(opts.model).toBeUndefined();
+      } finally {
+        if (prev === undefined) delete process.env.SDD_RUNTIME;
+        else process.env.SDD_RUNTIME = prev;
+      }
+    });
+
+    it('explicit options.model wins for any runtime', async () => {
+      await runPhaseStepSession(
+        'prompt',
+        PhaseStepType.Execute,
+        makeConfig({ runtime: 'codex' } as Partial<SDDConfig>),
+        { model: 'gpt-5.3-codex' },
+      );
+      const opts = mockQueryCalls[0].options as { model?: string };
+      expect(opts.model).toBe('gpt-5.3-codex');
+    });
+  });
+});