goalforge-claude 1.0.0

package/README.md

@@ -0,0 +1,343 @@
+# GoalForge — Developer Reference
+
+Describe what you want. Claude builds it. No API key needed.
+
+An autonomous AI development loop that decomposes a high-level goal into tasks, executes them via Claude, validates the output, and iterates until the goal is met or a budget/iteration limit is hit.
+
+---
+
+## Table of Contents
+
+1. [Architecture](#architecture)
+2. [Component Reference](#component-reference)
+3. [Data Flow](#data-flow)
+4. [Memory Layout](#memory-layout)
+5. [Exit Conditions](#exit-conditions)
+6. [Configuration](#configuration)
+7. [Running Locally](#running-locally)
+8. [Testing](#testing)
+9. [Extending the System](#extending-the-system)
+
+---
+
+## Architecture
+
+```
+index.ts
+  └── LoopController          ← main event loop
+        ├── Planner           ← goal → ordered task list (Claude)
+        ├── TaskQueue         ← dependency-aware in-memory queue + disk persistence
+        ├── Executor          ← task → files + shell commands (Claude)
+        ├── TestRunner        ← runs jest/npm test in workspace, parses report
+        ├── Reviewer          ← critiques completed task output (Claude)
+        ├── CostOptimizer     ← spend budget tracking + prompt-level response cache
+        └── MemoryStore       ← file-system KV store for all persistent state
+```
+
+Each iteration of the loop runs six phases in order:
+
+```
+PLAN → EXECUTE → TEST → REVIEW → COST CHECK → MEMORY UPDATE → (repeat or exit)
+```
+
+---
+
+## Component Reference
+
+### `LoopController` (`src/loop-controller.ts`)
+
+The main orchestrator. Owns all component instances and drives the six-phase loop.
+
+**Key methods**
+
+| Method | Description |
+|--------|-------------|
+| `run()` | Start the loop. Returns a `LoopExitReason` when done. |
+| `getState()` | Snapshot of current `ProjectState` (safe to call before `run()`). |
+
+**Loop phases**
+
+| Phase | What it does |
+|-------|-------------|
+| `planPhase` | Skips re-planning if eligible tasks exist; otherwise calls `Planner`. |
+| `executePhase` | Runs up to 3 eligible tasks per iteration. |
+| `testPhase` | Calls `TestRunner`, updates coverage + pass/fail on state. |
+| `reviewPhase` | Reviews the last 3 completed tasks; requeues if score < 70 and `retryCount < 2`. |
+| `costCheckPhase` | Exits loop if total spend exceeds `maxCostUsd`. |
+| `updateMemoryPhase` | Persists `ProjectState` to disk and logs memory summary; `checkExitConditions()` is called immediately after by the loop. |
+
+---
+
+### `Planner` (`src/components/planner.ts`)
+
+Calls Claude with a structured prompt and the current project state to produce a prioritised task list and architecture decisions.
+
+**Caching**: the response cache key is a SHA-256 hash of the full prompt (goal + context). In dry-run mode responses are never cached to disk (use the `dryRun` flag for tests).
+
+**Output shape** (`PlannerOutput[]`)
+
+```ts
+{
+  objective: string;
+  priority: number;        // 1 = highest
+  dependencies: string[];  // index strings ("0", "1") referencing tasks in the same planner response
+  estimatedEffort: 'low' | 'medium' | 'high';
+  rationale?: string;
+}
+```
+
+---
+
+### `TaskQueue` (`src/components/task-queue.ts`)
+
+In-memory map of `Task` objects backed by `MemoryStore`. Dependency resolution happens at eligibility check time — a task is eligible only if all its dependency IDs have `status === 'COMPLETE'`.
+
+**Key methods**
+
+| Method | Description |
+|--------|-------------|
+| `nextEligible()` | Highest-priority PENDING task whose deps are all COMPLETE, or `null`. |
+| `enqueueBatch(plans)` | Bulk enqueue from planner output. |
+| `start(id)` | PENDING → RUNNING. Throws if deps unresolved. |
+| `complete(id)` | RUNNING → COMPLETE. |
+| `fail(id, reason?)` | Any → FAILED. |
+| `retry(id)` | Any → PENDING, increments `retryCount`. |
+| `isComplete()` | `true` if queue is non-empty and every task is COMPLETE or FAILED. |
+
+**Hydration**: on construction the queue loads all persisted tasks from `MemoryStore`. RUNNING tasks are reset to PENDING (crash recovery).
+
+---
+
+### `Executor` (`src/components/executor.ts`)
+
+Calls Claude to implement a single task. The model returns JSON describing files to write and shell commands to run. The executor writes the files under `workspaceDir` and runs the commands (skipped in dry-run mode).
+
+**dry-run output**: writes `dry-run/{taskId}.txt` to the workspace — a harmless placeholder.
+
+---
+
+### `Reviewer` (`src/components/reviewer.ts`)
+
+Calls Claude to score completed task output (0–100). A score ≥ 70 with no `critical` critiques counts as `passed`. Failed reviews trigger a retry via `TaskQueue.retry()` (max 2 retries per task).
+
+**dry-run output**: always returns score 85, passed: true, one low-severity placeholder critique.
+
+---
+
+### `TestRunner` (`src/components/test-runner.ts`)
+
+Runs the test suite inside `workspaceDir` and returns a structured `TestReport`.
+
+**Runner detection order**
+
+1. `jest.config.ts / .js / .json` found → `npx jest --json --coverage`
+2. `package.json` with jest dependency → `npx jest --coverage`
+3. `package.json` with `scripts.test` → `npm test`
+4. Neither found → returns an empty report immediately (no command run)
+
+> **Important**: the workspace must contain its own `package.json` for the runner to execute. Without one, the runner exits early. This prevents `npm` from crawling up to a parent `package.json` and triggering unintended test runs.
+
+---
+
+### `CostOptimizer` (`src/components/cost-optimizer.ts`)
+
+Tracks cumulative spend across all claude CLI calls and provides a prompt-level response cache backed by `MemoryStore`. Cost is recorded via `recordCost(usd)` using the value reported by the CLI; token-based estimation is used only for pre-call budget checks.
+
+**Budget enforcement**: before every claude CLI call, `estimate()` is called. If the projected cost would exceed the remaining budget it returns `recommendedAction: 'skip'` and the caller must not proceed.
+
+**Cache**: `buildCacheKey(...parts)` produces a 32-char SHA-256 hex key. `getCachedResponse` / `putCachedResponse` delegate to `MemoryStore.getCached` / `putCache`.
+
+---
+
+### `MemoryStore` (`src/components/memory-store.ts`)
+
+File-system backed key-value store. No external services. Layout:
+
+```
+memory/
+  state/project.json          ← single ProjectState document
+  tasks/<uuid>.json           ← one file per task
+  critiques/<uuid>.json       ← one file per Critique
+  decisions/<uuid>.json       ← one file per ArchitectureDecision
+  files/<path-hash>.json      ← metadata for each generated file
+  cache/<sha256>.json         ← CostOptimizer response cache entries
+```
+
+---
+
+## Data Flow
+
+```
+           ┌─────────────────────────────────┐
+           │          LoopController          │
+           │                                 │
+  goal ───►│  initState() ──► MemoryStore    │
+           │                                 │
+           │  ┌── ITERATION N ─────────────┐ │
+           │  │                            │ │
+           │  │  Planner.plan()            │ │
+           │  │    └─► claude CLI          │ │
+           │  │    └─► TaskQueue.enqueueBatch│ │
+           │  │    └─► MemoryStore.saveDecision│
+           │  │                            │ │
+           │  │  Executor.execute(task)    │ │
+           │  │    └─► claude CLI          │ │
+           │  │    └─► write files to workspace│
+           │  │    └─► run shell commands  │ │
+           │  │                            │ │
+           │  │  TestRunner.run()          │ │
+           │  │    └─► npx jest in workspace│ │
+           │  │                            │ │
+           │  │  Reviewer.review(task)     │ │
+           │  │    └─► claude CLI          │ │
+           │  │    └─► MemoryStore.saveCritique│
+           │  │                            │ │
+           │  │  CostOptimizer.isBudgetExceeded?│
+           │  │  checkExitConditions?      │ │
+           │  └────────────────────────────┘ │
+           │                                 │
+           │  return LoopExitReason          │
+           └─────────────────────────────────┘
+```
+
+---
+
+## Memory Layout
+
+```
+<project-root>/
+  engine/
+    memory/
+      state/project.json
+      tasks/
+      critiques/
+      decisions/
+      files/
+      cache/
+  workspace/          ← generated code lives here
+```
+
+Paths are configured via `workspaceDir` and `memoryDir` in `LoopConfig`. Tests write to isolated temp directories and clean up in `beforeEach` and `afterAll`.
+
+---
+
+## Exit Conditions
+
+The loop exits (returning a `LoopExitReason`) when the first of these is true:
+
+| Reason | Condition |
+|--------|-----------|
+| `no-critical-issues` | `coveragePercent >= targetCoveragePercent` AND `testsPassing` AND `criticalIssueCount <= maxCriticalIssues` |
+| `all-tasks-complete` | Queue is complete (all COMPLETE/FAILED) AND at least one task was completed |
+| `cost-exceeded` | `totalSpendUsd >= maxCostUsd` (checked after execute phase and after cost phase) |
+| `max-iterations` | Loop counter reaches `maxIterations` |
+
+---
+
+## Configuration
+
+All configuration lives in `LoopConfig`. Set via environment variables when using the default `index.ts` entry point.
+
+| Env var | Default | Description |
+|---------|---------|-------------|
+| `GOAL` | `'Build a production-ready stock fundamental analysis application'` | What the loop tries to build |
+| `PROJECT_ID` | `project-<timestamp>` | Unique identifier for memory persistence |
+| `MAX_ITERATIONS` | `20` | Hard cap on loop iterations |
+| `MAX_COST_USD` | `10` | Spend cap in USD as reported by the claude CLI (subscription billing — governs usage, not direct charges) |
+| `TARGET_COVERAGE` | `95` | Test coverage % needed to exit cleanly |
+| `DRY_RUN` | `false` | Set to `true` to skip all claude CLI calls and file writes |
+| `LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARN` / `ERROR` |
+
+Budget constants (not env-configurable without code change):
+
+```ts
+// src/core/config.ts
+DEFAULT_BUDGET = {
+  maxCostUsd: 10.0,
+  maxInputTokensPerCall: 100_000,
+  maxOutputTokensPerCall: 8_000,
+  warnThresholdPercent: 80,
+}
+```
+
+Model: determined by the `claude` CLI session (whichever model your Claude.ai subscription uses by default).
+
+---
+
+## Running Locally
+
+**Prerequisites**: Node.js 20+, the `claude` CLI installed and logged in (`claude login`).
+
+No `ANTHROPIC_API_KEY` is required. The orchestrator calls Claude via the `claude` CLI, which uses your Claude.ai subscription (Pro/Teams) for authentication.
+
+```bash
+cd engine
+
+# Install dependencies
+npm install
+
+# Build TypeScript
+npm run build
+
+# Dry run (no Claude calls, no file writes)
+DRY_RUN=true npm start
+
+# Real run with a custom goal
+GOAL="Build a REST API for user authentication" npm start
+
+# Override budget and iteration limit
+GOAL="..." MAX_COST_USD=5 MAX_ITERATIONS=10 npm start
+```
+
+Generated code is written to `../workspace/` (sibling of the `engine/` directory).
+
+---
+
+## Testing
+
+```bash
+cd engine
+
+# Run all tests with coverage
+npm test
+
+# Watch mode
+npm run test:watch
+```
+
+**Coverage thresholds** (enforced by jest):
+
+| Metric | Threshold |
+|--------|-----------|
+| Lines | 70% |
+| Functions | 70% |
+| Branches | 60% |
+| Statements | 70% |
+
+**Test isolation**: each test suite writes to its own temp directory (e.g. `task-queue-test-tmp/`) and cleans it up in both `beforeEach` and `afterAll`. Do not share `MemoryStore` instances or temp directories across test suites.
+
+---
+
+## Extending the System
+
+### Swap in a different model
+
+Pass `--model <model-id>` in the `spawn` call inside `src/components/claude-cli.ts`. The default is the model your `claude` CLI session is configured to use.
+
+### Add a new phase to the loop
+
+1. Add the method to `LoopController` following the existing phase pattern.
+2. Call it inside the `while` loop in `run()`.
+3. If it can trigger an early exit, return a `LoopExitReason`; otherwise return `null`.
+
+### Add a new exit condition
+
+Add a branch to `checkExitConditions()` and add the new reason string to the `LoopExitReason.reason` union type in `src/core/types.ts`.
+
+### Change the planner prompt
+
+Edit `SYSTEM_PROMPT` in `src/components/planner.ts`. The JSON schema returned by the model must match `PlannerResponse`; update both if you change the shape.
+
+### Persist additional data
+
+Add a new subdirectory constant to `MemoryStore.dirs`, create the directory in the constructor, and add typed `save*` / `load*` methods following the existing pattern.

package/dist/components/claude-cli.d.ts

@@ -0,0 +1,14 @@
+export interface CliResult {
+    text: string;
+    costUsd: number;
+}
+/**
+ * Call Claude via the `claude` CLI (uses Claude.ai subscription auth —
+ * no ANTHROPIC_API_KEY required).
+ *
+ * Spawns: claude -p --output-format json --dangerously-skip-permissions
+ * Sends the combined system+user prompt via stdin.
+ * Returns the result text and reported cost.
+ */
+export declare function callClaude(systemPrompt: string, userPrompt: string, timeoutMs?: number): Promise<CliResult>;
+//# sourceMappingURL=claude-cli.d.ts.map

package/dist/components/claude-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli.d.ts","sourceRoot":"","sources":["../../src/components/claude-cli.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,EAClB,SAAS,SAAU,GAClB,OAAO,CAAC,SAAS,CAAC,CA8CpB"}

package/dist/components/claude-cli.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callClaude = callClaude;
+const child_process_1 = require("child_process");
+/**
+ * Call Claude via the `claude` CLI (uses Claude.ai subscription auth —
+ * no ANTHROPIC_API_KEY required).
+ *
+ * Spawns: claude -p --output-format json --dangerously-skip-permissions
+ * Sends the combined system+user prompt via stdin.
+ * Returns the result text and reported cost.
+ */
+async function callClaude(systemPrompt, userPrompt, timeoutMs = 180000) {
+    const fullPrompt = `${systemPrompt}\n\n---\n\n${userPrompt}`;
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)('claude', ['-p', '--output-format', 'json', '--dangerously-skip-permissions'], { stdio: ['pipe', 'pipe', 'pipe'] });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            reject(new Error(`claude CLI timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code !== 0) {
+                reject(new Error(`claude exited ${code}: ${stderr.slice(0, 500)}`));
+                return;
+            }
+            try {
+                const envelope = JSON.parse(stdout.trim());
+                resolve({
+                    text: envelope.result ?? '',
+                    costUsd: typeof envelope.total_cost_usd === 'number' ? envelope.total_cost_usd : 0,
+                });
+            }
+            catch (err) {
+                reject(new Error(`Failed to parse claude CLI output: ${err}. stdout: ${stdout.slice(0, 300)}`));
+            }
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            reject(new Error(`Failed to spawn claude CLI: ${err.message}. Is claude installed and on PATH?`));
+        });
+        child.stdin.write(fullPrompt);
+        child.stdin.end();
+    });
+}
+//# sourceMappingURL=claude-cli.js.map

package/dist/components/claude-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-cli.js","sourceRoot":"","sources":["../../src/components/claude-cli.ts"],"names":[],"mappings":";;AAeA,gCAkDC;AAjED,iDAAsC;AAOtC;;;;;;;GAOG;AACI,KAAK,UAAU,UAAU,CAC9B,YAAoB,EACpB,UAAkB,EAClB,SAAS,GAAG,MAAO;IAEnB,MAAM,UAAU,GAAG,GAAG,YAAY,cAAc,UAAU,EAAE,CAAC;IAE7D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,IAAA,qBAAK,EACjB,QAAQ,EACR,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,gCAAgC,CAAC,EACnE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CACpC,CAAC;QAEF,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAEhB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,GAAG,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAE5E,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YACtB,MAAM,CAAC,IAAI,KAAK,CAAC,8BAA8B,SAAS,IAAI,CAAC,CAAC,CAAC;QACjE,CAAC,EAAE,SAAS,CAAC,CAAC;QAEd,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACzB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,MAAM,CAAC,IAAI,KAAK,CAAC,iBAAiB,IAAI,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;gBACpE,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;gBAC3C,OAAO,CAAC;oBACN,IAAI,EAAE,QAAQ,CAAC,MAAM,IAAI,EAAE;oBAC3B,OAAO,EAAE,OAAO,QAAQ,CAAC,cAAc,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;iBACnF,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,CAAC,IAAI,KAAK,CAAC,sCAAsC,GAAG,aAAa,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;YAClG,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;YACxB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,IAAI,KAAK,CAAC,+BAA+B,GAAG,CAAC,OAAO,oCAAoC,CAAC,CAAC,CAAC;QACpG,CAAC,CAAC,CAAC;QAEH,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QAC9B,KAAK,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/components/cost-optimizer.d.ts

@@ -0,0 +1,43 @@
+import { CostBudget, CostEstimate, TokenUsage } from '../core/types';
+import { MemoryStore } from './memory-store';
+/**
+ * Tracks cumulative token spend, enforces budget, and provides a hash-keyed
+ * response cache so identical prompts never hit the API twice.
+ */
+export declare class CostOptimizer {
+    private readonly budget;
+    private readonly memory;
+    private totalInputTokens;
+    private totalOutputTokens;
+    private directCostUsd;
+    private callCount;
+    private readonly log;
+    constructor(budget: CostBudget, memory: MemoryStore);
+    /** Deterministic cache key from prompt text + any context strings. */
+    buildCacheKey(prompt: string, ...contextParts: string[]): string;
+    getCachedResponse(cacheKey: string): string | null;
+    putCachedResponse(cacheKey: string, response: string): void;
+    /**
+     * Call before every LLM request.
+     * Returns a CostEstimate that includes a recommendedAction.
+     * Callers MUST respect 'skip' — it means the budget is exhausted.
+     */
+    estimate(promptText: string, estimatedOutputTokens: number, cacheKey: string): CostEstimate;
+    /** Record actual usage after an API call completes (token-based billing). */
+    recordUsage(usage: TokenUsage): void;
+    /** Record cost reported directly by the claude CLI (subscription billing). */
+    recordCost(usd: number): void;
+    totalSpend(): number;
+    isBudgetExceeded(): boolean;
+    getStats(): {
+        callCount: number;
+        totalInputTokens: number;
+        totalOutputTokens: number;
+        totalSpendUsd: number;
+        remainingBudgetUsd: number;
+        cacheEntries: number;
+    };
+    /** Sync cumulative totals from a ProjectState so they survive process restarts. */
+    restoreFromState(inputTokens: number, outputTokens: number): void;
+}
+//# sourceMappingURL=cost-optimizer.d.ts.map

package/dist/components/cost-optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-optimizer.d.ts","sourceRoot":"","sources":["../../src/components/cost-optimizer.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C;;;GAGG;AACH,qBAAa,aAAa;IAQtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IARzB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAiC;gBAGlC,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,WAAW;IAKtC,sEAAsE;IACtE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,YAAY,EAAE,MAAM,EAAE,GAAG,MAAM;IAKhE,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAQlD,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAM3D;;;;OAIG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,qBAAqB,EAAE,MAAM,EAC7B,QAAQ,EAAE,MAAM,GACf,YAAY;IA2Df,6EAA6E;IAC7E,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAYpC,8EAA8E;IAC9E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAY7B,UAAU,IAAI,MAAM;IAIpB,gBAAgB,IAAI,OAAO;IAI3B,QAAQ,IAAI;QACV,SAAS,EAAE,MAAM,CAAC;QAClB,gBAAgB,EAAE,MAAM,CAAC;QACzB,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,EAAE,MAAM,CAAC;QACtB,kBAAkB,EAAE,MAAM,CAAC;QAC3B,YAAY,EAAE,MAAM,CAAC;KACtB;IAYD,mFAAmF;IACnF,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;CAIlE"}

package/dist/components/cost-optimizer.js

@@ -0,0 +1,140 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CostOptimizer = void 0;
+const crypto_1 = require("crypto");
+const config_1 = require("../core/config");
+const logger_1 = require("../core/logger");
+/**
+ * Tracks cumulative token spend, enforces budget, and provides a hash-keyed
+ * response cache so identical prompts never hit the API twice.
+ */
+class CostOptimizer {
+    constructor(budget, memory) {
+        this.budget = budget;
+        this.memory = memory;
+        this.totalInputTokens = 0;
+        this.totalOutputTokens = 0;
+        this.directCostUsd = 0;
+        this.callCount = 0;
+        this.log = (0, logger_1.createLogger)('CostOptimizer');
+    }
+    // ── Cache ──────────────────────────────────────────────────────────────────
+    /** Deterministic cache key from prompt text + any context strings. */
+    buildCacheKey(prompt, ...contextParts) {
+        const raw = [prompt, ...contextParts].join('\n---\n');
+        return (0, crypto_1.createHash)('sha256').update(raw).digest('hex').slice(0, 32);
+    }
+    getCachedResponse(cacheKey) {
+        const hit = this.memory.getCached(cacheKey);
+        if (hit) {
+            this.log.debug('Cache hit', { cacheKey: cacheKey.slice(0, 8) + '…' });
+        }
+        return hit;
+    }
+    putCachedResponse(cacheKey, response) {
+        this.memory.putCache(cacheKey, response);
+    }
+    // ── Budget ─────────────────────────────────────────────────────────────────
+    /**
+     * Call before every LLM request.
+     * Returns a CostEstimate that includes a recommendedAction.
+     * Callers MUST respect 'skip' — it means the budget is exhausted.
+     */
+    estimate(promptText, estimatedOutputTokens, cacheKey) {
+        const isHit = this.memory.getCached(cacheKey) !== null;
+        if (isHit) {
+            return {
+                cacheKey,
+                isCacheHit: true,
+                inputTokens: 0,
+                outputTokens: 0,
+                estimatedCostUsd: 0,
+                recommendedAction: 'cache-hit',
+                reason: 'Response already cached — no API call needed',
+            };
+        }
+        // rough token estimate: 4 chars ≈ 1 token
+        const estimatedInput = Math.ceil(promptText.length / 4);
+        const estimatedCost = (0, config_1.calcCost)(estimatedInput, estimatedOutputTokens);
+        const currentSpend = this.totalSpend();
+        const remainingBudget = this.budget.maxCostUsd - currentSpend;
+        if (estimatedCost > remainingBudget) {
+            return {
+                cacheKey,
+                isCacheHit: false,
+                inputTokens: estimatedInput,
+                outputTokens: estimatedOutputTokens,
+                estimatedCostUsd: estimatedCost,
+                recommendedAction: 'skip',
+                reason: `Budget exhausted — $${currentSpend.toFixed(4)} of $${this.budget.maxCostUsd} spent`,
+            };
+        }
+        const spendPercent = (currentSpend / this.budget.maxCostUsd) * 100;
+        if (spendPercent >= this.budget.warnThresholdPercent) {
+            this.log.warn('Approaching budget limit', {
+                spentUsd: currentSpend.toFixed(4),
+                limitUsd: this.budget.maxCostUsd,
+                pct: spendPercent.toFixed(1) + '%',
+            });
+        }
+        const action = estimatedInput > this.budget.maxInputTokensPerCall ? 'optimize' : 'proceed';
+        return {
+            cacheKey,
+            isCacheHit: false,
+            inputTokens: estimatedInput,
+            outputTokens: estimatedOutputTokens,
+            estimatedCostUsd: estimatedCost,
+            recommendedAction: action,
+            reason: action === 'optimize'
+                ? `Prompt is large (${estimatedInput} estimated tokens) — consider trimming`
+                : 'Within limits — proceed',
+        };
+    }
+    /** Record actual usage after an API call completes (token-based billing). */
+    recordUsage(usage) {
+        this.totalInputTokens += usage.inputTokens;
+        this.totalOutputTokens += usage.outputTokens;
+        this.callCount++;
+        this.log.debug('Usage recorded', {
+            callCount: this.callCount,
+            totalInputTokens: this.totalInputTokens,
+            totalOutputTokens: this.totalOutputTokens,
+            totalSpendUsd: this.totalSpend().toFixed(4),
+        });
+    }
+    /** Record cost reported directly by the claude CLI (subscription billing). */
+    recordCost(usd) {
+        this.directCostUsd += usd;
+        this.callCount++;
+        this.log.debug('CLI cost recorded', {
+            callCount: this.callCount,
+            directCostUsd: this.directCostUsd.toFixed(4),
+            totalSpendUsd: this.totalSpend().toFixed(4),
+        });
+    }
+    // ── Stats ──────────────────────────────────────────────────────────────────
+    totalSpend() {
+        return (0, config_1.calcCost)(this.totalInputTokens, this.totalOutputTokens) + this.directCostUsd;
+    }
+    isBudgetExceeded() {
+        return this.totalSpend() >= this.budget.maxCostUsd;
+    }
+    getStats() {
+        const totalSpendUsd = this.totalSpend();
+        return {
+            callCount: this.callCount,
+            totalInputTokens: this.totalInputTokens,
+            totalOutputTokens: this.totalOutputTokens,
+            totalSpendUsd,
+            remainingBudgetUsd: Math.max(0, this.budget.maxCostUsd - totalSpendUsd),
+            cacheEntries: this.memory.getCacheSize(),
+        };
+    }
+    /** Sync cumulative totals from a ProjectState so they survive process restarts. */
+    restoreFromState(inputTokens, outputTokens) {
+        this.totalInputTokens = inputTokens;
+        this.totalOutputTokens = outputTokens;
+    }
+}
+exports.CostOptimizer = CostOptimizer;
+//# sourceMappingURL=cost-optimizer.js.map

package/dist/components/cost-optimizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost-optimizer.js","sourceRoot":"","sources":["../../src/components/cost-optimizer.ts"],"names":[],"mappings":";;;AAAA,mCAAoC;AAEpC,2CAA0C;AAE1C,2CAA8C;AAE9C;;;GAGG;AACH,MAAa,aAAa;IAOxB,YACmB,MAAkB,EAClB,MAAmB;QADnB,WAAM,GAAN,MAAM,CAAY;QAClB,WAAM,GAAN,MAAM,CAAa;QAR9B,qBAAgB,GAAG,CAAC,CAAC;QACrB,sBAAiB,GAAG,CAAC,CAAC;QACtB,kBAAa,GAAG,CAAC,CAAC;QAClB,cAAS,GAAG,CAAC,CAAC;QACL,QAAG,GAAG,IAAA,qBAAY,EAAC,eAAe,CAAC,CAAC;IAKlD,CAAC;IAEJ,8EAA8E;IAE9E,sEAAsE;IACtE,aAAa,CAAC,MAAc,EAAE,GAAG,YAAsB;QACrD,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,YAAY,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACtD,OAAO,IAAA,mBAAU,EAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,iBAAiB,CAAC,QAAgB;QAChC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAC5C,IAAI,GAAG,EAAE,CAAC;YACR,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,iBAAiB,CAAC,QAAgB,EAAE,QAAgB;QAClD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAED,8EAA8E;IAE9E;;;;OAIG;IACH,QAAQ,CACN,UAAkB,EAClB,qBAA6B,EAC7B,QAAgB;QAEhB,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;QAEvD,IAAI,KAAK,EAAE,CAAC;YACV,OAAO;gBACL,QAAQ;gBACR,UAAU,EAAE,IAAI;gBAChB,WAAW,EAAE,CAAC;gBACd,YAAY,EAAE,CAAC;gBACf,gBAAgB,EAAE,CAAC;gBACnB,iBAAiB,EAAE,WAAW;gBAC9B,MAAM,EAAE,8CAA8C;aACvD,CAAC;QACJ,CAAC;QAED,0CAA0C;QAC1C,MAAM,cAAc,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACxD,MAAM,aAAa,GAAG,IAAA,iBAAQ,EAAC,cAAc,EAAE,qBAAqB,CAAC,CAAC;QACtE,MAAM,YAAY,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACvC,MAAM,eAAe,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,YAAY,CAAC;QAE9D,IAAI,aAAa,GAAG,eAAe,EAAE,CAAC;YACpC,OAAO;gBACL,QAAQ;gBACR,UAAU,EAAE,KAAK;gBACjB,WAAW,EAAE,cAAc;gBAC3B,YAAY,EAAE,qBAAqB;gBACnC,gBAAgB,EAAE,aAAa;gBAC/B,iBAAiB,EAAE,MAAM;gBACzB,MAAM,EAAE,uBAAuB,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,UAAU,QAAQ;aAC7F,CAAC;QACJ,CAAC;QAED,MAAM,YAAY,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,GAAG,CAAC;QACnE,IAAI,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,oBAAoB,EAAE,CAAC;YACrD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,0BAA0B,EAAE;gBACxC,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC;gBACjC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU;gBAChC,GAAG,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG;aACnC,CAAC,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GACV,cAAc,GAAG,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;QAE9E,OAAO;YACL,QAAQ;YACR,UAAU,EAAE,KAAK;YACjB,WAAW,EAAE,cAAc;YAC3B,YAAY,EAAE,qBAAqB;YACnC,gBAAgB,EAAE,aAAa;YAC/B,iBAAiB,EAAE,MAAM;YACzB,MAAM,EACJ,MAAM,KAAK,UAAU;gBACnB,CAAC,CAAC,oBAAoB,cAAc,wCAAwC;gBAC5E,CAAC,CAAC,yBAAyB;SAChC,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,WAAW,CAAC,KAAiB;QAC3B,IAAI,CAAC,gBAAgB,IAAI,KAAK,CAAC,WAAW,CAAC;QAC3C,IAAI,CAAC,iBAAiB,IAAI,KAAK,CAAC,YAAY,CAAC;QAC7C,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,gBAAgB,EAAE;YAC/B,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,aAAa,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,UAAU,CAAC,GAAW;QACpB,IAAI,CAAC,aAAa,IAAI,GAAG,CAAC;QAC1B,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,mBAAmB,EAAE;YAClC,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,aAAa,EAAE,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC;YAC5C,aAAa,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;SAC5C,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAE9E,UAAU;QACR,OAAO,IAAA,iBAAQ,EAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,iBAAiB,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC;IACtF,CAAC;IAED,gBAAgB;QACd,OAAO,IAAI,CAAC,UAAU,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IACrD,CAAC;IAED,QAAQ;QAQN,MAAM,aAAa,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;QACxC,OAAO;YACL,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;YACvC,iBAAiB,EAAE,IAAI,CAAC,iBAAiB;YACzC,aAAa;YACb,kBAAkB,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,GAAG,aAAa,CAAC;YACvE,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE;SACzC,CAAC;IACJ,CAAC;IAED,mFAAmF;IACnF,gBAAgB,CAAC,WAAmB,EAAE,YAAoB;QACxD,IAAI,CAAC,gBAAgB,GAAG,WAAW,CAAC;QACpC,IAAI,CAAC,iBAAiB,GAAG,YAAY,CAAC;IACxC,CAAC;CACF;AAhKD,sCAgKC"}

package/dist/components/executor.d.ts

@@ -0,0 +1,18 @@
+import { Task, TaskResult } from '../core/types';
+import { CostOptimizer } from './cost-optimizer';
+import { MemoryStore } from './memory-store';
+export declare class Executor {
+    private readonly workspaceDir;
+    private readonly optimizer;
+    private readonly memory;
+    private readonly dryRun;
+    private readonly log;
+    constructor(workspaceDir: string, optimizer: CostOptimizer, memory: MemoryStore, dryRun?: boolean);
+    execute(task: Task): Promise<TaskResult>;
+    private buildContext;
+    private callApi;
+    private parse;
+    private apply;
+    private dryRunResponse;
+}
+//# sourceMappingURL=executor.d.ts.map

package/dist/components/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/components/executor.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAiC7C,qBAAa,QAAQ;IAIjB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IANzB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;gBAG7B,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,WAAW,EACnB,MAAM,UAAQ;IAK3B,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,UAAU,CAAC;IA0C9C,OAAO,CAAC,YAAY;YAuBN,OAAO;IASrB,OAAO,CAAC,KAAK;YAKC,KAAK;IA0CnB,OAAO,CAAC,cAAc;CAavB"}