@a5c-ai/genty-platform 5.1.1-staging.00ceebd28cf2

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,72 @@
+/**
+ * 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;
+    pauseReason?: string;
+}
+export interface RunCostUpdate {
+    runId: string;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface SessionBudgetEnforcementResult {
+    costState: SessionCostState;
+    budget: BudgetCheckResult;
+    paused: boolean;
+    pauseReason?: string;
+}
+export declare function setSessionPaused(stateDir: string, sessionId: string, paused: boolean): Promise<SessionCostState>;
+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>;
+export declare function enforceSessionBudgetForRun(stateDir: string, sessionId: string, update: RunCostUpdate): Promise<SessionBudgetEnforcementResult>;
+//# 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;IACrB,WAAW,CAAC,EAAE,MAAM,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;AAED,MAAM,WAAW,8BAA8B;IAC7C,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoDD,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,gBAAgB,CAAC,CAO3B;AAMD,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,CA8B1E;AAED;;;GAGG;AACH,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAAE,GACnB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,8BAA8B,CAAC,CAkBzC"}

package/dist/session/cost.js

@@ -0,0 +1,221 @@
+"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.setSessionPaused = setSessionPaused;
+exports.getSessionCostPath = getSessionCostPath;
+exports.getSessionCost = getSessionCost;
+exports.updateSessionCost = updateSessionCost;
+exports.setSessionBudget = setSessionBudget;
+exports.checkBudget = checkBudget;
+exports.markThresholdsTriggered = markThresholdsTriggered;
+exports.enforceSessionBudgetForRun = enforceSessionBudgetForRun;
+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);
+}
+async function setSessionPaused(stateDir, sessionId, paused) {
+    const filePath = getSessionCostPath(stateDir, sessionId);
+    const data = await readRaw(filePath);
+    data.paused = paused;
+    data.lastUpdatedAt = new Date().toISOString();
+    await writeRaw(filePath, data);
+    return data;
+}
+// ---------------------------------------------------------------------------
+// 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,
+        pauseReason: exceeded && autoPause
+            ? `Session cost budget exceeded: $${costState.totalCostUsd.toFixed(4)} / $${maxCostUsd.toFixed(2)}`
+            : undefined,
+    };
+}
+/**
+ * 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);
+}
+async function enforceSessionBudgetForRun(stateDir, sessionId, update) {
+    const updated = await updateSessionCost(stateDir, sessionId, update);
+    const budget = checkBudget(updated);
+    await markThresholdsTriggered(stateDir, sessionId, budget.alerts.map((alert) => alert.thresholdPct));
+    const costState = budget.shouldPause
+        ? await setSessionPaused(stateDir, sessionId, true)
+        : await getSessionCost(stateDir, sessionId);
+    return {
+        costState,
+        budget,
+        paused: budget.shouldPause,
+        pauseReason: budget.pauseReason,
+    };
+}

package/dist/session/crossRunComm.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Cross-Run Communication (GAP-AGENT-005).
+ *
+ * Provides a file-backed mailbox for sending messages between concurrent
+ * or sequential babysitter runs. Messages are persisted as append-only
+ * JSONL in a configurable state directory.
+ */
+export type CrossRunMessageType = 'data' | 'signal' | 'query' | 'response';
+export interface CrossRunMessage {
+    fromRunId: string;
+    toRunId: string;
+    type: CrossRunMessageType;
+    payload: unknown;
+    timestamp: number;
+}
+export declare class CrossRunMailbox {
+    private readonly stateDir;
+    private readonly filePath;
+    constructor(stateDir: string);
+    /**
+     * Send a message to another run's mailbox.
+     */
+    send(msg: CrossRunMessage): void;
+    /**
+     * Receive and consume all messages addressed to `runId`, optionally
+     * filtered by message type. Consumed messages are removed from the file.
+     */
+    receive(runId: string, type?: CrossRunMessageType): CrossRunMessage[];
+    /**
+     * Peek at messages for `runId` without consuming them.
+     */
+    peek(runId: string): CrossRunMessage[];
+    /**
+     * Clear all messages addressed to `runId`.
+     */
+    clear(runId: string): void;
+    private loadAll;
+    private writeAll;
+}
+//# sourceMappingURL=crossRunComm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crossRunComm.d.ts","sourceRoot":"","sources":["../../src/session/crossRunComm.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AASH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AAE3E,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAQD,qBAAa,eAAe;IAGd,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAFrC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEL,QAAQ,EAAE,MAAM;IAI7C;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAOhC;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,eAAe,EAAE;IAiBrE;;OAEG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,eAAe,EAAE;IAItC;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAS1B,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,QAAQ;CASjB"}

