@smartmemory/compose 0.2.57-beta → 0.3.0

package/lib/lane-gate.js

@@ -0,0 +1,200 @@
+// lib/lane-gate.js
+//
+// COMP-TRIAGE-5 — E3 (Estimate → Execute → Expand) front-of-pipeline scope
+// estimation + verification-gated escalation. Two entry points, extracted from
+// build.js runBuild/executeShipStep so they are unit-testable in isolation:
+//
+//   applyFrontTriage()  — E3 "Estimate": derive the lane from the RAW REQUEST
+//                         before any design/plan/blueprint doc is read, and
+//                         persist validated feature fields (closing the
+//                         complexity: String(tier) bypass at build.js:997/1006).
+//
+//   maybeEscalateLane() — E3 "Expand": on a failed ship-time test gate, escalate
+//                         the lane so the NEXT build runs wider — persist the
+//                         escalated lane + a widened profile + a bounded counter
+//                         and drop a resume checkpoint. STOP → human handoff.
+//                         Re-entry is via re-invocation reading the escalated
+//                         lane, NOT inline runBuild surgery.
+
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import {
+  estimateScope,
+  tierToComplexity,
+  floorProfileToLane,
+  runTriage,
+  tierToLane,
+  narrowerLane,
+} from './triage.js';
+import { validateFeatureFields } from './feature-writer.js';
+import { escalate } from './escalation.js';
+
+// Docs that make a doc-reading refinement meaningful. Absent all three, runTriage
+// would see zero files and return tier 0 ('trivial') — which is "no signal", not
+// "confirmed simple", and must NOT be allowed to narrow away the front safety clamp.
+const REFINEMENT_DOCS = ['design.md', 'plan.md', 'blueprint.md'];
+
+/**
+ * E3 Estimate. Runs before spec load. Derives {tier, profile, lane} from the raw
+ * request (doc-free) and persists validated fields through the shared validator
+ * (so the tier can no longer be stringified into `complexity`). Returns the
+ * values runBuild needs to toggle skip_if.
+ *
+ * @param {object} a
+ * @param {string} a.featureCode
+ * @param {string} [a.request]        raw task text (opts.description); falls back to the code
+ * @param {object} a.provider         build provider (getFeature/createFeature/putFeature)
+ * @param {object|null} a.cachedFeature  already-fetched feature.json, or null
+ * @returns {Promise<{buildProfile:object, tier:number, lane:string, tierLabel:string, rationale:string, cachedFeature:object}>}
+ */
+export async function applyFrontTriage({ featureCode, request, provider, cachedFeature, cwd, featuresDir }) {
+  // The CLI build path does not thread a description into opts, so fall back to
+  // the feature's own persisted description before the (signal-free) code string —
+  // otherwise every CLI build would classify the code and land low-confidence.
+  const req = request ?? cachedFeature?.description ?? featureCode;
+  const front = estimateScope(req);
+  let tier = front.tier;
+  let lane = front.lane;
+  let buildProfile = front.profile;
+  let estimateSource = 'front';
+
+  // E3 refinement (narrow-only): once design/plan/blueprint docs exist, a
+  // doc-reading pass may CONFIRM a smaller scope than the raw request implied —
+  // but it may only narrow the front lane, never widen it (widening is the
+  // escalation path's job). Gated on doc existence so a doc-less tier-0 read
+  // cannot undo the front safety clamp.
+  if (cwd && featuresDir) {
+    const dir = resolve(cwd, featuresDir, featureCode);
+    const hasDocs = REFINEMENT_DOCS.some((f) => existsSync(join(dir, f)));
+    if (hasDocs) {
+      try {
+        const refined = await runTriage(featureCode, { cwd, featuresDir });
+        const narrowed = narrowerLane(lane, tierToLane(refined.tier));
+        if (narrowed !== lane) {
+          lane = narrowed;
+          tier = refined.tier;
+          buildProfile = floorProfileToLane(refined.profile, narrowed);
+          estimateSource = 'refined';
+        }
+      } catch {
+        /* triage read failed — keep the front estimate */
+      }
+    }
+  }
+
+  const fields = {
+    complexity: tierToComplexity(tier),
+    triageTier: tier,
+    lane,
+    estimateSource,
+    profile: buildProfile,
+    triageTimestamp: new Date().toISOString(),
+  };
+  // Throws on any invalid field — this is the guard the raw provider write bypassed.
+  validateFeatureFields(fields);
+
+  let updated;
+  if (!cachedFeature) {
+    updated = await provider.createFeature(featureCode, {
+      code: featureCode,
+      description: req,
+      status: 'PLANNED',
+      ...fields,
+    });
+  } else {
+    updated = await provider.putFeature(featureCode, { ...cachedFeature, ...fields });
+  }
+
+  return {
+    buildProfile,
+    tier,
+    lane,
+    tierLabel: fields.complexity,
+    rationale: front.rationale,
+    cachedFeature: updated,
+  };
+}
+
+/**
+ * E3 Expand. On a failed ship-time test gate, escalate the lane so the next build
+ * runs wider. Bounded via escalationCount; on STOP or exhausted ladder, writes a
+ * checkpoint and hands off to a human. Best-effort — the caller never blocks ship
+ * on this. Only acts on features that went through front triage (have a `lane`).
+ *
+ * @param {object} a
+ * @param {string} a.featureCode
+ * @param {object} a.provider        build provider
+ * @param {string} [a.featureDir]    dir to write the escalation checkpoint into
+ * @param {string|null} [a.currentPhase]  optional live phase (unused for reEntry today; see escalation.js)
+ * @returns {Promise<{action:'none'|'escalate'|'stop', [from]:string, [to]:string, [reEntryPhase]:string, [escalationCount]:number}>}
+ */
+export async function maybeEscalateLane({ featureCode, provider, featureDir, currentPhase = null }) {
+  const feature = await provider.getFeature(featureCode);
+  // Only features that went through the front seam carry a lane — never escalate
+  // a feature that never opted into lane-based execution.
+  if (!feature?.lane) return { action: 'none' };
+
+  const lane = feature.lane;
+  const escalationCount = feature.escalationCount ?? 0;
+  const decision = escalate({ gate: 'test', passed: false }, lane, escalationCount, currentPhase);
+
+  if (decision === 'STOP') {
+    writeCheckpoint(featureDir, { featureCode, lane, decision: 'STOP', reEntryPhase: null, escalationCount });
+    return { action: 'stop', lane, escalationCount };
+  }
+  if (!decision) return { action: 'none' };
+
+  // Widen the profile to match the ESCALATED lane (not always full) so lane and
+  // profile stay consistent and each rung actually adds phases.
+  const widenedProfile = floorProfileToLane(feature.profile ?? {}, decision.nextLane);
+  validateFeatureFields({ lane: decision.nextLane, estimateSource: 'escalated' });
+  // Write the checkpoint BEFORE stamping triageTimestamp so the checkpoint file's
+  // mtime is older than the stamp — otherwise isTriageStale would treat the just-
+  // escalated feature as stale on the next build and overwrite the escalation.
+  writeCheckpoint(featureDir, {
+    featureCode,
+    lane: decision.nextLane,
+    decision: 'escalate',
+    reEntryPhase: decision.reEntryPhase,
+    escalationCount: escalationCount + 1,
+  });
+  await provider.putFeature(featureCode, {
+    ...feature,
+    lane: decision.nextLane,
+    estimateSource: 'escalated',
+    escalationCount: escalationCount + 1,
+    profile: widenedProfile,
+    triageTimestamp: new Date().toISOString(),
+  });
+  return {
+    action: 'escalate',
+    from: lane,
+    to: decision.nextLane,
+    reEntryPhase: decision.reEntryPhase,
+    escalationCount: escalationCount + 1,
+  };
+}
+
+function writeCheckpoint(featureDir, { featureCode, lane, decision, reEntryPhase, escalationCount }) {
+  if (!featureDir) return;
+  try {
+    mkdirSync(featureDir, { recursive: true });
+    const lines = [
+      `# COMP-TRIAGE-5 Escalation Checkpoint — ${featureCode}`,
+      '',
+      `- Decision: ${decision}`,
+      `- Lane: ${lane}`,
+      reEntryPhase ? `- Re-enter at phase: ${reEntryPhase}` : '- Re-enter: n/a (STOP — human handoff)',
+      `- Escalation count: ${escalationCount}`,
+      '- Trigger: ship-time test gate failed (E3 Expand)',
+      '',
+      decision === 'STOP'
+        ? 'Escalation bound reached. A human should investigate before re-running.'
+        : `Re-run \`compose build ${featureCode}\` — it reads the escalated lane and runs the heavier phases.`,
+      '',
+    ];
+    writeFileSync(join(featureDir, 'escalation-checkpoint.md'), lines.join('\n'), 'utf-8');
+  } catch {
+    /* best-effort — a checkpoint failure must never break the build */
+  }
+}

