@fungi.computer/truffle 0.5.0 → 0.7.0

package/dist/private-local-computer-processes.js

@@ -7,7 +7,7 @@ import { setTimeout as delay } from "node:timers/promises";
 import { defineIdFamily } from "@fungi.computer/cairn";
 import { z } from "zod";
 import { combinedArgvBytes, launchCwdSchema, launchStdinSchema, maximumLaunchTextLength, } from "./private-local-exec-launch.js";
-import { privateLocalExecEnvironment } from "./private-local-exec-environment.js";
+import { privateLocalExecEnvironment, privateLocalExecEnvironmentInput, } from "./private-local-exec-environment.js";
 import { capturePrivateLocalConfigRoot } from "./private-local-config-root.js";
 import { Writable } from "node:stream";
 /**
@@ -70,6 +70,7 @@ const shellStartInput = z.strictObject({
         .optional(),
     command: z.string().min(1).max(maximumLaunchTextLength),
     stdin: launchStdinSchema.optional(),
+    env: privateLocalExecEnvironmentInput.optional(),
     cwd: launchCwdSchema.optional(),
 });
 /** The direct form of background `start`: argv run with no shell interpretation. */
@@ -82,6 +83,7 @@ const directStartInput = z
     executable: z.string().min(1),
     args: z.array(z.string()).default([]),
     stdin: launchStdinSchema.optional(),
