@fungi.computer/truffle 0.2.1 → 0.3.0

package/dist/private-local-delegation.js

@@ -1,6 +1,5 @@
-import { deterministicReplayKey } from "@fungi.computer/cairn";
 import { AgentArchiveRefused } from "@fungi.computer/shiitake/agent-control";
-import { createFleetDelegation, delegationProvenance, delegationReplyMeta, delegationSendMeta, } from "@fungi.computer/shiitake/fleet";
+import { agentDelegationRequestKey, createFleetDelegation, delegationProvenance, delegationReplyMeta, delegationSendMeta, } from "@fungi.computer/shiitake/fleet";
 /** How long one Local delegation grant stays valid while it is admitted. */
 const grantLifetimeMs = 60_000;
 /**
@@ -32,21 +31,17 @@ export function createPrivateLocalDelegation(input) {
         }
         return agents;
     }
-    function requestKey(task, sourceSessionId) {
-        return deterministicReplayKey("local-agent-delegation", [
-            input.agentId,
-            sourceSessionId,
-            task.agentId,
-            task.sessionId,
-            task.requestId,
-        ]);
-    }
     /** Send with one caller-owned identity; follow-up replies return here. */
     async function send(task, sourceSessionId, signal, invocation) {
         if (invocation === undefined)
             throw new Error("Delegation requires a tool invocation");
         const agents = await authorizedMembers(task.agentId, signal);
-        const requestId = await requestKey(task, sourceSessionId);
+        const requestId = await agentDelegationRequestKey({
+            owner: { kind: "local", agentId: input.agentId },
+            sourceSessionId,
+            targetAgentId: task.agentId,
+            requestId: task.requestId,
+        });
         signal.throwIfAborted();
         if (task.delivery === "steer") {
             const opened = await input.directory.open(task.agentId, signal);
@@ -83,12 +78,21 @@ export function createPrivateLocalDelegation(input) {
     /** Resolve only this sender's receipt, then let the target own the pending guard. */
     async function recall(task, sourceSessionId, signal) {
         await authorizedMembers(task.agentId, signal);
-        const requestId = await requestKey(task, sourceSessionId);
+        const requestId = await agentDelegationRequestKey({
+            owner: { kind: "local", agentId: input.agentId },
+            sourceSessionId,
+            targetAgentId: task.agentId,
+            requestId: task.requestId,
+        });
         signal.throwIfAborted();
         const opened = await input.directory.open(task.agentId, signal);
         try {
-            const session = opened.agent.session(task.sessionId);
-            const admitted = fleet.receipt(requestId) ?? (await session.withdraw(requestId));
+            const receipt = fleet.receipt(requestId);
+            if (receipt?.sessionId !== undefined &&
+                receipt.sessionId !== task.sessionId)
+                return { status: "unknown" };
+            const session = opened.agent.session(receipt?.sessionId ?? task.sessionId);
+            const admitted = receipt ?? (await session.withdraw(requestId));
             return admitted.status === "accepted"
                 ? await session.cancel({
                     commandId: admitted.commandId,
@@ -110,7 +114,11 @@ export function createPrivateLocalDelegation(input) {
         if (mail.to.agentId !== input.agentId && mesh === undefined)
             throw new Error("Local addressed mail recipient is not authorized");
         const agents = mesh ?? (await members(new AbortController().signal));
-        if (!agents.some(({ agentId }) => agentId === mail.from.agentId))
+        const delegation = mail.replyTo.length === 0 ? fleet.authenticateReply(mail) : undefined;
+        const frozenUndeliverable = delegation?.reply.outcome === "undeliverable" &&
+            delegation.reply.agentId === mail.from.agentId;
+        if (!agents.some(({ agentId }) => agentId === mail.from.agentId) &&
+            !frozenUndeliverable)
             throw new Error("Local mail sender is outside this project");
         if (mail.replyTo.length > 0) {
             const [destination] = mail.replyTo;
@@ -120,13 +128,18 @@ export function createPrivateLocalDelegation(input) {
                 throw new Error("Local delegated work must reply to its sender");
             return input.accept(mail, mail.meta);
         }
-        const delegation = fleet.authenticateReply(mail);
+        if (mail.reply?.outcome === "accepted") {
+            const receipt = fleet.recordAcceptedNotice(mail);
+            if (receipt === undefined)
+                throw new Error("Local acceptance notice does not match sent work");
+            return receipt;
+        }
         if (delegation === undefined)
             throw new Error("Local reply does not match work this Agent sent");
         const replier = agents.find(({ agentId }) => agentId === delegation.reply.agentId);
-        if (replier === undefined)
+        if (replier === undefined && !frozenUndeliverable)
             throw new Error("Local reply sender is outside this project");
-        const meta = delegationReplyMeta(delegation, replier.name);
+        const meta = delegationReplyMeta(delegation, replier?.name ?? delegation.reply.agentId);
         return input.accept({ ...mail, meta }, meta, delegation.reply);
     }
     return { send, recall, receive, outstanding: fleet.outstanding };

package/dist/private-local-exec-review.d.ts

@@ -0,0 +1,10 @@
+import type { LocalApprovalReview } from "./private-mcp-form-session.js";
+/** Build the host's review before the approval record is staged or displayed. */
+export declare function localExecEscapeReview(request: {
+    command?: string | undefined;
+    executable?: string | undefined;
+    args?: string[] | undefined;
+    escape?: {
+        justification: string;
+    } | undefined;
+}, cwd: string): LocalApprovalReview;

package/dist/private-local-exec-review.js

@@ -0,0 +1,50 @@
+import { rulePrefix } from "./private-local-exec-rules.js";
+const gitHookGrantSubcommands = new Set([
+    "add",
+    "branch",
+    "checkout",
+    "commit",
+    "diff",
+    "fetch",
+    "merge",
+    "pull",
+    "push",
+    "reset",
+    "restore",
+    "stash",
+    "status",
+    "switch",
+    "tag",
+]);
+/** Build the host's review before the approval record is staged or displayed. */
+export function localExecEscapeReview(request, cwd) {
+    if (request.escape === undefined)
+        throw new Error("An escape requires a justification");
+    const command = request.command ??
+        JSON.stringify([request.executable, ...(request.args ?? [])]);
+    const prefix = request.executable === undefined
+        ? undefined
+        : rulePrefix([request.executable, ...(request.args ?? [])]);
+    const review = {
+        command,
+        cwd,
+        justification: request.escape.justification,
+    };
+    if (prefix !== undefined) {
+        review.prefix = prefix;
+        if (prefix[0] === "git") {
+            const hookCapable = gitHookGrantSubcommands.has(prefix[1] ?? "");
+            review.warning =
+                (hookCapable
+                    ? "Project hooks can run code as you under this grant. Only the hooksPath setting must pre-exist; this Agent can create missing hook files there. A configured fsmonitor path in the worktree may also be Agent-writable."
+                    : "This command runs as you outside the sandbox.") +
+                    (prefix[1] === "push"
+                        ? " This grant can push all branches, force-update them, or delete remote branches."
+                        : "") +
+                    (["push", "fetch", "pull"].includes(prefix[1] ?? "")
+                        ? " Remote URLs can invoke ssh with your HOME and keys."
+                        : "");
+        }
+    }
+    return review;
+}

package/dist/private-local-exec-rules.d.ts

@@ -0,0 +1,14 @@
+/** Offer only direct, narrow grants; extension installs require a fresh card. */
+export declare function rulePrefix(argv: readonly string[]): string[] | undefined;
+/** One host-owned project file; every Agent in the project sees the same rules. */
+export declare function localExecRules(project: string): {
+    list: () => string[][];
+    add: (prefix: readonly string[]) => void;
+    remove: (prefix: readonly string[]) => void;
+    match: (argv: readonly string[], configuredRemotes?: ReadonlySet<string>) => {
+        ruleId: import("@fungi.computer/cairn").CairnId<"local-exec-rules", "rule", 1>;
+    } | undefined;
+    matches: (argv: readonly string[], configuredRemotes?: ReadonlySet<string>) => boolean;
+};
+/** Human CLI management only; no model-facing capability exposes this writer. */
+export declare function manageLocalExecRules(project: string, action: "list" | "remove", prefix?: readonly string[]): readonly (readonly string[])[];

package/dist/private-local-exec-rules.js

@@ -0,0 +1,420 @@
+import { lstatSync, mkdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, } from "node:fs";
+import { basename, join } from "node:path";
+import { correlationKey, defineIdFamily } from "@fungi.computer/cairn";
+import { z } from "zod";
+const prefixSchema = z.array(z.string().min(1).max(4096)).min(1).max(32);
+const projectRuleIds = defineIdFamily({
+    family: "local-exec-rules",
+    version: 1,
+    kinds: { rule: { prefix: "local_exec_rule" } },
+});
+const projectRuleSchema = z.strictObject({
+    id: projectRuleIds.rule.schema,
+    prefix: prefixSchema,
+});
+const projectRulesSchema = z.strictObject({
+    version: z.literal(2),
+    rules: z.array(projectRuleSchema).max(256),
+});
+const gitOptions = {
+    add: {
+        flags: [
+            "--",
+            "-A",
+            "--all",
+            "-u",
+            "--update",
+            "-p",
+            "--patch",
+            "-n",
+            "--dry-run",
+        ],
+        values: [],
+    },
+    branch: {
+        flags: [
+            "--",
+            "-a",
+            "--all",
+            "-d",
+            "-D",
+            "--delete",
+            "-r",
+            "--remotes",
+            "--list",
+            "--show-current",
+            "-v",
+        ],
+        values: ["-m", "-M"],
+    },
+    checkout: {
+        flags: ["--", "-f", "--force", "--detach"],
+        values: ["-b", "-B"],
+    },
+    commit: {
+        flags: [
+            "--",
+            "-a",
+            "--all",
+            "--amend",
+            "--no-edit",
+            "--allow-empty",
+            "-s",
+            "--signoff",
+        ],
+        values: ["-m", "--message"],
+    },
+    diff: {
+        flags: [
+            "--",
+            "--stat",
+            "--cached",
+            "--staged",
+            "--name-only",
+            "--name-status",
+            "--quiet",
+            "--check",
+        ],
+        values: [],
+    },
+    fetch: {
+        flags: [
+            "--",
+            "--all",
+            "--prune",
+            "-p",
+            "--tags",
+            "-t",
+            "-q",
+            "--quiet",
+            "-v",
+            "--verbose",
+            "-n",
+            "--dry-run",
+        ],
+        values: [],
+    },
+    log: {
+        flags: [
+            "--",
+            "--oneline",
+            "--all",
+            "--decorate",
+            "--no-decorate",
+            "--stat",
+            "--name-only",
+            "--graph",
+            "-1",
+            "-2",
+            "-5",
+            "-10",
+        ],
+        values: [],
+    },
+    merge: {
+        flags: [
+            "--",
+            "--abort",
+            "--continue",
+            "--no-ff",
+            "--ff-only",
+            "--squash",
+            "--no-commit",
+        ],
+        values: [],
+    },
+    pull: {
+        flags: [
+            "--",
+            "--ff-only",
+            "--no-rebase",
+            "--no-commit",
+            "--no-edit",
+            "-q",
+            "--quiet",
+            "-v",
+            "--verbose",
+        ],
+        values: [],
+    },
+    push: {
+        flags: [
+            "--",
+            "-u",
+            "--set-upstream",
+            "--all",
+            "--tags",
+            "--delete",
+            "-d",
+            "--force-with-lease",
+            "--dry-run",
+            "-n",
+            "--follow-tags",
+        ],
+        values: [],
+    },
+    remote: { flags: ["-v", "--verbose"], values: [] },
+    reset: {
+        flags: ["--", "--soft", "--mixed", "--hard", "--keep", "-q", "--quiet"],
+        values: [],
+    },
+    restore: { flags: ["--", "--staged", "--worktree"], values: [] },
+    "rev-parse": {
+        flags: [
+            "--",
+            "--verify",
+            "--short",
+            "--abbrev-ref",
+            "--is-inside-work-tree",
+            "--show-toplevel",
+            "--git-dir",
+            "--absolute-git-dir",
+            "--show-prefix",
+        ],
+        values: [],
+    },
+    show: {
+        flags: ["--", "--stat", "--oneline", "--name-only", "-1"],
+        values: [],
+    },
+    stash: {
+        flags: [
+            "--",
+            "-u",
+            "--include-untracked",
+            "-a",
+            "--all",
+            "-k",
+            "--keep-index",
+            "-p",
+            "--patch",
+        ],
+        values: ["-m", "--message"],
+    },
+    status: {
+        flags: [
+            "--",
+            "-s",
+            "--short",
+            "-b",
+            "--branch",
+            "--porcelain",
+            "--ignored",
+        ],
+        values: [],
+    },
+    switch: { flags: ["--", "--detach"], values: ["-c", "-C"] },
+    tag: {
+        flags: ["--", "-l", "--list", "-d", "--delete", "-a", "--annotate"],
+        values: ["-m", "--message"],
+    },
+};
+// Git aliases may run shell commands; never grant a global option or alias.
+const gitProfiles = new Map(Object.entries(gitOptions));
+const gitBuiltins = new Set(gitProfiles.keys());
+const shellExecutables = new Set(["sh", "bash", "zsh", "dash", "fish", "ksh"]);
+const commandWrappers = new Set([
+    "env",
+    "nice",
+    "nohup",
+    "timeout",
+    "xargs",
+    "sudo",
+    "doas",
+    "command",
+    "exec",
+    "stdbuf",
+    "time",
+    "setsid",
+    "chroot",
+    "flock",
+    "busybox",
+]);
+function unsafeExecutable(executable) {
+    const name = basename(executable).toLowerCase();
+    return (shellExecutables.has(name) ||
+        commandWrappers.has(name) ||
+        (name === "git" && executable !== "git") ||
+        (name === "fungi" && executable !== "fungi"));
+}
+function validPrefix(prefix) {
+    return (prefix[0] !== undefined &&
+        !prefix[0].startsWith(".") &&
+        !prefix[0].includes("/") &&
+        !prefix[0].includes("\\") &&
+        !unsafeExecutable(prefix[0]) &&
+        !(basename(prefix[0]) === "fungi" &&
+            (prefix.length === 1 || prefix[1] === "extension")) &&
+        (basename(prefix[0]) !== "git" ||
+            (prefix[0] === "git" &&
+                prefix.length === 2 &&
+                gitBuiltins.has(prefix[1] ?? ""))));
+}
+/** Offer only direct, narrow grants; extension installs require a fresh card. */
+export function rulePrefix(argv) {
+    if (argv.length === 0 ||
+        argv[0]?.startsWith(".") ||
+        argv[0]?.includes("/") ||
+        argv[0]?.includes("\\") ||
+        unsafeExecutable(argv[0] ?? ""))
+        return undefined;
+    if (basename(argv[0] ?? "") === "git") {
+        const prefix = argv.slice(0, 2);
+        return validPrefix(prefix) ? prefix : undefined;
+    }
+    if (basename(argv[0] ?? "") === "fungi" &&
+        argv[1] === "extension" &&
+        argv[2] === "add")
+        return undefined;
+    const parsed = prefixSchema.safeParse(argv.slice(0, 2));
+    return parsed.success && validPrefix(parsed.data) ? parsed.data : undefined;
+}
+function safeRemote(remote, configuredRemotes) {
+    if (remote === undefined)
+        return true;
+    if (/^(https?|ssh|git):\/\//u.test(remote))
+        return true;
+    // A bare token is also a relative path. Only the protected repository's
+    // configured remote names can authorize it, regardless of filesystem state.
+    return (/^[A-Za-z][A-Za-z0-9_.-]*$/u.test(remote) &&
+        configuredRemotes?.has(remote) === true);
+}
+/** A Git prefix never authorizes options outside the reviewed subcommand profile. */
+function safeGitCommand(argv, configuredRemotes) {
+    if (argv[0] !== "git")
+        return false;
+    const subcommand = argv[1];
+    const profile = gitProfiles.get(subcommand ?? "");
+    if (profile === undefined)
+        return false;
+    const operands = [];
+    for (let index = 2; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg === undefined)
+            return false;
+        if (arg === "--") {
+            operands.push(...argv.slice(index + 1));
+            break;
+        }
+        if (arg.startsWith("-") && arg !== "-") {
+            if (profile.flags.some((option) => option === arg))
+                continue;
+            if (!profile.values.some((option) => option === arg))
+                return false;
+            // A missing value must not turn a following option into an operand.
+            if (argv[index + 1] === undefined || argv[index + 1]?.startsWith("-"))
+                return false;
+            index++;
+        }
+        else {
+            operands.push(arg);
+        }
+    }
+    if (subcommand === "remote") {
+        if (operands.length === 0)
+            return true;
+        if (operands.length > 2 ||
+            (operands[0] !== "show" && operands[0] !== "get-url"))
+            return false;
+        return safeRemote(operands[1], configuredRemotes);
+    }
+    if (subcommand === "push" || subcommand === "fetch" || subcommand === "pull")
+        return safeRemote(operands[0], configuredRemotes);
+    return true;
+}
+function projectFile(project) {
+    const directory = join(project, ".fungi");
+    const marker = lstatSync(directory, { throwIfNoEntry: false });
+    if (marker !== undefined && !marker.isDirectory())
+        throw new Error("Project .fungi must be a real directory");
+    return { directory, file: join(directory, "exec-rules.json") };
+}
+function readProject(project) {
+    const file = join(project, ".fungi", "exec-rules.json");
+    try {
+        return readProjectFile(project);
+    }
+    catch (cause) {
+        throw new Error(`Invalid ${file}; delete it and reapprove Always-allow rules`, { cause });
+    }
+}
+function readProjectFile(project) {
+    const { file } = projectFile(project);
+    const entry = lstatSync(file, { throwIfNoEntry: false });
+    if (entry === undefined)
+        return { version: 2, rules: [] };
+    if (!entry.isFile() || entry.nlink !== 1)
+        throw new Error("Project exec rules must be an independent regular file");
+    const stored = projectRulesSchema.parse(JSON.parse(readFileSync(file, "utf8")));
+    if (stored.rules.some((rule) => !validPrefix(rule.prefix)))
+        throw new Error("Project exec rules contain an unsafe prefix");
+    return stored;
+}
+/** Fail closed on contention instead of overwriting another process's grant. */
+function lockedUpdate(project, update) {
+    const { directory } = projectFile(project);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const lock = join(directory, "exec-rules.lock");
+    mkdirSync(lock, { mode: 0o700 });
+    try {
+        update();
+    }
+    finally {
+        rmdirSync(lock);
+    }
+}
+function writeProject(project, rules) {
+    const content = projectRulesSchema.parse({ version: 2, rules });
+    const { directory, file } = projectFile(project);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temp = join(directory, "exec-rules-" + correlationKey() + ".tmp");
+    writeFileSync(temp, JSON.stringify(content), { flag: "wx", mode: 0o600 });
+    renameSync(temp, file);
+}
+/** One host-owned project file; every Agent in the project sees the same rules. */
+export function localExecRules(project) {
+    const list = () => readProject(project).rules.map((rule) => rule.prefix);
+    const add = (prefix) => {
+        const parsed = prefixSchema.parse(prefix);
+        if (!validPrefix(parsed))
+            throw new Error("Unsafe Always-allow prefix");
+        lockedUpdate(project, () => {
+            const existing = readProject(project).rules;
+            if (!existing.some((rule) => JSON.stringify(rule.prefix) === JSON.stringify(parsed)))
+                writeProject(project, [
+                    ...existing,
+                    { id: projectRuleIds.rule.generate(), prefix: parsed },
+                ]);
+        });
+    };
+    const remove = (prefix) => {
+        const parsed = prefixSchema.parse(prefix);
+        lockedUpdate(project, () => {
+            writeProject(project, readProject(project).rules.filter((rule) => JSON.stringify(rule.prefix) !== JSON.stringify(parsed)));
+        });
+    };
+    const match = (argv, configuredRemotes) => {
+        if (unsafeExecutable(argv[0] ?? "") ||
+            (basename(argv[0] ?? "") === "fungi" &&
+                argv[1] === "extension" &&
+                argv[2] === "add"))
+            return undefined;
+        if (argv[0] === "git" && !safeGitCommand(argv, configuredRemotes))
+            return undefined;
+        const matched = readProject(project).rules.find((rule) => rule.prefix.every((part, index) => argv[index] === part));
+        // The stored Cairn id identifies the rule without exposing its prefix.
+        return matched === undefined ? undefined : { ruleId: matched.id };
+    };
+    const matches = (argv, configuredRemotes) => match(argv, configuredRemotes) !== undefined;
+    return { list, add, remove, match, matches };
+}
+/** Human CLI management only; no model-facing capability exposes this writer. */
+export function manageLocalExecRules(project, action, prefix) {
+    const rules = localExecRules(project);
+    if (action === "remove") {
+        if (prefix === undefined)
+            throw new Error("A prefix is required");
+        rules.remove(prefix);
+    }
+    return rules.list();
+}

package/dist/private-local-git-exclude.js

@@ -1,25 +1,35 @@
-import { execFile as execFileCallback } from "node:child_process";
 import { appendFile, mkdir, readFile } from "node:fs/promises";
-import { resolve, join } from "node:path";
-import { promisify } from "node:util";
-const execFile = promisify(execFileCallback);
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { gitDirectories } from "./private-local-sandbox-policy.js";
 const excludeEntry = ".fungi/";
 /** Keep generated project state out of Git without changing tracked ignore rules. */
 export async function ensurePrivateLocalGitExclude(projectRoot) {
-    let common;
-    try {
-        const result = await execFile("git", ["rev-parse", "--git-common-dir"], {
-            cwd: projectRoot,
-        });
-        common = resolve(projectRoot, result.stdout.trim());
+    const root = realpathSync(projectRoot);
+    // Never append as the host to a common dir selected by a planted .git.
+    // Git's read-only answer alone cannot authorize a host write.
+    const git = gitDirectories(root, root);
+    if (git === undefined)
+        return;
+    const marker = join(root, ".git");
+    const entry = lstatSync(marker, { throwIfNoEntry: false });
+    if (entry?.isDirectory()) {
+        if (realpathSync(marker) !== git.common || git.worktree !== git.common)
+            return;
     }
-    catch (cause) {
-        // A non-Git project still keeps its local Fungi store.
-        if (cause instanceof Error && "code" in cause && cause.code === 128)
+    else if (entry?.isFile()) {
+        if (dirname(git.worktree) !== join(git.common, "worktrees"))
+            return;
+        // A real linked worktree's Git-owned backlink must point to this marker.
+        const backlink = readFileSync(join(git.worktree, "gitdir"), "utf8");
+        if (!backlink.endsWith("\n") ||
+            backlink.split("\n").length !== 2 ||
+            resolve(git.worktree, backlink.trimEnd()) !== marker)
             return;
-        throw cause;
     }
-    const info = join(common, "info");
+    else
+        return;
+    const info = join(git.common, "info");
     await mkdir(info, { recursive: true });
     const exclude = join(info, "exclude");
     const current = await readFile(exclude, "utf8").catch((cause) => {

package/dist/private-local-linux-sandbox.d.ts

@@ -1,7 +1,9 @@
-import { type LocalSandboxPolicy } from "./private-local-sandbox-policy.js";
-import type { LinuxSandboxPayload } from "./private-local-bwrap.js";
+import { type LinuxSandboxProfile } from "./private-local-sandbox-policy.js";
 /** Ordinary upstream bwrap argv. There is no approval or bare-command path. */
-export declare function linuxSandboxCommand(policy: LocalSandboxPolicy, payload: LinuxSandboxPayload, cwd: string, argv: readonly [string, ...string[]], host?: NodeJS.ProcessEnv): {
+export declare function linuxSandboxCommand(policy: LinuxSandboxProfile, payload: Readonly<{
+    executable: string;
+    seccompFilter: Uint8Array;
+}>, cwd: string, argv: readonly [string, ...string[]], host?: NodeJS.ProcessEnv, readOnlyHelperFile?: string): {
     args: string[];
     executable: string;
     seccompFilter: Uint8Array;