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

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)),

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

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createMailboxHttpRequestHandler = createMailboxHttpRequestHandler;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const mailbox_http_hooks_1 = require("./mailbox-http-hooks");
 const mailbox_http_response_1 = require("./mailbox-http-response");
 const mailbox_http_static_1 = require("./mailbox-http-static");
 function decodePathSegment(value) {
@@ -46,6 +47,16 @@ function decodePathSegment(value) {
         return null;
     }
 }
+function rawRequestTargetsUnsafeAgent(urlValue = "/") {
+    const rawTarget = urlValue.split(/[?#]/, 1)[0];
+    const rawPath = rawTarget.replace(/\/+$/, "") || "/";
+    const pathname = (0, mailbox_http_static_1.normalizeLegacyMailboxApiPath)(rawPath);
+    const rawAgentMatch = /^\/api\/agents\/([^/]+)(?:\/|$)/.exec(pathname);
+    if (!rawAgentMatch)
+        return false;
+    const agent = decodePathSegment(rawAgentMatch[1]);
+    return !agent || !(0, mailbox_http_hooks_1.isSafeMailboxAgentName)(agent);
+}
 function parseHabitRunLimit(urlValue) {
     const rawLimit = new URL(urlValue, "http://127.0.0.1").searchParams.get("limit");
     if (rawLimit === null)
@@ -55,9 +66,47 @@ function parseHabitRunLimit(urlValue) {
     const limit = Number.parseInt(rawLimit, 10);
     return limit >= 1 && limit <= 100 ? limit : null;
 }
+const VALID_HABIT_SUMMARY_WHICH = new Set(["latest", "previous", "latest-success", "latest-failure"]);
+function firstQueryValue(params, names) {
+    for (const name of names) {
+        const value = params.get(name);
+        if (value !== null && value.trim().length > 0)
+            return value;
+    }
+    return undefined;
+}
+function parseHabitSummarySelector(urlValue) {
+    const params = new URL(urlValue, "http://127.0.0.1").searchParams;
+    const runId = firstQueryValue(params, ["runId", "run-id"]);
+    const habitName = firstQueryValue(params, ["habitName", "habit"]);
+    const operationId = firstQueryValue(params, ["operationId", "operation-id"]);
+    const which = firstQueryValue(params, ["which"]);
+    if (runId !== undefined && (habitName !== undefined || operationId !== undefined || which !== undefined)) {
+        return { ok: false, error: "--run-id cannot be combined with --habit, --operation-id, or --which" };
+    }
+    if (runId === undefined && habitName === undefined && operationId === undefined) {
+        return { ok: false, error: "provide runId, habitName, or operationId" };
+    }
+    if (which !== undefined && !VALID_HABIT_SUMMARY_WHICH.has(which)) {
+        return { ok: false, error: "which must be latest, previous, latest-success, or latest-failure" };
+    }
+    return {
+        ok: true,
+        selector: {
+            ...(runId ? { runId } : {}),
+            ...(habitName ? { habitName } : {}),
+            ...(operationId ? { operationId } : {}),
+            ...(which ? { which } : {}),
+        },
+    };
+}
 function createMailboxHttpRequestHandler(options) {
     const staticFiles = options.staticFiles ?? { resolveSpaDistDir: mailbox_http_static_1.resolveSpaDistDir, serveStaticFile: mailbox_http_static_1.serveStaticFile };
     return (request, response) => {
+        if (rawRequestTargetsUnsafeAgent(request.url)) {
+            (0, mailbox_http_response_1.writeJson)(response, 400, { ok: false, error: "agent name must be a safe bundle name" });
+            return;
+        }
         let pathname = (0, mailbox_http_static_1.normalizeMailboxRequestPath)(request.url);
         const origin = `http://${options.host}:${options.getPort()}`;
         if (pathname.startsWith("/assets/")) {
@@ -99,8 +148,14 @@ function createMailboxHttpRequestHandler(options) {
         }
         const agentMatch = /^\/api\/agents\/([^/]+)(?:\/(.+))?$/.exec(pathname);
         if (agentMatch) {
+            const agent = decodePathSegment(agentMatch[1]);
+            /* v8 ignore next -- rawRequestTargetsUnsafeAgent rejects unsafe/malformed agent segments before normalization @preserve */
+            if (!agent || !(0, mailbox_http_hooks_1.isSafeMailboxAgentName)(agent)) {
+                (0, mailbox_http_response_1.writeJson)(response, 400, { ok: false, error: "agent name must be a safe bundle name" });
+                return;
+            }
             void handleAgentRoute(request, response, {
-                agent: decodeURIComponent(agentMatch[1]),
+                agent,
                 surface: agentMatch[2] ?? null,
                 options,
             }).catch((error) => {
@@ -229,6 +284,32 @@ async function handleAgentRoute(request, response, context) {
         (0, mailbox_http_response_1.writeJson)(response, 200, view);
         return;
     }
+    if (surface === "habit-run-summaries") {
+        const limit = parseHabitRunLimit(request.url);
+        if (limit === null) {
+            (0, mailbox_http_response_1.writeJson)(response, 400, { ok: false, error: "limit must be an integer between 1 and 100" });
+            return;
+        }
+        const view = limit === undefined
+            ? options.hooks.readAgentHabitRunSummaries(agent)
+            : options.hooks.readAgentHabitRunSummaries(agent, { limit });
+        (0, mailbox_http_response_1.writeJson)(response, 200, view);
+        return;
+    }
+    if (surface === "habit-run-summary") {
+        const parsed = parseHabitSummarySelector(request.url);
+        if (!parsed.ok) {
+            (0, mailbox_http_response_1.writeJson)(response, 400, { ok: false, error: parsed.error });
+            return;
+        }
+        const summary = options.hooks.readAgentHabitRunSummary(agent, parsed.selector);
+        if (!summary) {
+            (0, mailbox_http_response_1.writeJson)(response, 404, { ok: false, error: "habit summary not found" });
+            return;
+        }
+        (0, mailbox_http_response_1.writeJson)(response, 200, summary);
+        return;
+    }
     if (surface.startsWith("habit-runs/")) {
         const rawRunId = surface.slice("habit-runs/".length);
         const runId = decodePathSegment(rawRunId);

package/dist/heart/mailbox/mailbox-read.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readSelfFixView = exports.readMailboxContinuity = exports.readOrientationView = exports.readObligationDetailView = exports.readNoteDecisionView = exports.readSentinelView = exports.readContextLossGauntletView = exports.readChangesView = exports.readNeedsMeView = exports.readNotesView = exports.readLogView = exports.readHabitView = exports.readHabitRunView = exports.readHabitRunReceiptView = exports.readFriendView = exports.readDeskPrefs = exports.readDaemonHealthDeep = exports.readCodingDeep = exports.readBridgeInventory = exports.readAttentionView = exports.readMailView = exports.readMailMessageView = exports.readSessionTranscript = exports.readSessionInventory = exports.readMailboxMachineState = exports.readMailboxAgentState = exports.readObligationSummary = void 0;
+exports.readSelfFixView = exports.readMailboxContinuity = exports.readOrientationView = exports.readObligationDetailView = exports.readNoteDecisionView = exports.readSentinelView = exports.readContextLossGauntletView = exports.readChangesView = exports.readNeedsMeView = exports.readNotesView = exports.readLogView = exports.readHabitView = exports.readHabitRunView = exports.readHabitRunReceiptView = exports.readHabitSessionSummaryView = exports.readHabitSessionSummaryListView = exports.readFriendView = exports.readDeskPrefs = exports.readDaemonHealthDeep = exports.readCodingDeep = exports.readBridgeInventory = exports.readAttentionView = exports.readMailView = exports.readMailMessageView = exports.readSessionTranscript = exports.readSessionInventory = exports.readMailboxMachineState = exports.readMailboxAgentState = exports.readObligationSummary = void 0;
 var agent_machine_1 = require("./readers/agent-machine");
 Object.defineProperty(exports, "readObligationSummary", { enumerable: true, get: function () { return agent_machine_1.readObligationSummary; } });
 Object.defineProperty(exports, "readMailboxAgentState", { enumerable: true, get: function () { return agent_machine_1.readMailboxAgentState; } });
@@ -18,6 +18,8 @@ Object.defineProperty(exports, "readCodingDeep", { enumerable: true, get: functi
 Object.defineProperty(exports, "readDaemonHealthDeep", { enumerable: true, get: function () { return runtime_readers_1.readDaemonHealthDeep; } });
 Object.defineProperty(exports, "readDeskPrefs", { enumerable: true, get: function () { return runtime_readers_1.readDeskPrefs; } });
 Object.defineProperty(exports, "readFriendView", { enumerable: true, get: function () { return runtime_readers_1.readFriendView; } });
+Object.defineProperty(exports, "readHabitSessionSummaryListView", { enumerable: true, get: function () { return runtime_readers_1.readHabitSessionSummaryListView; } });
+Object.defineProperty(exports, "readHabitSessionSummaryView", { enumerable: true, get: function () { return runtime_readers_1.readHabitSessionSummaryView; } });
 Object.defineProperty(exports, "readHabitRunReceiptView", { enumerable: true, get: function () { return runtime_readers_1.readHabitRunReceiptView; } });
 Object.defineProperty(exports, "readHabitRunView", { enumerable: true, get: function () { return runtime_readers_1.readHabitRunView; } });
 Object.defineProperty(exports, "readHabitView", { enumerable: true, get: function () { return runtime_readers_1.readHabitView; } });