package/lib/local-claude-connector.js

@@ -0,0 +1,149 @@
+/**
+ * local-claude-connector.js — V2/V3 (STRAT-TS-FANOUT-CONSUMER).
+ *
+ * The TS `stratum_agent_run` surface is a SYNCHRONOUS black box: it returns no
+ * runId (no pre-completion cancel handle), streams no progress notifications,
+ * and its `sandboxMode` binds only the codex connector. The engine's background
+ * agent mode (surface 8) is codex-only AND read-only-only. So there is NO engine
+ * seam that can, for a CLAUDE agent:
+ *   - enforce tool restrictions (V3 — a read-only review fanout must not Edit/
+ *     Write/Bash in the target workspace), or
+ *   - be interrupted mid-run (V2 — per-item timeout / stuck / user interrupt).
+ *
+ * Compose owns consumer/review execution by design, and already depends on
+ * `@anthropic-ai/claude-agent-sdk`, so CONTROLLED claude executions run here.
+ * The connector enforces allowedTools/disallowedTools, aborts via an
+ * AbortController, streams tool_use events (for the stuck detector + narration),
+ * and reports usage. The SDK `query` is injectable for tests.
+ */
+
+import { query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
+
+const SENSITIVE_ENV_VARS = ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY', 'CLAUDE_API_KEY', 'CLAUDECODE'];
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function nonneg(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+}
+
+/**
+ * Run a controlled claude agent locally.
+ *
+ * @param {string} prompt
+ * @param {object} [opts]
+ * @param {string}   [opts.cwd]
+ * @param {string}   [opts.model]
+ * @param {string[]} [opts.allowedTools]     enforced tool allowlist (read-only review)
+ * @param {string[]} [opts.disallowedTools]
+ * @param {object}   [opts.thinking]
+ * @param {AbortController} [opts.abortController]  abort → interrupt the run
+ * @param {(ev:{tool:string,input:object})=>void} [opts.onToolUse]  per tool_use block
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {Function} [opts.query]            SDK `query` seam for tests
+ * @returns {Promise<{text:string, usage:object, telemetry:object}>}
+ */
+export async function runLocalClaudeAgent(prompt, opts = {}) {
+  const query = opts.query ?? sdkQuery;
+  const env = { ...(opts.env ?? process.env) };
+  for (const key of SENSITIVE_ENV_VARS) delete env[key];
+
+  const sdkOptions = {
+    cwd: opts.cwd ?? process.cwd(),
+    model: opts.model ?? process.env.CLAUDE_MODEL ?? 'claude-sonnet-4-6',
+    permissionMode: 'acceptEdits',
+    env,
+    ...(opts.abortController ? { abortController: opts.abortController } : {}),
+    ...(opts.thinking !== undefined ? { thinking: opts.thinking } : {}),
+  };
+  // A read-only profile passes an explicit allowlist; without one, the agent
+  // gets the full claude_code preset (unrestricted).
+  if (opts.allowedTools !== undefined) {
+    // `allowedTools` only auto-allows-without-prompting; on its own the agent
+    // still HAS every tool (minus the denylist) under permissionMode
+    // 'acceptEdits'. To actually restrict AVAILABILITY (a read-only reviewer must
+    // not be able to Edit/Write/Bash), the SDK requires `tools` set to the
+    // specific tool names. Set both: `tools` binds availability, `allowedTools`
+    // suppresses the prompt for those same tools.
+    sdkOptions.tools = [...opts.allowedTools];
+    sdkOptions.allowedTools = opts.allowedTools;
+    if (opts.disallowedTools !== undefined) sdkOptions.disallowedTools = opts.disallowedTools;
+  } else {
+    sdkOptions.tools = { type: 'preset', preset: 'claude_code' };
+    if (opts.disallowedTools !== undefined) sdkOptions.disallowedTools = opts.disallowedTools;
+  }
+
+  const startedAt = Date.now();
+  let resolvedModel = sdkOptions.model;
+  let finalText;
+  let assistantText = '';
+  let durationMs = 0;
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let costUsd = 0;
+
+  for await (const raw of query({ prompt, options: sdkOptions })) {
+    if (!isRecord(raw)) continue;
+    if (raw.type === 'system' && raw.subtype === 'init' && typeof raw.model === 'string') {
+      resolvedModel = raw.model;
+    }
+    if (raw.type === 'assistant' && isRecord(raw.message) && Array.isArray(raw.message.content)) {
+      for (const block of raw.message.content) {
+        if (!isRecord(block)) continue;
+        if (block.type === 'text' && typeof block.text === 'string') assistantText += block.text;
+        if (block.type === 'tool_use' && typeof block.name === 'string' && typeof opts.onToolUse === 'function') {
+          opts.onToolUse({ tool: block.name, input: isRecord(block.input) ? block.input : {} });
+        }
+      }
+    }
+    if (raw.type !== 'result') continue;
+    durationMs = nonneg(raw.duration_ms);
+    if (raw.subtype !== 'success') {
+      // F3: a failed run still consumed billable tokens/cost. Capture them from
+      // the error result (SDKResultError carries usage + total_cost_usd) and
+      // attach to the thrown Error — same usage shape as the success return — so
+      // the consumer failure path can debit the engine/GSD ledgers. Without this,
+      // repeated failures evade budget exhaustion.
+      const failCost = nonneg(raw.total_cost_usd);
+      const failIn = isRecord(raw.usage) ? nonneg(raw.usage.input_tokens) : 0;
+      const failOut = isRecord(raw.usage) ? nonneg(raw.usage.output_tokens) : 0;
+      const errors = Array.isArray(raw.errors) ? raw.errors.filter((v) => typeof v === 'string') : [];
+      const err = new Error(errors.join('; ') || `claude query failed: ${String(raw.subtype)}`);
+      err.usage = {
+        input_tokens: failIn,
+        output_tokens: failOut,
+        tokens: failIn + failOut,
+        cost_usd: failCost,
+        usd: failCost,
+        duration_ms: durationMs,
+        ms: durationMs,
+        model: resolvedModel,
+      };
+      err.costUsd = failCost;
+      throw err;
+    }
+    if (typeof raw.result === 'string') finalText = raw.result;
+    costUsd = nonneg(raw.total_cost_usd);
+    if (isRecord(raw.usage)) {
+      inputTokens = nonneg(raw.usage.input_tokens);
+      outputTokens = nonneg(raw.usage.output_tokens);
+    }
+  }
+
+  return {
+    text: finalText ?? assistantText,
+    usage: {
+      input_tokens: inputTokens,
+      output_tokens: outputTokens,
+      tokens: inputTokens + outputTokens,
+      cost_usd: costUsd,
+      usd: costUsd,
+      duration_ms: durationMs,
+      ms: durationMs,
+      model: resolvedModel,
+    },
+    telemetry: { durationMs, model: resolvedModel },
+  };
+}