conatus 0.1.0

package/dist/event-server.js

@@ -0,0 +1,69 @@
+import * as http from "node:http";
+import { MotivaEventSchema } from "./types/drive.js";
+export class EventServer {
+    server = null;
+    driveSystem;
+    host;
+    port;
+    constructor(driveSystem, config) {
+        this.driveSystem = driveSystem;
+        this.host = config?.host ?? "127.0.0.1";
+        this.port = config?.port ?? 41700;
+    }
+    /** Start HTTP server */
+    async start() {
+        return new Promise((resolve, reject) => {
+            this.server = http.createServer((req, res) => this.handleRequest(req, res));
+            this.server.listen(this.port, this.host, () => resolve());
+            this.server.on("error", reject);
+        });
+    }
+    /** Stop HTTP server */
+    async stop() {
+        return new Promise((resolve) => {
+            if (!this.server) {
+                resolve();
+                return;
+            }
+            this.server.close(() => resolve());
+        });
+    }
+    /** Handle incoming HTTP request */
+    handleRequest(req, res) {
+        // Only accept POST /events
+        if (req.method !== "POST" || req.url !== "/events") {
+            res.writeHead(404, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Not found" }));
+            return;
+        }
+        let body = "";
+        req.on("data", (chunk) => {
+            body += chunk;
+        });
+        req.on("end", () => {
+            try {
+                const data = JSON.parse(body);
+                const event = MotivaEventSchema.parse(data);
+                // Write event to file queue (DriveSystem will pick it up)
+                this.driveSystem.writeEvent(event);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ status: "accepted", event_type: event.type }));
+            }
+            catch (err) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Invalid event", details: String(err) }));
+            }
+        });
+    }
+    /** Check if server is running */
+    isRunning() {
+        return this.server !== null && this.server.listening;
+    }
+    getPort() {
+        return this.port;
+    }
+    getHost() {
+        return this.host;
+    }
+}
+//# sourceMappingURL=event-server.js.map

package/dist/event-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-server.js","sourceRoot":"","sources":["../src/event-server.ts"],"names":[],"mappings":"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"}

package/dist/execution/adapter-layer.d.ts

@@ -0,0 +1,88 @@
+export interface AgentTask {
+    /** Session context + task instructions to pass to the agent */
+    prompt: string;
+    /** Timeout in milliseconds */
+    timeout_ms: number;
+    /** Which adapter to use for this task */
+    adapter_type: string;
+}
+export interface AgentResult {
+    /** Whether the task completed without error or timeout */
+    success: boolean;
+    /** stdout from CLI / LLM response text */
+    output: string;
+    /** stderr / error message, null on success */
+    error: string | null;
+    /** Process exit code for CLI adapters; null for API adapters */
+    exit_code: number | null;
+    /** Wall-clock time from execute() call to resolution, in milliseconds */
+    elapsed_ms: number;
+    /** How execution ended */
+    stopped_reason: "completed" | "timeout" | "error";
+    /**
+     * Whether the adapter actually modified any files, as detected by git diff --stat.
+     * undefined = check was not performed (e.g., not a git repo, or adapter skipped).
+     * true = files were changed; false = adapter reported success but no files changed.
+     */
+    filesChanged?: boolean;
+}
+export interface IAdapter {
+    execute(task: AgentTask): Promise<AgentResult>;
+    readonly adapterType: string;
+    readonly capabilities?: readonly string[];
+    /** Optional: return titles of existing tasks for dedup context injection into prompts. */
+    listExistingTasks?(): Promise<string[]>;
+    /** Optional: adapter-specific duplicate detection. Returns true if a duplicate exists. Fail-open: return false on error. */
+    checkDuplicate?(task: AgentTask): Promise<boolean>;
+}
+type CircuitState = "closed" | "open" | "half_open";
+/**
+ * Registry that maps adapter type strings to IAdapter instances.
+ * Tracks per-adapter circuit breaker state for fault tolerance.
+ */
+export declare class AdapterRegistry {
+    private readonly adapters;
+    private readonly circuitBreakers;
+    /**
+     * Register an adapter. Overwrites any previously registered adapter
+     * for the same adapterType.
+     */
+    register(adapter: IAdapter): void;
+    /**
+     * Retrieve an adapter by type string.
+     * Throws if no adapter is registered for that type.
+     */
+    getAdapter(type: string): IAdapter;
+    /**
+     * Returns a sorted list of all registered adapter type strings.
+     */
+    listAdapters(): string[];
+    /**
+     * Returns capabilities for all registered adapters.
+     * For adapters without capabilities defined, returns ["general_purpose"] as default.
+     */
+    getAdapterCapabilities(): Array<{
+        adapterType: string;
+        capabilities: string[];
+    }>;
+    private getCircuitBreaker;
+    /** Reset failure count and set circuit to closed after a successful execution. */
+    recordSuccess(adapterName: string): void;
+    /** Increment failure count; open the circuit when threshold is reached. */
+    recordFailure(adapterName: string): void;
+    /**
+     * Returns false if the circuit is open and cooldown has not elapsed.
+     * If cooldown has passed, transitions to half_open and returns true (probe attempt).
+     */
+    isAvailable(adapterName: string): boolean;
+    /** Returns the current circuit state for inspection/testing. */
+    getCircuitState(adapterName: string): CircuitState;
+    /**
+     * Finds the first registered adapter whose capabilities include ALL required strings.
+     * Excludes the named adapter and any adapter whose circuit is open.
+     * Returns the adapter name, or null if no match found.
+     */
+    selectByCapability(required: string[], excludeAdapter?: string): string | null;
+}
+export {};
+//# sourceMappingURL=adapter-layer.d.ts.map

