@ouro.bot/cli 0.1.0-alpha.92 → 0.1.0-alpha.921

package/dist/a2a/task-store.js

@@ -0,0 +1,69 @@
+"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.FileA2ATaskStore = void 0;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const runtime_1 = require("../nerves/runtime");
+function taskFileName(taskId, ownerScope) {
+    return `${(0, node_crypto_1.createHash)("sha256").update(`${ownerScope}\n${taskId}`).digest("hex")}.json`;
+}
+class FileA2ATaskStore {
+    dir;
+    constructor(agentRoot) {
+        this.dir = path.join(agentRoot, "state", "a2a", "tasks");
+        fs.mkdirSync(this.dir, { recursive: true });
+        (0, runtime_1.emitNervesEvent)({
+            component: "channels",
+            event: "channel.a2a_task_store_init",
+            message: "initialized A2A task store",
+            meta: { dir: this.dir },
+        });
+    }
+    put(task, ownerScope = "legacy") {
+        fs.writeFileSync(path.join(this.dir, taskFileName(task.id, ownerScope)), `${JSON.stringify(task, null, 2)}\n`, "utf-8");
+    }
+    get(taskId, ownerScope = "legacy") {
+        try {
+            const raw = fs.readFileSync(path.join(this.dir, taskFileName(taskId, ownerScope)), "utf-8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+}
+exports.FileA2ATaskStore = FileA2ATaskStore;

package/dist/a2a/transport.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeA2ATransport = makeA2ATransport;
+const runtime_1 = require("../nerves/runtime");
+const client_1 = require("./client");
+/** The not-wired marker for the relay/mailbox rungs (the stubbed seam). */
+const RELAY_NOT_WIRED = "A2A relay/mailbox transport is not wired — see ourostack/friends-relay";
+/**
+ * Build the harness `A2ATransport` (the outbound delivery seam friends' `sendShare`
+ * calls). Only the `direct` rung is wired in this slice: it HTTP-POSTs the sealed,
+ * `wrapInDataPart`-wrapped message to the peer's `endpointUrl` (the `address`) as a
+ * JSON-RPC `message/send`, reusing the harness `client.ts` plumbing. The `relay` and
+ * `mailbox` rungs are a TYPED-but-STUBBED seam: they throw a clear not-wired error
+ * naming the `ourostack/friends-relay` dependency, so a future relay slice has an
+ * exact insertion point without this slice shipping an untrusted relay.
+ */
+function makeA2ATransport(input = {}) {
+    return {
+        async send(target, message) {
+            if (target.rung === "direct") {
+                (0, runtime_1.emitNervesEvent)({
+                    component: "channels",
+                    event: "channel.a2a_transport_direct_send",
+                    message: "delivering sealed A2A message over the direct rung",
+                    meta: { address: target.address },
+                });
+                await (0, client_1.postA2AMessageEnvelope)({
+                    endpointUrl: target.address,
+                    message,
+                    ...(input.fetchImpl ? { fetchImpl: input.fetchImpl } : {}),
+                });
+                return;
+            }
+            // relay / mailbox: the typed-but-stubbed seam. Loud refusal (security-relevant:
+            // we never silently fall through to an untrusted relay).
+            (0, runtime_1.emitNervesEvent)({
+                component: "channels",
+                event: "channel.a2a_transport_not_wired",
+                message: "refused A2A transport over a non-direct rung (not wired)",
+                meta: { rung: target.rung, address: target.address, dependency: "ourostack/friends-relay" },
+            });
+            throw new Error(`${RELAY_NOT_WIRED} (rung: ${target.rung})`);
+        },
+    };
+}

package/dist/a2a/trust-commands.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeDelegatedCommandsCommand = executeDelegatedCommandsCommand;
+exports.executeEscalationCommand = executeEscalationCommand;
+const runtime_1 = require("../nerves/runtime");
+const delegated_command_grants_1 = require("./delegated-command-grants");
+const escalation_grants_1 = require("./escalation-grants");
+const replay_grant_holders_1 = require("./replay-grant-holders");
+const operator_trust_1 = require("./operator-trust");
+const resolution_proof_1 = require("./resolution-proof");
+const NEEDS_ROOT = "refusing: this command writes root-owned files the agent cannot forge, so it must run as root on the agent's host (for example docker exec as root, or sudo). Nothing was written.";
+function requireRoot(ctx) {
+    if (!ctx.isRoot)
+        throw new Error(NEEDS_ROOT);
+}
+async function requireFriend(ctx, friendId) {
+    const friend = await ctx.store.get(friendId);
+    if (!friend)
+        throw new Error(`friend not found: ${friendId}`);
+    return friend;
+}
+/** The --did rules shared by both grant commands. Returns the DID to pin (equal to the record's). */
+function checkedDid(friend, did) {
+    if (!did || !did.startsWith("did:"))
+        throw new Error(`refusing: --did ${did ?? "(missing)"} is not a DID (it starts with did:). Copy it from the sender's own host with: ouro a2a identity --json. Nothing was written.`);
+    const recorded = (0, resolution_proof_1.friendDid)(friend);
+    if (!recorded)
+        throw new Error(`refusing: ${friend.name} has no DID on record, so there is nothing to check --did against. Onboard it with its DID first (ouro a2a onboard --did <did> --name "${friend.name}"). Nothing was written.`);
+    if (recorded !== did)
+        throw new Error(`refusing: --did ${did} does not match the DID on ${friend.name}'s record (${recorded}). If the sender's key really changed, onboard it again; otherwise you copied the wrong DID. Nothing was written.`);
+    return did;
+}
+/**
+ * The checks both grant commands share before they pin a DID. It may not be this agent's own, and it may not already be pinned by
+ * another holder's grant in the same file. When this agent's own DID cannot be read (a one-off root container has no vault) the
+ * own-DID check cannot run, so the command instead refuses any DID that a second friend record also carries (a sender's key is on
+ * exactly one record), and says so in its output.
+ */
+async function vetPinnedDid(ctx, friend, did, held) {
+    const own = await ctx.ownDid();
+    if (own === did)
+        throw new Error("refusing: that is this agent's own DID. A grant must pin the sender's key, not this agent's. Nothing was written.");
+    const holder = Object.entries(held).find(([id, existing]) => id !== friend.id && existing.did === did);
+    if (holder)
+        throw new Error(`refusing: that DID is already pinned by ${holder[0]}'s grant. Revoke it first if the sender really moved to a different friend record. Nothing was written.`);
+    if (own !== null)
+        return [];
+    // The own DID is not available from the machine config here. A DID the agent published in its bundle is only a hint (the agent can write
+    // that file), so the friend-record comparison always runs as well, and the published value is reported with its source.
+    const published = await ctx.publishedDid?.() ?? null;
+    const records = await ctx.store.listAll?.() ?? [];
+    const twin = records.find((record) => record.id !== friend.id && (0, resolution_proof_1.friendDid)(record) === did);
+    if (twin)
+        throw new Error(`refusing: this agent's own DID could not be read from its machine config here, and another friend record (${twin.name}, ${twin.id}) carries that same DID, so it may be this agent's own key. Check it with: ouro a2a identity --agent ${ctx.agentName} --json. Nothing was written.`);
+    const notes = ["note: could not read this agent's own DID from its machine config here, so the own-DID check was skipped; compared --did with every DID in the friend records instead, and no other record carries it"];
+    if (published === did)
+        notes.push("warning: --did equals the DID published in the agent's bundle (source: bundle-published, which the agent itself can write, so this is advisory). Granting it would pin the agent's own key; check with ouro a2a identity --agent " + ctx.agentName + " --json before relying on this grant");
+    else if (published !== null)
+        notes.push(`note: the DID published in the agent's bundle (source: bundle-published, advisory) is ${published}, which differs from --did`);
+    return notes;
+}
+function notActiveFamilyNote(friend, what) {
+    return friend.trustLevel === "family" && friend.admissionState === "active"
+        ? []
+        : [`note: ${friend.name} is ${friend.trustLevel}, ${friend.admissionState}, so the grant stays suspended until it is active family${what}`];
+}
+function parseExpiry(expires, now) {
+    if (expires === undefined)
+        return undefined;
+    const at = Date.parse(expires);
+    if (!Number.isFinite(at) || at <= now.getTime())
+        throw new Error(`refusing: --expires ${expires} is not a time in the future (use an ISO date such as 2027-01-01T00:00:00Z). Nothing was written.`);
+    return new Date(at).toISOString();
+}
+async function executeDelegatedCommandsCommand(command, ctx) {
+    if (command.action === "list")
+        return listDelegatedCommands(ctx, command.json === true);
+    requireRoot(ctx);
+    if (command.action === "revoke")
+        return revokeDelegatedCommands(command.friendId, ctx);
+    const expiresAt = parseExpiry(command.expires, ctx.now);
+    const friend = await requireFriend(ctx, command.friendId);
+    if (expiresAt === undefined && (0, replay_grant_holders_1.isReplayGrantHolder)(ctx.agentRoot, friend.id))
+        throw new Error(`refusing: ${friend.name} is a replay peer (it is on the replay gate's list in ${(0, operator_trust_1.operatorTrustDir)(ctx.agentRoot)}), or that list is present but not trustworthy, and a replay peer's grant must expire. Pass --expires <ISO date>. Nothing was written.`);
+    const did = checkedDid(friend, command.did);
+    const selfNotes = await vetPinnedDid(ctx, friend, did, (0, delegated_command_grants_1.readDelegatedCommandGrants)(ctx.agentRoot));
+    const change = (0, delegated_command_grants_1.setDelegatedCommandGrant)(ctx.agentRoot, friend.id, { grant: true, did, source: command.source ?? `ouro a2a delegated-commands grant, ${ctx.now.toISOString()}`, ...(expiresAt ? { expiresAt } : {}) }, ctx.now);
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "grant", scope: "delegated_commands" } });
+    return [
+        `granted delegated commands: ${friend.name} (${friend.id})${change.changed ? "" : " (no change)"}`,
+        `pinned DID: ${did}`,
+        `expires: ${expiresAt ?? "never"}`,
+        `trust directory: ${(0, operator_trust_1.operatorTrustDir)(ctx.agentRoot)}`,
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+        ...selfNotes,
+        ...((0, delegated_command_grants_1.readDelegatedCommandGrants)(ctx.agentRoot)[friend.id] === undefined ? [`WARNING: the grant is written but will not be honoured: ${(0, delegated_command_grants_1.delegatedCommandGrantsPath)(ctx.agentRoot)} and every directory above it must be owned by root and writable by no one else. Run \`ouro a2a delegated-commands list\` for what the harness sees.`] : []),
+        ...notActiveFamilyNote(friend, ""),
+    ].join("\n");
+}
+/** The follow-up that clears the legacy record field as the resident user: the record is the Butler's own file, and this command runs as root, so it never writes it. */
+function clearLegacyGrantCommand(agentRoot, friendId) {
+    const file = `${agentRoot}/friends/${friendId}.json`;
+    const script = `const fs=require("fs");const f=${JSON.stringify(file)};const r=JSON.parse(fs.readFileSync(f,"utf8"));delete r.delegationGrant;fs.writeFileSync(f,JSON.stringify(r,null,2)+"\\n")`;
+    return [
+        "REQUIRED FOLLOW-UP: the trusted grant is removed, but the legacy delegationGrant on the friend record is still there (friend records are never written as root). An older harness would honour it after a rollback. Clear it as the resident user:",
+        `  docker exec -u 10001 ouro-butler node -e '${script}'`,
+    ].join("\n");
+}
+async function revokeDelegatedCommands(friendId, ctx) {
+    const friend = await ctx.store.get(friendId);
+    const change = (0, delegated_command_grants_1.setDelegatedCommandGrant)(ctx.agentRoot, friendId, { grant: false }, ctx.now);
+    // A rollback to an older harness reads the legacy record grant. This command runs as root and must not write the Butler's friend record, so it prints the resident-user follow-up instead.
+    const legacyFollowUp = friend?.delegationGrant !== undefined ? clearLegacyGrantCommand(ctx.agentRoot, friend.id) : null;
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "revoke", scope: "delegated_commands" } });
+    return [
+        `revoked delegated commands: ${friend ? `${friend.name} (${friend.id})` : `${friendId} (no friend record)`}${change.changed || legacyFollowUp ? "" : " (no change)"}`,
+        ...(legacyFollowUp ? [legacyFollowUp] : []),
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+    ].join("\n");
+}
+function statusOf(friendId, grant, friend, ctx) {
+    if (!friend)
+        return { status: "not_honoured", reason: "no_friend_record", text: `no friend record for ${friendId}` };
+    const check = (0, delegated_command_grants_1.checkDelegatedCommandGrant)(ctx.agentRoot, friend, (0, resolution_proof_1.friendDid)(friend), ctx.now.getTime());
+    if (check.ok)
+        return { status: "honoured" };
+    switch (check.reason) {
+        case "not_family":
+            return { status: "suspended", reason: check.reason, text: `${friend.name} is trust ${friend.trustLevel}, admission ${friend.admissionState}; the grant is kept and applies again once it is family and active` };
+        case "grant_did_mismatch":
+            return { status: "not_honoured", reason: check.reason, text: `the friend record names ${(0, resolution_proof_1.friendDid)(friend) ?? "no DID"}, but the grant pins ${grant.did}` };
+        default:
+            return { status: "not_honoured", reason: check.reason, text: "the grant is not in force: it expired, this is a replay identity outside its window, or the grant file stopped being trusted" };
+    }
+}
+async function listDelegatedCommands(ctx, json) {
+    const file = (0, delegated_command_grants_1.delegatedCommandGrantsPath)(ctx.agentRoot);
+    const view = (0, delegated_command_grants_1.viewDelegatedCommandGrants)(ctx.agentRoot);
+    const friends = await ctx.store.listAll?.() ?? [];
+    const byId = new Map(friends.map((friend) => [friend.id, friend]));
+    const entries = Object.entries(view.grants).map(([friendId, grant]) => {
+        const friend = byId.get(friendId) ?? null;
+        return { friendId, name: friend?.name ?? null, grant, ...statusOf(friendId, grant, friend, ctx) };
+    });
+    const legacy = friends.filter((friend) => friend.delegationGrant !== undefined);
+    if (json) {
+        return JSON.stringify({
+            agent: ctx.agentName,
+            file: { path: file, state: view.state, ...(view.state === "untrusted" ? { reason: view.reason } : {}) },
+            grants: entries.map(({ friendId, name, grant, ...status }) => ({ friendId, name, did: grant.did, grantedAt: grant.grantedAt, source: grant.source, expiresAt: grant.expiresAt ?? null, ...status })),
+            ignoredEntries: view.ignored,
+            legacyRecordGrants: legacy.map((friend) => ({ friendId: friend.id, name: friend.name })),
+        }, null, 2);
+    }
+    const header = view.state === "trusted" ? `trusted: ${file}` : view.state === "missing" ? `not present: ${file}` : `NOT TRUSTED: ${file} (${view.reason}); no grant in it is honoured`;
+    const lines = [`delegated-command grants for ${ctx.agentName}`, header];
+    if (entries.length === 0)
+        lines.push("no delegated-command grants");
+    for (const entry of entries) {
+        lines.push(`${entry.friendId}  ${entry.name ?? "(no friend record)"}`, `  DID ${entry.grant.did}; granted ${entry.grant.grantedAt} (${entry.grant.source}); expires ${entry.grant.expiresAt ?? "never"}`, entry.status === "honoured" ? "  HONOURED" : entry.status === "suspended" ? `  SUSPENDED: ${entry.text}` : `  NOT HONOURED: ${entry.text}`);
+    }
+    if (view.ignored.length > 0)
+        lines.push(`ignored (malformed) entries: ${view.ignored.join(", ")}`);
+    if (legacy.length > 0)
+        lines.push(`legacy friend-record grants (not honoured): ${legacy.map((friend) => `${friend.name} (${friend.id})`).join(", ")}`);
+    return lines.join("\n");
+}
+async function executeEscalationCommand(command, ctx) {
+    if (command.action === "list") {
+        const grants = Object.entries((0, escalation_grants_1.readEscalationGrants)(ctx.agentRoot));
+        const view = (0, escalation_grants_1.viewEscalationGrants)(ctx.agentRoot);
+        const note = view.state === "untrusted" ? `\nNOT TRUSTED: ${(0, escalation_grants_1.escalationGrantsPath)(ctx.agentRoot)} (${view.reason}); no grant in it is honoured` : "";
+        return (grants.length === 0 ? "no escalation grants" : grants.map(([id, grant]) => `${id}  granted ${grant.grantedAt}  ${grant.did}  ${grant.source}`).join("\n")) + note;
+    }
+    requireRoot(ctx);
+    if (command.action === "revoke")
+        return revokeEscalation(command.friendId, ctx);
+    const friend = await requireFriend(ctx, command.friendId);
+    if ((0, replay_grant_holders_1.isReplayGrantHolder)(ctx.agentRoot, friend.id))
+        throw new Error(`refusing: ${friend.name} is a replay peer (it is on the replay gate's list in ${(0, operator_trust_1.operatorTrustDir)(ctx.agentRoot)}). Only the replay gate grants it escalation, and only while a run is open. Nothing was written.`);
+    const did = checkedDid(friend, command.did);
+    const selfNotes = await vetPinnedDid(ctx, friend, did, (0, escalation_grants_1.readEscalationGrants)(ctx.agentRoot));
+    const change = (0, escalation_grants_1.setEscalationGrant)(ctx.agentRoot, friend.id, { grant: true, source: command.source ?? `ouro a2a escalation grant, ${ctx.now.toISOString()}`, did }, ctx.now);
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "grant", scope: "escalation" } });
+    return [
+        `granted escalation: ${friend.name} (${friend.id})${change.changed ? "" : " (no change)"}`,
+        `pinned DID: ${did}`,
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+        ...selfNotes,
+        ...((0, escalation_grants_1.readEscalationGrants)(ctx.agentRoot)[friend.id] === undefined ? [`WARNING: the grant is written but will not be honoured: ${(0, escalation_grants_1.escalationGrantsPath)(ctx.agentRoot)} and every directory above it must be owned by root and writable by no one else.`] : []),
+        ...(friend.trustLevel !== "family" || friend.admissionState !== "active" ? [`note: ${friend.name} only holds the grant while it is active family (now ${friend.trustLevel}, ${friend.admissionState})`] : []),
+    ].join("\n");
+}
+/** Revoke needs no friend record: a grant for a friend that was deleted must still be removable by its id. */
+async function revokeEscalation(friendId, ctx) {
+    const friend = await ctx.store.get(friendId);
+    const change = (0, escalation_grants_1.setEscalationGrant)(ctx.agentRoot, friendId, { grant: false }, ctx.now);
+    (0, runtime_1.emitNervesEvent)({ component: "senses", event: "senses.a2a_trust_grant_changed", message: "operator changed a trust grant", meta: { action: "revoke", scope: "escalation" } });
+    return [
+        `revoked escalation: ${friend ? `${friend.name} (${friend.id})` : `${friendId} (no friend record)`}${change.changed ? "" : " (no change)"}`,
+        ...(change.backup ? [`backup: ${change.backup}`] : []),
+    ].join("\n");
+}

