@ouro.bot/cli 0.1.0-alpha.488 → 0.1.0-alpha.489

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.489",
+      "changes": [
+        "Trip ledger Step 4 — harness-side trip tools land. Six new tools (`trip_ensure_ledger`, `trip_status`, `trip_get`, `trip_upsert`, `trip_attach_evidence`, `trip_new_id`) give the agent a private, encrypted, per-agent travel ledger backed by an RSA-OAEP-SHA256 + AES-256-GCM envelope. Ledger keypair lives at `state/trips/ledger.json`; encrypted records persist under `state/trips/records/<tripId>.json`. Tools are gated behind the same trust check as other private surfaces (only available to trusted callers) and validate `TripRecord` / `TripEvidence` shape before persisting. Vendor-copies the substrate trip-control types so the harness has no runtime dependency on a hosted ledger service yet, while keeping the on-disk format compatible for future migration."
+      ]
+    },
     {
       "version": "0.1.0-alpha.488",
       "changes": [

package/dist/nerves/coverage/file-completeness.js

@@ -101,6 +101,10 @@ const DISPATCH_EXEMPT_PATTERNS = [
     // arithmetic). The caller (search-cache.ts searchMailSearchCache) owns
     // observability via senses.mail_search_cache_upserted and friends.
     "mailroom/search-relevance",
+    // Trip ledger crypto helpers: pure RSA/AES envelope construction + slug
+    // hashing. The caller (trips/store.ts) owns observability via
+    // trips.ledger_created and trips.evidence_attached.
+    "trips/core",
     // Outlook HTTP helper modules: route/static/transport/hook seams are
     // dispatched by outlook-http.ts, whose server lifecycle owns observability.
     "heart/outlook/outlook-http-transport",

package/dist/repertoire/tools-base.js

@@ -17,6 +17,7 @@ const tools_stripe_1 = require("./tools-stripe");
 const tools_flight_1 = require("./tools-flight");
 const tools_attachments_1 = require("./tools-attachments");
 const tools_mail_1 = require("./tools-mail");
+const tools_trip_1 = require("./tools-trip");
 // Re-export flow tools for consumers that import them from tools-base
 var tools_flow_1 = require("./tools-flow");
 Object.defineProperty(exports, "ponderTool", { enumerable: true, get: function () { return tools_flow_1.ponderTool; } });
@@ -48,6 +49,7 @@ exports.baseToolDefinitions = [
     ...tools_flight_1.flightToolDefinitions,
     ...tools_attachments_1.attachmentToolDefinitions,
     ...tools_mail_1.mailToolDefinitions,
+    ...tools_trip_1.tripToolDefinitions,
 ];
 // Convenience array of just the tool schemas (no handler/integration metadata).
 // Used by consumers that need the OpenAI function-tool format.

package/dist/repertoire/tools-trip.js

@@ -0,0 +1,280 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tripToolDefinitions = void 0;
+const types_1 = require("../mind/friends/types");
+const runtime_1 = require("../nerves/runtime");
+const store_1 = require("../trips/store");
+const core_1 = require("../trips/core");
+const identity_1 = require("../heart/identity");
+function trustAllowsTripAccess(ctx) {
+    const trustLevel = ctx?.context?.friend?.trustLevel;
+    return trustLevel === undefined || (0, types_1.isTrustedLevel)(trustLevel);
+}
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseJsonArg(raw, label) {
+    if (typeof raw !== "string")
+        throw new Error(`${label} must be a JSON string`);
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`${label} is not valid JSON: ${error instanceof Error ? error.message : /* v8 ignore next -- JSON.parse only throws SyntaxError */ String(error)}`);
+    }
+}
+function validateTripRecord(value) {
+    if (!isRecord(value))
+        throw new Error("record must be a TripRecord object");
+    // Minimal structural validation — the agent is constructing the value but
+    // we still guard against the obvious shape mistakes that would break decrypt.
+    for (const field of ["tripId", "agentId", "ownerEmail", "name", "status", "createdAt", "updatedAt"]) {
+        if (typeof value[field] !== "string" || value[field].length === 0) {
+            throw new Error(`record.${field} must be a non-empty string`);
+        }
+    }
+    if (!Array.isArray(value.travellers))
+        throw new Error("record.travellers must be an array");
+    if (!Array.isArray(value.legs))
+        throw new Error("record.legs must be an array");
+    for (const leg of value.legs) {
+        if (!isRecord(leg))
+            throw new Error("each leg must be an object");
+        if (typeof leg.legId !== "string" || leg.legId.length === 0)
+            throw new Error("each leg requires a legId");
+        if (typeof leg.kind !== "string")
+            throw new Error("each leg requires a kind");
+        if (typeof leg.status !== "string")
+            throw new Error("each leg requires a status");
+        if (!Array.isArray(leg.evidence))
+            throw new Error(`leg ${leg.legId} requires an evidence array`);
+        for (const ev of leg.evidence) {
+            if (!isRecord(ev))
+                throw new Error(`leg ${leg.legId}: each evidence entry must be an object`);
+            if (typeof ev.messageId !== "string" || ev.messageId.length === 0)
+                throw new Error(`leg ${leg.legId}: evidence.messageId must be a non-empty string`);
+            if (typeof ev.discoveryMethod !== "string" || ev.discoveryMethod.length === 0)
+                throw new Error(`leg ${leg.legId}: evidence.discoveryMethod must be a non-empty string`);
+        }
+    }
+    return value;
+}
+function validateTripEvidence(value) {
+    if (!isRecord(value))
+        throw new Error("evidence must be a TripEvidence object");
+    for (const field of ["messageId", "reason", "recordedAt", "discoveryMethod"]) {
+        if (typeof value[field] !== "string" || value[field].length === 0) {
+            throw new Error(`evidence.${field} must be a non-empty string`);
+        }
+    }
+    return value;
+}
+function renderTripSummary(trip) {
+    const dateRange = trip.startDate && trip.endDate
+        ? `${trip.startDate} → ${trip.endDate}`
+        : trip.startDate ?? trip.endDate ?? "(no dates)";
+    const lines = [
+        `- ${trip.tripId} :: "${trip.name}" [${trip.status}; ${dateRange}; legs: ${trip.legs.length}]`,
+        `  travellers: ${trip.travellers.map((p) => p.name).join(", ") || "(none)"}`,
+    ];
+    if (trip.notes)
+        lines.push(`  notes: ${trip.notes}`);
+    return lines.join("\n");
+}
+exports.tripToolDefinitions = [
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "trip_ensure_ledger",
+                description: "Idempotently ensure this agent has a trip ledger keypair. Safe to call multiple times. Required once before any other trip_ tool.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        handler: async (_args, ctx) => {
+            if (!trustAllowsTripAccess(ctx))
+                return "trip ledger is private; this tool is only available in trusted contexts.";
+            const result = (0, store_1.ensureAgentTripLedger)({ agentName: (0, identity_1.getAgentName)() });
+            const verb = result.added ? "created" : "already present";
+            return `trip ledger ${verb}: ledgerId=${result.ledger.ledgerId}, keyId=${result.ledger.keyId}, createdAt=${result.ledger.createdAt}`;
+        },
+        summaryKeys: [],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "trip_status",
+                description: "List the agent's trip ids in sorted order. Cheap overview before opening individual trips.",
+                parameters: { type: "object", properties: {} },
+            },
+        },
+        handler: async (_args, ctx) => {
+            if (!trustAllowsTripAccess(ctx))
+                return "trip ledger is private; this tool is only available in trusted contexts.";
+            const tripIds = (0, store_1.listTripIds)((0, identity_1.getAgentName)());
+            if (tripIds.length === 0)
+                return "no trips on the ledger yet.";
+            return `${tripIds.length} trip(s):\n${tripIds.map((id) => `- ${id}`).join("\n")}`;
+        },
+        summaryKeys: [],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "trip_get",
+                description: "Read one trip record by id. Returns a structured summary plus the raw JSON for further reasoning.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        tripId: { type: "string", description: "Canonical trip id (trip_<slug>_<fingerprint>)." },
+                    },
+                    required: ["tripId"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!trustAllowsTripAccess(ctx))
+                return "trip ledger is private; this tool is only available in trusted contexts.";
+            const tripId = args.tripId;
+            if (typeof tripId !== "string" || tripId.length === 0)
+                return "tripId is required.";
+            try {
+                const trip = (0, store_1.readTripRecord)((0, identity_1.getAgentName)(), tripId);
+                return [
+                    renderTripSummary(trip),
+                    "",
+                    "raw record (JSON):",
+                    JSON.stringify(trip, null, 2),
+                ].join("\n");
+            }
+            catch (error) {
+                if (error instanceof store_1.TripNotFoundError)
+                    return error.message;
+                throw error;
+            }
+        },
+        summaryKeys: ["tripId"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "trip_upsert",
+                description: "Create or replace a TripRecord. Pass the full record as a JSON string in `record`. Every leg requires a legId and an evidence array (each evidence entry requires messageId + discoveryMethod). Returns the persisted tripId.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        record: { type: "string", description: "Full TripRecord JSON. Must include tripId, agentId, ownerEmail, name, status, travellers[], legs[], createdAt, updatedAt." },
+                    },
+                    required: ["record"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!trustAllowsTripAccess(ctx))
+                return "trip ledger is private; this tool is only available in trusted contexts.";
+            try {
+                const parsed = parseJsonArg(args.record, "record");
+                const trip = validateTripRecord(parsed);
+                (0, store_1.ensureAgentTripLedger)({ agentName: (0, identity_1.getAgentName)() });
+                (0, store_1.upsertTripRecord)((0, identity_1.getAgentName)(), trip);
+                return `trip upserted: ${trip.tripId} (${trip.legs.length} leg(s), status=${trip.status})`;
+            }
+            catch (error) {
+                return `upsert failed: ${error instanceof Error ? error.message : /* v8 ignore next -- non-Error throw is unreachable from validateTripRecord/parseJsonArg */ String(error)}`;
+            }
+        },
+        summaryKeys: [],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "trip_attach_evidence",
+                description: "Append a TripEvidence record to a specific leg's evidence array. Pass tripId, legId, and the evidence as a JSON string. Useful when extracting a fact from a single mail message and attaching it to an existing leg without re-uploading the whole record.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        tripId: { type: "string", description: "Canonical trip id." },
+                        legId: { type: "string", description: "Leg id within the trip." },
+                        evidence: { type: "string", description: "TripEvidence JSON: { messageId, reason, recordedAt, discoveryMethod, excerpt? }." },
+                    },
+                    required: ["tripId", "legId", "evidence"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!trustAllowsTripAccess(ctx))
+                return "trip ledger is private; this tool is only available in trusted contexts.";
+            const tripId = args.tripId;
+            const legId = args.legId;
+            if (typeof tripId !== "string" || tripId.length === 0)
+                return "tripId is required.";
+            if (typeof legId !== "string" || legId.length === 0)
+                return "legId is required.";
+            try {
+                const evidence = validateTripEvidence(parseJsonArg(args.evidence, "evidence"));
+                const trip = (0, store_1.readTripRecord)((0, identity_1.getAgentName)(), tripId);
+                const legIndex = trip.legs.findIndex((leg) => leg.legId === legId);
+                if (legIndex === -1)
+                    return `leg ${legId} not found in trip ${tripId}.`;
+                const leg = trip.legs[legIndex];
+                const updatedLeg = {
+                    ...leg,
+                    evidence: [...leg.evidence, evidence],
+                    updatedAt: evidence.recordedAt,
+                };
+                const updated = {
+                    ...trip,
+                    legs: [...trip.legs.slice(0, legIndex), updatedLeg, ...trip.legs.slice(legIndex + 1)],
+                    updatedAt: evidence.recordedAt,
+                };
+                (0, store_1.upsertTripRecord)((0, identity_1.getAgentName)(), updated);
+                (0, runtime_1.emitNervesEvent)({
+                    component: "trips",
+                    event: "trips.evidence_attached",
+                    message: "trip evidence attached to leg",
+                    meta: { agentId: (0, identity_1.getAgentName)(), tripId, legId, discoveryMethod: evidence.discoveryMethod, messageId: evidence.messageId },
+                });
+                return `evidence attached to leg ${legId} in ${tripId}; leg now carries ${updatedLeg.evidence.length} evidence entries.`;
+            }
+            catch (error) {
+                if (error instanceof store_1.TripNotFoundError)
+                    return error.message;
+                return `attach failed: ${error instanceof Error ? error.message : /* v8 ignore next -- non-Error throw is unreachable from validateTripEvidence/parseJsonArg/store */ String(error)}`;
+            }
+        },
+        summaryKeys: ["tripId", "legId"],
+    },
+    {
+        tool: {
+            type: "function",
+            function: {
+                name: "trip_new_id",
+                description: "Compute a deterministic trip id from agentId + name + createdAt. Useful before constructing a new TripRecord so the id is stable and reproducible.",
+                parameters: {
+                    type: "object",
+                    properties: {
+                        name: { type: "string", description: "Human-friendly trip name (e.g. \"Europe summer 2026\")." },
+                        createdAt: { type: "string", description: "ISO timestamp the trip was first conceived. Pass `now` if just creating it." },
+                    },
+                    required: ["name", "createdAt"],
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            if (!trustAllowsTripAccess(ctx))
+                return "trip ledger is private; this tool is only available in trusted contexts.";
+            const name = args.name;
+            const createdAt = args.createdAt;
+            if (typeof name !== "string" || name.length === 0)
+                return "name is required.";
+            if (typeof createdAt !== "string" || createdAt.length === 0)
+                return "createdAt is required.";
+            return (0, core_1.newTripId)((0, identity_1.getAgentName)(), name, createdAt);
+        },
+        summaryKeys: ["name"],
+    },
+];

package/dist/trips/core.js

@@ -0,0 +1,138 @@
+"use strict";
+// Harness-side trip ledger primitive.
+//
+// Mirrors the substrate's @ouro/work-protocol/src/trip.ts contract (vendored
+// the same way mailroom/core.ts vendors mail). Slugger's framing: today,
+// doc-edits-from-mail keep falling back on freeform parsing because there is
+// no structured object between "mail body" and "travel doc". TripRecord +
+// TripLeg are that object — every leg fact carries non-optional provenance
+// (TripEvidence with discoveryMethod) so the ledger can be audited cleanly
+// and reasoned about under conflict.
+//
+// Per-agent ledger keypair design: in v1 each agent has ONE ledger keypair.
+// All TripRecord blobs are encrypted with that key. Cross-trip sharing
+// (handing one trip's facts to another party without their owning the whole
+// ledger) is a follow-on; it would shard to per-trip keys, which the
+// substrate's TripLedgerRegistry can already represent.
+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.generateTripKeyPair = generateTripKeyPair;
+exports.encryptTripRecord = encryptTripRecord;
+exports.decryptTripRecord = decryptTripRecord;
+exports.newTripId = newTripId;
+exports.newLegId = newLegId;
+exports.newTripLedgerRecord = newTripLedgerRecord;
+const crypto = __importStar(require("node:crypto"));
+// ── Helpers: keys + crypto ─────────────────────────────────────────
+function safeLabel(label) {
+    return label.toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function generateTripKeyPair(label) {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("rsa", {
+        modulusLength: 2048,
+        publicKeyEncoding: { type: "spki", format: "pem" },
+        privateKeyEncoding: { type: "pkcs8", format: "pem" },
+    });
+    const slug = safeLabel(label) || "ledger";
+    const fingerprint = crypto.createHash("sha256").update(publicKey).digest("hex").slice(0, 16);
+    return {
+        keyId: `trip_${slug}_${fingerprint}`,
+        publicKeyPem: publicKey,
+        privateKeyPem: privateKey,
+    };
+}
+function encryptTripRecord(trip, publicKeyPem, keyId) {
+    const contentKey = crypto.randomBytes(32);
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv("aes-256-gcm", contentKey, iv);
+    const ciphertext = Buffer.concat([cipher.update(Buffer.from(JSON.stringify(trip), "utf-8")), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const wrappedKey = crypto.publicEncrypt({ key: publicKeyPem, oaepHash: "sha256" }, contentKey);
+    return {
+        algorithm: "RSA-OAEP-SHA256+A256GCM",
+        keyId,
+        wrappedKey: wrappedKey.toString("base64"),
+        iv: iv.toString("base64"),
+        authTag: authTag.toString("base64"),
+        ciphertext: ciphertext.toString("base64"),
+    };
+}
+function decryptTripRecord(payload, privateKeyPem) {
+    const contentKey = crypto.privateDecrypt({
+        key: privateKeyPem,
+        oaepHash: "sha256",
+    }, Buffer.from(payload.wrappedKey, "base64"));
+    const decipher = crypto.createDecipheriv("aes-256-gcm", contentKey, Buffer.from(payload.iv, "base64"));
+    decipher.setAuthTag(Buffer.from(payload.authTag, "base64"));
+    const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(payload.ciphertext, "base64")),
+        decipher.final(),
+    ]);
+    return JSON.parse(plaintext.toString("utf-8"));
+}
+// ── Helpers: deterministic ids ─────────────────────────────────────
+function newTripId(agentId, name, createdAt) {
+    const fingerprint = crypto.createHash("sha256")
+        .update(`${agentId}\n${name}\n${createdAt}`)
+        .digest("hex")
+        .slice(0, 16);
+    const slug = safeLabel(name) || "trip";
+    return `trip_${slug}_${fingerprint}`;
+}
+function newLegId(input) {
+    const distinguish = input.vendor || input.confirmationCode || crypto.randomUUID();
+    const fingerprint = crypto.createHash("sha256")
+        .update(`${input.tripId}\n${input.kind}\n${distinguish}\n${input.createdAt}`)
+        .digest("hex")
+        .slice(0, 16);
+    return `leg_${input.kind}_${fingerprint}`;
+}
+// ── Ledger record helpers ──────────────────────────────────────────
+function newTripLedgerRecord(input) {
+    const now = (input.now ?? (() => new Date().toISOString()))();
+    const keypair = generateTripKeyPair(input.label ?? input.agentId);
+    const ledgerId = `ledger_${safeLabel(input.agentId) || "agent"}_${crypto.createHash("sha256").update(`${input.agentId}\n${now}\n${keypair.keyId}`).digest("hex").slice(0, 16)}`;
+    return {
+        ledger: {
+            schemaVersion: 1,
+            agentId: input.agentId,
+            ledgerId,
+            keyId: keypair.keyId,
+            publicKeyPem: keypair.publicKeyPem,
+            createdAt: now,
+        },
+        keypair,
+    };
+}

package/dist/trips/store.js

@@ -0,0 +1,146 @@
+"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.TripNotFoundError = void 0;
+exports.ensureAgentTripLedger = ensureAgentTripLedger;
+exports.readAgentTripKeypair = readAgentTripKeypair;
+exports.upsertTripRecord = upsertTripRecord;
+exports.readTripRecord = readTripRecord;
+exports.listTripIds = listTripIds;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const core_1 = require("./core");
+function tripsRoot(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "trips");
+}
+function ledgerPath(agentName) {
+    return path.join(tripsRoot(agentName), "ledger.json");
+}
+function recordsDir(agentName) {
+    return path.join(tripsRoot(agentName), "records");
+}
+function recordPath(agentName, tripId) {
+    return path.join(recordsDir(agentName), `${tripId}.json`);
+}
+function readJsonFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+function writeJsonAtomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2), "utf-8");
+    fs.renameSync(tmp, filePath);
+}
+class TripNotFoundError extends Error {
+    statusCode = 404;
+    constructor(input) {
+        super(`trip not found: agent=${input.agentName} trip=${input.tripId}`);
+    }
+}
+exports.TripNotFoundError = TripNotFoundError;
+/**
+ * Idempotent — if the agent already has a ledger on disk, return it; otherwise
+ * generate a fresh keypair and persist both halves.
+ */
+function ensureAgentTripLedger(input) {
+    const existing = readJsonFile(ledgerPath(input.agentName));
+    if (existing) {
+        return { ledger: existing.ledger, added: false };
+    }
+    const created = (0, core_1.newTripLedgerRecord)({
+        agentId: input.agentName,
+        ...(input.label ? { label: input.label } : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+    const stored = {
+        schemaVersion: 1,
+        ledger: created.ledger,
+        privateKeyPem: created.keypair.privateKeyPem,
+    };
+    writeJsonAtomic(ledgerPath(input.agentName), stored);
+    (0, runtime_1.emitNervesEvent)({
+        component: "trips",
+        event: "trips.ledger_created",
+        message: "agent trip ledger keypair created",
+        meta: { agentId: input.agentName, ledgerId: created.ledger.ledgerId, keyId: created.ledger.keyId },
+    });
+    return { ledger: created.ledger, added: true };
+}
+function readLedgerOrThrow(agentName) {
+    const stored = readJsonFile(ledgerPath(agentName));
+    if (!stored) {
+        throw new Error(`no trip ledger for agent ${agentName} — call ensureAgentTripLedger first`);
+    }
+    return stored;
+}
+function readAgentTripKeypair(agentName) {
+    const stored = readLedgerOrThrow(agentName);
+    return {
+        keyId: stored.ledger.keyId,
+        publicKeyPem: stored.ledger.publicKeyPem,
+        privateKeyPem: stored.privateKeyPem,
+    };
+}
+function upsertTripRecord(agentName, trip) {
+    const stored = readLedgerOrThrow(agentName);
+    const payload = (0, core_1.encryptTripRecord)(trip, stored.ledger.publicKeyPem, stored.ledger.keyId);
+    writeJsonAtomic(recordPath(agentName, trip.tripId), payload);
+    (0, runtime_1.emitNervesEvent)({
+        component: "trips",
+        event: "trips.record_upserted",
+        message: "trip record upserted",
+        meta: { agentId: agentName, tripId: trip.tripId, legCount: trip.legs.length, status: trip.status },
+    });
+}
+function readTripRecord(agentName, tripId) {
+    const payload = readJsonFile(recordPath(agentName, tripId));
+    if (!payload)
+        throw new TripNotFoundError({ agentName, tripId });
+    const stored = readLedgerOrThrow(agentName);
+    return (0, core_1.decryptTripRecord)(payload, stored.privateKeyPem);
+}
+function listTripIds(agentName) {
+    const dir = recordsDir(agentName);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => entry.slice(0, -".json".length))
+        .sort();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.488",
+  "version": "0.1.0-alpha.489",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",