package/dist/execution/adapter-layer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-layer.d.ts","sourceRoot":"","sources":["../../src/execution/adapter-layer.ts"],"names":[],"mappings":"AAWA,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,8BAA8B;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,gEAAgE;IAChE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,cAAc,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;IAClD;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAID,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,0FAA0F;IAC1F,iBAAiB,CAAC,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACxC,4HAA4H;IAC5H,cAAc,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACpD;AAID,KAAK,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAcpD;;;GAGG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA0C;IAE1E;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI;IAIjC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAWlC;;OAEG;IACH,YAAY,IAAI,MAAM,EAAE;IAIxB;;;OAGG;IACH,sBAAsB,IAAI,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IAShF,OAAO,CAAC,iBAAiB;IAYzB,kFAAkF;IAClF,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAMxC,2EAA2E;IAC3E,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IASxC;;;OAGG;IACH,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAazC,gEAAgE;IAChE,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY;IAMlD;;;;OAIG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;CAgB/E"}

package/dist/execution/adapter-layer.js

@@ -0,0 +1,123 @@
+// ─── AdapterLayer ───
+//
+// Defines the IAdapter interface, AgentTask/AgentResult types, and
+// AdapterRegistry for managing multiple adapter implementations.
+// This is the abstraction layer that isolates TaskLifecycle from
+// concrete agent implementations (Claude Code CLI, Claude API, etc.).
+import { AdapterError } from "../utils/errors.js";
+const FAILURE_THRESHOLD = 5;
+const DEFAULT_COOLDOWN_MS = 60_000;
+// ─── AdapterRegistry ───
+/**
+ * Registry that maps adapter type strings to IAdapter instances.
+ * Tracks per-adapter circuit breaker state for fault tolerance.
+ */
+export class AdapterRegistry {
+    adapters = new Map();
+    circuitBreakers = new Map();
+    /**
+     * Register an adapter. Overwrites any previously registered adapter
+     * for the same adapterType.
+     */
+    register(adapter) {
+        this.adapters.set(adapter.adapterType, adapter);
+    }
+    /**
+     * Retrieve an adapter by type string.
+     * Throws if no adapter is registered for that type.
+     */
+    getAdapter(type) {
+        const adapter = this.adapters.get(type);
+        if (!adapter) {
+            throw new AdapterError(`AdapterRegistry: no adapter registered for type "${type}". ` +
+                `Available types: [${this.listAdapters().join(", ")}]`);
+        }
+        return adapter;
+    }
+    /**
+     * Returns a sorted list of all registered adapter type strings.
+     */
+    listAdapters() {
+        return Array.from(this.adapters.keys()).sort();
+    }
+    /**
+     * Returns capabilities for all registered adapters.
+     * For adapters without capabilities defined, returns ["general_purpose"] as default.
+     */
+    getAdapterCapabilities() {
+        return Array.from(this.adapters.entries()).map(([type, adapter]) => ({
+            adapterType: type,
+            capabilities: adapter.capabilities ? Array.from(adapter.capabilities) : ["general_purpose"],
+        }));
+    }
+    // ─── Circuit Breaker Methods ───
+    getCircuitBreaker(adapterName) {
+        if (!this.circuitBreakers.has(adapterName)) {
+            this.circuitBreakers.set(adapterName, {
+                state: "closed",
+                failure_count: 0,
+                last_failure_at: 0,
+                cooldown_ms: DEFAULT_COOLDOWN_MS,
+            });
+        }
+        return this.circuitBreakers.get(adapterName);
+    }
+    /** Reset failure count and set circuit to closed after a successful execution. */
+    recordSuccess(adapterName) {
+        const cb = this.getCircuitBreaker(adapterName);
+        cb.state = "closed";
+        cb.failure_count = 0;
+    }
+    /** Increment failure count; open the circuit when threshold is reached. */
+    recordFailure(adapterName) {
+        const cb = this.getCircuitBreaker(adapterName);
+        cb.failure_count += 1;
+        cb.last_failure_at = Date.now();
+        if (cb.failure_count >= FAILURE_THRESHOLD) {
+            cb.state = "open";
+        }
+    }
+    /**
+     * Returns false if the circuit is open and cooldown has not elapsed.
+     * If cooldown has passed, transitions to half_open and returns true (probe attempt).
+     */
+    isAvailable(adapterName) {
+        const cb = this.getCircuitBreaker(adapterName);
+        if (cb.state !== "open") {
+            return true;
+        }
+        const elapsed = Date.now() - cb.last_failure_at;
+        if (elapsed >= cb.cooldown_ms) {
+            cb.state = "half_open";
+            return true;
+        }
+        return false;
+    }
+    /** Returns the current circuit state for inspection/testing. */
+    getCircuitState(adapterName) {
+        return this.getCircuitBreaker(adapterName).state;
+    }
+    // ─── Capability Matching ───
+    /**
+     * Finds the first registered adapter whose capabilities include ALL required strings.
+     * Excludes the named adapter and any adapter whose circuit is open.
+     * Returns the adapter name, or null if no match found.
+     */
+    selectByCapability(required, excludeAdapter) {
+        for (const [name, adapter] of this.adapters) {
+            if (excludeAdapter !== undefined && name === excludeAdapter) {
+                continue;
+            }
+            if (!this.isAvailable(name)) {
+                continue;
+            }
+            const caps = adapter.capabilities ? Array.from(adapter.capabilities) : ["general_purpose"];
+            const hasAll = required.every((r) => caps.includes(r));
+            if (hasAll) {
+                return name;
+            }
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=adapter-layer.js.map

package/dist/execution/adapter-layer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-layer.js","sourceRoot":"","sources":["../../src/execution/adapter-layer.ts"],"names":[],"mappings":"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"}

package/dist/execution/checkpoint-manager.d.ts

@@ -0,0 +1,49 @@
+import { StateManager } from '../state-manager.js';
+import { Checkpoint, CheckpointIndex } from '../types/checkpoint.js';
+import type { IPromptGateway } from '../prompt/gateway.js';
+interface LLMClient {
+    chat(messages: Array<{
+        role: string;
+        content: string;
+    }>): Promise<{
+        content: string;
+    }>;
+}
+interface Logger {
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+interface CheckpointManagerDeps {
+    stateManager: StateManager;
+    llmClient?: LLMClient;
+    logger?: Logger;
+    gateway?: IPromptGateway;
+}
+export declare class CheckpointManager {
+    private readonly deps;
+    constructor(deps: CheckpointManagerDeps);
+    private indexPath;
+    private checkpointPath;
+    private readIndex;
+    private writeIndex;
+    saveCheckpoint(params: {
+        goalId: string;
+        taskId: string;
+        agentId: string;
+        sessionContextSnapshot: string;
+        intermediateResults?: string[];
+        metadata?: Record<string, unknown>;
+    }): Promise<Checkpoint>;
+    loadCheckpoint(goalId: string, taskId?: string): Promise<Checkpoint | null>;
+    loadAndAdaptCheckpoint(goalId: string, currentAgentId: string, taskId?: string): Promise<{
+        checkpoint: Checkpoint;
+        adaptedContext: string;
+        wasAdapted: boolean;
+    } | null>;
+    listCheckpoints(goalId: string): Promise<CheckpointIndex['checkpoints']>;
+    deleteCheckpoint(goalId: string, checkpointId: string): Promise<void>;
+    garbageCollect(goalId: string, maxAgeDays?: number): Promise<number>;
+}
+export {};
+//# sourceMappingURL=checkpoint-manager.d.ts.map

package/dist/execution/checkpoint-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-manager.d.ts","sourceRoot":"","sources":["../../src/execution/checkpoint-manager.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EACL,UAAU,EAEV,eAAe,EAEhB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,UAAU,SAAS;IACjB,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACxF;AAED,UAAU,MAAM;IACd,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAMD,UAAU,qBAAqB;IAC7B,YAAY,EAAE,YAAY,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,qBAAqB;IAExD,OAAO,CAAC,SAAS,CAA0D;IAC3E,OAAO,CAAC,cAAc,CACyB;YAEjC,SAAS;YAWT,UAAU;IAIlB,cAAc,CAAC,MAAM,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,sBAAsB,EAAE,MAAM,CAAC;QAC/B,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;QAC/B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC,UAAU,CAAC;IAkCjB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAsB3E,sBAAsB,CAC1B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;QAAE,UAAU,EAAE,UAAU,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAqCpF,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,aAAa,CAAC,CAAC;IAKxE,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcrE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,SAAI,GAAG,OAAO,CAAC,MAAM,CAAC;CAwBtE"}

package/dist/execution/checkpoint-manager.js

@@ -0,0 +1,143 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { CheckpointSchema, CheckpointIndexSchema, } from '../types/checkpoint.js';
+const CheckpointAdaptResponseSchema = z.object({
+    adapted_context: z.string(),
+});
+export class CheckpointManager {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    indexPath = (goalId) => `checkpoints/${goalId}/index.json`;
+    checkpointPath = (goalId, checkpointId) => `checkpoints/${goalId}/${checkpointId}.json`;
+    async readIndex(goalId) {
+        const raw = await this.deps.stateManager.readRaw(this.indexPath(goalId));
+        if (!raw)
+            return { goal_id: goalId, checkpoints: [] };
+        try {
+            return CheckpointIndexSchema.parse(raw);
+        }
+        catch {
+            this.deps.logger?.warn('checkpoint index parse failed, resetting', { goalId });
+            return { goal_id: goalId, checkpoints: [] };
+        }
+    }
+    async writeIndex(index) {
+        await this.deps.stateManager.writeRaw(this.indexPath(index.goal_id), index);
+    }
+    async saveCheckpoint(params) {
+        const checkpoint = CheckpointSchema.parse({
+            checkpoint_id: randomUUID(),
+            goal_id: params.goalId,
+            task_id: params.taskId,
+            agent_id: params.agentId,
+            session_context_snapshot: params.sessionContextSnapshot,
+            intermediate_results: params.intermediateResults ?? [],
+            created_at: new Date().toISOString(),
+            metadata: params.metadata ?? {},
+        });
+        await this.deps.stateManager.writeRaw(this.checkpointPath(params.goalId, checkpoint.checkpoint_id), checkpoint);
+        const index = await this.readIndex(params.goalId);
+        index.checkpoints.push({
+            checkpoint_id: checkpoint.checkpoint_id,
+            task_id: checkpoint.task_id,
+            agent_id: checkpoint.agent_id,
+            created_at: checkpoint.created_at,
+        });
+        await this.writeIndex(index);
+        this.deps.logger?.info('checkpoint saved', {
+            checkpointId: checkpoint.checkpoint_id,
+            goalId: params.goalId,
+        });
+        return checkpoint;
+    }
+    async loadCheckpoint(goalId, taskId) {
+        const index = await this.readIndex(goalId);
+        let entries = index.checkpoints;
+        if (taskId)
+            entries = entries.filter((e) => e.task_id === taskId);
+        if (entries.length === 0)
+            return null;
+        const latest = entries.reduce((a, b) => (a.created_at > b.created_at ? a : b));
+        const raw = await this.deps.stateManager.readRaw(this.checkpointPath(goalId, latest.checkpoint_id));
+        if (!raw)
+            return null;
+        try {
+            return CheckpointSchema.parse(raw);
+        }
+        catch {
+            this.deps.logger?.warn('checkpoint parse failed', {
+                checkpointId: latest.checkpoint_id,
+            });
+            return null;
+        }
+    }
+    async loadAndAdaptCheckpoint(goalId, currentAgentId, taskId) {
+        const checkpoint = await this.loadCheckpoint(goalId, taskId);
+        if (!checkpoint)
+            return null;
+        if (checkpoint.agent_id === currentAgentId) {
+            return { checkpoint, adaptedContext: checkpoint.session_context_snapshot, wasAdapted: false };
+        }
+        if (!this.deps.llmClient && !this.deps.gateway) {
+            return { checkpoint, adaptedContext: checkpoint.session_context_snapshot, wasAdapted: false };
+        }
+        const prompt = `You are helping transfer context from agent '${checkpoint.agent_id}' to agent '${currentAgentId}'. ` +
+            `Summarize and adapt the following session context and intermediate results for the new agent to continue the work.\n\n` +
+            `Context:\n${checkpoint.session_context_snapshot}\n\n` +
+            `Intermediate Results:\n${checkpoint.intermediate_results.join('\n')}`;
+        try {
+            if (this.deps.gateway) {
+                const result = await this.deps.gateway.execute({
+                    purpose: "checkpoint_adapt",
+                    goalId,
+                    additionalContext: { adapt_prompt: prompt },
+                    responseSchema: CheckpointAdaptResponseSchema,
+                });
+                return { checkpoint, adaptedContext: result.adapted_context, wasAdapted: true };
+            }
+            else {
+                const response = await this.deps.llmClient.chat([{ role: 'user', content: prompt }]);
+                return { checkpoint, adaptedContext: response.content, wasAdapted: true };
+            }
+        }
+        catch (err) {
+            this.deps.logger?.error('context adaptation failed', { error: String(err) });
+            return { checkpoint, adaptedContext: checkpoint.session_context_snapshot, wasAdapted: false };
+        }
+    }
+    async listCheckpoints(goalId) {
+        const index = await this.readIndex(goalId);
+        return index.checkpoints;
+    }
+    async deleteCheckpoint(goalId, checkpointId) {
+        const filePath = path.join(this.deps.stateManager.getBaseDir(), this.checkpointPath(goalId, checkpointId));
+        await fsp.unlink(filePath).catch((err) => {
+            console.error("[CheckpointManager] failed to delete checkpoint file:", err instanceof Error ? err.message : err);
+        });
+        const index = await this.readIndex(goalId);
+        index.checkpoints = index.checkpoints.filter((e) => e.checkpoint_id !== checkpointId);
+        await this.writeIndex(index);
+        this.deps.logger?.info('checkpoint deleted', { checkpointId, goalId });
+    }
+    async garbageCollect(goalId, maxAgeDays = 7) {
+        const index = await this.readIndex(goalId);
+        const cutoff = Date.now() - maxAgeDays * 86_400_000;
+        const toDelete = index.checkpoints.filter((e) => new Date(e.created_at).getTime() < cutoff);
+        for (const entry of toDelete) {
+            const filePath = path.join(this.deps.stateManager.getBaseDir(), this.checkpointPath(goalId, entry.checkpoint_id));
+            await fsp.unlink(filePath).catch((err) => {
+                console.error("[CheckpointManager] failed to delete checkpoint file during GC:", err instanceof Error ? err.message : err);
+            });
+        }
+        const deletedIds = new Set(toDelete.map((e) => e.checkpoint_id));
+        index.checkpoints = index.checkpoints.filter((e) => !deletedIds.has(e.checkpoint_id));
+        await this.writeIndex(index);
+        this.deps.logger?.info('garbage collected checkpoints', { goalId, count: toDelete.length });
+        return toDelete.length;
+    }
+}
+//# sourceMappingURL=checkpoint-manager.js.map

package/dist/execution/checkpoint-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint-manager.js","sourceRoot":"","sources":["../../src/execution/checkpoint-manager.ts"],"names":[],"mappings":"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"}

package/dist/execution/context-budget.d.ts

@@ -0,0 +1,35 @@
+import type { TierBudget } from "../types/memory-lifecycle.js";
+/**
+ * Distributes a total token budget across memory tiers.
+ * - core: 50% (always included items)
+ * - recall: 35% (recent observations, strategy history)
+ * - archival: remaining (completed-goal knowledge)
+ */
+export declare function allocateTierBudget(totalTokens: number): TierBudget;
+export interface BudgetAllocation {
+    goalDefinition: number;
+    observations: number;
+    knowledge: number;
+    transferKnowledge: number;
+    meta: number;
+}
+export declare function allocateBudget(totalBudget: number): BudgetAllocation;
+/** Estimate token count. Heuristic: 1 token ≈ 4 characters. */
+export declare function estimateTokens(text: string): number;
+/**
+ * Select candidates greedily by similarity (descending) until the budget is exhausted.
+ * Assumes `candidates` is already sorted by similarity descending.
+ */
+export declare function selectWithinBudget<T extends {
+    text: string;
+    similarity: number;
+}>(candidates: T[], budgetTokens: number): T[];
+/**
+ * When total actual usage exceeds the budget, reduce allocations starting from
+ * the lowest-priority categories.
+ *
+ * Priority order (highest first): observations, knowledge, goalDefinition,
+ * transferKnowledge, meta.
+ */
+export declare function trimToBudget(allocation: BudgetAllocation, actualUsage: Record<keyof BudgetAllocation, number>, totalBudget: number): BudgetAllocation;
+//# sourceMappingURL=context-budget.d.ts.map

package/dist/execution/context-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.d.ts","sourceRoot":"","sources":["../../src/execution/context-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAI/D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,UAAU,CAKlE;AAID,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,CAQpE;AAID,+DAA+D;AAC/D,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAC/E,UAAU,EAAE,CAAC,EAAE,EACf,YAAY,EAAE,MAAM,GACnB,CAAC,EAAE,CAUL;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,CAAC,MAAM,gBAAgB,EAAE,MAAM,CAAC,EACnD,WAAW,EAAE,MAAM,GAClB,gBAAgB,CAmBlB"}

package/dist/execution/context-budget.js

@@ -0,0 +1,73 @@
+// ─── Tier Budget Allocation ───
+/**
+ * Distributes a total token budget across memory tiers.
+ * - core: 50% (always included items)
+ * - recall: 35% (recent observations, strategy history)
+ * - archival: remaining (completed-goal knowledge)
+ */
+export function allocateTierBudget(totalTokens) {
+    const core = Math.floor(totalTokens * 0.50);
+    const recall = Math.floor(totalTokens * 0.35);
+    const archival = totalTokens - core - recall;
+    return { core, recall, archival };
+}
+export function allocateBudget(totalBudget) {
+    return {
+        goalDefinition: Math.floor(totalBudget * 0.20),
+        observations: Math.floor(totalBudget * 0.30),
+        knowledge: Math.floor(totalBudget * 0.30),
+        transferKnowledge: Math.floor(totalBudget * 0.15),
+        meta: Math.floor(totalBudget * 0.05),
+    };
+}
+// ─── Token Estimation ───
+/** Estimate token count. Heuristic: 1 token ≈ 4 characters. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// ─── Progressive Disclosure Selection ───
+/**
+ * Select candidates greedily by similarity (descending) until the budget is exhausted.
+ * Assumes `candidates` is already sorted by similarity descending.
+ */
+export function selectWithinBudget(candidates, budgetTokens) {
+    const selected = [];
+    let usedTokens = 0;
+    for (const candidate of candidates) {
+        const tokens = estimateTokens(candidate.text);
+        if (usedTokens + tokens > budgetTokens)
+            break;
+        selected.push(candidate);
+        usedTokens += tokens;
+    }
+    return selected;
+}
+// ─── Budget Trimming ───
+/**
+ * When total actual usage exceeds the budget, reduce allocations starting from
+ * the lowest-priority categories.
+ *
+ * Priority order (highest first): observations, knowledge, goalDefinition,
+ * transferKnowledge, meta.
+ */
+export function trimToBudget(allocation, actualUsage, totalBudget) {
+    const trimOrder = [
+        "meta",
+        "transferKnowledge",
+        "goalDefinition",
+        "knowledge",
+        "observations",
+    ];
+    const result = { ...allocation };
+    let totalUsed = Object.values(actualUsage).reduce((a, b) => a + b, 0);
+    for (const category of trimOrder) {
+        if (totalUsed <= totalBudget)
+            break;
+        const excess = totalUsed - totalBudget;
+        const reduction = Math.min(result[category], excess);
+        result[category] -= reduction;
+        totalUsed -= reduction;
+    }
+    return result;
+}
+//# sourceMappingURL=context-budget.js.map

package/dist/execution/context-budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.js","sourceRoot":"","sources":["../../src/execution/context-budget.ts"],"names":[],"mappings":"AAEA,iCAAiC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,WAAW,GAAG,IAAI,GAAG,MAAM,CAAC;IAC7C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AACpC,CAAC;AAYD,MAAM,UAAU,cAAc,CAAC,WAAmB;IAChD,OAAO;QACL,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;QAC9C,YAAY,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;QAC5C,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;QACzC,iBAAiB,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;QACjD,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,GAAG,IAAI,CAAC;KACrC,CAAC;AACJ,CAAC;AAED,2BAA2B;AAE3B,+DAA+D;AAC/D,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,2CAA2C;AAE3C;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAe,EACf,YAAoB;IAEpB,MAAM,QAAQ,GAAQ,EAAE,CAAC;IACzB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC9C,IAAI,UAAU,GAAG,MAAM,GAAG,YAAY;YAAE,MAAM;QAC9C,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzB,UAAU,IAAI,MAAM,CAAC;IACvB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,0BAA0B;AAE1B;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,UAA4B,EAC5B,WAAmD,EACnD,WAAmB;IAEnB,MAAM,SAAS,GAA+B;QAC5C,MAAM;QACN,mBAAmB;QACnB,gBAAgB;QAChB,WAAW;QACX,cAAc;KACf,CAAC;IACF,MAAM,MAAM,GAAG,EAAE,GAAG,UAAU,EAAE,CAAC;IACjC,IAAI,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAEtE,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,SAAS,IAAI,WAAW;YAAE,MAAM;QACpC,MAAM,MAAM,GAAG,SAAS,GAAG,WAAW,CAAC;QACvC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,CAAC;QACrD,MAAM,CAAC,QAAQ,CAAC,IAAI,SAAS,CAAC;QAC9B,SAAS,IAAI,SAAS,CAAC;IACzB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/execution/dimension-selector.d.ts

@@ -0,0 +1,22 @@
+import type { GapVector } from "../types/gap.js";
+import type { DriveContext } from "../types/drive.js";
+import type { Dimension } from "../types/goal.js";
+/**
+ * Confidence-tier weights for dimension selection.
+ * Mechanically-observable dimensions are prioritized over LLM-only ones.
+ */
+export declare const CONFIDENCE_WEIGHTS: Record<string, number>;
+export declare function getConfidenceWeight(dim: Dimension): number;
+/**
+ * Select the highest-priority dimension to work on based on drive scoring,
+ * weighted by observation confidence tier so that mechanically-observable
+ * dimensions are preferred over LLM-only ones at equal gap severity.
+ *
+ * @param gapVector - current gap state for the goal
+ * @param driveContext - per-dimension timing/deadline/opportunity context
+ * @param dimensions - optional goal dimensions used to apply confidence-tier weighting
+ * @returns the name of the top-ranked dimension
+ * @throws if gapVector has no gaps (empty)
+ */
+export declare function selectTargetDimension(gapVector: GapVector, driveContext: DriveContext, dimensions?: Dimension[]): string;
+//# sourceMappingURL=dimension-selector.d.ts.map