@fungi.computer/truffle 0.3.1 → 0.5.0

package/dist/private-local-delegation.js

@@ -1,3 +1,4 @@
+import * as Effect from "effect/Effect";
 import { AgentArchiveRefused } from "@fungi.computer/shiitake/agent-control";
 import { agentDelegationRequestKey, createFleetDelegation, delegationProvenance, delegationReplyMeta, delegationSendMeta, } from "@fungi.computer/shiitake/fleet";
 /** How long one Local delegation grant stays valid while it is admitted. */
@@ -31,7 +32,67 @@ export function createPrivateLocalDelegation(input) {
         }
         return agents;
     }
-    /** Send with one caller-owned identity; follow-up replies return here. */
+    /**
+     * Items a child left waiting on this Agent, by the reply command that told
+     * it. When the work that carried the reply ends, whatever the Agent neither
+     * answered nor escalated goes to a person, so no waiting item is silent.
+     */
+    const unattended = new Map();
+    let poll;
+    /** Escalate the items of every reply whose carrying work has settled. */
+    async function settleUnattended() {
+        const handling = input.unattended;
+        if (handling === undefined)
+            return;
+        for (const [commandId, entry] of unattended) {
+            const settlement = await handling
+                .readSettlement(entry.sessionId, commandId)
+                .catch((cause) => {
+                // Not settled as far as anyone can tell; try again on the next poll.
+                Effect.runFork(Effect.logWarning("delegation.settlement", cause));
+                return undefined;
+            });
+            if (settlement === undefined)
+                continue;
+            unattended.delete(commandId);
+            for (const itemId of entry.items)
+                await handling
+                    .escalate({ ...entry.child, itemId }, entry.sessionId)
+                    .catch((cause) => {
+                    Effect.runFork(Effect.logWarning("delegation.escalate", cause));
+                });
+        }
+        if (unattended.size === 0 && poll !== undefined) {
+            clearInterval(poll);
+            poll = undefined;
+        }
+    }
+    function watchUnattended(accepted, receiverSessionId, reply) {
+        if (input.unattended === undefined ||
+            reply.outcome === "undeliverable" ||
+            reply.waitingOnYou === undefined)
+            return;
+        if (receiverSessionId === undefined)
+            return;
+        unattended.set(accepted.commandId, {
+            sessionId: receiverSessionId,
+            child: { agentId: reply.agentId, sessionId: reply.sessionId },
+            items: reply.waitingOnYou.map(({ itemId }) => itemId),
+        });
+        poll ??= setInterval(() => {
+            void settleUnattended();
+        }, 1_000);
+        poll.unref();
+    }
+    /** Escalate what is owed now and stop watching; the Agent is closing. */
+    async function close() {
+        await settleUnattended();
+        unattended.clear();
+        if (poll !== undefined)
+            clearInterval(poll);
+        poll = undefined;
+    }
+    /** Send with one caller-owned identity; follow-up and steer replies return here. */
     async function send(task, sourceSessionId, signal, invocation) {
         if (invocation === undefined)
             throw new Error("Delegation requires a tool invocation");
@@ -43,19 +104,9 @@ export function createPrivateLocalDelegation(input) {
             requestId: task.requestId,
         });
         signal.throwIfAborted();
-        if (task.delivery === "steer") {
-            const opened = await input.directory.open(task.agentId, signal);
-            try {
-                return await opened.agent.session(task.sessionId).send(task.text, {
-                    requestId,
-                    delivery: "steer",
-                });
-            }
-            finally {
-                await opened.release();
-            }
-        }
-        const meta = delegationSendMeta({ id: input.agentId, name: input.agentId }, invocation.meta);
+        // A person reads this name where work waits on its sender.
+        const sender = agents.find(({ agentId }) => agentId === input.agentId);
+        const meta = delegationSendMeta({ id: input.agentId, name: sender?.name ?? input.agentId }, invocation.meta);
         // The caller's request key owns replay, not the current model program's bytes.
         const provenance = await delegationProvenance({
             agentId: input.agentId,
@@ -71,6 +122,7 @@ export function createPrivateLocalDelegation(input) {
         }, {
             agentId: task.agentId,
             sessionId: task.sessionId,
+            delivery: task.delivery,
             text: task.text,
             requestId,
         });
@@ -114,15 +166,22 @@ 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));
+        const sender = mail.from;
         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)
