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

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

@@ -0,0 +1,618 @@
+"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.isSafeHabitRunId = void 0;
+exports.readLatestHabitSessionState = readLatestHabitSessionState;
+exports.createHabitSessionPaths = createHabitSessionPaths;
+exports.normalizeHabitPermissionEnvelope = normalizeHabitPermissionEnvelope;
+exports.resolveHabitReturnRoute = resolveHabitReturnRoute;
+exports.filterHabitToolsForEnvelope = filterHabitToolsForEnvelope;
+exports.buildHabitRunReceipt = buildHabitRunReceipt;
+exports.completeHabitRun = completeHabitRun;
+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 cadence_1 = require("../daemon/cadence");
+const habit_runtime_state_1 = require("./habit-runtime-state");
+var flight_recorder_2 = require("../../arc/flight-recorder");
+Object.defineProperty(exports, "isSafeHabitRunId", { enumerable: true, get: function () { return flight_recorder_2.isSafeHabitRunId; } });
+function habitSessionRoot(agentRoot) {
+    return path.join(agentRoot, "state", "habit-sessions");
+}
+function isHabitRuntimeStateSnapshot(value, habitName) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    return record.schemaVersion === 1
+        && record.name === habitName
+        && typeof record.lastRun === "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 {
+                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",
+            event: "daemon.habit_runtime_state_malformed",
+            message: "habit runtime state could not be used for recovery",
+            meta: { agentRoot, habitName, runtimeStatePath },
+        });
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function readLatestHabitSessionState(agentRoot, options = {}) {
+    const receipt = (0, flight_recorder_1.listHabitRunReceipts)(agentRoot)
+        .find((entry) => options.habitName === undefined || entry.habitName === options.habitName);
+    if (!receipt) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "daemon",
+            event: "daemon.habit_session_recovery_state_empty",
+            message: "no habit session receipt available for recovery",
+            meta: { agentRoot, habitName: options.habitName ?? null },
+        });
+        return null;
+    }
+    const state = {
+        receipt,
+        runtimeState: readHabitRuntimeStateSnapshot(agentRoot, receipt.habitName),
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.habit_session_recovery_state_read",
+        message: "habit session recovery state read",
+        meta: { agentRoot, habitName: receipt.habitName, runId: receipt.runId, hasRuntimeState: state.runtimeState !== null },
+    });
+    return state;
+}
+function createHabitSessionPaths(agentRoot, runId, habitName = "heartbeat") {
+    if (!(0, flight_recorder_1.isSafeHabitRunId)(runId)) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "daemon",
+            event: "daemon.habit_session_unsafe_run_id",
+            message: "unsafe habit session run id rejected",
+            meta: { agentRoot, runId },
+        });
+        throw new Error(`unsafe habit run id: ${runId}`);
+    }
+    const sessionLocator = `state/habit-sessions/${runId}/session.json`;
+    const pendingLocator = `state/habit-sessions/${runId}/pending`;
+    const runtimeStateLocator = `state/habits/${habitName}.json`;
+    const receiptLocator = `arc/flight-recorder/habit-receipts/${runId}.json`;
+    return {
+        runDir: path.join(habitSessionRoot(agentRoot), runId),
+        sessionPath: path.join(habitSessionRoot(agentRoot), runId, "session.json"),
+        pendingDir: path.join(habitSessionRoot(agentRoot), runId, "pending"),
+        runtimeStatePath: path.join(agentRoot, "state", "habits", `${habitName}.json`),
+        receiptPath: path.join(agentRoot, "arc", "flight-recorder", "habit-receipts", `${runId}.json`),
+        sessionLocator,
+        pendingLocator,
+        runtimeStateLocator,
+        receiptLocator,
+    };
+}
+function normalizeIdentifier(value) {
+    return value.trim().toLowerCase();
+}
+function isSelfTarget(friendId, channel, key) {
+    return normalizeIdentifier(friendId) === "self"
+        || normalizeIdentifier(channel ?? "") === "inner"
+        || `${normalizeIdentifier(friendId)}/${normalizeIdentifier(channel ?? "")}/${normalizeIdentifier(key ?? "")}` === "self/inner/dialog";
+}
+function decodedSegment(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return null;
+    }
+}
+function isUnsafePathSegment(value) {
+    const raw = value.trim();
+    const decoded = decodedSegment(raw);
+    const decodedTrimmed = decoded === null ? null : decoded.trim();
+    return raw.length === 0
+        || decodedTrimmed === null
+        || raw === "."
+        || raw === ".."
+        || decodedTrimmed === "."
+        || decodedTrimmed === ".."
+        || raw.includes("..")
+        || decodedTrimmed.includes("..")
+        || raw.includes("/")
+        || raw.includes("\\")
+        || decodedTrimmed.includes("/")
+        || decodedTrimmed.includes("\\");
+}
+function unsafeRouteSegmentReason(friendId, channel, key) {
+    const segments = [
+        ["friendId", friendId],
+        ["channel", channel],
+        ["key", key],
+    ];
+    for (const [name, value] of segments) {
+        if (value.length > 0 && isUnsafePathSegment(value))
+            return `unsafe route ${name}: ${value}`;
+    }
+    return null;
+}
+async function resolveFriend(friendStore, rawFriendIdOrName) {
+    const raw = rawFriendIdOrName.trim();
+    if (!raw)
+        return null;
+    const direct = await friendStore?.get(raw);
+    if (direct) {
+        return { id: direct.id, name: direct.name, trustLevel: direct.trustLevel, isSelf: isSelfTarget(direct.id) };
+    }
+    const all = await friendStore?.listAll?.();
+    const lowered = normalizeIdentifier(raw);
+    const matched = all?.find((record) => normalizeIdentifier(record.id) === lowered || normalizeIdentifier(record.name) === lowered);
+    if (matched) {
+        return { id: matched.id, name: matched.name, trustLevel: matched.trustLevel, isSelf: isSelfTarget(matched.id) };
+    }
+    if (!friendStore)
+        return { id: raw, name: raw, isSelf: false };
+    return null;
+}
+function unresolvedRoute(kind, recipient, reason) {
+    return { kind, recipient, status: "unresolved", reason };
+}
+function allowedRoute(kind, recipient, friendId, channel, key) {
+    return {
+        kind,
+        recipient,
+        status: "allowed",
+        ...(friendId ? { friendId } : {}),
+        ...(channel ? { channel } : {}),
+        ...(key ? { key } : {}),
+    };
+}
+async function resolveExactRoute(kind, recipient, channel, key, options) {
+    const routeRecipient = `${recipient}/${channel}/${key}`;
+    const unsafeReason = unsafeRouteSegmentReason(recipient, channel, key);
+    if (unsafeReason) {
+        return { route: unresolvedRoute(kind, routeRecipient, unsafeReason), warning: unsafeReason };
+    }
+    if (isSelfTarget(recipient, channel, key)) {
+        const warning = `${kind} route targets self/inner and cannot be used by a habit`;
+        return { route: unresolvedRoute(kind, routeRecipient, warning), warning };
+    }
+    const friend = await resolveFriend(options.friendStore, recipient);
+    if (!friend) {
+        const warning = `${kind} route recipient unresolved: ${recipient}`;
+        return { route: unresolvedRoute(kind, recipient, warning), warning };
+    }
+    const resolvedUnsafeReason = unsafeRouteSegmentReason(friend.id, channel, key);
+    if (resolvedUnsafeReason) {
+        return { route: unresolvedRoute(kind, routeRecipient, resolvedUnsafeReason), warning: resolvedUnsafeReason };
+    }
+    if (friend.isSelf || isSelfTarget(friend.id, channel, key)) {
+        const warning = `${kind} route targets self/inner and cannot be used by a habit`;
+        return { route: unresolvedRoute(kind, routeRecipient, warning), warning };
+    }
+    return { route: allowedRoute(kind, recipient, friend.id, channel, key) };
+}
+function parseExtraRouteSpec(spec) {
+    const parts = spec.split("/").map((part) => part.trim());
+    if (parts.length !== 3 || parts.some((part) => part.length === 0))
+        return null;
+    return { recipient: parts[0], channel: parts[1], key: parts[2] };
+}
+async function normalizeHabitPermissionEnvelope(habit, options) {
+    const returnRoutes = [];
+    const warnings = [];
+    if (habit.surface.family) {
+        returnRoutes.push(allowedRoute("family", "family"));
+    }
+    if (habit.surface.originator) {
+        if (habit.origin) {
+            const resolved = await resolveExactRoute("originator", habit.origin.friendId, habit.origin.channel, habit.origin.key, options);
+            returnRoutes.push(resolved.route);
+            if (resolved.warning)
+                warnings.push(resolved.warning);
+        }
+        else {
+            const warning = "originator route requested but habit has no origin";
+            returnRoutes.push(unresolvedRoute("originator", "originator", warning));
+            warnings.push(warning);
+        }
+    }
+    for (const spec of habit.surface.extra) {
+        const parsed = parseExtraRouteSpec(spec);
+        if (!parsed) {
+            const warning = `malformed extra route: ${spec}`;
+            returnRoutes.push(unresolvedRoute("extra", spec, warning));
+            warnings.push(warning);
+            continue;
+        }
+        const resolved = await resolveExactRoute("extra", parsed.recipient, parsed.channel, parsed.key, options);
+        returnRoutes.push(resolved.route);
+        if (resolved.warning)
+            warnings.push(resolved.warning);
+    }
+    const canMessageOutward = returnRoutes.some((route) => route.status === "allowed");
+    const envelope = {
+        schemaVersion: 1,
+        canMessageOutward,
+        returnRoutes,
+        deniedTools: canMessageOutward ? [] : ["send_message", "surface"],
+        warnings,
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.habit_permission_envelope_normalized",
+        message: "habit permission envelope normalized",
+        meta: { agentRoot: options.agentRoot, habitName: habit.name, routes: returnRoutes.length, canMessageOutward },
+    });
+    return envelope;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function resolveRouteTarget(input) {
+    if (input.toolName === "send_message") {
+        const friendId = readString(input.args.friendId);
+        const channel = readString(input.args.channel);
+        const key = readString(input.args.key);
+        if (!friendId || !channel || !key)
+            return null;
+        return {
+            friendId,
+            channel,
+            key,
+        };
+    }
+    if (input.toolName !== "surface")
+        return null;
+    const delegationId = readString(input.args.delegationId);
+    if (delegationId) {
+        const origin = input.delegatedOrigins?.find((item) => item.id === delegationId);
+        return origin ? { friendId: origin.friendId, channel: origin.channel, key: origin.key } : null;
+    }
+    const friendId = readString(input.args.friendId);
+    if (friendId) {
+        const channel = readString(input.args.channel);
+        const key = readString(input.args.key);
+        if (!channel || !key)
+            return null;
+        return {
+            friendId,
+            channel,
+            key,
+        };
+    }
+    if (input.delegatedOrigins?.length === 1) {
+        const [origin] = input.delegatedOrigins;
+        return { friendId: origin.friendId, channel: origin.channel, key: origin.key };
+    }
+    return null;
+}
+function isLiveVoiceAttempt(args, target) {
+    const channel = normalizeIdentifier(readString(args.channel) ?? target?.channel ?? "");
+    return channel === "voice"
+        || readString(args.phoneNumber) !== null
+        || Object.keys(args).some((key) => normalizeIdentifier(key).includes("voice") || normalizeIdentifier(key).includes("audio"));
+}
+function exactRouteMatches(route, target) {
+    return route.status === "allowed"
+        && route.kind !== "family"
+        && route.friendId === target.friendId
+        && route.channel === target.channel
+        && route.key === target.key;
+}
+function deniedRoute(reason) {
+    return { allowed: false, reason };
+}
+async function resolveHabitReturnRoute(input) {
+    const target = resolveRouteTarget(input);
+    if (isLiveVoiceAttempt(input.args, target)) {
+        return deniedRoute("live voice routes are not allowed from habit sessions");
+    }
+    if (!target) {
+        return deniedRoute("habit tool call has no permitted return route target");
+    }
+    const unsafeReason = unsafeRouteSegmentReason(target.friendId, target.channel, target.key);
+    if (unsafeReason) {
+        return deniedRoute(`habit return route target is unsafe: ${unsafeReason}`);
+    }
+    if (isSelfTarget(target.friendId, target.channel, target.key)) {
+        return deniedRoute("habit sessions cannot route messages to self/inner");
+    }
+    const friend = await resolveFriend(input.friendStore, target.friendId);
+    if (!friend)
+        return deniedRoute(`habit return route recipient unresolved: ${target.friendId}`);
+    const resolvedUnsafeReason = unsafeRouteSegmentReason(friend.id, target.channel, target.key);
+    if (resolvedUnsafeReason) {
+        return deniedRoute(`habit return route target is unsafe: ${resolvedUnsafeReason}`);
+    }
+    if (friend.isSelf || isSelfTarget(friend.id, target.channel, target.key)) {
+        return deniedRoute("habit sessions cannot route messages to self/inner");
+    }
+    const normalizedTarget = { ...target, friendId: friend.id };
+    const exactRoute = input.envelope.returnRoutes.find((route) => exactRouteMatches(route, normalizedTarget));
+    if (exactRoute) {
+        return {
+            allowed: true,
+            routeKind: exactRoute.kind,
+            friendId: friend.id,
+            channel: target.channel,
+            key: target.key,
+        };
+    }
+    const familyRoute = input.envelope.returnRoutes.find((route) => route.kind === "family" && route.status === "allowed");
+    if (familyRoute) {
+        if (friend.trustLevel === "family") {
+            return { allowed: true, routeKind: "family", friendId: friend.id, channel: target.channel, key: target.key };
+        }
+        return deniedRoute(`habit family route requires family trust for ${friend.id}`);
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "daemon",
+        event: "daemon.habit_return_route_denied",
+        message: "habit return route denied",
+        meta: { agentRoot: input.agentRoot, toolName: input.toolName, friendId: friend.id },
+    });
+    return deniedRoute(`no habit return route allows ${friend.id}/${target.channel}/${target.key}`);
+}
+function toolName(definition) {
+    return definition.tool.function.name;
+}
+function isOutwardMessagingTool(name) {
+    return name === "send_message" || name === "surface";
+}
+function isHighRisk(profile) {
+    return profile.risk === "high";
+}
+function filterHabitToolsForEnvelope(definitions, requestedTools, envelope, riskClassifier) {
+    const requested = requestedTools ? new Set(requestedTools) : null;
+    const grantedTools = [];
+    const deniedTools = [];
+    for (const definition of definitions) {
+        const name = toolName(definition);
+        if (requested && !requested.has(name))
+            continue;
+        const deniedByEnvelope = envelope.deniedTools.includes(name);
+        const profile = riskClassifier(definition, name);
+        const allowedOutward = isOutwardMessagingTool(name) && envelope.canMessageOutward && !deniedByEnvelope;
+        if (deniedByEnvelope || (isHighRisk(profile) && !allowedOutward)) {
+            deniedTools.push(name);
+            continue;
+        }
+        grantedTools.push(name);
+    }
+    const policy = {
+        requestedTools: requestedTools ? [...requestedTools] : null,
+        grantedTools,
+        deniedTools,
+        outwardMessagingAllowed: envelope.canMessageOutward,
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.habit_tool_policy_filtered",
+        message: "habit tool policy filtered",
+        meta: { requested: requestedTools?.length ?? null, granted: grantedTools.length, denied: deniedTools.length },
+    });
+    return policy;
+}
+function computeNextRunAt(habit, endedAt) {
+    if (habit.status !== "active" || !habit.cadence)
+        return null;
+    const cadenceMs = (0, cadence_1.parseCadenceToMs)(habit.cadence);
+    const endedMs = Date.parse(endedAt);
+    if (cadenceMs === null || !Number.isFinite(endedMs))
+        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 = {
+        schemaVersion: 2,
+        runId: input.runId,
+        sessionId: input.runId,
+        habitName: input.habit.name,
+        trigger: input.trigger,
+        startedAt: input.startedAt,
+        endedAt: input.endedAt,
+        outcome: input.outcome,
+        definitionLocator: `habits/${input.habit.name}.md`,
+        sessionLocator: paths.sessionLocator,
+        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 ?? [],
+    };
+    (0, runtime_1.emitNervesEvent)({
+        component: "daemon",
+        event: "daemon.habit_run_receipt_built",
+        message: "habit run receipt built",
+        meta: { agentRoot: input.agentRoot, habitName: input.habit.name, runId: input.runId, outcome: input.outcome },
+    });
+    return receipt;
+}
+function successfulSurfaceAttempt(attempt) {
+    return attempt.result !== "blocked"
+        && attempt.result !== "failed"
+        && attempt.result !== "unavailable";
+}
+function surfaceRefsFromAttempts(attempts) {
+    return attempts
+        .filter(successfulSurfaceAttempt)
+        .map((attempt) => ({
+        kind: "surface",
+        locator: `surface/${attempt.recipient}/${attempt.channel}`,
+    }));
+}
+function habitOutcomeForCompletion(input) {
+    const attempts = input.surfaceAttempts ?? [];
+    const producedRefs = input.producedRefs && input.producedRefs.length > 0
+        ? [...input.producedRefs]
+        : surfaceRefsFromAttempts(attempts);
+    if ((input.errors ?? []).length > 0)
+        return { outcome: "error", producedRefs };
+    if (producedRefs.some((ref) => ref.kind === "surface"))
+        return { outcome: "surfaced", producedRefs };
+    if (producedRefs.some((ref) => ref.kind === "desk_record"))
+        return { outcome: "wrote_record", producedRefs };
+    if (producedRefs.some((ref) => ref.kind === "desk_task"))
+        return { outcome: "updated_desk", producedRefs };
+    if (producedRefs.some((ref) => ref.kind === "arc" || ref.kind === "claim"))
+        return { outcome: "wrote_arc", producedRefs };
+    if (attempts.length > 0 && attempts.every((attempt) => !successfulSurfaceAttempt(attempt))) {
+        return { outcome: "blocked", producedRefs };
+    }
+    return { outcome: "no_change", producedRefs };
+}
+function completeHabitRun(input) {
+    const { outcome, producedRefs } = habitOutcomeForCompletion(input);
+    let receipt;
+    try {
+        receipt = buildHabitRunReceipt({
+            agentRoot: input.agentRoot,
+            habit: input.habit,
+            runId: input.runId,
+            trigger: input.trigger,
+            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)({
+            level: "error",
+            component: "senses",
+            event: "senses.habit_receipt_write_error",
+            message: "habit receipt could not be written; runtime state was not advanced",
+            meta: {
+                habitName: input.habit.name,
+                runId: input.runId,
+                error: String(error),
+            },
+        });
+        return { outcome, producedRefs, receiptWritten: false, runtimeStateRecorded: false };
+    }
+    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 };
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.habit_runtime_state_record_error",
+            message: "habit runtime state could not be updated after receipt write",
+            meta: {
+                habitName: input.habit.name,
+                runId: input.runId,
+                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)),
@@ -58,6 +82,10 @@ function createMailboxHttpReadHooks(options) {
         readAgentSentinel: options.readAgentSentinel ?? ((agentName) => (0, mailbox_read_1.readSentinelView)(agentRoot(agentName))),
         readAgentNoteDecisions: options.readAgentNoteDecisions ?? ((agentName) => (0, mailbox_read_1.readNoteDecisionView)(agentRoot(agentName))),
         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)),