@fungi.computer/truffle 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+export declare const sandboxUnavailableReasonSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        missing: "missing";
+        "invalid-digest": "invalid-digest";
+        "digest-mismatch": "digest-mismatch";
+        "not-executable": "not-executable";
+        "unsupported-platform": "unsupported-platform";
+        "invalid-folder": "invalid-folder";
+        "backend-refused": "backend-refused";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type SandboxUnavailableReason = z.output<typeof sandboxUnavailableReasonSchema>;
+export declare class LocalSandboxUnavailable extends Error {
+    readonly reason: SandboxUnavailableReason;
+    readonly name = "LocalSandboxUnavailable";
+    constructor(reason: SandboxUnavailableReason);
+}
+export type SandboxCommand = Readonly<{
+    executable: string;
+    args: readonly string[];
+    environment: Readonly<{
+        TMPDIR: string;
+    }>;
+    /** Linux only: feed these verified bytes to fd3; never inherit arbitrary fds. */
+    seccompFilter?: Uint8Array;
+}>;
+/** Existing foreground/background owners retain process and cancellation lifetime. */
+export type LocalSandbox = Readonly<{
+    command(cwd: string, argv: readonly [string, ...string[]]): SandboxCommand;
+    close(): void;
+}>;
+export type SandboxAdmission = Readonly<{
+    state: "ready";
+    sandbox: LocalSandbox;
+}> | Readonly<{
+    state: "unavailable";
+    reason: SandboxUnavailableReason;
+}>;
+/**
+ * The caller already owns the person's auto-approve choice. This module has no
+ * mode, setting, bare-command branch, PATH fallback or permission to widen it.
+ * A ready result proves only that the backend can start, not the escape matrix.
+ */
+export declare function establishLocalSandbox(input: Readonly<{
+    project: string;
+    /** Absolute folder selected by the Local owner. */
+    folder: string;
+    platform?: string;
+}>): SandboxAdmission;

package/dist/private-local-containment.js

