@fungi.computer/mycelium 0.0.0-stage → 0.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jamstack Consulting LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,304 @@
-# Temporary Holding Version
+# Mycelium (`@fungi.computer/mycelium`)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Mycelium gives an Agent typed operations through one `execute` tool. It
+validates operations, acquires a coherent capability snapshot and releases it
+when the run ends. You can also execute a known operation without a model.
+
+## Set up
+
+```sh
+npm install @fungi.computer/mycelium
+```
+
+The package ships ESM only and depends on Zod, Effect, `acorn`,
+[Cairn](../cairn/README.md), [Forage](../forage/README.md), and
+[Mule](../mule/README.md) at runtime, all installed automatically. The root
+entrypoint is the Promise host facade. `@fungi.computer/mycelium/effect`
+supplies the scoped Effect API. Both produce an Effect-native Mule tool. The
+`./sandbox-guest`, `./sandbox-wire`, `./sandbox-failure`, `./sandbox-boundary`,
+and `./semaphore-transition` subpaths support a host's sandbox adapter. A host
+supplies the sandbox that actually evaluates code and enforces isolation,
+external access and cancellation.
+
+## Quick start without a model
+
+This example registers `demo.ping`, executes one known binding and prints
+`{"value":"pong"}`. The direct callback deliberately ignores submitted code. It
+is **not isolation**: it runs with host privileges and checks registration,
+validation and cleanup.
+
+```ts
+import { Mycelium } from "@fungi.computer/mycelium";
+import { directSandbox } from "@fungi.computer/mycelium/testing";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { z } from "zod";
+
+const runtime = await Mycelium.make({
+  modules: [
+    Mycelium.module({
+      id: "example-demo",
+      name: "demo",
+      operations: {
+        ping: Mycelium.operation({
+          input: z.object({}),
+          output: z.object({ value: z.string() }),
+          execute: async () => ({ value: "pong" }),
+        }),
+      },
+    }),
+  ],
+  sandbox: directSandbox((bindings, signal) => {
+    signal.throwIfAborted();
+    const ping = bindings.demo?.ping;
+    if (ping === undefined) throw new Error("Missing demo.ping binding");
+    return ping({});
+  }),
+});
+const lease = await runtime.acquire();
+try {
+  const prepared = await Effect.runPromise(
+    lease.executeTool.prepare({
+      type: "toolCall",
+      id: "example-execute",
+      name: "execute",
+      arguments: { code: "return demo.ping({})" },
+    }),
+  );
+  const parts = await Effect.runPromise(Stream.runCollect(prepared.execute()));
+  const text = parts[0]?.result.content[0];
+  if (text?.type !== "text" || text.text !== '{"value":"pong"}') {
+    throw new Error("Unexpected execute result");
+  }
+  console.log(text.text);
+} finally {
+  await lease.release();
+  await runtime.close();
+}
+```
+
+The [public-import fixture](test/stranger/runtime.mjs) uses the same
+known-binding pattern. A real evaluator must implement the public sandbox
+contract. Its request carries code, execution identity, limits and admitted
+bindings. Do not replace it with evaluation in the host's privileged process.
+
+## Operations and discovery
+
+Declare input and output with an Effect schema or any Standard Schema that also
+implements Standard JSON Schema, such as Zod 4. Mycelium decodes input with the
+schema before the operation runs. An Effect output schema encodes the result (so
+a codec such as `Schema.NumberFromString` returns `"1"`); a Standard output
+schema validates it. An Effect schema is exchanged as its canonical JSON codec
+(`Schema.toCodecJson`), so the description, the decoder and the encoder agree. A
+throwing filter or transformation is a host error, never reported to the model
+as invalid input. Stable module IDs identify authority. Names become
+model-facing aliases. Input ordering does not choose either identity. Forage
+prepares the bounded discovery catalog for the captured graph.
+
+Mule receives this runtime's one top-level `execute` tool. Inner operations,
+including `forage.search` and `forage.describe`, stay behind that tool. The
+operation callback receives only its declared input and execution context.
+Access checks and authorization gates run before the operation. Product
+membership, resource ownership and final external access checks remain host
+responsibilities.
+
+## Access labels and grants
+
+Each operation's author labels what it does: `access: "read"` observes,
+`access: "write"` changes something, and an unlabelled operation is `write`. An
+author may add `confirm: true` to ask a person before each call. Labels are
+fixed facts about the operation; the host never edits them.
+
+The host passes its decisions down as data in `access`. `grants` maps a module
+id to `"write"` (every operation), `"read"` (only `read` operations) or
+`"none"`. A module the host does not name keeps full access, so a host that
+grants nothing writes no permission code. `sessionGrants` reads the current
+Session's stored grants at every call; they override `grants` key by key, so a
+revoked grant applies to the very next call. Keys in `required` fail closed:
+when neither names one, it is `"none"`. Labels are parsed at definition with
+`ToolPolicySchema`: anything but exactly `"read"`/`"write"` and a boolean
+`confirm` is a definition error. `confirm` is how the host asks a person;
+without it, a `confirm` operation is refused and never runs unasked.
+
+```ts
+const runtime = await Mycelium.make({
+  modules: [notes],
+  sandbox,
+  access: {
+    grants: { notes: "read" },
+    confirm: (request) => askPerson(request),
+  },
+});
+```
+
+Mycelium checks the grant first, then the person, before the operation's input
+decoder runs. A refused call returns an `AccessRefusal` (`module`, `operation`,
+`reason` and a plain `message`) as its ordinary result. `onRefused` observes
+each refusal for logs or metering and never changes the decision.
+`Mycelium.grantAs` looks a module's grant up by a wider owner's key, such as the
+extension that built it. Labelled direct tools passed as `tools` sit behind the
+same check and come back on the lease's `tools`.
+[Access tests](test/access.test.ts) cover each rule.
+
+## Nested namespaces
+
+Compose modules in `operations` to expose any namespace depth. The enclosing
+module ID remains the authority identity; child registration IDs do not create
+new authority. For example, a module named `bazaar` with `namespace: ["apps"]`
+and `operations: { windows: windowModule }` exposes the child's `open` operation
+as `env.apps.bazaar.windows.open(...)`. A child's own `namespace` adds segments
+after its registration key. Omit `namespace` for the ordinary depth-1 form
+`env.demo.ping(...)`; the existing `demo.ping(...)` form also works.
+
+> An operation key may also be a dotted relative path:
+> `operations: { "repos.list": op }` is called as
+> `env.<module>.repos.list(...)`, exactly like a child module `repos` with
+> operation `list`. Installation refuses a key that is both an operation and a
+> namespace prefix (`files` with `files.read`).
+
+Every leaf keeps its declared input/output types. A gate on the enclosing module
+sees relative paths such as `windows.open`. Forage search, list and describe use
+the complete logical path, and descriptions declare the same nested, callable
+`env`. Names are allocated within their logical namespace, so an App and a
+Computer can share a name without renaming either. Transport aliases and flat
+operation tables remain host-only implementation details. Sandbox adapters use
+`/sandbox-guest`'s parsed namespace metadata and `sandboxGuestProgram` to
+project those bindings; provider adapters also use
+`sandboxProviderOperationName` to avoid Codemode's dotted-name collisions.
+
+## Changing capabilities and lifetime
+
+Use `sources` when a host must acquire a current Computer, Connection or other
+capability projection. A source returns its bounded snapshot and an awaited
+release function. Its `invalidate()` callback marks that snapshot stale. The
+next lease builds a new coherent graph. An existing lease keeps its captured
+snapshot.
+
+Release each lease and close the runtime. Partial acquisition unwinds already
+acquired sources in reverse order. Mycelium owns the scoped resources it
+acquires, while the host owns durable relationships, credentials and current
+policy. A captured snapshot does not excuse a missing final authority check.
+
+## Cancellation and errors
+
+Execution has a deadline, a cancellation acknowledgement grace and a bounded
+JSON result. Cancellation aborts the invocation signal and waits for backing
+sandbox settlement. If the sandbox ignores it, the result reports
+`acknowledged: false`. Do not report that work as stopped.
+
+The typed failure channel includes syntax errors, guest exceptions, lost
+transport, bad responses, failed capabilities, deadline/cancellation and invalid
+or oversized results. A foreign throw becomes `Unknown`. The model receives the
+bounded `sandboxFailureMessage` projection with a reference. The host receives
+operator evidence through `onSandboxFailure` and the existing reporting path.
+Preserve that evidence without sending host diagnostics to the guest.
+
+An Effect host with a Promise sandbox uses `fromTypedSandbox`, which waits for
+that Promise to settle when interrupted. The concrete sandbox and broker decide
+how backing work is stopped. Hosts supply the Worker Loader binding and
+credential custody. The Workers-only `@fungi.computer/mycelium/workers` entry
+exports `createCodemodeSandbox(loader, adapter?, options?)`, a Codemode adapter
+runnable on Workers and celld. It disables guest network access, binds only the
+supplied operations, preserves typed failures and awaits the backing execution
+when cancellation cannot be acknowledged. Import this entry only in Workers
+hosts; the root and other Node entries do not load it.
+
+The adapter forwards the request's existing `timeoutMs` budget as the Worker
+Loader's `cpuMs` limit, retaining any tighter loader limit. Cloudflare and celld
+enforce native CPU limits. Local workerd development does not; execution still
+runs. The local host declares that fact with
+`{ localDevUnenforcedLimits: ["cpu"] }` as the third argument. Mycelium prints
+`CPU limits are not enforced in local dev` once per runtime, across sandbox
+instances. Hosts may also declare unenforced `memory`, `output` and `cancel`
+controls; each gets its own once-only diagnostic. The option reports host facts;
+it adds no enforcement or guest policy. Cancellation still waits for backing
+settlement, and a wall-time timeout does not prove isolate termination.
+
+The
+[Worker Loader custom-limit contract](https://developers.cloudflare.com/dynamic-workers/usage/limits/)
+and the pinned celld invocation types expose `cpuMs` and `subRequests`. They do
+not expose per-invocation memory or output caps, or an execution-cancel
+operation. The adapter preserves supported loader limits without inventing
+fields for those controls. Host-wide memory limits remain host configuration;
+they are not a guest-widenable sandbox setting. The canonical Mycelium
+invocation owner checks its JSON result budget; calling the bare `Sandbox`
+interface does not run that owner's result validation.
+
+An abort before dispatch starts no guest. An abort during execution remains
+authoritative after backing settlement: the adapter's Promise rejects with typed
+`Cancelled { by: "caller" }` instead of resolving a late success. Hosts retain
+invocation custody until that Promise settles; an abort does not release custody
+early. Codemode has no immediate cancellation API. The native qualification
+checks this behavior through the real Worker Loader, along with the trusted
+deadline, CPU forwarding and once-only local notices. These are sandbox checks;
+they do not prove a Workflow host's cancellation path.
+
+## API and examples
+
+Use the [generated API reference](docs/api/README.md) and
+[exports](package.json). Root and `/effect` expose lifecycle construction. The
+sandbox subpaths expose wire, guest, failure and boundary contracts for
+adapters.
+
+[Capability lifecycle tests](test/capability-plane.test.ts) cover source updates
+and release. [Gate tests](test/gate.test.ts) exercise refusals.
+[Sandbox boundary tests](test/sandbox-boundary.test.ts) exercise failure
+projection. These package proofs do not qualify a particular sandbox's isolation
+or deployment.
+
+## Contribute and license
+
+Add a regression to the nearest capability, gate or sandbox test. From the root:
+
+```sh
+pnpm --dir packages/mycelium run test
+pnpm --dir packages/mycelium run docs
+```
+
+MIT. See [LICENSE](LICENSE) and [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES).
+
+## MCP
+
+`@fungi.computer/mycelium/mcp` exports `createMcp({ catalog, authenticate })`,
+returning `{ handleRequest, close }`. Mount `handleRequest` at the host's MCP
+route. Authentication runs for every HTTP request, including notifications and
+disconnects, and before each operation. Return either
+`{ kind: "admitted", principal }` or `{ kind: "refused", status: 401 | 403 }`.
+The principal is the host's canonical actor: a member with its role
+(`{ actor: { kind: "member", memberId }, role }`), or an Agent or Team key
+(`{ actor: { kind: "agent", agentId } }`,
+`{ actor: { kind: "team-key", keyId } }`). Its ids identify the credential's
+actor, never a bearer token.
+
+For installed-App hosts, `createMcpCatalog({ load, sandbox })` adapts ordinary
+Mycelium capability sources. `load(principal)` returns the current
+`{ instructions, sources, grants }` authorized for that principal. It runs again
+before execution and after approval. Each invocation must begin a fresh
+authority read; returning an older cached snapshot cannot establish current
+grants. Grants are explicit: an omitted module is refused. The supplied sandbox
+remains the host's isolated executor; this entry provides no host-fetch
+fallback. This catalog keeps at most eight open connections in process memory
+and releases each acquired tool runtime when its request finishes.
+
+Durable Agent hosts implement `McpCatalogProvider` over their existing Session
+owner. `open` atomically reserves the supplied connection bound, `resume`
+returns only an open principal-bound Session, and `refresh` delivers current
+grants. The MCP server independently checks the stored principal. The Session's
+`call` must carry `McpExecutionContext.access` into its ordinary Mycelium
+execution, including direct tools, without persisting request callbacks.
+
+MCP execution requires approval for every write-level operation not covered by
+the catalog snapshot's `approvedWrites`, including unlabelled operations. Read
+operations retain their declared confirmation policy. `approvedWrites` names
+granted modules whose writes a person already approved for that principal; it is
+read from the current snapshot at each call, and an operation labelled `confirm`
+still asks. Form elicitation runs before the operation, and authority is
+refreshed again after acceptance; missing or declined approval refuses
+execution. The server supports MCP `2025-11-25` Streamable HTTP so an approval
+can suspend the existing execution without replaying already-completed
+operations. Approval requests contain the module, operation and access label,
+not credential data or operation arguments. `close()` closes transport streams;
+Session retention and connection persistence remain with the catalog owner.
+After transport process loss, a resumed connection has no recorded client
+elicitation capability and refuses writes. Delete that connection and initialize
+a fresh one to negotiate form elicitation again.

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,2 @@
+Mycelium v0.0.1 is informed by the retained MIT-licensed @shiit/mycelium
+implementation. No retained source is copied without an explicit source receipt.

package/dist/access.d.ts

@@ -0,0 +1,129 @@
+import type { MuleTool } from "@fungi.computer/mule/effect";
+import type { SandboxValue } from "./index.js";
+import * as Schema from "effect/Schema";
+/**
+ * What one operation does, declared by its author as a fixed fact: `read`
+ * observes, `write` changes something. An unlabelled operation is `write`.
+ */
+export declare const ToolAccessSchema: Schema.Literals<readonly ["read", "write"]>;
+/** What one operation does: `read` observes, `write` changes something. */
+export type Access = typeof ToolAccessSchema.Type;
+/** Whether the author asks that a person approve each call first. */
+export declare const ToolConfirmSchema: Schema.Boolean;
+/**
+ * An author's labels for one operation or direct tool: the one definition
+ * both the TypeScript type and the registration-time parse derive from.
+ */
+export declare const ToolPolicySchema: Schema.Struct<{
+    readonly access: Schema.optional<Schema.Literals<readonly ["read", "write"]>>;
+    readonly confirm: Schema.optional<Schema.Boolean>;
+}>;
+/** An author's labels for one operation or direct tool. */
+export type ToolPolicy = typeof ToolPolicySchema.Type;
+/**
+ * The access a host grants one module: `write` allows every operation,
+ * `read` allows only `read` operations, `none` allows nothing.
+ */
+export declare const GrantSchema: Schema.Literals<readonly ["none", "read", "write"]>;
+/** The access a host grants one module. */
+export type Grant = typeof GrantSchema.Type;
+/**
+ * A host's grants, keyed by module id. An unnamed module uses defaultGrant
+ * unless it is required, in which case missing authority is refused.
+ */
+export type Grants = Readonly<Record<string, Grant>>;
+/** The labels an operation or direct tool carries, as its author declared them. */
+export type AccessLabel = Readonly<{
+    /** Stable module id the grant is looked up by. */
+    module: string;
+    /** Operation path inside the module, or the direct tool's name. */
+    operation: string;
+    access: Access;
+    /** The author asks that a person approve each call first. */
+    confirm: boolean;
+}>;
+/** The Session a runtime serves; null for a session-free host. */
+export type AccessContext = Readonly<{
+    sessionId: string | null;
+}>;
+/** One call the host is asked to approve before it runs. */
+export type ConfirmRequest = Readonly<Omit<AccessLabel, "confirm"> & AccessContext & {
+    /** The requested input exactly as the caller supplied it, not yet decoded. */
+    input: SandboxValue;
+}>;
+/** Why a call was refused before it ran. */
+export type AccessRefusalReason = "not-granted" | "read-only" | "confirmation-unavailable" | "declined";
+/** The ordinary result a refused call returns in place of running. */
+export type AccessRefusal = Readonly<{
+    refused: true;
+    module: string;
+    operation: string;
+    reason: AccessRefusalReason;
+    message: string;
+}>;
+/**
+ * Host-supplied access data and the one way to ask a person. Every field is
+ * optional: hosted defaults allow unnamed modules, and no `confirm` means an
+ * operation requiring approval is refused, never run unasked. MCP catalogs
+ * explicitly default unnamed modules to none and require approval for writes.
+ */
+export type AccessOptions = Readonly<{
+    /** Grant for unnamed modules; MCP catalogs use none. Defaults to write for hosted callers. */
+    defaultGrant?: Grant;
+    /** The default grants as plain data; absent is full access. */
+    grants?: Grants;
+    /**
+     * Module keys under grant control. A required key that neither the Session
+     * grants nor the default names is refused, so a missing delivery fails
+     * closed. Other unnamed keys use defaultGrant.
+     */
+    required?: readonly string[];
+    /**
+     * Read the current Session's stored grants at every call; they override
+     * `grants` key by key, so a revoked grant applies to the very next call.
+     */
+    sessionGrants?: (context: AccessContext) => Grants;
+    /** Refresh authority before a call and again after approval. Failure refuses execution. */
+    beforeCall?: (signal: AbortSignal) => Promise<void>;
+    /** Require approval for every write, including operations without an explicit confirm label. */
+    confirmWrites?: boolean;
+    /**
+     * Read, at every call, the module ids whose writes a person already
+     * approved for this caller. Such a write needs no per-call `confirm`; an
+     * operation its author labelled `confirm` still asks, and grants still apply.
+     */
+    approvedWrites?: (context: AccessContext) => readonly string[];
+    /** Ask a person to approve one call; resolve true to run it. */
+    confirm?: ((request: ConfirmRequest, signal: AbortSignal) => Promise<boolean>) | undefined;
+    /** Operator-only observer of every refusal; never changes the decision. */
+    onRefused?: (refusal: AccessRefusal, context: AccessContext) => void;
+}>;
+/** A Mule tool that carries its author's access labels outside execute. */
+export type LabelledTool = MuleTool & Readonly<{
+    /** Stable module id the grant is looked up by. */
+    module: string;
+    /** Unlabelled means `write`. */
+    access?: Access;
+    /** Ask a person before each call. */
+    confirm?: boolean;
+}>;
+/**
+ * Parse an author's labels at definition. Only the exact `"read"` and
+ * `"write"` and a boolean `confirm` are labels; anything else is a definition
+ * error, never quietly read as a weaker label.
+ */
+export declare function parseAccessLabels(labels: Readonly<{
+    access?: SandboxValue;
+    confirm?: SandboxValue;
+}>): Pick<AccessLabel, "access" | "confirm">;
+/**
+ * Decide one call against its labels and the host's current grants: the grant
+ * first, then the person. Returns the refusal, or undefined to run the call.
+ */
+export declare function checkAccess(options: AccessOptions, context: AccessContext, label: AccessLabel, input: SandboxValue, signal: AbortSignal): Promise<AccessRefusal | undefined>;
+/**
+ * Put one labelled direct tool behind the host's access options. A refused
+ * call never reaches the tool's decoder and returns the refusal as its
+ * ordinary result, as a refused operation does inside execute.
+ */
+export declare function guardTool(tool: LabelledTool, options: AccessOptions, context: AccessContext): MuleTool;

package/dist/access.js

@@ -0,0 +1,166 @@
+import { MyceliumDefinitionError } from "./errors.js";
+import * as Effect from "effect/Effect";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+/**
+ * What one operation does, declared by its author as a fixed fact: `read`
+ * observes, `write` changes something. An unlabelled operation is `write`.
+ */
+export const ToolAccessSchema = Schema.Literals(["read", "write"]);
+/** Whether the author asks that a person approve each call first. */
+export const ToolConfirmSchema = Schema.Boolean;
+/**
+ * An author's labels for one operation or direct tool: the one definition
+ * both the TypeScript type and the registration-time parse derive from.
+ */
+export const ToolPolicySchema = Schema.Struct({
+    access: Schema.optional(ToolAccessSchema),
+    confirm: Schema.optional(ToolConfirmSchema),
+});
+/**
+ * The access a host grants one module: `write` allows every operation,
+ * `read` allows only `read` operations, `none` allows nothing.
+ */
+export const GrantSchema = Schema.Literals(["none", "read", "write"]);
+const decodeToolPolicy = Schema.decodeUnknownResult(ToolPolicySchema);
+const decodeGrant = Schema.decodeUnknownResult(GrantSchema);
+/**
+ * Parse an author's labels at definition. Only the exact `"read"` and
+ * `"write"` and a boolean `confirm` are labels; anything else is a definition
+ * error, never quietly read as a weaker label.
+ */
+export function parseAccessLabels(labels) {
+    const parsed = decodeToolPolicy({
+        access: labels.access,
+        confirm: labels.confirm,
+    });
+    if (Result.isFailure(parsed))
+        throw new MyceliumDefinitionError('Access labels must be access: "read" | "write" and confirm: boolean');
+    return {
+        access: parsed.success.access ?? "write",
+        confirm: parsed.success.confirm ?? false,
+    };
+}
+function messageFor(reason, label) {
+    const name = `${label.module}.${label.operation}`;
+    switch (reason) {
+        case "not-granted":
+            return `${name} is not granted to this Agent.`;
+        case "read-only":
+            return `${name} changes something, and this Agent has read-only access to ${label.module}.`;
+        case "confirmation-unavailable":
+            return `${name} needs a person's approval, and no one can be asked here.`;
+        case "declined":
+            return `${name} was not approved.`;
+    }
+}
+function refusal(reason, label) {
+    return Object.freeze({
+        refused: true,
+        module: label.module,
+        operation: label.operation,
+        reason,
+        message: messageFor(reason, label),
+    });
+}
+/**
+ * The grant for one module. An unnamed module uses the configured default
+ * unless it is required; a present entry that is not a grant refuses, so a
+ * malformed host value fails closed.
+ */
+function grantFor(options, context, module) {
+    const session = options.sessionGrants?.(context);
+    const owner = session !== undefined && Object.hasOwn(session, module)
+        ? session
+        : options.grants;
+    if (owner === undefined || !Object.hasOwn(owner, module))
+        return options.required?.includes(module) === true
+            ? "none"
+            : (options.defaultGrant ?? "write");
+    const parsed = decodeGrant(owner[module]);
+    return Result.isSuccess(parsed) ? parsed.success : "none";
+}
+/**
+ * Decide one call against its labels and the host's current grants: the grant
+ * first, then the person. Returns the refusal, or undefined to run the call.
+ */
+export async function checkAccess(options, context, label, input, signal) {
+    const decided = await decide(options, context, label, input, signal);
+    if (decided !== undefined)
+        options.onRefused?.(decided, context);
+    return decided;
+}
+async function decide(options, context, label, input, signal) {
+    await options.beforeCall?.(signal);
+    signal.throwIfAborted();
+    const granted = grantRefusal(options, context, label);
+    if (granted !== undefined)
+        return granted;
+    if (!label.confirm &&
+        !(options.confirmWrites === true && label.access !== "read"))
+        return undefined;
+    if (!label.confirm &&
+        options.approvedWrites?.(context).includes(label.module) === true)
+        return undefined;
+    if (options.confirm === undefined)
+        return refusal("confirmation-unavailable", label);
+    const approved = await options.confirm({
+        module: label.module,
+        operation: label.operation,
+        access: label.access,
+        sessionId: context.sessionId,
+        input,
+    }, signal);
+    if (!approved)
+        return refusal("declined", label);
+    await options.beforeCall?.(signal);
+    signal.throwIfAborted();
+    // A grant revoked while the person was deciding still applies.
+    return grantRefusal(options, context, label);
+}
+/** The refusal the current grant gives this label, if any. */
+function grantRefusal(options, context, label) {
+    const grant = grantFor(options, context, label.module);
+    if (grant === "none")
+        return refusal("not-granted", label);
+    // Only an exact "read" label is a read; every other operation writes.
+    if (grant === "read" && label.access !== "read")
+        return refusal("read-only", label);
+    return undefined;
+}
+/**
+ * Put one labelled direct tool behind the host's access options. A refused
+ * call never reaches the tool's decoder and returns the refusal as its
+ * ordinary result, as a refused operation does inside execute.
+ */
+export function guardTool(tool, options, context) {
+    const label = {
+        module: tool.module,
+        operation: tool.descriptor.name,
+        ...parseAccessLabels(tool),
+    };
+    return {
+        ...tool,
+        prepare: (call) => Effect.tryPromise({
+            try: (signal) => checkAccess(options, context, label, call.arguments, signal),
+            // Host failures stay out of the model's view; the call fails closed.
+            catch: () => ({ message: "Access check failed" }),
+        }).pipe(Effect.flatMap((refused) => refused === undefined
+            ? tool.prepare(call)
+            : Effect.succeed({
+                execute: () => Stream.succeed({
+                    type: "result",
+                    result: {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(refused),
+                            },
+                        ],
+                        isError: false,
+                    },
+                }),
+            }))),
+    };
+}