package/dist/a2a/trusted-files.js

@@ -0,0 +1,185 @@
+"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.TRUSTED_UID = void 0;
+exports.overrideTrustedUidForTests = overrideTrustedUidForTests;
+exports.overrideTrustChainRootForTests = overrideTrustChainRootForTests;
+exports.overrideOwnerForTests = overrideOwnerForTests;
+exports.__resetRejectionRateLimitForTests = __resetRejectionRateLimitForTests;
+exports.isTrustedDirectory = isTrustedDirectory;
+exports.inspectTrustedDirectory = inspectTrustedDirectory;
+exports.inspectTrustedJson = inspectTrustedJson;
+exports.readTrustedJson = readTrustedJson;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const runtime_1 = require("../nerves/runtime");
+/**
+ * Operator-set state is only honoured when the agent's own process (and anything a prompt-injected model can run
+ * through its shell) cannot have written it. The rule is the one sshd calls StrictModes: the file and EVERY directory
+ * above it, up to `/`, must be real (no symlinks), owned by the trusted uid (root), and closed to group and other
+ * writes. A check on the file's own directory alone is not enough: an agent that owns the parent can rename the
+ * root-owned directory away and put one of its own making in its place (rename-then-rebless). Anything that fails reads
+ * as "not there", so every consumer fails closed.
+ */
+exports.TRUSTED_UID = 0;
+let uidOverride;
+let chainRootOverride;
+let ownerOverride;
+/** Only a test runner sets VITEST; the running Butler (and its prompt-injected shell) cannot reach this process's environment. */
+const underTestRunner = () => process.env.VITEST !== undefined;
+/** Tests run as an ordinary user, so they declare that user trusted. Refused outside a test runner, and ignored there too. */
+function overrideTrustedUidForTests(uid) {
+    if (!underTestRunner())
+        throw new Error("overrideTrustedUidForTests is for tests only");
+    uidOverride = uid;
+}
+/**
+ * Tests keep their files under a private temp root whose ancestors (`/tmp`, `/private`) are not the test user's. A test
+ * names that root here, and the ancestor walk stops there (the root itself and everything above it are skipped).
+ */
+function overrideTrustChainRootForTests(root) {
+    if (!underTestRunner())
+        throw new Error("overrideTrustChainRootForTests is for tests only");
+    chainRootOverride = root;
+}
+/** Tests are not root, so they cannot hand a path to another owner: this reports the owner a test wants for a path (`undefined` keeps the real one). */
+function overrideOwnerForTests(lookup) {
+    if (!underTestRunner())
+        throw new Error("overrideOwnerForTests is for tests only");
+    ownerOverride = lookup;
+}
+const ownerOf = (target, stat) => (underTestRunner() ? ownerOverride?.(target) : undefined) ?? stat.uid;
+const effectiveTrustedUid = () => (underTestRunner() ? uidOverride : undefined) ?? exports.TRUSTED_UID;
+const effectiveChainRoot = () => (underTestRunner() ? chainRootOverride : undefined);
+const REJECTION_WINDOW_MS = 60_000;
+const lastRejection = new Map();
+/** Test hook: the rate limiter is module state. */
+function __resetRejectionRateLimitForTests() {
+    lastRejection.clear();
+}
+/** One warn per target and reason per minute: a rejected file is re-read on every inbound message. */
+function rejected(target, reason) {
+    const key = `${target}\u0000${reason}`;
+    const now = Date.now();
+    const last = lastRejection.get(key);
+    if (last !== undefined && now - last < REJECTION_WINDOW_MS)
+        return;
+    lastRejection.set(key, now);
+    (0, runtime_1.emitNervesEvent)({ level: "warn", component: "senses", event: "senses.a2a_trusted_file_rejected", message: "ignored operator-set state the agent could have written", meta: { target, reason } });
+}
+/** Every directory from `target` up to `/` (or the test chain root): a real directory, trusted owner, closed to group and other writes. */
+function inspectChain(target, trustedUid) {
+    const stop = effectiveChainRoot();
+    let current = path.resolve(target);
+    for (;;) {
+        if (stop !== undefined && current === stop)
+            return { state: "trusted" };
+        let stat;
+        try {
+            stat = fs.lstatSync(current);
+        }
+        catch (error) {
+            return error.code === "ENOENT" || error.code === "ENOTDIR"
+                ? { state: "missing" }
+                : { state: "untrusted", reason: `cannot inspect ${current}` };
+        }
+        if (stat.isSymbolicLink())
+            return { state: "untrusted", reason: `${current} is a symlink` };
+        if (!stat.isDirectory())
+            return { state: "untrusted", reason: `${current} is not a directory` };
+        if (ownerOf(current, stat) !== trustedUid)
+            return { state: "untrusted", reason: `${current} is not owned by the trusted uid` };
+        if ((stat.mode & 0o022) !== 0)
+            return { state: "untrusted", reason: `${current} is writable by group or other` };
+        const parent = path.dirname(current);
+        if (parent === current)
+            return { state: "trusted" };
+        current = parent;
+    }
+}
+/** A real directory (no symlink) owned by the trusted uid and closed to group and other writes, with every ancestor up to `/` the same. */
+function isTrustedDirectory(target, trustedUid = effectiveTrustedUid()) {
+    const result = inspectChain(target, trustedUid);
+    if (result.state === "trusted")
+        return true;
+    rejected(target, result.state === "missing" ? "directory does not exist" : result.reason);
+    return false;
+}
+/** Same chain check, without the warning: for callers that probe before they decide whether the state is wrong. */
+function inspectTrustedDirectory(target, trustedUid = effectiveTrustedUid()) {
+    return inspectChain(target, trustedUid);
+}
+/**
+ * Reads a JSON file only if the whole chain above it is trusted and the file actually opened is trusted. The path is
+ * opened once with O_NOFOLLOW, then the descriptor itself is checked (regular file, trusted owner, not group- or
+ * other-writable) and read, so a rename loop cannot swap a different file in between the check and the read.
+ * `missing` means the file or a directory above it does not exist; everything else that fails is `untrusted`.
+ */
+function inspectTrustedJson(file, trustedUid = effectiveTrustedUid()) {
+    const chain = inspectChain(path.dirname(file), trustedUid);
+    if (chain.state === "missing")
+        return { state: "missing" };
+    if (chain.state === "untrusted") {
+        rejected(file, chain.reason);
+        return chain;
+    }
+    let fd;
+    try {
+        fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || ownerOf(file, stat) !== trustedUid || (stat.mode & 0o022) !== 0) {
+            const reason = "file is not a regular file owned by the trusted uid and closed to group and other writes";
+            rejected(file, reason);
+            return { state: "untrusted", reason };
+        }
+        return { state: "trusted", value: JSON.parse(fs.readFileSync(fd, "utf8")) };
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { state: "missing" };
+        const reason = error instanceof SyntaxError ? "file is not valid JSON" : "file could not be opened without following links";
+        rejected(file, reason);
+        return { state: "untrusted", reason };
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/** The parsed JSON of a trusted file, or `undefined` for anything else. */
+function readTrustedJson(file, trustedUid = effectiveTrustedUid()) {
+    const result = inspectTrustedJson(file, trustedUid);
+    return result.state === "trusted" ? result.value : undefined;
+}

package/dist/a2a/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/* v8 ignore file -- type-only A2A protocol definitions */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/arc/attention-types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Shared attention queue types.
+ *
+ * Canonical home for the AttentionItem interface — consumed by heart/, repertoire/, nerves/, and senses/.
+ * Placed in heart/ because attention is a turn-coordination concern.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });