@ouro.bot/cli 0.1.0-alpha.666 → 0.1.0-alpha.668

package/dist/heart/habits/habit-parser.js

@@ -104,6 +104,11 @@ function parseSurface(raw) {
         extra: record ? parseStringArray(record.extra) : [],
     };
 }
+function parseContinuity(raw) {
+    const record = objectRecord(raw);
+    const mode = record ? record.mode : null;
+    return { mode: mode === "stateful" ? "stateful" : "fresh" };
+}
 function extractFrontmatterAndBody(content) {
     const lines = content.split(/\r?\n/);
     if (lines[0]?.trim() !== "---") {
@@ -137,6 +142,7 @@ function parseHabitFile(content, filePath) {
             tools: undefined,
             origin: null,
             surface: { family: true, originator: true, extra: [] },
+            continuity: { mode: "fresh" },
             body: content.trim(),
         };
     }
@@ -154,6 +160,7 @@ function parseHabitFile(content, filePath) {
     const tools = parseToolsField(frontmatter.tools);
     const origin = parseOrigin(frontmatter.origin);
     const surface = parseSurface(frontmatter.surface);
+    const continuity = parseContinuity(frontmatter.continuity);
     return {
         name: stem,
         title,
@@ -164,6 +171,7 @@ function parseHabitFile(content, filePath) {
         tools,
         origin,
         surface,
+        continuity,
         body,
     };
 }

package/dist/heart/habits/habit-runtime-state.js

@@ -47,6 +47,9 @@ function habitRuntimeStateDir(agentRoot) {
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
+function nullableCursor(value) {
+    return isNonEmptyString(value) ? value.trim() : null;
+}
 function stripLegacyLastRunFromDefinition(definitionPath) {
     const content = fs.readFileSync(definitionPath, "utf-8");
     const lines = content.split(/\r?\n/);
@@ -72,23 +75,34 @@ function applyHabitRuntimeState(agentRoot, habit) {
         return habit;
     return { ...habit, lastRun: runtimeLastRun };
 }
-function writeHabitLastRun(agentRoot, habitName, lastRun, updatedAt = lastRun) {
+function writeHabitLastRun(agentRoot, habitName, lastRun, updatedAt = lastRun, options = {}) {
     const record = {
         schemaVersion: 1,
         name: habitName,
         lastRun,
         updatedAt,
+        activeOperationId: nullableCursor(options.activeOperationId),
+        latestRunId: nullableCursor(options.latestRunId),
+        latestReceiptLocator: nullableCursor(options.latestReceiptLocator),
     };
     (0, json_store_1.writeJsonFile)(habitRuntimeStateDir(agentRoot), habitName, record);
     (0, runtime_1.emitNervesEvent)({
         component: "daemon",
         event: "daemon.habit_runtime_state_write",
         message: "wrote habit runtime state",
-        meta: { agentRoot, habitName, lastRun, updatedAt },
+        meta: {
+            agentRoot,
+            habitName,
+            lastRun,
+            updatedAt,
+            activeOperationId: record.activeOperationId,
+            latestRunId: record.latestRunId,
+            latestReceiptLocator: record.latestReceiptLocator,
+        },
     });
 }
 function recordHabitRun(agentRoot, habitName, lastRun, options = {}) {
-    writeHabitLastRun(agentRoot, habitName, lastRun);
+    writeHabitLastRun(agentRoot, habitName, lastRun, lastRun, options);
     if (!options.definitionPath)
         return;
     try {

package/dist/heart/habits/habit-session-summary.js

@@ -0,0 +1,318 @@
+"use strict";
+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.selectHabitRunReceipt = selectHabitRunReceipt;
+exports.readHabitSessionSummary = readHabitSessionSummary;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const flight_recorder_1 = require("../../arc/flight-recorder");
+const runtime_1 = require("../../nerves/runtime");
+const session_events_1 = require("../session-events");
+const VALID_WHICH = new Set(["latest", "previous", "latest-success", "latest-failure"]);
+const SUCCESS_OUTCOMES = new Set([
+    "no_change",
+    "wrote_arc",
+    "updated_desk",
+    "wrote_record",
+    "surfaced",
+]);
+const FAILURE_OUTCOMES = new Set(["blocked", "error"]);
+const MAX_SUMMARY_CHARS = 1600;
+const TRUNCATION_SUFFIX = "\n[truncated]";
+function selectorError(code, message) {
+    return { ok: false, error: { code, message } };
+}
+function normalizeWhich(value) {
+    if (value === undefined)
+        return "latest";
+    return VALID_WHICH.has(value) ? value : null;
+}
+function sortNewestFirst(receipts) {
+    return [...receipts].sort((left, right) => right.endedAt.localeCompare(left.endedAt) || right.runId.localeCompare(left.runId));
+}
+function filterReceipts(receipts, selector) {
+    return receipts.filter((receipt) => {
+        if (selector.habitName !== undefined && receipt.habitName !== selector.habitName)
+            return false;
+        if (selector.operationId !== undefined && receipt.operationId !== selector.operationId)
+            return false;
+        return true;
+    });
+}
+function filterByWhich(receipts, which) {
+    if (which === "latest" || which === "previous")
+        return receipts;
+    const outcomes = which === "latest-success" ? SUCCESS_OUTCOMES : FAILURE_OUTCOMES;
+    return receipts.filter((receipt) => outcomes.has(receipt.outcome));
+}
+function selectHabitRunReceipt(receipts, selector) {
+    if (selector.runId !== undefined) {
+        if (selector.habitName !== undefined || selector.operationId !== undefined || selector.which !== undefined) {
+            return selectorError("run_id_exclusive", "runId cannot be combined with habitName, operationId, or which");
+        }
+        const receipt = receipts.find((entry) => entry.runId === selector.runId);
+        return receipt ? { ok: true, receipt } : selectorError("not_found", "no habit run matched selector");
+    }
+    if (selector.habitName === undefined && selector.operationId === undefined) {
+        return selectorError("selector_required", "provide runId, habitName, or operationId");
+    }
+    const which = normalizeWhich(selector.which);
+    if (which === null) {
+        return selectorError("invalid_which", "which must be latest, previous, latest-success, or latest-failure");
+    }
+    const matches = filterByWhich(sortNewestFirst(filterReceipts([...receipts], selector)), which);
+    const index = which === "previous" ? 1 : 0;
+    const receipt = matches[index];
+    return receipt ? { ok: true, receipt } : selectorError("not_found", "no habit run matched selector");
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function summarySnapshot(receipt) {
+    const snapshot = receipt.summarySnapshot;
+    return {
+        summary: snapshot.summary,
+        decisions: snapshot.decisions,
+        nextLikelyStep: snapshot.nextLikelyStep,
+    };
+}
+function relativeSource(receipt, key) {
+    if (key === "receipt")
+        return receipt.receiptLocator;
+    if (key === "session")
+        return receipt.sessionLocator;
+    if (key === "pending")
+        return receipt.pendingLocator;
+    return receipt.runtimeStateLocator;
+}
+function safeSourcePath(agentRoot, locator, key, expectedPrefix) {
+    const normalizedInput = locator.replace(/\\/g, "/");
+    const normalized = path.posix.normalize(normalizedInput);
+    const unsafe = path.isAbsolute(locator)
+        || normalizedInput.startsWith("/")
+        || normalized === "."
+        || normalized === ".."
+        || normalized.startsWith("../")
+        || normalized !== normalizedInput
+        || !normalized.startsWith(expectedPrefix);
+    if (unsafe) {
+        return { ok: false, warning: `${key} locator unsafe: ${locator}` };
+    }
+    const root = path.resolve(agentRoot);
+    const filePath = path.resolve(agentRoot, normalized);
+    /* v8 ignore next -- defensive containment check after normalized bundle-relative locator validation @preserve */
+    if (filePath !== root && !filePath.startsWith(`${root}${path.sep}`)) {
+        return { ok: false, warning: `${key} locator escaped bundle: ${locator}` };
+    }
+    return { ok: true, filePath };
+}
+function safeExistingRealPath(agentRoot, filePath, key, locator) {
+    try {
+        const root = fs.realpathSync.native(agentRoot);
+        const realPath = fs.realpathSync.native(filePath);
+        if (realPath !== root && !realPath.startsWith(`${root}${path.sep}`)) {
+            return { ok: false, warning: `${key} locator escaped bundle via symlink: ${locator}` };
+        }
+        return { ok: true, filePath: realPath };
+    }
+    catch {
+        /* v8 ignore next -- defensive realpath race/permission guard; existence is checked before callers invoke this @preserve */
+        return { ok: false, warning: `${key} locator unreadable: ${locator}` };
+    }
+}
+function sessionSummaryFromMessages(messages) {
+    const toolsUsed = new Set();
+    for (const message of messages) {
+        /* v8 ignore next -- defensive: session projection returns message records; this protects malformed direct projection callers @preserve */
+        if (!isRecord(message))
+            continue;
+        const name = stringValue(message.name) ?? stringValue(message.toolName);
+        /* v8 ignore next -- defensive: canonical projections expose tool names from assistant tool_calls; legacy direct tool-name projections still count if present @preserve */
+        if (name && message.role === "tool")
+            toolsUsed.add(name);
+        if (Array.isArray(message.tool_calls)) {
+            /* v8 ignore start -- defensive: projected provider messages normally expose structured tool calls; malformed direct envelopes are kept inert @preserve */
+            for (const toolCall of message.tool_calls) {
+                if (!isRecord(toolCall))
+                    continue;
+                const fn = isRecord(toolCall.function) ? toolCall.function : null;
+                const toolName = fn ? stringValue(fn.name) : null;
+                if (toolName)
+                    toolsUsed.add(toolName);
+            }
+            /* v8 ignore stop @preserve */
+        }
+    }
+    const warnings = messages.length === 0 ? ["session file had no usable messages"] : [];
+    return {
+        decisions: [],
+        nextLikelyStep: null,
+        toolsUsed: [...toolsUsed].sort(),
+        warnings,
+    };
+}
+function readSessionEnrichment(agentRoot, receipt) {
+    const source = safeSourcePath(agentRoot, receipt.sessionLocator, "session", "state/habit-sessions/");
+    if (!source.ok) {
+        return { decisions: [], nextLikelyStep: null, toolsUsed: [], warnings: [source.warning] };
+    }
+    if (!fs.existsSync(source.filePath)) {
+        return { decisions: [], nextLikelyStep: null, toolsUsed: [], warnings: ["session file missing"] };
+    }
+    const realSource = safeExistingRealPath(agentRoot, source.filePath, "session", receipt.sessionLocator);
+    if (!realSource.ok) {
+        return { decisions: [], nextLikelyStep: null, toolsUsed: [], warnings: [realSource.warning] };
+    }
+    const envelope = (0, session_events_1.loadSessionEnvelopeFile)(realSource.filePath);
+    if (!envelope) {
+        return { decisions: [], nextLikelyStep: null, toolsUsed: [], warnings: ["session file malformed"] };
+    }
+    return sessionSummaryFromMessages((0, session_events_1.projectProviderMessages)(envelope));
+}
+function readPending(agentRoot, receipt) {
+    const source = safeSourcePath(agentRoot, receipt.pendingLocator, "pending", "state/habit-sessions/");
+    if (!source.ok)
+        return { pending: { count: 0, files: [] }, warnings: [source.warning] };
+    try {
+        if (!fs.existsSync(source.filePath))
+            return { pending: { count: 0, files: [] }, warnings: [] };
+        const realSource = safeExistingRealPath(agentRoot, source.filePath, "pending", receipt.pendingLocator);
+        if (!realSource.ok)
+            return { pending: { count: 0, files: [] }, warnings: [realSource.warning] };
+        const entries = fs.readdirSync(realSource.filePath, { withFileTypes: true })
+            .filter((entry) => entry.isFile())
+            .map((entry) => entry.name)
+            .sort();
+        return { pending: { count: entries.length, files: entries }, warnings: [] };
+    }
+    catch {
+        return { pending: { count: 0, files: [] }, warnings: [] };
+    }
+}
+function runtimeOperationId(agentRoot, receipt) {
+    const source = safeSourcePath(agentRoot, receipt.runtimeStateLocator, "runtimeState", "state/habits/");
+    if (!source.ok)
+        return { operationId: null, warnings: [source.warning] };
+    try {
+        if (!fs.existsSync(source.filePath))
+            return { operationId: null, warnings: [] };
+        const realSource = safeExistingRealPath(agentRoot, source.filePath, "runtimeState", receipt.runtimeStateLocator);
+        if (!realSource.ok)
+            return { operationId: null, warnings: [realSource.warning] };
+        const parsed = JSON.parse(fs.readFileSync(realSource.filePath, "utf-8"));
+        if (!isRecord(parsed))
+            return { operationId: null, warnings: [] };
+        if (parsed.schemaVersion !== 1)
+            return { operationId: null, warnings: [] };
+        if (stringValue(parsed.name) !== receipt.habitName)
+            return { operationId: null, warnings: [] };
+        if (stringValue(parsed.latestRunId) !== receipt.runId)
+            return { operationId: null, warnings: [] };
+        if (stringValue(parsed.latestReceiptLocator) !== receipt.receiptLocator)
+            return { operationId: null, warnings: [] };
+        return { operationId: stringValue(parsed.activeOperationId), warnings: [] };
+    }
+    catch {
+        return { operationId: null, warnings: [] };
+    }
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function truncateSummary(value) {
+    if (value.length <= MAX_SUMMARY_CHARS)
+        return value;
+    return `${value.slice(0, MAX_SUMMARY_CHARS - TRUNCATION_SUFFIX.length)}${TRUNCATION_SUFFIX}`;
+}
+function legacySummaryWarnings(receipt) {
+    return receipt.permissionEnvelope.warnings.some((warning) => warning.includes("legacy receipt normalized"))
+        ? ["legacy receipt normalized"]
+        : [];
+}
+function readHabitSessionSummary(agentRoot, selector) {
+    const selection = selectHabitRunReceipt((0, flight_recorder_1.listHabitRunReceipts)(agentRoot), selector);
+    if (!selection.ok)
+        return null;
+    const receipt = selection.receipt;
+    const snapshot = summarySnapshot(receipt);
+    const session = readSessionEnrichment(agentRoot, receipt);
+    const pending = readPending(agentRoot, receipt);
+    const runtime = runtimeOperationId(agentRoot, receipt);
+    const operationId = receipt.operationId ?? runtime.operationId;
+    const decisions = uniqueStrings([
+        ...snapshot.decisions,
+        ...session.decisions,
+    ]);
+    const summary = truncateSummary(snapshot.summary);
+    const nextLikelyStep = snapshot.nextLikelyStep ?? session.nextLikelyStep;
+    const result = {
+        runId: receipt.runId,
+        habitName: receipt.habitName,
+        operationId: operationId ?? null,
+        status: receipt.outcome,
+        triggeredAt: receipt.startedAt,
+        completedAt: receipt.endedAt,
+        summary,
+        decisions,
+        pending: pending.pending,
+        messagesSent: receipt.surfaceAttempts,
+        toolsUsed: session.toolsUsed,
+        producedRefs: receipt.producedRefs,
+        errors: receipt.errors,
+        nextLikelyStep: nextLikelyStep ?? null,
+        sources: {
+            receipt: relativeSource(receipt, "receipt"),
+            session: relativeSource(receipt, "session"),
+            pending: relativeSource(receipt, "pending"),
+            runtimeState: relativeSource(receipt, "runtimeState"),
+        },
+        warnings: [
+            ...legacySummaryWarnings(receipt),
+            ...session.warnings,
+            ...pending.warnings,
+            ...runtime.warnings,
+        ],
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.habit_session_summary_read",
+        message: "habit session summary read",
+        meta: { agentRoot, runId: receipt.runId, habitName: receipt.habitName, warningCount: result.warnings.length },
+    });
+    return result;
+}

package/dist/heart/habits/habit-session.js

@@ -59,14 +59,29 @@ function isHabitRuntimeStateSnapshot(value, habitName) {
     return record.schemaVersion === 1
         && record.name === habitName
         && typeof record.lastRun === "string"
-        && typeof record.updatedAt === "string";
+        && typeof record.updatedAt === "string"
+        && (record.activeOperationId === undefined || record.activeOperationId === null || typeof record.activeOperationId === "string")
+        && (record.latestRunId === undefined || record.latestRunId === null || typeof record.latestRunId === "string")
+        && (record.latestReceiptLocator === undefined || record.latestReceiptLocator === null || typeof record.latestReceiptLocator === "string");
+}
+function runtimeCursorValue(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
 }
 function readHabitRuntimeStateSnapshot(agentRoot, habitName) {
     const runtimeStatePath = path.join(agentRoot, "state", "habits", `${habitName}.json`);
     try {
         const parsed = JSON.parse(fs.readFileSync(runtimeStatePath, "utf-8"));
-        if (isHabitRuntimeStateSnapshot(parsed, habitName))
-            return parsed;
+        if (isHabitRuntimeStateSnapshot(parsed, habitName)) {
+            return {
+                schemaVersion: 1,
+                name: parsed.name,
+                lastRun: parsed.lastRun,
+                updatedAt: parsed.updatedAt,
+                activeOperationId: runtimeCursorValue(parsed.activeOperationId),
+                latestRunId: runtimeCursorValue(parsed.latestRunId),
+                latestReceiptLocator: runtimeCursorValue(parsed.latestReceiptLocator),
+            };
+        }
         (0, runtime_1.emitNervesEvent)({
             level: "warn",
             component: "daemon",
@@ -444,6 +459,37 @@ function computeNextRunAt(habit, endedAt) {
         return null;
     return new Date(endedMs + cadenceMs).toISOString();
 }
+function defaultSummarySnapshot(input) {
+    const errors = input.errors ?? [];
+    if (errors.length > 0) {
+        return {
+            summary: `Habit ${input.habit.name} finished with errors: ${errors.join("; ")}`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const surfaced = (input.surfaceAttempts ?? []).find((attempt) => attempt.result !== "blocked" && attempt.result !== "failed" && attempt.result !== "unavailable");
+    if (surfaced) {
+        return {
+            summary: `Habit ${input.habit.name} surfaced via ${surfaced.recipient}/${surfaced.channel}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    const produced = (input.producedRefs ?? []).find((ref) => ref.kind !== "none");
+    if (produced) {
+        return {
+            summary: `Habit ${input.habit.name} produced ${produced.kind}: ${produced.locator}.`,
+            decisions: [],
+            nextLikelyStep: null,
+        };
+    }
+    return {
+        summary: `Habit ${input.habit.name} finished with ${input.outcome}.`,
+        decisions: [],
+        nextLikelyStep: null,
+    };
+}
 function buildHabitRunReceipt(input) {
     const paths = createHabitSessionPaths(input.agentRoot, input.runId, input.habit.name);
     const receipt = {
@@ -460,9 +506,11 @@ function buildHabitRunReceipt(input) {
         pendingLocator: paths.pendingLocator,
         runtimeStateLocator: paths.runtimeStateLocator,
         receiptLocator: paths.receiptLocator,
+        operationId: input.operationId ?? null,
         nextRunAt: input.nextRunAt ?? computeNextRunAt(input.habit, input.endedAt),
         permissionEnvelope: input.permissionEnvelope,
         toolPolicy: input.toolPolicy,
+        summarySnapshot: input.summarySnapshot ?? defaultSummarySnapshot(input),
         producedRefs: input.producedRefs ?? [],
         surfaceAttempts: input.surfaceAttempts ?? [],
         errors: input.errors ?? [],
@@ -510,8 +558,9 @@ function habitOutcomeForCompletion(input) {
 }
 function completeHabitRun(input) {
     const { outcome, producedRefs } = habitOutcomeForCompletion(input);
+    let receipt;
     try {
-        (0, flight_recorder_1.writeHabitRunReceipt)(input.agentRoot, buildHabitRunReceipt({
+        receipt = buildHabitRunReceipt({
             agentRoot: input.agentRoot,
             habit: input.habit,
             runId: input.runId,
@@ -519,12 +568,15 @@ function completeHabitRun(input) {
             startedAt: input.startedAt,
             endedAt: input.endedAt,
             outcome,
+            operationId: input.operationId ?? null,
             permissionEnvelope: input.permissionEnvelope,
             toolPolicy: input.toolPolicy,
             producedRefs,
             surfaceAttempts: input.surfaceAttempts,
             errors: input.errors,
-        }));
+            summarySnapshot: input.summarySnapshot,
+        });
+        (0, flight_recorder_1.writeHabitRunReceipt)(input.agentRoot, receipt);
     }
     catch (error) {
         (0, runtime_1.emitNervesEvent)({
@@ -535,7 +587,7 @@ function completeHabitRun(input) {
             meta: {
                 habitName: input.habit.name,
                 runId: input.runId,
-                error: error instanceof Error ? error.message : String(error),
+                error: String(error),
             },
         });
         return { outcome, producedRefs, receiptWritten: false, runtimeStateRecorded: false };
@@ -543,6 +595,9 @@ function completeHabitRun(input) {
     try {
         (0, habit_runtime_state_1.recordHabitRun)(input.agentRoot, input.habit.name, input.endedAt, {
             definitionPath: path.join(input.agentRoot, "habits", `${input.habit.name}.md`),
+            activeOperationId: receipt.operationId ?? null,
+            latestRunId: receipt.runId,
+            latestReceiptLocator: receipt.receiptLocator,
         });
         return { outcome, producedRefs, receiptWritten: true, runtimeStateRecorded: true };
     }
@@ -555,7 +610,7 @@ function completeHabitRun(input) {
             meta: {
                 habitName: input.habit.name,
                 runId: input.runId,
-                error: error instanceof Error ? error.message : String(error),
+                error: String(error),
             },
         });
         return { outcome, producedRefs, receiptWritten: true, runtimeStateRecorded: false };

package/dist/heart/mailbox/mailbox-http-hooks.js

@@ -33,13 +33,37 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSafeMailboxAgentName = isSafeMailboxAgentName;
 exports.createMailboxHttpReadHooks = createMailboxHttpReadHooks;
 const path = __importStar(require("path"));
 const mailbox_read_1 = require("./mailbox-read");
+function isSafeMailboxAgentName(agentName) {
+    const trimmed = agentName.trim();
+    return trimmed === agentName
+        && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(agentName)
+        && agentName !== "."
+        && agentName !== ".."
+        && !agentName.includes("/")
+        && !agentName.includes("\\");
+}
+function resolveAgentRoot(bundlesRoot, agentName) {
+    if (!isSafeMailboxAgentName(agentName)) {
+        throw new Error("mailbox API requires a safe agent name");
+    }
+    if (!bundlesRoot)
+        return path.join(`${agentName}.ouro`);
+    const root = path.resolve(bundlesRoot);
+    const agentRoot = path.resolve(root, `${agentName}.ouro`);
+    /* v8 ignore next -- defensive containment guard after strict safe bundle-name validation @preserve */
+    if (agentRoot !== root && !agentRoot.startsWith(`${root}${path.sep}`)) {
+        throw new Error("mailbox API agent root escaped bundles root");
+    }
+    return agentRoot;
+}
 function createMailboxHttpReadHooks(options) {
     const bundlesRoot = options.bundlesRoot;
     const readOptions = bundlesRoot ? { bundlesRoot } : undefined;
-    const agentRoot = (agentName) => path.join(bundlesRoot ?? "", `${agentName}.ouro`);
+    const agentRoot = (agentName) => resolveAgentRoot(bundlesRoot, agentName);
     return {
         agentRoot,
         readAgentSessions: options.readAgentSessions ?? ((agentName) => (0, mailbox_read_1.readSessionInventory)(agentName, readOptions)),
@@ -60,6 +84,8 @@ function createMailboxHttpReadHooks(options) {
         readAgentHabits: options.readAgentHabits ?? ((agentName) => (0, mailbox_read_1.readHabitView)(agentRoot(agentName))),
         readAgentHabitRuns: options.readAgentHabitRuns ?? ((agentName, habitOptions) => (0, mailbox_read_1.readHabitRunView)(agentRoot(agentName), habitOptions)),
         readAgentHabitRun: options.readAgentHabitRun ?? ((agentName, runId) => (0, mailbox_read_1.readHabitRunReceiptView)(agentRoot(agentName), runId)),
+        readAgentHabitRunSummaries: options.readAgentHabitRunSummaries ?? ((agentName, habitOptions) => (0, mailbox_read_1.readHabitSessionSummaryListView)(agentRoot(agentName), habitOptions)),
+        readAgentHabitRunSummary: options.readAgentHabitRunSummary ?? ((agentName, selector) => (0, mailbox_read_1.readHabitSessionSummaryView)(agentRoot(agentName), selector)),
         readAgentMail: options.readAgentMail ?? ((agentName) => (0, mailbox_read_1.readMailView)(agentName)),
         readAgentMailMessage: options.readAgentMailMessage ?? ((agentName, messageId) => (0, mailbox_read_1.readMailMessageView)(agentName, messageId)),
         readDaemonHealth: options.readDaemonHealth ?? (() => (0, mailbox_read_1.readDaemonHealthDeep)(options.healthPath)),