@@ -0,0 +1,161 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, mkdtempSync, openSync, realpathSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LocalBwrapUnavailable, localLinuxSandboxPayload, } from "./private-local-bwrap.js";
+import { linuxSandboxCommand } from "./private-local-linux-sandbox.js";
+import { seatbeltCommand } from "./private-local-seatbelt.js";
+import { sandboxPolicy } from "./private-local-sandbox-policy.js";
+import { z } from "zod";
+export const sandboxUnavailableReasonSchema = z.strictObject({
+    kind: z.enum([
+        "unsupported-platform",
+        "invalid-folder",
+        "missing",
+        "invalid-digest",
+        "digest-mismatch",
+        "not-executable",
+        "backend-refused",
+    ]),
+    message: z.string(),
+});
+export class LocalSandboxUnavailable extends Error {
+    reason;
+    name = "LocalSandboxUnavailable";
+    constructor(reason) {
+        super(`Local sandbox unavailable: ${reason.message}`);
+        this.reason = reason;
+    }
+}
+function unavailable(cause) {
+    if (cause instanceof LocalBwrapUnavailable)
+        return { kind: cause.reason, message: cause.message };
+    return {
+        kind: "backend-refused",
+        message: cause instanceof Error ? cause.message : "Sandbox preparation failed.",
+    };
+}
+/**
+ * The caller already owns the person's auto-approve choice. This module has no
+ * mode, setting, bare-command branch, PATH fallback or permission to widen it.
+ * A ready result proves only that the backend can start, not the escape matrix.
+ */
+export function establishLocalSandbox(input) {
+    try {
+        sandboxPolicy(input.project, input.folder);
+    }
+    catch (cause) {
+        return {
+            state: "unavailable",
+            reason: {
+                kind: "invalid-folder",
+                message: cause instanceof Error ? cause.message : "Invalid sandbox folder.",
+            },
+        };
+    }
+    const platform = input.platform ?? process.platform;
+    if (platform !== "linux" && platform !== "darwin")
+        return {
+            state: "unavailable",
+            reason: {
+                kind: "unsupported-platform",
+                message: `Local sandbox is unavailable on ${platform}.`,
+            },
+        };
+    let temporaryDirectory;
+    try {
+        // A sandbox owns only its own temporary directory, never the host's HOME.
+        temporaryDirectory = realpathSync(mkdtempSync(join(tmpdir(), "fungi-sandbox-")));
+        const temporary = temporaryDirectory;
+        let closed = false;
+        const sandbox = {
+            command: (cwd, argv) => {
+                if (closed)
+                    throw new LocalSandboxUnavailable({
+                        kind: "backend-refused",
+                        message: "Sandbox has been closed.",
+                    });
+                // Failed/incomplete authority discovery is not an unavailable backend:
+                // it must not turn into an authorized unsandboxed retry.
+                const policy = sandboxPolicy(input.project, input.folder);
+                try {
+                    const launch = platform === "linux"
+                        ? linuxSandboxCommand(policy, localLinuxSandboxPayload(), cwd, argv)
+                        : seatbeltCommand({ ...policy, temporaryDirectory: temporary }, argv);
+                    return {
+                        ...launch,
+                        environment: { TMPDIR: platform === "linux" ? "/tmp" : temporary },
+                    };
+                }
+                catch (cause) {
+                    throw new LocalSandboxUnavailable(unavailable(cause));
+                }
+            },
+            close: () => {
+                if (closed)
+                    return;
+                closed = true;
+                rmSync(temporary, { recursive: true });
+            },
+        };
+        const command = sandbox.command(realpathSync(input.folder), [
+            "/usr/bin/true",
+        ]);
+        let filterDescriptor;
+        const probe = () => {
+            if (command.seccompFilter !== undefined) {
+                const path = join(temporary, "seccomp.bpf");
+                writeFileSync(path, command.seccompFilter, { mode: 0o600 });
+                filterDescriptor = openSync(path, "r");
+            }
+            return spawnSync(command.executable, [...command.args], {
+                cwd: input.folder,
+                env: { ...command.environment },
+                encoding: "utf8",
+                timeout: 5_000,
+                // Node's maintained spawn allowlist closes every other inherited fd.
+                // bwrap loads and closes fd3 before exec (seccomp_program_new).
+                stdio: [
+                    "ignore",
+                    "pipe",
+                    "pipe",
+                    ...(filterDescriptor === undefined ? [] : [filterDescriptor]),
+                ],
+            });
+        };
+        const result = (() => {
+            try {
+                return probe();
+            }
+            finally {
+                if (filterDescriptor !== undefined)
+                    closeSync(filterDescriptor);
+            }
+        })();
+        if (result.status !== 0) {
+            sandbox.close();
+            const stderr = result.stderr.trim();
+            return {
+                state: "unavailable",
+                reason: {
+                    kind: "backend-refused",
+                    message: result.error?.message ??
+                        (stderr.length > 0
+                            ? stderr
+                            : `Sandbox startup exited ${String(result.status)} (${String(result.signal)}).`),
+                },
+            };
+        }
+        return { state: "ready", sandbox };
+    }
+    catch (cause) {
+        if (temporaryDirectory !== undefined)
+            rmSync(temporaryDirectory, { recursive: true });
+        return {
+            state: "unavailable",
+            reason: cause instanceof LocalSandboxUnavailable
+                ? cause.reason
+                : unavailable(cause),
+        };
+    }
+}

package/dist/private-local-default-model.d.ts

@@ -0,0 +1,11 @@
+import type { Models } from "@earendil-works/pi-ai";
+import type { ModelPreference } from "@fungi.computer/shiitake/model-preference";
+/** One model offered by a signed-in or configured provider, as a provider/model address. */
+export type OfferedLocalModel = Readonly<{
+    address: string;
+    name: string;
+}>;
+/** The provider registry and its auth owner determine the available fallback. */
+export declare function defaultLocalModel(models: Models, signal: AbortSignal): Promise<ModelPreference | null>;
+/** List models from signed-in or configured providers only, in registry order. */
+export declare function listOfferedLocalModels(models: Models, signal: AbortSignal): Promise<readonly OfferedLocalModel[]>;

package/dist/private-local-default-model.js

