@ouro.bot/cli 0.1.0-alpha.804 → 0.1.0-alpha.805

package/dist/heart/frontend-approval-runtime.js

@@ -0,0 +1,432 @@
+"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.settleFrontendApproval = settleFrontendApproval;
+exports.createFrontendApprovalRuntime = createFrontendApprovalRuntime;
+const node_crypto_1 = require("node:crypto");
+const path = __importStar(require("node:path"));
+const approval_files_1 = require("./approval-files");
+const approval_store_1 = require("./approval-store");
+const tool_approval_1 = require("./tool-approval");
+const core_1 = require("./core");
+const identity_1 = require("./identity");
+const turn_execution_lease_1 = require("./turn-execution-lease");
+const context_1 = require("../mind/context");
+const session_transaction_1 = require("../mind/session-transaction");
+const tools_1 = require("../repertoire/tools");
+const mcp_manager_1 = require("../repertoire/mcp-manager");
+const runtime_1 = require("../nerves/runtime");
+const PERMISSION_OPTIONS = [
+    { optionId: "allow-once", name: "Allow once", kind: "allow_once" },
+    { optionId: "reject-once", name: "Reject", kind: "reject_once" },
+];
+/* v8 ignore start -- lazy default adapter avoids widening every daemon test mock; settlement behavior is covered through the injected dependency @preserve */
+async function defaultReleaseRuntimeMcpServers() {
+    const manager = await Promise.resolve().then(() => __importStar(require("../repertoire/mcp-manager")));
+    await manager.releaseRuntimeMcpServers();
+}
+/* v8 ignore stop */
+const DEFAULT_SETTLEMENT_DEPENDENCIES = {
+    withTurnExecutionLease: turn_execution_lease_1.withTurnExecutionLease,
+    setAgentName: identity_1.setAgentName,
+    withSessionTurnLease: session_transaction_1.withSessionTurnLease,
+    readSessionTransaction: session_transaction_1.readSessionTransaction,
+    executeApprovalDecision: tool_approval_1.executeApprovalDecision,
+    resolveToolDefinition: tools_1.resolveToolDefinition,
+    approvalPolicyForInvocation: tools_1.approvalPolicyForInvocation,
+    execTool: tools_1.execTool,
+    getSharedMcpManager: mcp_manager_1.getSharedMcpManager,
+    releaseRuntimeMcpServers: defaultReleaseRuntimeMcpServers,
+    loadSession: context_1.loadSession,
+    postTurnTrim: context_1.postTurnTrim,
+    postTurnPersist: context_1.postTurnPersist,
+    resumeApprovalContinuation: core_1.resumeApprovalContinuation,
+    runAgent: core_1.runAgent,
+    randomUUID: node_crypto_1.randomUUID,
+};
+async function settleFrontendApproval(input, dependencies = DEFAULT_SETTLEMENT_DEPENDENCIES) {
+    const token = input.tokenStore.get(input.suspension.approvalId);
+    if (!token)
+        throw new Error(`frontend approval decision token is unavailable: ${input.suspension.approvalId}`);
+    const checkpoint = input.checkpointStore.read(input.suspension.approvalId);
+    if (!checkpoint)
+        throw new Error(`frontend approval checkpoint is unavailable: ${input.suspension.approvalId}`);
+    const record = input.approvalStore.read(input.suspension.approvalId);
+    if (!record)
+        throw new Error(`frontend approval record is unavailable: ${input.suspension.approvalId}`);
+    return dependencies.withTurnExecutionLease(async () => {
+        dependencies.setAgentName(input.request.agent);
+        try {
+            const mcpManager = await dependencies.getSharedMcpManager(input.request.runtimeMcpServers ? { runtimeServers: input.request.runtimeMcpServers } : undefined) ?? undefined;
+            return await dependencies.withSessionTurnLease(record.sessionPath, async (lease) => {
+                const currentRevision = dependencies.readSessionTransaction(record.sessionPath, lease).revision;
+                const continuationSignal = input.optionId === "cancelled" ? AbortSignal.abort() : input.signal;
+                const liveToolContext = input.approvalRequest.liveToolContext ?? {
+                    signin: async () => undefined,
+                    agentRoot: input.agentRoot,
+                    currentSession: {
+                        friendId: input.request.friendId,
+                        channel: input.request.channel,
+                        key: input.request.sessionKey,
+                        sessionPath: record.sessionPath,
+                    },
+                    currentUserMessage: input.request.message,
+                };
+                const terminal = await dependencies.executeApprovalDecision({
+                    approvalStore: input.approvalStore,
+                    checkpointStore: input.checkpointStore,
+                    decision: {
+                        approvalId: record.approvalId,
+                        decisionToken: token,
+                        decision: input.optionId === "allow-once" ? "approve" : "deny",
+                        requesterId: input.request.friendId,
+                        transport: "frontend",
+                        transportUserId: input.request.friendId,
+                        transportChatId: input.request.sessionKey,
+                        transportMessageId: record.approvalId,
+                        sessionKey: input.request.sessionKey,
+                        ...(input.optionId === "expired" ? { decisionAt: Date.parse(record.expiresAt) } : {}),
+                    },
+                    ownerId: `frontend-decision-${dependencies.randomUUID()}`,
+                    currentSessionRevision: currentRevision,
+                    resolveTool: dependencies.resolveToolDefinition,
+                    resolveApprovalPolicy: (name, args) => dependencies.approvalPolicyForInvocation(name, args, liveToolContext),
+                    liveGuard: async () => ({ ok: true }),
+                    liveRisk: async () => ({ ok: true }),
+                    execute: (name, args) => dependencies.execTool(name, args, liveToolContext),
+                });
+                input.tokenStore.remove(record.approvalId);
+                const existing = dependencies.loadSession(record.sessionPath);
+                const existingStructuredOutputIds = new Set(existing?.structuredOutputs.map((output) => output.id) ?? []);
+                const deliveries = [];
+                let response = "";
+                const emit = input.frontendEventSink.onEvent;
+                const callbacks = {
+                    settleOutputMode: "retractable_buffer",
+                    onModelStart: () => emit({ type: "model_started", data: {} }),
+                    onModelStreamStart: () => emit({ type: "model_stream_started", data: {} }),
+                    onTextChunk: (text) => {
+                        response += text;
+                        emit({ type: "text_delta", data: { text } });
+                    },
+                    onReasoningChunk: (text) => emit({ type: "reasoning_delta", data: { text } }),
+                    onToolStart: (name, args) => emit({ type: "tool_started", data: { name, args } }),
+                    onToolEnd: (name, summary, success) => emit({ type: "tool_completed", data: { name, summary, success } }),
+                    onError: (error, severity) => emit({ type: "error", data: { message: error.message, severity } }),
+                    onClearText: () => {
+                        response = "";
+                        emit({ type: "text_cleared", data: {} });
+                    },
+                };
+                let continuationEpoch = 0;
+                const continuationOwnerId = `frontend-continuation-${dependencies.randomUUID()}`;
+                const nestedCoordinator = {
+                    propose: (request) => input.approvalCoordinatorFactory({
+                        request: input.request,
+                        publish: input.publish,
+                    })({
+                        sessionPath: record.sessionPath,
+                        baseSessionRevision: dependencies.readSessionTransaction(record.sessionPath, lease).revision,
+                    }).propose(request),
+                };
+                const persist = (messages, result) => {
+                    const expectedRevision = dependencies.readSessionTransaction(record.sessionPath, lease).revision;
+                    const prepared = dependencies.postTurnTrim(messages, result?.usage);
+                    dependencies.postTurnPersist(record.sessionPath, prepared, result?.usage, existing?.state, lease, expectedRevision);
+                };
+                const continuation = await dependencies.resumeApprovalContinuation({
+                    record: terminal,
+                    checkpoint,
+                    currentSessionRevision: dependencies.readSessionTransaction(record.sessionPath, lease).revision,
+                    sessionMessages: checkpoint.preCallMessages,
+                    callbacks,
+                    channel: input.request.channel,
+                    claimContinuation: () => {
+                        const claim = input.approvalStore.claimContinuation({
+                            approvalId: record.approvalId,
+                            ownerId: continuationOwnerId,
+                        });
+                        continuationEpoch = claim.record.continuationEpoch;
+                        return claim;
+                    },
+                    markContinuationMaterialized: () => {
+                        input.approvalStore.markContinuationMaterialized({
+                            approvalId: record.approvalId,
+                            ownerId: continuationOwnerId,
+                            epoch: continuationEpoch,
+                        });
+                    },
+                    markContinuationAttempted: () => {
+                        input.approvalStore.markContinuationAttempted({
+                            approvalId: record.approvalId,
+                            ownerId: continuationOwnerId,
+                            epoch: continuationEpoch,
+                        });
+                    },
+                    completeContinuation: () => {
+                        input.approvalStore.completeContinuation({
+                            approvalId: record.approvalId,
+                            ownerId: continuationOwnerId,
+                            epoch: continuationEpoch,
+                        });
+                    },
+                    runAgent: dependencies.runAgent,
+                    runAgentOptions: {
+                        mcpManager,
+                        toolContext: liveToolContext,
+                        approvalCoordinator: nestedCoordinator,
+                    },
+                    persist,
+                    deliver: async (text) => {
+                        response = text;
+                        deliveries.push({ kind: "text", text });
+                        emit({ type: "assistant_delivery", data: { kind: "text", text } });
+                    },
+                    signal: continuationSignal,
+                });
+                const persisted = dependencies.loadSession(record.sessionPath);
+                for (const output of persisted?.structuredOutputs ?? []) {
+                    if (!existingStructuredOutputIds.has(output.id)) {
+                        emit({ type: "structured_output", data: { output } });
+                    }
+                }
+                const turnOutcome = continuation.outcome === "terminal_notice"
+                    ? "settled"
+                    : continuation.outcome === "already_continued"
+                        ? "superseded"
+                        : continuation.outcome;
+                if (turnOutcome === "suspended" && !continuation.suspension) {
+                    throw new Error("frontend approval continuation omitted its nested suspension");
+                }
+                return {
+                    response,
+                    ponderDeferred: false,
+                    deliveries,
+                    deliveryFailures: [],
+                    sessionPath: record.sessionPath,
+                    turnOutcome,
+                    ...(continuation.suspension ? { suspension: continuation.suspension } : {}),
+                };
+            });
+        }
+        finally {
+            if (input.request.runtimeMcpServers) {
+                await dependencies.releaseRuntimeMcpServers();
+            }
+        }
+    });
+}
+function createFrontendApprovalRuntime(options) {
+    const agentRoot = options.agentRoot ?? identity_1.getAgentRoot;
+    const now = options.now ?? Date.now;
+    const approvalTimeoutMs = options.approvalTimeoutMs ?? 300_000;
+    const settleApproval = options.settleApproval ?? settleFrontendApproval;
+    if (!Number.isSafeInteger(approvalTimeoutMs) || approvalTimeoutMs < 1) {
+        throw new Error("approvalTimeoutMs must be a positive integer");
+    }
+    (0, runtime_1.emitNervesEvent)({
+        component: "heart",
+        event: "heart.frontend_approval_runtime_ready",
+        message: "frontend approval runtime ready",
+    });
+    const states = new Map();
+    const pending = new Map();
+    let closed = false;
+    function closeStatesWhenIdle() {
+        if (!closed || pending.size > 0)
+            return;
+        for (const state of states.values())
+            state.approvalStore.close();
+        states.clear();
+    }
+    function stateFor(agent) {
+        let state = states.get(agent);
+        if (state)
+            return state;
+        const stateRoot = path.join(agentRoot(agent), "state", "approvals");
+        state = {
+            approvalStore: (0, approval_store_1.openApprovalStore)({ databasePath: path.join(stateRoot, "approvals.sqlite") }),
+            checkpointStore: new approval_files_1.FileApprovalCheckpointStore(path.join(stateRoot, "checkpoints.json")),
+            tokenStore: new approval_files_1.FileApprovalTokenStore(path.join(stateRoot, "tokens.json")),
+        };
+        states.set(agent, state);
+        return state;
+    }
+    function settlePending(item, optionId) {
+        if (item.settled)
+            return false;
+        item.settled = true;
+        item.resolve(optionId);
+        item.publish("permission_resolved", { requestId: item.requestId, optionId }, "permission_resolved");
+        return true;
+    }
+    const runtime = {
+        approvalCoordinatorFactory(input) {
+            return (context) => ({
+                propose: async (request) => {
+                    if (closed)
+                        throw new Error("frontend approval runtime is closed");
+                    if (request.toolCall.type !== "function")
+                        throw new Error("frontend approval requires a function tool call");
+                    const state = stateFor(input.request.agent);
+                    const committed = (0, tool_approval_1.commitApprovalProposal)({
+                        approvalStore: state.approvalStore,
+                        checkpointStore: state.checkpointStore,
+                        tokenStore: state.tokenStore,
+                        proposal: {
+                            toolCallId: request.toolCall.id,
+                            toolName: request.toolCall.function.name,
+                            arguments: request.arguments,
+                            schemaDigest: request.schemaDigest,
+                            toolDigest: request.toolDigest,
+                            policyDigest: request.policyDigest,
+                            policyId: request.policyId,
+                            sessionKey: input.request.sessionKey,
+                            sessionPath: context.sessionPath,
+                            baseSessionRevision: context.baseSessionRevision,
+                            checkpointDigest: "0".repeat(64),
+                            requesterId: input.request.friendId,
+                            transport: "frontend",
+                            transportUserId: input.request.friendId,
+                            transportChatId: input.request.sessionKey,
+                            expiresAt: new Date(now() + approvalTimeoutMs).toISOString(),
+                            frozenAssistantMessage: request.frozenAssistantMessage,
+                        },
+                        preCallMessages: request.preCallMessages,
+                    });
+                    const decision = Promise.withResolvers();
+                    state.approvalStore.bindPrompt({
+                        approvalId: committed.record.approvalId,
+                        transport: "frontend",
+                        transportChatId: input.request.sessionKey,
+                        transportMessageId: committed.record.approvalId,
+                    });
+                    const item = {
+                        requestId: committed.record.approvalId,
+                        toolCallId: request.toolCall.id,
+                        title: `Approve ${request.toolCall.function.name}`,
+                        request: input.request,
+                        approvalRequest: request,
+                        expiresAt: Date.parse(committed.record.expiresAt),
+                        publish: input.publish,
+                        decision: decision.promise,
+                        resolve: decision.resolve,
+                        settled: false,
+                    };
+                    pending.set(committed.record.approvalId, item);
+                    input.publish("permission_requested", {
+                        requestId: committed.record.approvalId,
+                        toolCallId: request.toolCall.id,
+                        title: `Approve ${request.toolCall.function.name}`,
+                        options: PERMISSION_OPTIONS,
+                    }, "permission_requested");
+                    return {
+                        approvalId: committed.record.approvalId,
+                        checkpointDigest: committed.record.checkpointDigest,
+                        suspendedSessionRevision: committed.record.suspendedSessionRevision,
+                    };
+                },
+            });
+        },
+        async resumeApproval(input) {
+            const item = pending.get(input.suspension.approvalId);
+            if (!item || item.request.turnId !== input.request.turnId) {
+                throw new Error(`frontend approval ${input.suspension.approvalId} does not own turn ${input.request.turnId}`);
+            }
+            const abort = () => settlePending(item, "cancelled");
+            if (input.signal.aborted)
+                abort();
+            else
+                input.signal.addEventListener("abort", abort, { once: true });
+            const timeout = setTimeout(() => settlePending(item, "expired"), Math.max(0, item.expiresAt - now()));
+            try {
+                const optionId = await item.decision;
+                const state = stateFor(input.request.agent);
+                return await settleApproval({
+                    ...input,
+                    approvalRequest: item.approvalRequest,
+                    optionId,
+                    publish: item.publish,
+                    agentRoot: agentRoot(input.request.agent),
+                    ...state,
+                    approvalCoordinatorFactory: runtime.approvalCoordinatorFactory,
+                });
+            }
+            finally {
+                clearTimeout(timeout);
+                input.signal.removeEventListener("abort", abort);
+                pending.delete(input.suspension.approvalId);
+                closeStatesWhenIdle();
+            }
+        },
+        resolvePermission(requestId, optionId) {
+            if (closed || (optionId !== "allow-once" && optionId !== "reject-once" && optionId !== "cancelled"))
+                return false;
+            const item = pending.get(requestId);
+            return item ? settlePending(item, optionId) : false;
+        },
+        cancelTurn(turnId) {
+            for (const item of pending.values()) {
+                if (item.request.turnId === turnId)
+                    settlePending(item, "cancelled");
+            }
+        },
+        pendingPermissions(ref) {
+            return [...pending.values()].flatMap((item) => {
+                if (item.settled
+                    || item.request.agent !== ref.agent
+                    || item.request.friendId !== ref.friendId
+                    || item.request.sessionKey !== ref.sessionKey)
+                    return [];
+                return [{
+                        requestId: item.requestId,
+                        turnId: item.request.turnId,
+                        toolCallId: item.toolCallId,
+                        title: item.title,
+                        options: [...PERMISSION_OPTIONS],
+                    }];
+            });
+        },
+        close() {
+            if (closed)
+                return;
+            for (const item of pending.values())
+                settlePending(item, "cancelled");
+            closed = true;
+            closeStatesWhenIdle();
+        },
+    };
+    return runtime;
+}