+    env: privateLocalExecEnvironmentInput.optional(),
     cwd: launchCwdSchema.optional(),
 })
     .refine((value) => combinedArgvBytes(value.executable, value.args) <=
@@ -166,18 +168,18 @@ function groupAlive(groupId) {
     }
 }
 function toCommandSpec(request) {
-    if ("command" in request) {
-        const spec = { kind: "shell", command: request.command };
-        return request.stdin === undefined
-            ? spec
-            : { ...spec, stdin: request.stdin };
-    }
-    const spec = {
-        kind: "direct",
-        executable: request.executable,
-        args: request.args,
-    };
-    return request.stdin === undefined ? spec : { ...spec, stdin: request.stdin };
+    let spec = "command" in request
+        ? { kind: "shell", command: request.command }
+        : {
+            kind: "direct",
+            executable: request.executable,
+            args: request.args,
+        };
+    if (request.stdin !== undefined)
+        spec = { ...spec, stdin: request.stdin };
+    if (request.env !== undefined)
+        spec = { ...spec, env: request.env };
+    return spec;
 }
 /**
  * A one-line, human-readable label for a spec; never used for execution.
@@ -221,6 +223,7 @@ class ManagedProcess {
     #signal = null;
     #endedAt = null;
     #leaderExited = false;
+    #output = new Map();
     command;
     constructor(spec, cwd, logDirectory, executionPath, home, launch) {
         this.spec = spec;
@@ -234,7 +237,7 @@ class ManagedProcess {
             HOME: home,
             XDG_RUNTIME_DIR: process.env.XDG_RUNTIME_DIR,
             DBUS_SESSION_BUS_ADDRESS: process.env.DBUS_SESSION_BUS_ADDRESS,
-        });
+        }, spec.env);
         if (launch !== undefined) {
             delete env.XDG_RUNTIME_DIR;
             delete env.DBUS_SESSION_BUS_ADDRESS;
@@ -300,11 +303,12 @@ class ManagedProcess {
             pid !== undefined && Number.isSafeInteger(pid) && pid > 1
                 ? pid
                 : undefined;
-        const append = (chunk) => {
-            this.#append(chunk);
-        };
-        this.#child.stdout?.on("data", append);
-        this.#child.stderr?.on("data", append);
+        this.#child.stdout?.on("data", (chunk) => {
+            this.#append(chunk, "stdout");
+        });
+        this.#child.stderr?.on("data", (chunk) => {
+            this.#append(chunk, "stderr");
+        });
         this.#child.on("error", (error) => {
             this.#append(Buffer.from(`\n[fungi: process failed: ${error.message}]\n`));
             this.#finish(closed.resolve);
@@ -327,7 +331,7 @@ class ManagedProcess {
     get running() {
         return this.#endedAt === null;
     }
-    #append(chunk) {
+    #append(chunk, stream = "stderr") {
         const fd = this.#fd;
         if (fd === undefined)
             return;
@@ -342,6 +346,22 @@ class ManagedProcess {
             writeSync(fd, kept, first, kept.byteLength - first, 0);
         this.#logBytes += chunk.byteLength;
         this.#logTruncated = this.#logBytes > maximumLogBytes;
+        for (const output of this.#output.keys())
+            output.write(stream, chunk);
+    }
+    /** Observe only new chunks during this wait; no extra pipe reader or replay. */
+    observeOutput(output) {
+        if (output !== undefined)
+            this.#output.set(output, (this.#output.get(output) ?? 0) + 1);
+        return () => {
+            if (output === undefined)
+                return;
+            const remaining = (this.#output.get(output) ?? 1) - 1;
+            if (remaining === 0)
+                this.#output.delete(output);
+            else
+                this.#output.set(output, remaining);
+        };
     }
     /** Read atomically with appends, including a wrap in circular storage. */
     read(offset, maxBytes) {
@@ -504,8 +524,10 @@ export function createPrivateLocalComputerProcesses(root, home = capturePrivateL
             status: (id) => find(id).snapshot(),
             list: () => [...(scopes.get(key)?.values() ?? [])].map((r) => r.snapshot()),
             read: (id, offset, maxBytes) => Promise.resolve(find(id).read(offset, maxBytes)),
-            wait: async (id, timeoutMs, signal) => {
+            wait: async (id, timeoutMs, signal, output) => {
+                signal.throwIfAborted();
                 const record = find(id);
+                const stopOutput = record.observeOutput(output);
                 const controller = new AbortController();
                 const abandon = () => {
                     controller.abort();
@@ -519,6 +541,7 @@ export function createPrivateLocalComputerProcesses(root, home = capturePrivateL
                     return waitOutput.parse({ process: record.snapshot(), timedOut });
                 }
                 finally {
+                    stopOutput();
                     signal.removeEventListener("abort", abandon);
                     controller.abort();
                 }
@@ -589,7 +612,7 @@ const backgroundResult = readOutput.extend({
 });
 export const backgroundExecOutput = z.union([backgroundResult, listOutput]);
 /** Reuse Session ownership and logs; a wait deadline never cancels the command. */
-export async function callBackgroundExec(scope, request, resolveCwd, executionPath, signal, sandbox) {
+export async function callBackgroundExec(scope, request, resolveCwd, executionPath, signal, sandbox, sink) {
     signal.throwIfAborted();
     if (request.operation === "list")
         return { processes: [...scope.list()] };
@@ -605,7 +628,8 @@ export async function callBackgroundExec(scope, request, resolveCwd, executionPa
         }
         case "wait":
             id = request.id;
-            timedOut = (await scope.wait(id, request.timeoutMs, signal)).timedOut;
+            timedOut = (await scope.wait(id, request.timeoutMs, signal, sink))
+                .timedOut;
             break;
         case "kill":
             id = request.id;

package/dist/private-local-delegation.js

@@ -1,6 +1,6 @@
 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";
+import { agentDelegationRequestKey, createFleetDelegation, delegationProvenance, delegationReplyMeta, delegationSendMeta, isOneWayAncestorNotice, } from "@fungi.computer/shiitake/fleet";
 /** How long one Local delegation grant stays valid while it is admitted. */
 const grantLifetimeMs = 60_000;
 /**
@@ -113,19 +113,22 @@ export function createPrivateLocalDelegation(input) {
             sessionId: sourceSessionId,
         });
         signal.throwIfAborted();
+        let delegation = {
+            agentId: task.agentId,
+            sessionId: task.sessionId,
+            delivery: task.delivery,
+            text: task.text,
+            requestId,
+        };
+        if (task.delivery === "followUp" && task.goal !== undefined)
+            delegation = { ...delegation, goal: task.goal };
         return fleet.start({
             agents: agents.map(({ agentId }) => agentId),
             actions: ["delegate"],
             expiresAt: Date.now() + grantLifetimeMs,
             provenance,
             meta,
-        }, {
-            agentId: task.agentId,
-            sessionId: task.sessionId,
-            delivery: task.delivery,
-            text: task.text,
-            requestId,
-        });
+        }, delegation);
     }
     /** Resolve only this sender's receipt, then let the target own the pending guard. */
     async function recall(task, sourceSessionId, signal) {
@@ -157,9 +160,8 @@ export function createPrivateLocalDelegation(input) {
         }
     }
     /**
-     * Admit one mail addressed to this Agent. New work must name its sender as
-     * its only reply destination; a reply-less mail is admitted only as an
-     * authenticated reply. Everything else is refused.
+     * Admit delegated work, one-way ancestor notices and authenticated replies.
+     * Other reply-less mail is refused.
      */
     async function receive(mail) {
         const mesh = await input.meshAdmission?.(mail.to.agentId);
@@ -187,6 +189,8 @@ export function createPrivateLocalDelegation(input) {
                 throw new Error("Local delegated work must reply to its sender");
             return input.accept(mail, mail.meta);
         }
+        if (isOneWayAncestorNotice(mail))
+            return input.accept(mail, mail.meta);
         if (mail.reply?.outcome === "accepted") {
             const receipt = fleet.recordAcceptedNotice(mail);
             if (receipt === undefined)

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

@@ -1,3 +1,6 @@
+import { z } from "zod";
+/** Shared admission for shell/direct run and managed start. */
+export declare const privateLocalExecEnvironmentInput: z.ZodRecord<z.ZodString, z.ZodString>;
 /**
  * The only host variables a Local exec child receives besides its selected
  * PATH and HOME. Exec runs as the host's own user, so that user's session
@@ -5,7 +8,7 @@
  * `loginctl` and other user-service tools need to find the user manager.
  * Every other host variable, credentials included, stays out.
  */
-export type PrivateLocalExecEnvironment = {
+export type PrivateLocalExecEnvironment = Record<string, string> & {
     PATH: string;
     HOME: string;
     XDG_RUNTIME_DIR?: string;
@@ -13,4 +16,4 @@ export type PrivateLocalExecEnvironment = {
 };
 export declare function privateLocalExecEnvironment(executionPath: string, host: NodeJS.ProcessEnv & {
     HOME: string;
-}): PrivateLocalExecEnvironment;
+}, extra?: Readonly<Record<string, string>>): PrivateLocalExecEnvironment;

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

@@ -1,5 +1,39 @@
-export function privateLocalExecEnvironment(executionPath, host) {
+import { z } from "zod";
+// Extras reach the native sandbox launcher too; its loader controls stay owned
+// by the host rather than loading model-selected code before containment.
+const hostOwnedNames = new Set([
+    "PATH",
+    "HOME",
+    "XDG_RUNTIME_DIR",
+    "DBUS_SESSION_BUS_ADDRESS",
+    "TMPDIR",
+    "SSH_AUTH_SOCK",
+    "GIT_DISCOVERY_ACROSS_FILESYSTEM",
+    "FUNGI_SANDBOX",
+    "FUNGI_SANDBOX_NETWORK_DISABLED",
+    "GLIBC_TUNABLES",
+    "GCONV_PATH",
+    "LOCPATH",
+]);
+const environmentName = z
+    .string()
+    .regex(/^[A-Z_][A-Z0-9_]*$/u)
+    .refine((name) => !hostOwnedNames.has(name) &&
+    !name.startsWith("LD_") &&
+    !name.startsWith("DYLD_"), "Host-owned environment variable");
+/** Shared admission for shell/direct run and managed start. */
+export const privateLocalExecEnvironmentInput = z
+    .record(environmentName, z
+    .string()
+    .max(1_024)
+    .regex(/^[^\0]*$/u, "Environment values cannot contain NUL"))
+    .refine((environment) => Object.keys(environment).length <= 64, {
+    message: "Exec env accepts at most 64 variables",
+})
+    .describe("Up to 64 extra string variables, each at most 1024 UTF-16 code units, with uppercase ASCII names (letters, digits and underscores; no leading digit). Host-owned names, including HOME, PATH, session/sandbox locators and dynamic-loader controls, are refused.");
+export function privateLocalExecEnvironment(executionPath, host, extra = {}) {
     const environment = {
+        ...extra,
         PATH: executionPath,
         HOME: host.HOME,
     };

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

@@ -1,5 +1,6 @@
-import { gitRuleCoverage, rulePrefix } from "./private-local-exec-rules.js";
-import { quote } from "shell-quote";
+import * as Result from "effect/Result";
+import { gitRuleCoverage, hasExtensionInstallRisk, rulePrefix, } from "./private-local-exec-rules.js";
+import { parse, quote } from "shell-quote";
 const gitHookGrantSubcommands = new Set([
     "add",
     "branch",
@@ -25,6 +26,12 @@ export function localExecEscapeReview(request, cwd, gitGrant) {
         ? undefined
         : [request.executable, ...(request.args ?? [])];
     const command = request.command ?? quote(argv ?? []);
+    // Literal shell tokens only add the extension risk note. They never turn
+    // shell text into argv, establish command identity, or permit a saved rule.
+    // Opaque shell text keeps its existing once-only generic review.
+    const words = argv ??
+        Result.getOrElse(Result.try(() => parse(command, {})), () => []);
+    const extensionInstall = hasExtensionInstallRisk(words, argv === undefined ? "shell" : "direct");
     const prefix = argv === undefined || (argv[0] === "git" && gitGrant === undefined)
         ? undefined
         : rulePrefix(argv, gitGrant?.configuredRemotes);
@@ -33,9 +40,7 @@ export function localExecEscapeReview(request, cwd, gitGrant) {
         cwd,
         justification: request.escape.justification,
         form: argv === undefined ? "shell" : "direct",
-        kind: argv?.[0] === "fungi" && argv[1] === "extension" && argv[2] === "add"
-            ? "extension-install"
-            : "exec",
+        kind: extensionInstall ? "extension-install" : "exec",
     };
     if (argv !== undefined)
         review.argv = argv;
@@ -44,7 +49,7 @@ export function localExecEscapeReview(request, cwd, gitGrant) {
         review.alwaysAllowCoverage =
             prefix[0] === "git"
                 ? gitRuleCoverage(prefix[1] ?? "")
-                : `Direct argv commands beginning ${JSON.stringify(prefix)} in this project; shell commands still ask.`;
+                : `Direct argv commands beginning ${JSON.stringify(prefix)} in this project; shell commands${prefix[0] === "fungi" ? " and extension installs" : ""} still ask.`;
         if (prefix[0] === "git") {
             const hookCapable = gitHookGrantSubcommands.has(prefix[1] ?? "");
             const summary = (hookCapable
@@ -68,7 +73,9 @@ export function localExecEscapeReview(request, cwd, gitGrant) {
             review.risk = { summary, detail };
         }
         else {
-            const summary = `Every \`${prefix.join(" ")} …\` command will run outside the sandbox, as you.`;
+            const summary = prefix[0] === "fungi"
+                ? `Matching \`${prefix.join(" ")} …\` commands run outside the sandbox, as you. Extension installs still ask.`
+                : `Every \`${prefix.join(" ")} …\` command will run outside the sandbox, as you.`;
             review.risk = { summary, detail: summary };
         }
     }

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

@@ -1,3 +1,10 @@
+import type { ParseEntry } from "shell-quote";
+/**
+ * Conservative literal risk, not CLI parsing or executable identity. Global
+ * options can occur among positionals. Shell tokens may disclose risk, but
+ * only actual direct argv ever reaches the reusable-grant matcher.
+ */
+export declare function hasExtensionInstallRisk(words: readonly ParseEntry[], form: "direct" | "shell"): boolean;
 /** Offer only direct commands that this same matcher can authorize. */
 export declare function rulePrefix(argv: readonly string[], configuredRemotes?: ReadonlySet<string>): string[] | undefined;
 /** Text for the same Git option profile that gates matching, not a second list. */

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

@@ -2,6 +2,27 @@ import { lstatSync, mkdirSync, readFileSync, renameSync, rmdirSync, writeFileSyn
 import { basename, join } from "node:path";
 import { correlationKey, defineIdFamily } from "@fungi.computer/cairn";
 import { z } from "zod";
+function fungiWord(word) {
+    const parsed = z.string().safeParse(word);
+    return parsed.success && basename(parsed.data) === "fungi";
+}
+/**
+ * Conservative literal risk, not CLI parsing or executable identity. Global
+ * options can occur among positionals. Shell tokens may disclose risk, but
+ * only actual direct argv ever reaches the reusable-grant matcher.
+ */
+export function hasExtensionInstallRisk(words, form) {
+    const executable = form === "direct"
+        ? fungiWord(words[0])
+            ? 0
+            : -1
+        : words.findIndex(fungiWord);
+    if (executable < 0)
+        return false;
+    const extension = words.findIndex((word, index) => index > executable && word === "extension");
+    return (extension >= 0 &&
+        words.some((word, index) => index > extension && word === "add"));
+}
 const prefixSchema = z.array(z.string().min(1).max(4096)).min(1).max(32);
 const projectRuleIds = defineIdFamily({
     family: "local-exec-rules",
@@ -264,9 +285,7 @@ export function rulePrefix(argv, configuredRemotes) {
             ? prefix
             : undefined;
     }
-    if (basename(argv[0] ?? "") === "fungi" &&
-        argv[1] === "extension" &&
-        argv[2] === "add")
+    if (hasExtensionInstallRisk(argv, "direct"))
         return undefined;
     const parsed = prefixSchema.safeParse(argv.slice(0, 2));
     return parsed.success && validPrefix(parsed.data) ? parsed.data : undefined;
@@ -416,9 +435,7 @@ export function localExecRules(project) {
     };
     const match = (argv, configuredRemotes) => {
         if (unsafeExecutable(argv[0] ?? "") ||
-            (basename(argv[0] ?? "") === "fungi" &&
-                argv[1] === "extension" &&
-                argv[2] === "add"))
+            hasExtensionInstallRisk(argv, "direct"))
             return undefined;
         if (argv[0] === "git" && !safeGitCommand(argv, configuredRemotes))
             return undefined;

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

@@ -7,6 +7,7 @@ export declare const activationsSchema: z.ZodObject<{
         revision: z.ZodString;
         capabilities: z.ZodArray<z.ZodEnum<{
             state: "state";
+            prompt: "prompt";
             attention: "attention";
             settled: "settled";
             send: "send";
@@ -15,7 +16,6 @@ export declare const activationsSchema: z.ZodObject<{
             projection: "projection";
             run_tools: "run_tools";
             files: "files";
-            prompt: "prompt";
             compaction_handoff: "compaction_handoff";
         }>>;
         skills: z.ZodBoolean;

package/dist/private-local-runtime-host.js

@@ -1348,7 +1348,7 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
                 throw new Error("Local escape approval could not be presented");
             return pending;
         };
-        const policyForSession = (sessionId) => async ({ request, cwd, mode, executionPath }) => {
+        const policyForSession = (sessionId) => async ({ request, cwd, mode, executionPath, context }) => {
             if (mode !== "workspace" || !("executable" in request))
                 return undefined;
             let configuredRemotes;
@@ -1365,7 +1365,7 @@ export async function openPrivateLocalRuntimeHost(input, suppliedModels) {
                 executable: request.executable,
                 ruleId: matched.ruleId,
             });
-            return shellOutput.parse(await dispatchApprovedLocalExec(request, cwd, executionPath, configRoot.home, localTools.processes.scope(sessionId), mode));
+            return shellOutput.parse(await dispatchApprovedLocalExec(request, cwd, executionPath, configRoot.home, localTools.processes.scope(sessionId), mode, context.output));
         };
         const localTools = await createPrivateLocalTools(selectedFolder.absolute, input.fungiMcp, subagents?.directory, (sessionId) => sessionPaths.get(sessionId), dirname(paths.databasePath), subagents, await input.configuration?.(dirname(paths.databasePath)), configRoot, sandboxOwner, () => sandboxOwner.status().mode, escapeForSession, policyForSession);
         processes = localTools.processes;

package/dist/private-local-sandbox-policy.js

@@ -90,6 +90,10 @@ osHome, platform = "linux") {
         mode,
         temporaryDirectory,
         fungiCache: protectedFungiCache,
+        // Adding PATH lookup directories would invalidate the current name-based
+        // extension-install risk classification; revisit private-local-exec-rules.ts
+        // before widening this set. Guard: ../test/private-local-containment.test.ts,
+        // "keeps every captured PATH directory outside Workspace writable roots".
         writable: mode === "workspace"
             ? [...new Set([policy.writableRoot, ...writableCaches])]
             : [],

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

@@ -1,6 +1,6 @@
 import type { NativeSourceReader } from "./private-local-bwrap.js";
 import { z } from "zod";
-import { sandboxUnavailableReasonSchema, type SandboxUnavailableReason } from "./private-local-containment.js";
+import { establishLocalSandbox, sandboxUnavailableReasonSchema, type SandboxUnavailableReason } from "./private-local-containment.js";
 import type { LocalPermissionMode } from "./private-local-permission-mode.js";
 import type { LocalSandboxWrites } from "./private-invocation-files.js";
 import type { NativePayloadStaging } from "./private-local-native-staging.js";
@@ -48,6 +48,8 @@ export declare function createLocalSandboxControls(input: Readonly<{
     platform?: string;
     readNativePatchSource?: NativeSourceReader;
     native?: NativePayloadStaging | undefined;
+    /** Test-only hook for inspecting probe launches without native execution. */
+    runProbe?: Parameters<typeof establishLocalSandbox>[2];
 }>): LocalSandboxControls;
 /** Probe a fresh Agent before deciding its mode; never treat an unavailable backend as a sandboxed run. */
 export declare function probeLocalSandbox(project: string, folder: string, native?: NativePayloadStaging): SandboxUnavailableReason | undefined;

package/dist/private-local-sandbox.js

@@ -97,7 +97,7 @@ export function createLocalSandboxControls(input) {
                 temporaryDirectory: temporaryDirectory ??
                     agentSandboxTemporaryDirectory(temporaryOwner, input.project),
                 ...platform,
-            }, native);
+            }, native, input.runProbe);
         }
     }
     catch (cause) {
@@ -167,7 +167,7 @@ export function createLocalSandboxControls(input) {
             mode: nextMode,
             temporaryDirectory,
             ...platform,
-        }, native);
+        }, native, input.runProbe);
         if (admission.state === "ready") {
             sandbox = admission.sandbox;
             preparedMode = nextMode;

package/dist/private-local-schedule-client.d.ts

@@ -0,0 +1,12 @@
+import type { z } from "zod";
+import { type AgentScheduleRow, type AgentScheduleTarget } from "@fungi.computer/shiitake-extensions/schedules";
+import { localScheduleListInputSchema, type LocalSchedulePage } from "./private-local-schedules.js";
+import type { PrivateLocalServiceRequestOptions, PrivateLocalServiceStatus } from "./private-local-service-contract.js";
+/** A private, folder-bound owner capability; it contains no public URL or grant. */
+export type PrivateLocalScheduleCapability = Readonly<{
+    list(input?: Omit<z.input<typeof localScheduleListInputSchema>, "invocationRoot">, options?: PrivateLocalServiceRequestOptions): Promise<LocalSchedulePage>;
+    pause(target: AgentScheduleTarget, options?: PrivateLocalServiceRequestOptions): Promise<AgentScheduleRow>;
+    delete(target: AgentScheduleTarget, options?: PrivateLocalServiceRequestOptions): Promise<AgentScheduleRow>;
+}>;
+/** Only a native private service client creates this capability for its person. */
+export declare function createPrivateLocalScheduleCapability(invocationRoot: string, start: (options?: PrivateLocalServiceRequestOptions) => Promise<PrivateLocalServiceStatus>): PrivateLocalScheduleCapability;

package/dist/private-local-schedule-client.js

@@ -0,0 +1,41 @@
+import * as Schema from "effect/Schema";
+import { parseShiitakeError } from "@fungi.computer/shiitake/client";
+import { agentScheduleRowSchema, } from "@fungi.computer/shiitake-extensions/schedules";
+import { readBoundedResponse } from "./private-bounded-response.js";
+import { localScheduleControlInputSchema, localScheduleListInputSchema, localSchedulePageSchema, } from "./private-local-schedules.js";
+// A page has at most 64 prompts of 256 KiB, including JSON escaping and metadata.
+// This is a wire budget, not a limit on retained records or future occurrences.
+const maximumResponseBytes = 128 * 1024 * 1024;
+/** Only a native private service client creates this capability for its person. */
+export function createPrivateLocalScheduleCapability(invocationRoot, start) {
+    async function call(operation, input, output, options = {}) {
+        options.signal?.throwIfAborted();
+        const service = await start(options);
+        const request = {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(input),
+            redirect: "error",
+        };
+        if (options.signal !== undefined)
+            request.signal = options.signal;
+        const response = await fetch(`${service.baseUrl}/service/${service.serviceId}/schedules/${operation}`, request);
+        const body = await readBoundedResponse(response, maximumResponseBytes, `Private Local schedule ${operation}`);
+        if (!response.ok) {
+            let failure;
+            try {
+                failure = parseShiitakeError(body);
+            }
+            catch (cause) {
+                throw new Error(`Private Local schedule ${operation} failed (${String(response.status)})`, { cause });
+            }
+            throw failure;
+        }
+        return Schema.decodeUnknownSync(output, { onExcessProperty: "error" })(JSON.parse(body));
+    }
+    return {
+        list: (input = {}, options) => call("list", localScheduleListInputSchema.parse({ ...input, invocationRoot }), localSchedulePageSchema, options),
+        pause: (target, options) => call("pause", localScheduleControlInputSchema.parse({ invocationRoot, target }), agentScheduleRowSchema, options),
+        delete: (target, options) => call("delete", localScheduleControlInputSchema.parse({ invocationRoot, target }), agentScheduleRowSchema, options),
+    };
+}

package/dist/private-local-schedules.d.ts

@@ -0,0 +1,84 @@
+import * as Schema from "effect/Schema";
+import { z } from "zod";
+import type { ShiitakeAgent } from "@fungi.computer/shiitake";
+/** Private service ingress, never a Team/member or machine-link request. */
+export declare const localScheduleListInputSchema: z.ZodObject<{
+    after: z.ZodOptional<z.ZodObject<{
+        agentId: z.ZodString;
+        kind: z.ZodUnion<readonly [z.ZodLiteral<"almanac">, z.ZodLiteral<"loop">]>;
+        after: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    limit: z.ZodDefault<z.ZodNumber>;
+    invocationRoot: z.ZodString;
+}, z.core.$strict>;
+/** Private person-only mutation, distinct from the finite list request. */
+export declare const localScheduleControlInputSchema: z.ZodObject<{
+    invocationRoot: z.ZodString;
+    target: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"almanac">;
+        agentId: z.ZodString;
+        scheduleId: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"loop">;
+        agentId: z.ZodString;
+        sessionId: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+        loopId: z.ZodString & z.ZodType<string, string, z.core.$ZodTypeInternals<string, string>>;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+/** Local directory pages reuse the schedule owner's decoder and retained state. */
+export declare const localSchedulePageSchema: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly agentId: Schema.String;
+        readonly kind: Schema.Literal<"almanac">;
+        readonly schedule: Schema.Struct<{
+            readonly id: Schema.String;
+            readonly sessionId: Schema.String;
+            readonly prompt: Schema.String;
+            readonly cron: Schema.NullOr<Schema.Struct<{
+                readonly expression: Schema.String;
+                readonly timeZone: Schema.String;
+            }>>;
+            readonly nextDueAt: Schema.Int;
+            readonly state: Schema.Literals<readonly ["active", "paused", "cancelled", "finished"]>;
+            readonly lastCommandId: Schema.NullOr<Schema.String>;
+            readonly lastError: Schema.NullOr<Schema.String>;
+            readonly attempt: Schema.Int;
+        }>;
+    }>, Schema.Struct<{
+        readonly agentId: Schema.String;
+        readonly kind: Schema.Literal<"loop">;
+        readonly schedule: Schema.Struct<{
+            readonly sessionId: Schema.String;
+            readonly loopId: Schema.String;
+            readonly origin: Schema.Literals<readonly ["human", "model"]>;
+            readonly expiresAt: Schema.NullOr<Schema.Int>;
+            readonly prompt: Schema.String;
+            readonly mode: Schema.Literals<readonly ["self_paced", "fixed_interval"]>;
+            readonly cron: Schema.NullOr<Schema.Struct<{
+                readonly expression: Schema.String;
+                readonly timeZone: Schema.String;
+            }>>;
+            readonly state: Schema.Literals<readonly ["active", "paused", "finished", "failed", "cancelled"]>;
+            readonly commandId: Schema.String;
+            readonly reason: Schema.NullOr<Schema.String>;
+            readonly nextDueAt: Schema.NullOr<Schema.Int>;
+            readonly lastError: Schema.NullOr<Schema.String>;
+            readonly consecutiveFailures: Schema.Int;
+        }>;
+    }>]>>;
+    readonly unavailable: Schema.$Array<Schema.Struct<{
+        readonly agentId: Schema.String;
+        readonly reason: Schema.Literal<"owner_unavailable">;
+    }>>;
+    readonly next: Schema.NullOr<Schema.Struct<{
+        readonly agentId: Schema.String;
+        readonly kind: Schema.Literals<readonly ["almanac", "loop"]>;
+        readonly after: Schema.optionalKey<Schema.String>;
+    }>>;
+}>;
+export type LocalSchedulePage = typeof localSchedulePageSchema.Type;
+/** One bounded read, borrowing existing admitted Agent owners one at a time. */
+export declare function readLocalSchedulePage(agentIds: readonly string[], open: (agentId: string, signal: AbortSignal) => Promise<{
+    owner: Pick<ShiitakeAgent, "extensions">;
+    release: () => void;
+}>, input: z.output<typeof localScheduleListInputSchema>, signal: AbortSignal): Promise<LocalSchedulePage>;