@@ -0,0 +1,45 @@
+import { logEvent } from "./log-event.js";
+/** Return a provider's catalog only when its auth owner admits it. */
+async function offeredCatalog(models, providerId, signal) {
+    signal.throwIfAborted();
+    try {
+        if ((await models.checkAuth(providerId, { signal })) === undefined)
+            return [];
+    }
+    catch (cause) {
+        // A provider whose login cannot be resolved offers no models here.
+        // Explicit selections report their own safe, provider-specific refusal.
+        signal.throwIfAborted();
+        logEvent("model-default.check-auth", cause);
+        return [];
+    }
+    if (models.getModels(providerId).length === 0) {
+        const refreshed = await models.refresh({
+            providers: [providerId],
+            signal,
+        });
+        signal.throwIfAborted();
+        if (refreshed.aborted || refreshed.errors.has(providerId))
+            return [];
+    }
+    return models.getModels(providerId);
+}
+/** The provider registry and its auth owner determine the available fallback. */
+export async function defaultLocalModel(models, signal) {
+    for (const provider of models.getProviders()) {
+        const catalog = await offeredCatalog(models, provider.id, signal);
+        const model = catalog.find((entry) => "default" in entry && entry.default === true) ??
+            catalog[0];
+        if (model !== undefined)
+            return { providerId: provider.id, modelId: model.id };
+    }
+    return null;
+}
+/** List models from signed-in or configured providers only, in registry order. */
+export async function listOfferedLocalModels(models, signal) {
+    const offered = [];
+    for (const provider of models.getProviders())
+        for (const model of await offeredCatalog(models, provider.id, signal))
+            offered.push({ address: `${provider.id}/${model.id}`, name: model.name });
+    return offered;
+}

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

@@ -0,0 +1,36 @@
+import type { BirdDogMail } from "@fungi.computer/bird-dog";
+import type { Accepted, CancelResult, CommandSettlement, VerifiedAgentReply } from "@fungi.computer/shiitake";
+import type { AgentControlDirectory, AgentDelegationInput, AgentDelegationInvocation, AgentRecallInput } from "@fungi.computer/shiitake/agent-control";
+import { createFleetDelegation } from "@fungi.computer/shiitake/fleet";
+/**
+ * The Local service's project mail routing, shared by every Agent it owns.
+ * `deliver` admits frozen mail at its addressed Agent, opening that Agent's
+ * owner when it is idle; `readSettlement` reads one exact command there.
+ */
+export type PrivateLocalMailRouting = Readonly<{
+    deliver: (mail: BirdDogMail) => Promise<Accepted>;
+    readSettlement: (agentId: string, sessionId: string, commandId: string) => Promise<CommandSettlement | undefined>;
+}>;
+/**
+ * One Local Agent's side of delegation, over the same fleet contract as the
+ * Hub: a `followUp` send freezes BirdDog mail in this Agent's store, and an
+ * arriving reply is admitted only after `fleet.authenticateReply` checks it
+ * against that frozen mail. The replying child authors the reply line.
+ */
+export declare function createPrivateLocalDelegation(input: Readonly<{
+    agentId: string;
+    storage: Parameters<typeof createFleetDelegation>[0]["storage"];
+    directory: Pick<AgentControlDirectory, "list" | "open">;
+    routing: PrivateLocalMailRouting;
+    /** Current Team role of this physical store, projected by its enrolled link. */
+    meshAdmission?: ((recipientAgentId: string) => Promise<readonly {
+        agentId: string;
+        name: string;
+    }[] | undefined>) | undefined;
+    accept: (mail: BirdDogMail, meta?: BirdDogMail["meta"], reply?: VerifiedAgentReply) => Promise<Accepted>;
+}>): {
+    send: (task: AgentDelegationInput, sourceSessionId: string, signal: AbortSignal, invocation?: AgentDelegationInvocation) => Promise<Accepted>;
+    recall: (task: AgentRecallInput, sourceSessionId: string, signal: AbortSignal) => Promise<CancelResult>;
+    receive: (mail: BirdDogMail) => Promise<Accepted>;
+    outstanding: () => Promise<import("@fungi.computer/shiitake/fleet").OutstandingDelegation | undefined>;
+};

package/dist/private-local-delegation.js

