@a5c-ai/agent-runtime 5.0.1-staging.04ca6ab00d21

package/dist/session/continuityState.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * GAP-PERF-008: Structured Continuity State.
+ *
+ * Structured state that persists across session compaction. Captures
+ * key decisions, current phase, and working context for seamless
+ * resume after context compression.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTINUITY_STATE_SCHEMA_VERSION = void 0;
+exports.getContinuityStatePath = getContinuityStatePath;
+exports.getContinuityState = getContinuityState;
+exports.setCurrentPhase = setCurrentPhase;
+exports.upsertDecision = upsertDecision;
+exports.updateWorkingContext = updateWorkingContext;
+exports.buildContinuityResumePrompt = buildContinuityResumePrompt;
+const fs = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+exports.CONTINUITY_STATE_SCHEMA_VERSION = "2026.01.continuity-state-v1";
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function emptyContinuityState() {
+    return {
+        schemaVersion: exports.CONTINUITY_STATE_SCHEMA_VERSION,
+        updatedAt: new Date().toISOString(),
+        currentPhase: null,
+        decisions: [],
+        workingContext: { focus: "", blockers: [], nextSteps: [] },
+    };
+}
+async function readRaw(filePath) {
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch {
+        return emptyContinuityState();
+    }
+    try {
+        const data = JSON.parse(raw);
+        return {
+            schemaVersion: typeof data.schemaVersion === "string" ? data.schemaVersion : exports.CONTINUITY_STATE_SCHEMA_VERSION,
+            updatedAt: typeof data.updatedAt === "string" ? data.updatedAt : new Date().toISOString(),
+            currentPhase: data.currentPhase ?? null,
+            decisions: Array.isArray(data.decisions) ? data.decisions : [],
+            workingContext: data.workingContext ?? { focus: "", blockers: [], nextSteps: [] },
+        };
+    }
+    catch {
+        return emptyContinuityState();
+    }
+}
+async function writeRaw(filePath, data) {
+    const dir = path.dirname(filePath);
+    const tempPath = `${filePath}.tmp.${process.pid}`;
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(tempPath, JSON.stringify(data, null, 2), "utf8");
+    await fs.rename(tempPath, filePath);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+function getContinuityStatePath(stateDir, sessionId) {
+    return path.join(stateDir, `${sessionId}.continuity.json`);
+}
+async function getContinuityState(stateDir, sessionId) {
+    return readRaw(getContinuityStatePath(stateDir, sessionId));
+}
+async function setCurrentPhase(stateDir, sessionId, phase) {
+    const filePath = getContinuityStatePath(stateDir, sessionId);
+    const state = await readRaw(filePath);
+    state.currentPhase = { ...phase, startedAt: new Date().toISOString() };
+    state.updatedAt = new Date().toISOString();
+    await writeRaw(filePath, state);
+}
+async function upsertDecision(stateDir, sessionId, decision) {
+    const filePath = getContinuityStatePath(stateDir, sessionId);
+    const state = await readRaw(filePath);
+    const existing = state.decisions.findIndex((d) => d.key === decision.key);
+    const entry = { ...decision, madeAt: new Date().toISOString() };
+    if (existing >= 0) {
+        state.decisions[existing] = entry;
+    }
+    else {
+        state.decisions.push(entry);
+    }
+    state.updatedAt = new Date().toISOString();
+    await writeRaw(filePath, state);
+}
+async function updateWorkingContext(stateDir, sessionId, updates) {
+    const filePath = getContinuityStatePath(stateDir, sessionId);
+    const state = await readRaw(filePath);
+    if (updates.focus !== undefined)
+        state.workingContext.focus = updates.focus;
+    if (updates.blockers !== undefined)
+        state.workingContext.blockers = updates.blockers;
+    if (updates.nextSteps !== undefined)
+        state.workingContext.nextSteps = updates.nextSteps;
+    state.updatedAt = new Date().toISOString();
+    await writeRaw(filePath, state);
+}
+async function buildContinuityResumePrompt(stateDir, sessionId) {
+    const state = await getContinuityState(stateDir, sessionId);
+    const sections = [];
+    if (state.currentPhase) {
+        sections.push(`## Current Phase: ${state.currentPhase.name}\n${state.currentPhase.description}`);
+    }
+    if (state.decisions.length > 0) {
+        const items = state.decisions.map((d) => {
+            const rationale = d.rationale ? ` (${d.rationale})` : "";
+            return `- **${d.key}**: ${d.value}${rationale}`;
+        });
+        sections.push(`## Key Decisions\n${items.join("\n")}`);
+    }
+    const wc = state.workingContext;
+    if (wc.focus || wc.blockers.length > 0 || wc.nextSteps.length > 0) {
+        const parts = [];
+        if (wc.focus)
+            parts.push(`**Focus**: ${wc.focus}`);
+        if (wc.blockers.length > 0)
+            parts.push(`**Blockers**: ${wc.blockers.join(", ")}`);
+        if (wc.nextSteps.length > 0)
+            parts.push(`**Next Steps**: ${wc.nextSteps.join(", ")}`);
+        sections.push(`## Working Context\n${parts.join("\n")}`);
+    }
+    return sections.length > 0 ? sections.join("\n\n") : "";
+}

package/dist/session/cost.d.ts

@@ -0,0 +1,63 @@
+/**
+ * GAP-SESSION-004: Session-Level Cost Tracking and Budgets.
+ *
+ * Aggregates cost data from runs within a session. Supports configurable
+ * budgets with threshold alerts and auto-pause.
+ * Uses the same atomic temp-file + rename pattern as context.ts.
+ */
+export interface SessionBudget {
+    /** Maximum cost in USD. 0 = unlimited. */
+    maxCostUsd: number;
+    /** Alert threshold percentages (default: [50, 80, 100]). */
+    alertThresholds: number[];
+    /** Whether to auto-pause orchestration when budget exceeded. */
+    autoPause: boolean;
+}
+export interface SessionCostState {
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    runCosts: Array<{
+        runId: string;
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+    }>;
+    budget?: SessionBudget;
+    triggeredThresholds: number[];
+    paused: boolean;
+    lastUpdatedAt: string;
+}
+export interface SessionBudgetAlert {
+    thresholdPct: number;
+    currentCostUsd: number;
+    budgetUsd: number;
+    currentPct: number;
+    message: string;
+}
+export interface BudgetCheckResult {
+    exceeded: boolean;
+    alerts: SessionBudgetAlert[];
+    shouldPause: boolean;
+}
+export interface RunCostUpdate {
+    runId: string;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+export declare function getSessionCostPath(stateDir: string, sessionId: string): string;
+export declare function getSessionCost(stateDir: string, sessionId: string): Promise<SessionCostState>;
+export declare function updateSessionCost(stateDir: string, sessionId: string, update: RunCostUpdate): Promise<SessionCostState>;
+export declare function setSessionBudget(stateDir: string, sessionId: string, budget: SessionBudget): Promise<SessionCostState>;
+/**
+ * Pure function: evaluate budget thresholds against current cost.
+ * Returns new alerts (excluding already-triggered thresholds).
+ */
+export declare function checkBudget(costState: SessionCostState): BudgetCheckResult;
+/**
+ * Persist triggered thresholds back to cost state after checkBudget produces alerts.
+ * Call this after processing alerts to prevent re-triggering.
+ */
+export declare function markThresholdsTriggered(stateDir: string, sessionId: string, thresholds: number[]): Promise<void>;
+//# sourceMappingURL=cost.d.ts.map

package/dist/session/cost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.d.ts","sourceRoot":"","sources":["../../src/session/cost.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/F,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAwDD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAE9E;AAED,wBAAsB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAEnG;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAiC3B;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,gBAAgB,CAAC,CAO3B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,gBAAgB,GAAG,iBAAiB,CA2B1E;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,CASf"}

package/dist/session/cost.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * GAP-SESSION-004: Session-Level Cost Tracking and Budgets.
+ *
+ * Aggregates cost data from runs within a session. Supports configurable
+ * budgets with threshold alerts and auto-pause.
+ * Uses the same atomic temp-file + rename pattern as context.ts.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSessionCostPath = getSessionCostPath;
+exports.getSessionCost = getSessionCost;
+exports.updateSessionCost = updateSessionCost;
+exports.setSessionBudget = setSessionBudget;
+exports.checkBudget = checkBudget;
+exports.markThresholdsTriggered = markThresholdsTriggered;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+function emptyCostState() {
+    return {
+        totalCostUsd: 0,
+        totalInputTokens: 0,
+        totalOutputTokens: 0,
+        runCosts: [],
+        triggeredThresholds: [],
+        paused: false,
+        lastUpdatedAt: new Date().toISOString(),
+    };
+}
+async function readRaw(filePath) {
+    let raw;
+    try {
+        raw = await node_fs_1.promises.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT")
+            return emptyCostState();
+        return emptyCostState();
+    }
+    try {
+        const data = JSON.parse(raw);
+        return {
+            totalCostUsd: typeof data.totalCostUsd === "number" ? data.totalCostUsd : 0,
+            totalInputTokens: typeof data.totalInputTokens === "number" ? data.totalInputTokens : 0,
+            totalOutputTokens: typeof data.totalOutputTokens === "number" ? data.totalOutputTokens : 0,
+            runCosts: Array.isArray(data.runCosts) ? data.runCosts : [],
+            budget: data.budget,
+            triggeredThresholds: Array.isArray(data.triggeredThresholds) ? data.triggeredThresholds : [],
+            paused: typeof data.paused === "boolean" ? data.paused : false,
+            lastUpdatedAt: typeof data.lastUpdatedAt === "string" ? data.lastUpdatedAt : new Date().toISOString(),
+        };
+    }
+    catch {
+        return emptyCostState();
+    }
+}
+async function writeRaw(filePath, data) {
+    const dir = path.dirname(filePath);
+    const tempPath = `${filePath}.tmp.${process.pid}`;
+    await node_fs_1.promises.mkdir(dir, { recursive: true });
+    await node_fs_1.promises.writeFile(tempPath, JSON.stringify(data, null, 2), "utf8");
+    await node_fs_1.promises.rename(tempPath, filePath);
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+function getSessionCostPath(stateDir, sessionId) {
+    return path.join(stateDir, `${sessionId}.cost.json`);
+}
+async function getSessionCost(stateDir, sessionId) {
+    return readRaw(getSessionCostPath(stateDir, sessionId));
+}
+async function updateSessionCost(stateDir, sessionId, update) {
+    const filePath = getSessionCostPath(stateDir, sessionId);
+    const data = await readRaw(filePath);
+    // Check for duplicate run cost entry and update or add
+    const existingIdx = data.runCosts.findIndex((r) => r.runId === update.runId);
+    if (existingIdx >= 0) {
+        // Update existing entry (re-aggregation): subtract old, add new
+        const old = data.runCosts[existingIdx];
+        data.totalCostUsd += update.costUsd - old.costUsd;
+        data.totalInputTokens += update.inputTokens - old.inputTokens;
+        data.totalOutputTokens += update.outputTokens - old.outputTokens;
+        data.runCosts[existingIdx] = {
+            runId: update.runId,
+            costUsd: update.costUsd,
+            inputTokens: update.inputTokens,
+            outputTokens: update.outputTokens,
+        };
+    }
+    else {
+        data.totalCostUsd += update.costUsd;
+        data.totalInputTokens += update.inputTokens;
+        data.totalOutputTokens += update.outputTokens;
+        data.runCosts.push({
+            runId: update.runId,
+            costUsd: update.costUsd,
+            inputTokens: update.inputTokens,
+            outputTokens: update.outputTokens,
+        });
+    }
+    data.lastUpdatedAt = new Date().toISOString();
+    await writeRaw(filePath, data);
+    return data;
+}
+async function setSessionBudget(stateDir, sessionId, budget) {
+    const filePath = getSessionCostPath(stateDir, sessionId);
+    const data = await readRaw(filePath);
+    data.budget = budget;
+    data.lastUpdatedAt = new Date().toISOString();
+    await writeRaw(filePath, data);
+    return data;
+}
+/**
+ * Pure function: evaluate budget thresholds against current cost.
+ * Returns new alerts (excluding already-triggered thresholds).
+ */
+function checkBudget(costState) {
+    if (!costState.budget || costState.budget.maxCostUsd <= 0) {
+        return { exceeded: false, alerts: [], shouldPause: false };
+    }
+    const { maxCostUsd, alertThresholds, autoPause } = costState.budget;
+    const currentPct = (costState.totalCostUsd / maxCostUsd) * 100;
+    const exceeded = currentPct >= 100;
+    const alerts = [];
+    for (const threshold of alertThresholds) {
+        if (currentPct >= threshold && !costState.triggeredThresholds.includes(threshold)) {
+            alerts.push({
+                thresholdPct: threshold,
+                currentCostUsd: costState.totalCostUsd,
+                budgetUsd: maxCostUsd,
+                currentPct,
+                message: `Session cost ${currentPct.toFixed(1)}% of budget ($${costState.totalCostUsd.toFixed(4)} / $${maxCostUsd.toFixed(2)})`,
+            });
+        }
+    }
+    return {
+        exceeded,
+        alerts,
+        shouldPause: exceeded && autoPause,
+    };
+}
+/**
+ * Persist triggered thresholds back to cost state after checkBudget produces alerts.
+ * Call this after processing alerts to prevent re-triggering.
+ */
+async function markThresholdsTriggered(stateDir, sessionId, thresholds) {
+    if (thresholds.length === 0)
+        return;
+    const filePath = getSessionCostPath(stateDir, sessionId);
+    const data = await readRaw(filePath);
+    const existing = new Set(data.triggeredThresholds);
+    for (const t of thresholds)
+        existing.add(t);
+    data.triggeredThresholds = [...existing];
+    data.lastUpdatedAt = new Date().toISOString();
+    await writeRaw(filePath, data);
+}

package/dist/session/discovery.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Mapping of harness identifiers to their native session environment variables.
+ *
+ * Only Pi-specific env vars are kept here. External harness session discovery
+ * is handled by agent-mux session management.
+ */
+export declare const HARNESS_ENV_VARS: Record<string, string[]>;
+/**
+ * Resolve the current session ID from the ambient environment (markers + env vars).
+ *
+ * This is used for "autodiscovery" in contexts where no explicit session ID
+ * was provided (e.g. journaling low-level events).
+ *
+ * Precedence:
+ *   1. Harness-native env vars (Pi / oh-my-pi)
+ *   2. AGENT_SESSION_ID
+ *   3. PID-scoped marker for the given harness (fallback only)
+ *
+ * External harness session discovery is delegated to agent-mux.
+ */
+export declare function resolveAmbientSessionId(harness?: string): string | undefined;
+//# sourceMappingURL=discovery.d.ts.map

package/dist/session/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/session/discovery.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAGrD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAO5E"}

package/dist/session/discovery.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HARNESS_ENV_VARS = void 0;
+exports.resolveAmbientSessionId = resolveAmbientSessionId;
+const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
+/**
+ * Mapping of harness identifiers to their native session environment variables.
+ *
+ * Only Pi-specific env vars are kept here. External harness session discovery
+ * is handled by agent-mux session management.
+ */
+exports.HARNESS_ENV_VARS = {
+    "pi": ["PI_SESSION_ID"],
+    "oh-my-pi": ["OMP_SESSION_ID"],
+};
+/**
+ * Resolve the current session ID from the ambient environment (markers + env vars).
+ *
+ * This is used for "autodiscovery" in contexts where no explicit session ID
+ * was provided (e.g. journaling low-level events).
+ *
+ * Precedence:
+ *   1. Harness-native env vars (Pi / oh-my-pi)
+ *   2. AGENT_SESSION_ID
+ *   3. PID-scoped marker for the given harness (fallback only)
+ *
+ * External harness session discovery is delegated to agent-mux.
+ */
+function resolveAmbientSessionId(harness) {
+    if (!harness) {
+        return process.env.AGENT_SESSION_ID;
+    }
+    const envVars = exports.HARNESS_ENV_VARS[harness] || [];
+    return (0, babysitter_sdk_1.resolveSessionIdWithMarker)(harness, {}, envVars);
+}

package/dist/session/history.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Session history persistence for GAP-SESSION-002.
+ *
+ * Stores accumulated decisions, run summaries, and context snapshots
+ * in a dedicated <sessionId>.history.json file alongside the session state.
+ * Uses the same atomic temp-file + rename pattern as context.ts.
+ */
+import type { SessionDecision, SessionRunSummary, SessionContextSnapshot, SessionHistory } from "./types";
+/** Get the file path for a session's history JSON file. */
+export declare function getSessionHistoryPath(stateDir: string, sessionId: string): string;
+/**
+ * Append a decision to the session's history.
+ * Automatically adds a timestamp.
+ */
+export declare function addDecision(stateDir: string, sessionId: string, decision: Omit<SessionDecision, "timestamp">): Promise<void>;
+/**
+ * Append a run summary to the session's history.
+ */
+export declare function addRunSummary(stateDir: string, sessionId: string, summary: SessionRunSummary): Promise<void>;
+/**
+ * Save a context snapshot to the session's history.
+ * Automatically adds a timestamp.
+ */
+export declare function saveContextSnapshot(stateDir: string, sessionId: string, snapshot: Omit<SessionContextSnapshot, "timestamp">): Promise<void>;
+/**
+ * Get the full session history: SessionContext fields + history arrays.
+ * Returns empty defaults when files do not exist.
+ */
+export declare function getSessionHistory(stateDir: string, sessionId: string): Promise<SessionHistory>;
+//# sourceMappingURL=history.d.ts.map

package/dist/session/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../src/session/history.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EACV,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,EACf,MAAM,SAAS,CAAC;AAOjB,2DAA2D;AAC3D,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEjF;AAuDD;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GAC3C,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,IAAI,CAAC,sBAAsB,EAAE,WAAW,CAAC,GAClD,OAAO,CAAC,IAAI,CAAC,CAKf;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,cAAc,CAAC,CAazB"}

package/dist/session/history.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * Session history persistence for GAP-SESSION-002.
+ *
+ * Stores accumulated decisions, run summaries, and context snapshots
+ * in a dedicated <sessionId>.history.json file alongside the session state.
+ * Uses the same atomic temp-file + rename pattern as context.ts.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSessionHistoryPath = getSessionHistoryPath;
+exports.addDecision = addDecision;
+exports.addRunSummary = addRunSummary;
+exports.saveContextSnapshot = saveContextSnapshot;
+exports.getSessionHistory = getSessionHistory;
+const node_fs_1 = require("node:fs");
+const path = __importStar(require("node:path"));
+const context_1 = require("./context");
+// ---------------------------------------------------------------------------
+// Path helper
+// ---------------------------------------------------------------------------
+/** Get the file path for a session's history JSON file. */
+function getSessionHistoryPath(stateDir, sessionId) {
+    return path.join(stateDir, `${sessionId}.history.json`);
+}
+function emptyHistoryData() {
+    return { decisions: [], runSummaries: [], contextSnapshots: [] };
+}
+async function readRawHistory(filePath) {
+    let raw;
+    try {
+        raw = await node_fs_1.promises.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === "ENOENT") {
+            return emptyHistoryData();
+        }
+        return emptyHistoryData();
+    }
+    try {
+        const data = JSON.parse(raw);
+        return {
+            decisions: Array.isArray(data.decisions) ? data.decisions : [],
+            runSummaries: Array.isArray(data.runSummaries) ? data.runSummaries : [],
+            contextSnapshots: Array.isArray(data.contextSnapshots) ? data.contextSnapshots : [],
+        };
+    }
+    catch {
+        return emptyHistoryData();
+    }
+}
+async function writeRawHistory(filePath, data) {
+    const dir = path.dirname(filePath);
+    const tempPath = `${filePath}.tmp.${process.pid}`;
+    await node_fs_1.promises.mkdir(dir, { recursive: true });
+    await node_fs_1.promises.writeFile(tempPath, JSON.stringify(data, null, 2), "utf8");
+    await node_fs_1.promises.rename(tempPath, filePath);
+}
+function nowTimestamp() {
+    return new Date().toISOString();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Append a decision to the session's history.
+ * Automatically adds a timestamp.
+ */
+async function addDecision(stateDir, sessionId, decision) {
+    const filePath = getSessionHistoryPath(stateDir, sessionId);
+    const data = await readRawHistory(filePath);
+    data.decisions.push({ ...decision, timestamp: nowTimestamp() });
+    await writeRawHistory(filePath, data);
+}
+/**
+ * Append a run summary to the session's history.
+ */
+async function addRunSummary(stateDir, sessionId, summary) {
+    const filePath = getSessionHistoryPath(stateDir, sessionId);
+    const data = await readRawHistory(filePath);
+    data.runSummaries.push(summary);
+    await writeRawHistory(filePath, data);
+}
+/**
+ * Save a context snapshot to the session's history.
+ * Automatically adds a timestamp.
+ */
+async function saveContextSnapshot(stateDir, sessionId, snapshot) {
+    const filePath = getSessionHistoryPath(stateDir, sessionId);
+    const data = await readRawHistory(filePath);
+    data.contextSnapshots.push({ ...snapshot, timestamp: nowTimestamp() });
+    await writeRawHistory(filePath, data);
+}
+/**
+ * Get the full session history: SessionContext fields + history arrays.
+ * Returns empty defaults when files do not exist.
+ */
+async function getSessionHistory(stateDir, sessionId) {
+    const [context, rawHistory] = await Promise.all([
+        (0, context_1.getSessionContext)(stateDir, sessionId),
+        readRawHistory(getSessionHistoryPath(stateDir, sessionId)),
+    ]);
+    return {
+        notes: context.notes,
+        sharedKnowledge: context.sharedKnowledge,
+        decisions: rawHistory.decisions,
+        runSummaries: rawHistory.runSummaries,
+        contextSnapshots: rawHistory.contextSnapshots,
+    };
+}