package/dist/session/crossRunComm.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Cross-Run Communication (GAP-AGENT-005).
+ *
+ * Provides a file-backed mailbox for sending messages between concurrent
+ * or sequential babysitter runs. Messages are persisted as append-only
+ * JSONL in a configurable state directory.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CrossRunMailbox = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// ---------------------------------------------------------------------------
+// CrossRunMailbox
+// ---------------------------------------------------------------------------
+const MESSAGES_FILENAME = 'messages.jsonl';
+class CrossRunMailbox {
+    stateDir;
+    filePath;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        this.filePath = (0, node_path_1.join)(stateDir, MESSAGES_FILENAME);
+    }
+    /**
+     * Send a message to another run's mailbox.
+     */
+    send(msg) {
+        if (!(0, node_fs_1.existsSync)(this.stateDir)) {
+            (0, node_fs_1.mkdirSync)(this.stateDir, { recursive: true });
+        }
+        (0, node_fs_1.appendFileSync)(this.filePath, JSON.stringify(msg) + '\n', 'utf8');
+    }
+    /**
+     * Receive and consume all messages addressed to `runId`, optionally
+     * filtered by message type. Consumed messages are removed from the file.
+     */
+    receive(runId, type) {
+        const all = this.loadAll();
+        const matched = [];
+        const remaining = [];
+        for (const msg of all) {
+            if (msg.toRunId === runId && (type == null || msg.type === type)) {
+                matched.push(msg);
+            }
+            else {
+                remaining.push(msg);
+            }
+        }
+        this.writeAll(remaining);
+        return matched;
+    }
+    /**
+     * Peek at messages for `runId` without consuming them.
+     */
+    peek(runId) {
+        return this.loadAll().filter((msg) => msg.toRunId === runId);
+    }
+    /**
+     * Clear all messages addressed to `runId`.
+     */
+    clear(runId) {
+        const remaining = this.loadAll().filter((msg) => msg.toRunId !== runId);
+        this.writeAll(remaining);
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    loadAll() {
+        if (!(0, node_fs_1.existsSync)(this.filePath))
+            return [];
+        const raw = (0, node_fs_1.readFileSync)(this.filePath, 'utf8').trim();
+        if (!raw)
+            return [];
+        return raw.split('\n').map((line) => JSON.parse(line));
+    }
+    writeAll(messages) {
+        if (!(0, node_fs_1.existsSync)(this.stateDir)) {
+            (0, node_fs_1.mkdirSync)(this.stateDir, { recursive: true });
+        }
+        const content = messages.length > 0
+            ? messages.map((m) => JSON.stringify(m)).join('\n') + '\n'
+            : '';
+        (0, node_fs_1.writeFileSync)(this.filePath, content, 'utf8');
+    }
+}
+exports.CrossRunMailbox = CrossRunMailbox;

package/dist/session/crossRunState.d.ts

@@ -0,0 +1,8 @@
+export interface CrossRunStateStore {
+    get(key: string): unknown | undefined;
+    set(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    listKeys(): string[];
+}
+export declare function createCrossRunStateStore(stateDir: string): CrossRunStateStore;
+//# sourceMappingURL=crossRunState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"crossRunState.d.ts","sourceRoot":"","sources":["../../src/session/crossRunState.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;IACtC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IACvC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7B,QAAQ,IAAI,MAAM,EAAE,CAAC;CACtB;AAID,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAqC7E"}

package/dist/session/crossRunState.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCrossRunStateStore = createCrossRunStateStore;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const STATE_FILENAME = 'shared-state.json';
+function createCrossRunStateStore(stateDir) {
+    const filePath = (0, node_path_1.join)(stateDir, STATE_FILENAME);
+    function load() {
+        if (!(0, node_fs_1.existsSync)(filePath))
+            return {};
+        try {
+            return JSON.parse((0, node_fs_1.readFileSync)(filePath, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+    function save(data) {
+        if (!(0, node_fs_1.existsSync)(stateDir))
+            (0, node_fs_1.mkdirSync)(stateDir, { recursive: true });
+        (0, node_fs_1.writeFileSync)(filePath, JSON.stringify(data, null, 2), 'utf8');
+    }
+    return {
+        get(key) {
+            return load()[key];
+        },
+        set(key, value) {
+            const data = load();
+            data[key] = value;
+            save(data);
+        },
+        delete(key) {
+            const data = load();
+            if (!(key in data))
+                return false;
+            delete data[key];
+            save(data);
+            return true;
+        },
+        listKeys() {
+            return Object.keys(load());
+        },
+    };
+}

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 adapters 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 adapters.
+ */
+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"}