+        const authenticatedUndeliverable = delegation?.reply.outcome === "undeliverable";
+        const senderIsMember = sender.kind === "agent" &&
+            agents.some(({ agentId }) => agentId === sender.agentId);
+        if (!senderIsMember && !authenticatedUndeliverable) {
+            if (sender.kind === "system" &&
+                mail.replyTo.length === 0 &&
+                mail.reply?.outcome !== "accepted")
+                throw new Error("Local reply does not match work this Agent sent");
             throw new Error("Local mail sender is outside this project");
+        }
         if (mail.replyTo.length > 0) {
             const [destination] = mail.replyTo;
             if (mail.replyTo.length !== 1 ||
+                mail.from.kind !== "agent" ||
                 destination?.agentId !== mail.from.agentId ||
                 destination.sessionId !== mail.from.sessionId)
                 throw new Error("Local delegated work must reply to its sender");
@@ -137,10 +196,12 @@ export function createPrivateLocalDelegation(input) {
         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 && !frozenUndeliverable)
+        if (replier === undefined && !authenticatedUndeliverable)
             throw new Error("Local reply sender is outside this project");
         const meta = delegationReplyMeta(delegation, replier?.name ?? delegation.reply.agentId);
-        return input.accept({ ...mail, meta }, meta, delegation.reply);
+        const accepted = await input.accept({ ...mail, meta }, meta, delegation.reply);
+        watchUnattended(accepted, mail.to.sessionId, delegation.reply);
+        return accepted;
     }
-    return { send, recall, receive, outstanding: fleet.outstanding };
+    return { send, recall, receive, close, outstanding: fleet.outstanding };
 }

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

@@ -1,4 +1,5 @@
 import { gitRuleCoverage, rulePrefix } from "./private-local-exec-rules.js";