package/dist/heart/frontend-journal.js

@@ -0,0 +1,215 @@
+"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.FrontendJournalStore = exports.FrontendJournalPayloadTooLargeError = exports.FrontendJournalCorruptError = void 0;
+const node_crypto_1 = require("node:crypto");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const identity_1 = require("./identity");
+const runtime_1 = require("../nerves/runtime");
+const JOURNAL_VERSION = 1;
+const DEFAULT_MAX_EVENT_BYTES = 256 * 1024;
+const DEFAULT_REPLAY_LIMIT = 1_000;
+const EVENT_TYPES = new Set([
+    "user_message",
+    "turn_started",
+    "assistant_delivery",
+    "tool_started",
+    "tool_completed",
+    "structured_output",
+    "permission_requested",
+    "permission_resolved",
+    "error",
+    "turn_completed",
+    "turn_failed",
+    "turn_cancelled",
+]);
+class FrontendJournalCorruptError extends Error {
+    constructor(journalPath) {
+        super(`frontend journal has an invalid tail: ${journalPath}`);
+        this.name = "FrontendJournalCorruptError";
+    }
+}
+exports.FrontendJournalCorruptError = FrontendJournalCorruptError;
+class FrontendJournalPayloadTooLargeError extends Error {
+    constructor(size, limit) {
+        super(`frontend journal event is ${size} bytes; limit is ${limit}`);
+        this.name = "FrontendJournalPayloadTooLargeError";
+    }
+}
+exports.FrontendJournalPayloadTooLargeError = FrontendJournalPayloadTooLargeError;
+function required(value, field) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`${field} must be a non-empty string`);
+    return trimmed;
+}
+function opaqueSegment(value) {
+    return (0, node_crypto_1.createHash)("sha256").update(value).digest("hex").slice(0, 32);
+}
+function record(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("journal data must be an object");
+    return value;
+}
+function parseEvent(raw, ref, expectedSequence) {
+    const value = record(raw);
+    if (value.version !== JOURNAL_VERSION)
+        throw new Error("unsupported journal version");
+    if (value.sequence !== expectedSequence)
+        throw new Error("invalid journal sequence");
+    if (value.agent !== ref.agent || value.friendId !== ref.friendId || value.sessionId !== ref.sessionId) {
+        throw new Error("journal identity mismatch");
+    }
+    if (typeof value.turnId !== "string" || !value.turnId)
+        throw new Error("invalid journal turnId");
+    if (typeof value.type !== "string" || !EVENT_TYPES.has(value.type)) {
+        throw new Error("invalid journal event type");
+    }
+    if (typeof value.occurredAt !== "string" || !value.occurredAt)
+        throw new Error("invalid journal timestamp");
+    return {
+        version: JOURNAL_VERSION,
+        sequence: expectedSequence,
+        agent: ref.agent,
+        friendId: ref.friendId,
+        sessionId: ref.sessionId,
+        turnId: value.turnId,
+        type: value.type,
+        occurredAt: value.occurredAt,
+        data: record(value.data),
+    };
+}
+class FrontendJournalStore {
+    agentRoot;
+    now;
+    maxEventBytes;
+    constructor(options = {}) {
+        this.agentRoot = options.agentRoot ?? identity_1.getAgentRoot;
+        this.now = options.now ?? (() => new Date().toISOString());
+        this.maxEventBytes = options.maxEventBytes ?? DEFAULT_MAX_EVENT_BYTES;
+        if (!Number.isSafeInteger(this.maxEventBytes) || this.maxEventBytes < 1) {
+            throw new Error("maxEventBytes must be a positive integer");
+        }
+    }
+    pathFor(ref) {
+        const agent = required(ref.agent, "agent");
+        const friendId = required(ref.friendId, "friendId");
+        const sessionId = required(ref.sessionId, "sessionId");
+        return path.join(this.agentRoot(agent), "state", "frontend-sessions", opaqueSegment(friendId), `${opaqueSegment(sessionId)}.jsonl`);
+    }
+    replay(ref, options = {}) {
+        const afterSequence = options.afterSequence ?? 0;
+        const limit = options.limit ?? DEFAULT_REPLAY_LIMIT;
+        if (!Number.isSafeInteger(afterSequence) || afterSequence < 0) {
+            throw new Error("afterSequence must be a non-negative integer");
+        }
+        if (!Number.isSafeInteger(limit) || limit < 1) {
+            throw new Error("limit must be a positive integer");
+        }
+        const journalPath = this.pathFor(ref);
+        if (!fs.existsSync(journalPath)) {
+            return { events: [], lastSequence: 0, hasMore: false, degraded: false, incompleteTurnIds: [] };
+        }
+        const valid = [];
+        let degraded = false;
+        const lines = fs.readFileSync(journalPath, "utf8").split("\n").filter((line) => line.length > 0);
+        for (const line of lines) {
+            try {
+                valid.push(parseEvent(JSON.parse(line), ref, valid.length + 1));
+            }
+            catch {
+                degraded = true;
+                break;
+            }
+        }
+        const matching = valid.filter((event) => event.sequence > afterSequence);
+        const incompleteTurnIds = new Set();
+        for (const event of valid) {
+            if (event.type === "turn_started") {
+                incompleteTurnIds.add(event.turnId);
+            }
+            else if (event.type === "turn_completed"
+                || event.type === "turn_failed"
+                || event.type === "turn_cancelled") {
+                incompleteTurnIds.delete(event.turnId);
+            }
+        }
+        return {
+            events: matching.slice(0, limit),
+            lastSequence: valid.at(-1)?.sequence ?? 0,
+            hasMore: matching.length > limit,
+            degraded,
+            incompleteTurnIds: [...incompleteTurnIds],
+        };
+    }
+    append(ref, input) {
+        const journalPath = this.pathFor(ref);
+        const replay = this.replay(ref);
+        if (replay.degraded)
+            throw new FrontendJournalCorruptError(journalPath);
+        if (!EVENT_TYPES.has(input.type))
+            throw new Error("invalid journal event type");
+        const event = {
+            version: JOURNAL_VERSION,
+            sequence: replay.lastSequence + 1,
+            agent: required(ref.agent, "agent"),
+            friendId: required(ref.friendId, "friendId"),
+            sessionId: required(ref.sessionId, "sessionId"),
+            turnId: required(input.turnId, "turnId"),
+            type: input.type,
+            occurredAt: this.now(),
+            data: record(input.data),
+        };
+        const encoded = `${JSON.stringify(event)}\n`;
+        const size = Buffer.byteLength(encoded);
+        if (size > this.maxEventBytes)
+            throw new FrontendJournalPayloadTooLargeError(size, this.maxEventBytes);
+        // ponytail: semantic event volume is low; add a side index only if replay-on-append becomes measurable.
+        const directory = path.dirname(journalPath);
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        fs.chmodSync(directory, 0o700);
+        fs.appendFileSync(journalPath, encoded, { encoding: "utf8", mode: 0o600 });
+        fs.chmodSync(journalPath, 0o600);
+        (0, runtime_1.emitNervesEvent)({
+            component: "heart",
+            event: "heart.frontend_journal_appended",
+            message: "frontend journal event appended",
+            meta: { type: event.type, sequence: event.sequence },
+        });
+        return event;
+    }
+}
+exports.FrontendJournalStore = FrontendJournalStore;