package/dist/capability-source.d.ts

@@ -0,0 +1,44 @@
+import type * as Schema from "effect/Schema";
+import type { ModuleRegistration } from "./registration.js";
+/** Session on whose behalf one runtime acquires its capability projections. */
+export type CapabilitySession = Readonly<{
+    /** Stable Session identity supplied by the session host (Shiitake). */
+    sessionId: string;
+    /** Host's stored command identity; stable across run recovery. */
+    commandId?: string;
+    /** Opaque host metadata from that stored command, never a model argument. */
+    meta?: typeof Schema.Json.Type;
+}>;
+/** Context supplied while acquiring one current capability projection. */
+export type CapabilitySourceContext = Readonly<{
+    /**
+     * Session the projection is acquired for; absent for session-free hosts.
+     * A source uses it to project only what that Session is permitted to use.
+     */
+    session?: CapabilitySession;
+    /** Cooperative cancellation for this bounded acquisition attempt. */
+    signal: AbortSignal;
+    /** Mark the candidate stale when the source's current projection changes. */
+    invalidate: () => void;
+}>;
+/** Bounded current projection returned by one capability source. */
+export type CapabilitySourceSnapshot = Readonly<{
+    /** Stable, secret-free version of this source projection. */
+    version: string;
+    /** Unordered modules contributed by this projection. */
+    modules: readonly ModuleRegistration[];
+}>;
+/** Acquired source projection and the cleanup that owns its live adapter. */
+export type CapabilitySourceAcquisition = Readonly<{
+    /** Current immutable projection captured by this acquisition. */
+    snapshot: CapabilitySourceSnapshot;
+    /** Release subscriptions and adapters owned by this acquisition. */
+    release: () => Promise<void>;
+}>;
+/** Promise-shaped host boundary for one versioned capability projection. */
+export type CapabilitySource = Readonly<{
+    /** Stable, bounded, secret-free source identity. */
+    id: string;
+    /** Acquire one current projection and its awaited cleanup. */
+    acquire: (context: CapabilitySourceContext) => Promise<CapabilitySourceAcquisition>;
+}>;

package/dist/capability-source.js

@@ -0,0 +1 @@
+export {};