+import { quote } from "shell-quote";
 const gitHookGrantSubcommands = new Set([
     "add",
     "branch",
@@ -20,29 +21,62 @@ const gitHookGrantSubcommands = new Set([
 export function localExecEscapeReview(request, cwd, gitGrant) {
     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 ||
-        (request.executable === "git" && gitGrant === undefined)
+    const argv = request.executable === undefined
         ? undefined
-        : rulePrefix([request.executable, ...(request.args ?? [])], gitGrant?.configuredRemotes);
+        : [request.executable, ...(request.args ?? [])];
+    const command = request.command ?? quote(argv ?? []);
+    const prefix = argv === undefined || (argv[0] === "git" && gitGrant === undefined)
+        ? undefined
+        : rulePrefix(argv, gitGrant?.configuredRemotes);
     const review = {
         command,
         cwd,
         justification: request.escape.justification,
+        form: argv === undefined ? "shell" : "direct",
+        kind: argv?.[0] === "fungi" && argv[1] === "extension" && argv[2] === "add"
+            ? "extension-install"
+            : "exec",
     };
-    if (prefix !== undefined) {
+    if (argv !== undefined)
+        review.argv = argv;
+    if (prefix !== undefined && review.kind === "exec") {
         review.prefix = prefix;
         review.alwaysAllowCoverage =
             prefix[0] === "git"
                 ? gitRuleCoverage(prefix[1] ?? "")
                 : `Direct argv commands beginning ${JSON.stringify(prefix)} in this project; shell commands still ask.`;
+        if (prefix[0] === "git") {
+            const hookCapable = gitHookGrantSubcommands.has(prefix[1] ?? "");
+            const summary = (hookCapable
+                ? "Git hooks in this project can run code as you, and this Agent can add hooks."
+                : "This Git command will run outside the sandbox, as you.") +
+                (prefix[1] === "push"
+                    ? " It can push, force-push or delete any branch."
+                    : "") +
+                (["push", "fetch", "pull"].includes(prefix[1] ?? "")
+                    ? " Remotes can use your SSH keys."
+                    : "");
+            const detail = (hookCapable
+                ? "Git runs hook scripts from the folder the project's hooksPath setting names. That setting must already exist, but this Agent can add hook files there. A configured fsmonitor program in this folder may also be writable by this Agent."
+                : summary) +
+                (prefix[1] === "push"
+                    ? " A push grant can push all branches, force-update them or delete remote branches."
+                    : "") +
+                (["push", "fetch", "pull"].includes(prefix[1] ?? "")
+                    ? " Remote URLs can run ssh with your HOME and keys."
+                    : "");
+            review.risk = { summary, detail };
+        }
+        else {
+            const summary = `Every \`${prefix.join(" ")} …\` command will run outside the sandbox, as you.`;
+            review.risk = { summary, detail: summary };
+        }
     }
     if (request.executable === "git") {
         const hookCapable = gitHookGrantSubcommands.has(request.args?.[0] ?? "");
         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."
+                ? `Project hooks can run code as you ${review.prefix === undefined ? "when this command runs" : "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.") +
                 (request.args?.[0] === "push"
                     ? " This grant can push all branches, force-update them, or delete remote branches."
@@ -51,7 +85,10 @@ export function localExecEscapeReview(request, cwd, gitGrant) {
                     ? " Remote URLs can invoke ssh with your HOME and keys."
                     : "");
     }
-    if (prefix === undefined)
+    if (review.kind === "extension-install")
+        review.alwaysAllowUnavailableReason =
+            "Extension installs require a fresh approval; no reusable rule applies.";
+    else if (review.prefix === undefined)
         review.alwaysAllowUnavailableReason =
             request.executable === undefined
                 ? "Shell command text cannot match a saved argv rule; Approve once or Deny."

package/dist/private-local-extension-archive-notice.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+export declare const extensionArchiveNameSchema: z.ZodString;
+export declare function deferExtensionArchiveNotices(home: string): void;
+export declare function extensionArchiveNoticesAreDeferred(home: string): boolean;
+export declare function acquireExtensionOwnerLock(root: string): Promise<() => Promise<void>>;
+export declare function writeExtensionArchiveNotice(home: string, slug: "unversioned", filename: string, names: readonly string[]): Promise<void>;
+export declare function takePendingExtensionArchiveNoticesUnderOwnerLock(home: string): Promise<string[]>;
+export declare function takePendingExtensionArchiveNotices(home: string): Promise<string[]>;

package/dist/private-local-extension-archive-notice.js

@@ -0,0 +1,108 @@
+import { mkdir, readFile, readdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+import writeFileAtomic from "write-file-atomic";
+import { z } from "zod";
+export const extensionArchiveNameSchema = z
+    .string()
+    .trim()
+    .min(1)
+    .max(214)
+    .refine((name) => /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/iu.test(name));
+const noticeSchema = z.strictObject({
+    version: z.literal(3),
+    slug: z.literal("unversioned"),
+    filename: z.string().regex(/^installed(?:-[2-9])?\.json$/u),
+    names: z.array(extensionArchiveNameSchema).max(20),
+    additionalNameCount: z.number().int().min(0),
+    shown: z.boolean(),
+});
+const deferredHomes = new Set();
+function absent(cause) {
+    return (cause instanceof Error &&
+        "code" in cause &&
+        (cause.code === "ENOENT" || cause.code === "ENOTDIR"));
+}
+export function deferExtensionArchiveNotices(home) {
+    deferredHomes.add(resolve(home));
+}
+export function extensionArchiveNoticesAreDeferred(home) {
+    return deferredHomes.has(resolve(home));
+}
+export async function acquireExtensionOwnerLock(root) {
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    return lockfile.lock(root, {
+        realpath: false,
+        lockfilePath: join(root, ".owner.lock"),
+        stale: 30_000,
+        update: 10_000,
+        retries: { retries: 20, factor: 1.2, minTimeout: 25, maxTimeout: 100 },
+    });
+}
+function formatNotice(notice) {
+    const archivePath = `~/.fungi/archive/${notice.slug}/extensions/${notice.filename}`;
+    if (notice.names.length === 0)
+        return `Extensions from an earlier version were set aside, but no extension names could be read. Re-add each with: fungi extension add <its source>. Archived registry: ${archivePath}.`;
+    const more = notice.additionalNameCount > 0
+        ? `, and ${notice.additionalNameCount.toString()} more`
+        : "";
+    return `Extensions from an earlier version were set aside: ${notice.names.join(", ")}${more}. Re-add each with: fungi extension add <its source>. Archived registry: ${archivePath}.`;
+}
+export async function writeExtensionArchiveNotice(home, slug, filename, names) {
+    const notice = noticeSchema.parse({
+        version: 3,
+        slug,
+        filename,
+        names: names.slice(0, 20),
+        additionalNameCount: Math.max(0, names.length - 20),
+        shown: false,
+    });
+    const directory = join(resolve(home), ".fungi", "archive", slug, "extensions");
+    await writeFileAtomic(join(directory, `${filename}.notice.json`), `${JSON.stringify(notice)}\n`, { encoding: "utf8", fsync: true, mode: 0o600 });
+}
+export async function takePendingExtensionArchiveNoticesUnderOwnerLock(home) {
+    const directory = join(resolve(home), ".fungi", "archive", "unversioned", "extensions");
+    let names;
+    try {
+        names = await readdir(directory);
+    }
+    catch (cause) {
+        if (absent(cause))
+            return [];
+        throw cause;
+    }
+    const notices = [];
+    for (const name of names
+        .filter((candidate) => /^installed(?:-[2-9])?\.json\.notice\.json$/u.test(candidate))
+        .sort()) {
+        const path = join(directory, name);
+        let value;
+        try {
+            value = JSON.parse(await readFile(path, "utf8"));
+        }
+        catch (cause) {
+            if (absent(cause) || cause instanceof SyntaxError)
+                continue;
+            throw cause;
+        }
+        const parsed = noticeSchema.safeParse(value);
+        if (!parsed.success || parsed.data.shown)
+            continue;
+        const archivedName = name.replace(/\.notice\.json$/u, "");
+        if (parsed.data.filename !== archivedName)
+            continue;
+        await writeFileAtomic(path, `${JSON.stringify({ ...parsed.data, shown: true })}\n`, { encoding: "utf8", fsync: true, mode: 0o600 });
+        notices.push(formatNotice(parsed.data));
+    }
+    return notices;
+}
+export async function takePendingExtensionArchiveNotices(home) {
+    const root = join(resolve(home), ".fungi", "extensions");
+    const release = await acquireExtensionOwnerLock(root);
+    try {
+        return await takePendingExtensionArchiveNoticesUnderOwnerLock(home);
+    }
+    finally {
+        await release();
+    }
+}

package/dist/private-local-extension-records.d.ts

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/** One vocabulary for installed declarations and the activation reader. */
+export declare const capabilities: readonly ["state", "attention", "settled", "send", "timers", "commands", "projection", "run_tools", "files", "prompt", "compaction_handoff"];
+export declare const activationsSchema: z.ZodObject<{
+    projects: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>>;
+    agents: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodObject<{
+        revision: z.ZodString;
+        capabilities: z.ZodArray<z.ZodEnum<{
+            state: "state";
+            attention: "attention";
+            settled: "settled";
+            send: "send";
+            timers: "timers";
+            commands: "commands";
+            projection: "projection";
+            run_tools: "run_tools";
+            files: "files";
+            prompt: "prompt";
+            compaction_handoff: "compaction_handoff";
+        }>>;
+        skills: z.ZodBoolean;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+/** Only refused activations belong to the home upgrader, not installed.json. */
+export declare function incompatibleLocalExtensionActivations(home: string): Promise<readonly string[]>;

package/dist/private-local-extension-records.js

@@ -0,0 +1,51 @@
+import { readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+/** One vocabulary for installed declarations and the activation reader. */
+export const capabilities = [
+    "state",
+    "attention",
+    "settled",
+    "send",
+    "timers",
+    "commands",
+    "projection",
+    "run_tools",
+    "files",
+    "prompt",
+    "compaction_handoff",
+];
+export const activationsSchema = z.strictObject({
+    projects: z.record(z.string(), z.record(z.string(), z.string())),
+    agents: z.record(z.string(), z.record(z.string(), z.strictObject({
+        revision: z.string(),
+        capabilities: z.array(z.enum(capabilities)),
+        /** The opt-in to the revision's skills folder; separate from tools. */
+        skills: z.boolean(),
+    }))),
+});
+/** Only refused activations belong to the home upgrader, not installed.json. */
+export async function incompatibleLocalExtensionActivations(home) {
+    const path = join(resolve(home), ".fungi", "extensions", "activations.json");
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            "code" in cause &&
+            (cause.code === "ENOENT" || cause.code === "ENOTDIR"))
+            return [];
+        throw cause;
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (cause) {
+        if (cause instanceof SyntaxError)
+            return [path];
+        throw cause;
+    }
+    return activationsSchema.safeParse(value).success ? [] : [path];
+}

package/dist/private-local-process-identity.d.ts

@@ -1,3 +1,11 @@
+export type ServiceProcessIdentity = Readonly<{
+    kind: "ours";
+    evidence: "start-time" | "command-line";
+}> | Readonly<{
+    kind: "other";
+}> | Readonly<{
+    kind: "gone";
+}>;
 /**
  * A process-start discriminator. `unverifiable` means no sufficiently precise
  * reader is implemented on this platform.
@@ -16,5 +24,11 @@ export type ProcessStart = Readonly<{
  * accepted as signal authority. No sub-second macOS reader is implemented.
  */
 export declare function readProcessStart(pid: number): Promise<ProcessStart>;
+/** Never signal a PID merely because a lease names it. */
+export declare function identifyLocalServiceProcess(claim: Readonly<{
+    pid: number;
+    startedAt: string;
+    directory: string;
+}>): Promise<ServiceProcessIdentity>;
 /** The owner's start discriminator; an unverifiable marker never permits signalling. */
 export declare function readOwnProcessStart(): Promise<string>;

package/dist/private-local-process-identity.js

@@ -1,6 +1,25 @@
+import { execFile } from "node:child_process";
 import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
 import { z } from "zod";
 const procStartSchema = z.string().regex(/^\d+$/u);
+const execFileAsync = promisify(execFile);
+/** Signal 0 checks existence, not identity; EPERM is still a live process. */
+function processIsGone(pid) {
+    try {
+        process.kill(pid, 0);
+        return false;
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause) {
+            if (cause.code === "ESRCH")
+                return true;
+            if (cause.code === "EPERM")
+                return false;
+        }
+        throw cause;
+    }
+}
 /**
  * Linux reads proc(5)'s `starttime` (field 22 of `/proc/<pid>/stat`, in clock
  * ticks since boot). macOS's ps lstart is only second-resolution and is not
@@ -29,6 +48,38 @@ export async function readProcessStart(pid) {
     }
     return { kind: "unverifiable" };
 }
+/** Never signal a PID merely because a lease names it. */
+export async function identifyLocalServiceProcess(claim) {
+    const start = await readProcessStart(claim.pid);
+    if (start.kind === "gone")
+        return { kind: "gone" };
+    if (start.kind === "running")
+        return start.start === claim.startedAt
+            ? { kind: "ours", evidence: "start-time" }
+            : { kind: "other" };
+    if (process.platform !== "darwin")
+        return { kind: "other" };
+    if (processIsGone(claim.pid))
+        return { kind: "gone" };
+    // ps is only a corroborating channel after the caller has checked the
+    // matching service.json and owner.sqlite lease. Its output is bounded; an
+    // unreadable or different argv never grants signal authority.
+    let argv;
+    try {
+        ({ stdout: argv } = await execFileAsync("ps", ["-p", String(claim.pid), "-o", "args="], { timeout: 2_000, maxBuffer: 4_096 }));
+    }
+    catch {
+        return processIsGone(claim.pid) ? { kind: "gone" } : { kind: "other" };
+    }
+    const marker = `--internal-service ${claim.directory}`;
+    const offset = argv.indexOf(marker);
+    return offset >= 0 &&
+        (offset === 0 || /\s/u.test(argv[offset - 1] ?? "")) &&
+        (offset + marker.length === argv.trimEnd().length ||
+            /\s/u.test(argv[offset + marker.length] ?? ""))
+        ? { kind: "ours", evidence: "command-line" }
+        : { kind: "other" };
+}
 /** The owner's start discriminator; an unverifiable marker never permits signalling. */
 export async function readOwnProcessStart() {
     const own = await readProcessStart(process.pid);

package/dist/private-local-runtime-host.d.ts

@@ -80,6 +80,8 @@ export type PrivateLocalRuntimeHostOptions = Readonly<{
     name?: string | undefined;
     /** The Agent that created this one; recorded once with its identity. Absent when a human made it. */
     createdBy?: string | undefined;
+    /** The Session whose create request is durably bound to this Local receipt. */
+    createdBySessionId?: string | undefined;
     /** Immutable project-relative folder authority, inherited by child Agents. */
     folder?: string | undefined;
     /** Persist before constructing the Agent, which can recover durable work. */
@@ -172,8 +174,12 @@ export type PrivateLocalCreateStore = Readonly<{
     agentId: LocalStoreId;
     databasePath: string;
 }>;
+export type PrivateLocalCreateCreator = Readonly<{
+    agentId: string;
+    sessionId: string;
+}>;
 /** Resolve an Agent create request through its durable Local receipt. */
-export declare function resolvePrivateLocalCreateStore(root: string, requestId: string): Promise<PrivateLocalCreateStore>;
+export declare function resolvePrivateLocalCreateStore(root: string, requestId: string, creator?: PrivateLocalCreateCreator): Promise<PrivateLocalCreateStore>;
 /** Build the fixed source read by Shiitake once for each local run. */
 export declare function createPrivateLocalInstructionSource(port: Awaited<ReturnType<typeof createPrivateInvocationFilesPort>>): InstructionSource;
 export declare function createPrivateLocalModelSource(models: Models, providerId: string | undefined, modelId: string | undefined, providerCacheKey: string, selectedOwnerReasoning?: ThinkingLevel, defaults?: Readonly<{