@@ -0,0 +1,133 @@
+import { deterministicReplayKey } from "@fungi.computer/cairn";
+import { AgentArchiveRefused } from "@fungi.computer/shiitake/agent-control";
+import { 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;
+/**
+ * One Local Agent's side of delegation, over the same fleet contract as the
+ * Hub: a `followUp` send freezes BirdDog mail in this Agent's store, and an
+ * arriving reply is admitted only after `fleet.authenticateReply` checks it
+ * against that frozen mail. The replying child authors the reply line.
+ */
+export function createPrivateLocalDelegation(input) {
+    const fleet = createFleetDelegation({
+        storage: input.storage,
+        deliver: input.routing.deliver,
+        readSettlement: input.routing.readSettlement,
+        open: (agentId) => input.directory.open(agentId, new AbortController().signal),
+    });
+    async function members(signal) {
+        return (await input.directory.list(signal)).map(({ agentId, name }) => ({
+            agentId,
+            name,
+        }));
+    }
+    async function authorizedMembers(agentId, signal) {
+        const agents = await members(signal);
+        if (!agents.some(({ agentId: memberId }) => memberId === agentId)) {
+            const archived = await input.directory.list(signal, { archived: true });
+            if (archived.some(({ agentId: memberId }) => memberId === agentId))
+                throw new AgentArchiveRefused("archived", `Agent ${agentId} is archived; unarchive it to send it work`);
+            throw new Error("Agent is outside this Local project");
+        }
+        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);
+        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);
+        // The caller's request key owns replay, not the current model program's bytes.
+        const provenance = await delegationProvenance({
+            agentId: input.agentId,
+            sessionId: sourceSessionId,
+        });
+        signal.throwIfAborted();
+        return fleet.start({
+            agents: agents.map(({ agentId }) => agentId),
+            actions: ["delegate"],
+            expiresAt: Date.now() + grantLifetimeMs,
+            provenance,
+            meta,
+        }, {
+            agentId: task.agentId,
+            sessionId: task.sessionId,
+            text: task.text,
+            requestId,
+        });
+    }
+    /** 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);
+        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));
+            return admitted.status === "accepted"
+                ? await session.cancel({
+                    commandId: admitted.commandId,
+                    onlyIfPending: true,
+                })
+                : admitted;
+        }
+        finally {
+            await opened.release();
+        }
+    }
+    /**
+     * 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.
+     */
+    async function receive(mail) {
+        const mesh = await input.meshAdmission?.(mail.to.agentId);
+        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))
+            throw new Error("Local mail sender is outside this project");
+        if (mail.replyTo.length > 0) {
+            const [destination] = mail.replyTo;
+            if (mail.replyTo.length !== 1 ||
+                destination?.agentId !== mail.from.agentId ||
+                destination.sessionId !== mail.from.sessionId)
+                throw new Error("Local delegated work must reply to its sender");
+            return input.accept(mail, mail.meta);
+        }
+        const delegation = fleet.authenticateReply(mail);
+        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)
+            throw new Error("Local reply sender is outside this project");
+        const meta = delegationReplyMeta(delegation, replier.name);
+        return input.accept({ ...mail, meta }, meta, delegation.reply);
+    }
+    return { send, recall, receive, outstanding: fleet.outstanding };
+}

package/dist/private-local-effective-model.d.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/** Secret-free model status published by the Local owner for one Session. */
+export declare const privateLocalEffectiveModelSchema: z.ZodObject<{
+    agentName: z.ZodLiteral<"Shiitake">;
+    providerId: z.ZodString;
+    providerName: z.ZodString;
+    modelId: z.ZodString;
+    modelName: z.ZodString;
+    credential: z.ZodObject<{
+        kind: z.ZodEnum<{
+            oauth: "oauth";
+            api_key: "api_key";
+            missing: "missing";
+        }>;
+        source: z.ZodString;
+    }, z.core.$strict>;
+    reasoning: z.ZodOptional<z.ZodEnum<{
+        minimal: "minimal";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        xhigh: "xhigh";
+        max: "max";
+    }>>;
+    label: z.ZodString;
+}, z.core.$strict>;
+export type PrivateLocalEffectiveModel = z.output<typeof privateLocalEffectiveModelSchema>;

package/dist/private-local-effective-model.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { thinkingLevelSchema } from "./private-fungi-model-catalog.js";
+/** Secret-free model status published by the Local owner for one Session. */
+export const privateLocalEffectiveModelSchema = z.strictObject({
+    agentName: z.literal("Shiitake"),
+    providerId: z.string().min(1).max(160),
+    providerName: z.string().min(1).max(256),
+    modelId: z.string().min(1).max(160),
+    modelName: z.string().min(1).max(256),
+    credential: z.strictObject({
+        kind: z.enum(["oauth", "api_key", "missing"]),
+        source: z.string().min(1).max(160),
+    }),
+    /** The resolved thinking level a run would use; absent when the model has none. */
+    reasoning: thinkingLevelSchema.optional(),
+    label: z.string().min(1).max(640),
+});

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

@@ -0,0 +1,16 @@
+/**
+ * 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
+ * locator variables are not a secret and are what `systemd-run --user`,
+ * `loginctl` and other user-service tools need to find the user manager.
+ * Every other host variable, credentials included, stays out.
+ */
+export type PrivateLocalExecEnvironment = {
+    PATH: string;
+    HOME: string;
+    XDG_RUNTIME_DIR?: string;
+    DBUS_SESSION_BUS_ADDRESS?: string;
+};
+export declare function privateLocalExecEnvironment(executionPath: string, host: NodeJS.ProcessEnv & {
+    HOME: string;
+}): PrivateLocalExecEnvironment;

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

@@ -0,0 +1,11 @@
+export function privateLocalExecEnvironment(executionPath, host) {
+    const environment = {
+        PATH: executionPath,
+        HOME: host.HOME,
+    };
+    if (host.XDG_RUNTIME_DIR)
+        environment.XDG_RUNTIME_DIR = host.XDG_RUNTIME_DIR;
+    if (host.DBUS_SESSION_BUS_ADDRESS)
+        environment.DBUS_SESSION_BUS_ADDRESS = host.DBUS_SESSION_BUS_ADDRESS;
+    return environment;
+}

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

@@ -0,0 +1,41 @@
+import { z } from "zod";
+/**
+ * One exec launch's own text ceiling: 16384, shared by the shell form's
+ * `command` and the direct form's combined `executable`+`args`, so neither
+ * gets a materially larger budget. This is exec's own bound, not borrowed
+ * from any other owner's limit.
+ *
+ * The two forms count against it in different units, which the name
+ * deliberately leaves open rather than mis-claiming one: `command` is
+ * bounded by `z.string().max()`, zod's native UTF-16 code-unit count, the
+ * same as the field already was before the direct form existed. The direct
+ * form's `combinedArgvBytes` below counts real UTF-8 bytes, because argv is
+ * a byte protocol with no code-unit concept. For multi-byte text the two
+ * measures diverge; both stay well inside this ceiling for any launch a
+ * model would actually send.
+ */
+export declare const maximumLaunchTextLength: number;
+/**
+ * One exec launch's own stdin bound. A launch's stdin is a finite payload
+ * held fully in memory and written to the child once, then closed; it is
+ * never streamed, paginated or interactive. 128 KiB keeps that one-shot
+ * payload bounded while still fitting an ordinary small script or data blob.
+ * This is exec's own bound, not borrowed from any other owner's limit (in
+ * particular, not Files' write bound, which governs a different resource:
+ * durable file content, read and written in pages).
+ */
+export declare const maximumLaunchStdinBytes: number;
+/**
+ * Finite UTF-8 text delivered to a launched child once, then closed; never
+ * an interactive protocol. A lone surrogate is refused rather than silently
+ * becoming U+FFFD, so byte-identity is a real guarantee, not a best effort.
+ */
+export declare const launchStdinSchema: z.ZodString;
+/** Combined UTF-8 bytes of a direct form's executable and its args. */
+export declare function combinedArgvBytes(executable: string, args: readonly string[]): number;
+/**
+ * One launch's requested `cwd`: absolute, bounded, no NUL. The caller still
+ * resolves and contains it under the invocation root; this schema only
+ * shapes the raw string.
+ */
+export declare const launchCwdSchema: z.ZodString;

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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+/**
+ * One exec launch's own text ceiling: 16384, shared by the shell form's
+ * `command` and the direct form's combined `executable`+`args`, so neither
+ * gets a materially larger budget. This is exec's own bound, not borrowed
+ * from any other owner's limit.
+ *
+ * The two forms count against it in different units, which the name
+ * deliberately leaves open rather than mis-claiming one: `command` is
+ * bounded by `z.string().max()`, zod's native UTF-16 code-unit count, the
+ * same as the field already was before the direct form existed. The direct
+ * form's `combinedArgvBytes` below counts real UTF-8 bytes, because argv is
+ * a byte protocol with no code-unit concept. For multi-byte text the two
+ * measures diverge; both stay well inside this ceiling for any launch a
+ * model would actually send.
+ */
+export const maximumLaunchTextLength = 16 * 1_024;
+/**
+ * One exec launch's own stdin bound. A launch's stdin is a finite payload
+ * held fully in memory and written to the child once, then closed; it is
+ * never streamed, paginated or interactive. 128 KiB keeps that one-shot
+ * payload bounded while still fitting an ordinary small script or data blob.
+ * This is exec's own bound, not borrowed from any other owner's limit (in
+ * particular, not Files' write bound, which governs a different resource:
+ * durable file content, read and written in pages).
+ */
+export const maximumLaunchStdinBytes = 128 * 1_024;
+/**
+ * Finite UTF-8 text delivered to a launched child once, then closed; never
+ * an interactive protocol. A lone surrogate is refused rather than silently
+ * becoming U+FFFD, so byte-identity is a real guarantee, not a best effort.
+ */
+export const launchStdinSchema = z
+    .string()
+    .refine((value) => value.isWellFormed(), "Computer exec stdin must be well-formed UTF-16 text (no lone surrogates)")
+    .refine((value) => Buffer.byteLength(value, "utf8") <= maximumLaunchStdinBytes, `Computer exec stdin exceeds the ${String(maximumLaunchStdinBytes)}-byte bound`);
+/** Combined UTF-8 bytes of a direct form's executable and its args. */
+export function combinedArgvBytes(executable, args) {
+    return [executable, ...args].reduce((total, value) => total + Buffer.byteLength(value, "utf8"), 0);
+}
+/**
+ * One launch's requested `cwd`: absolute, bounded, no NUL. The caller still
+ * resolves and contains it under the invocation root; this schema only
+ * shapes the raw string.
+ */
+export const launchCwdSchema = z
+    .string()
+    .min(1)
+    .max(4_096)
+    .startsWith("/")
+    .refine((path) => !path.includes("\0"), "Path cannot contain null bytes");

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

@@ -0,0 +1,6 @@
+import { z } from "zod";
+/** Only the invoking client's bounded PATH crosses the local service boundary. */
+export declare const privateLocalExecPathSchema: z.ZodString;
+export declare function parsePrivateLocalExecPath(value: string): string;
+/** Resolve shell-relative client entries before the absolute-only RPC boundary. */
+export declare function capturePrivateLocalExecPath(value: string, clientDirectory: string): string;

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

@@ -0,0 +1,40 @@
+import { isAbsolute, resolve } from "node:path";
+import { z } from "zod";
+const maximumPathCharacters = 8_192;
+const maximumPathDirectories = 64;
+/** Only the invoking client's bounded PATH crosses the local service boundary. */
+export const privateLocalExecPathSchema = z
+    .string()
+    .min(1)
+    .max(maximumPathCharacters)
+    .superRefine((path, context) => {
+    const directories = path.split(":");
+    if (directories.length > maximumPathDirectories)
+        context.addIssue({
+            code: "custom",
+            message: "PATH has too many directories",
+        });
+    for (const directory of directories) {
+        if (directory === "" ||
+            !isAbsolute(directory) ||
+            /[\p{Cc}\p{Cf}]/u.test(directory)) {
+            context.addIssue({
+                code: "custom",
+                message: "PATH must contain only nonempty absolute directories",
+            });
+            break;
+        }
+    }
+});
+export function parsePrivateLocalExecPath(value) {
+    return privateLocalExecPathSchema.parse(value);
+}
+/** Resolve shell-relative client entries before the absolute-only RPC boundary. */
+export function capturePrivateLocalExecPath(value, clientDirectory) {
+    const absolute = value
+        .split(":")
+        .map((directory) => directory === "" || isAbsolute(directory)
+        ? directory
+        : resolve(clientDirectory, directory));
+    return parsePrivateLocalExecPath(absolute.join(":"));
+}

package/dist/private-local-git-exclude.d.ts

@@ -0,0 +1,2 @@
+/** Keep generated project state out of Git without changing tracked ignore rules. */
+export declare function ensurePrivateLocalGitExclude(projectRoot: string): Promise<void>;