@fungi.computer/graft 0.0.0-stage → 0.0.1

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,154 @@
-# Temporary Holding Version
+# Graft (`@fungi.computer/graft`)
 
-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.
+This package presents an authorized Shiitake Session through the stable Agent
+Client Protocol (ACP) v1. Editor and host integrations use it to create, load,
+prompt, and observe Sessions while the host remains responsible for
+authorization.
+
+Just want Fungi in Zed or another ACP editor? Run `fungi acp` — see
+[Use Fungi in your editor](https://docs.fungi.computer/guides/use-fungi-in-your-editor/).
+Graft is for people embedding ACP in their own host.
+
+## Install or set up
+
+Graft is a public package qualified with packed npm consumers. Qualification
+does not publish an npm release; check the registry before choosing a released
+version. To build the source workspace and qualify its tarballs:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm turbo:run run build --filter=@fungi.computer/graft
+pnpm --filter @fungi.computer/graft run pack
+pnpm --filter @fungi.computer/graft run stranger
+```
+
+The source workspace supplies Graft's workspace dependencies. The stranger proof
+packs the dependency closure and installs it in a fresh consumer; a standalone
+release needs those dependencies published too. Strict TypeScript consumers also
+install `@modelcontextprotocol/sdk@1.30.0`: the transitive Google GenAI
+declarations reference this optional peer. Both packed proofs include it; the
+stranger proof keeps library checking enabled.
+
+## Quick start
+
+Just want Fungi in Zed or another ACP editor? Run `fungi acp` — see
+[Use Fungi in your editor](https://docs.fungi.computer/guides/use-fungi-in-your-editor/).
+Graft is for people embedding ACP in their own host.
+
+This self-contained example initializes an ACP connection without granting
+access to any Session. Replace the refusing directory with your host's
+authorized Session directory before accepting create or load requests.
+
+```ts
+import * as acp from "@agentclientprotocol/sdk";
+import { createHttpStream } from "@agentclientprotocol/sdk/experimental/http-client";
+import {
+  agentAcpMethods,
+  type AuthorizedShiitakeSessionDirectory,
+} from "@fungi.computer/graft";
+import { createShiitakeAcpServer } from "@fungi.computer/graft/server";
+
+const directory: AuthorizedShiitakeSessionDirectory = {
+  create() {
+    return Promise.reject(new Error("Session access is not granted"));
+  },
+  load() {
+    return Promise.reject(new Error("Session access is not granted"));
+  },
+};
+const server = createShiitakeAcpServer(directory);
+const stream = createHttpStream("https://agent.test/acp", {
+  fetch: (input, init) => server.handleRequest(new Request(input, init)),
+});
+try {
+  await acp
+    .client({ name: "graft-example" })
+    .connectWith(stream, async (ctx) => {
+      const initialized = await ctx.request(agentAcpMethods.initialize, {
+        protocolVersion: acp.PROTOCOL_VERSION,
+      });
+      console.log(initialized.protocolVersion);
+    });
+} finally {
+  await stream.writable.close();
+  await server.close();
+}
+```
+
+The fetch adapter calls the server in-process; it makes no network request and
+needs no model or credentials. The packed runtime proof in
+[`test/stranger/runtime.mjs`](test/stranger/runtime.mjs) exercises this flow on
+Node. [`test/index.test.ts`](test/index.test.ts) additionally proves Session
+creation, prompting and cleanup through the maintained ACP client.
+
+## Core concepts
+
+- **The directory owns access.** Its `create` and `load` methods return a
+  Session binding only after the host authorizes it. It can validate the working
+  directory, additional directories, and MCP servers before opening the Session.
+- **Shiitake owns Session state.** The ACP adapter projects messages, tool
+  calls, progress, cancellation, and terminal results. It does not own the
+  transcript or delete the durable Session.
+- **An ACP connection owns its lease.** Closing a Session or connection releases
+  its host-provided client lease and observation. An active prompt is cancelled
+  and allowed to settle for up to five seconds by default when its Session
+  closes.
+- **The server is an adapter.** `createShiitakeAcpServer` exposes the same agent
+  through the maintained Streamable HTTP transport; it does not supply
+  authorization by itself.
+
+## API reference
+
+The package exports `createShiitakeAcpAgent`, the authorization and adapter
+types, and `agentAcpMethods` from [`src/index.ts`](src/index.ts). The HTTP
+server is exported separately from [`src/server.ts`](src/server.ts). The
+host-owned directory adapter lives in
+[`src/session-directory.ts`](src/session-directory.ts). The generated
+[API reference](docs/api/README.md) is included in the tarball.
+
+## Examples
+
+- [`test/index.test.ts`](test/index.test.ts) proves create/load/prompt behavior,
+  streamed message projection, cancellation and cleanup through the maintained
+  ACP client.
+- The private Local stdio host currently rejects ACP `additionalDirectories` and
+  `mcpServers`; other hosts may support them when their authorization boundary
+  permits them.
+
+## Limits and errors
+
+The adapter supports text and image prompts, embedded text or image resources,
+and text or image tool results. Audio and other binary resources are refused. A
+host decides which directories, MCP servers, and Sessions the connection may
+use. ACP create requests do not provide their own stable retry identity, so the
+directory generates a request identity for Shiitake. Callers must close the ACP
+connection so watches and authorization leases are released; closing the lease
+does not delete the Session.
+
+## Contribute and license
+
+Run `pnpm --filter @fungi.computer/graft test` for the ACP protocol and
+lifecycle tests, and `pnpm --filter @fungi.computer/graft build` to compile the
+package. The package uses the MIT license in [`LICENSE`](LICENSE).
+
+## Editor capabilities
+
+The adapter uses ACP SDK 1.7 and stable protocol v1. Initialization returns the
+supported protocol version even when an editor offers another version; the
+editor decides whether it can continue. Session listing is advertised only when
+the authorized host directory supplies it. Local lists saved project Sessions.
+
+A host may supply a terminal login method. It is advertised only when the editor
+supports terminal authentication; the editor runs the login command in a
+separate interactive process. Hosted directories do not acquire Local
+credentials.
+
+Text resources retain their URI and contents in prompt context. Resource links
+retain their name and URI for the Agent's authorized tools to resolve. Images,
+including embedded image resources, enter Shiitake's bounded prompt admission
+and persist as Pi image content. History replays images through ACP. Audio and
+other binary resources return `invalid_params`; they are not silently discarded.
+
+Protocol references:
+[initialization](https://agentclientprotocol.com/protocol/v1/initialization) and
+[content](https://agentclientprotocol.com/protocol/v1/content).

package/dist/adapter.d.ts

@@ -0,0 +1,95 @@
+import * as acp from "@agentclientprotocol/sdk";
+import type { ShiitakeSession } from "@fungi.computer/shiitake/client";
+/** Maintained ACP method descriptors advertised by this agent adapter. */
+export declare const agentAcpMethods: {
+    readonly initialize: "initialize";
+    readonly authenticate: "authenticate";
+    readonly logout: "logout";
+    readonly providers: {
+        readonly list: "providers/list";
+        readonly set: "providers/set";
+        readonly disable: "providers/disable";
+    };
+    readonly session: {
+        readonly new: "session/new";
+        readonly load: "session/load";
+        readonly list: "session/list";
+        readonly delete: "session/delete";
+        readonly fork: "session/fork";
+        readonly resume: "session/resume";
+        readonly close: "session/close";
+        readonly setMode: "session/set_mode";
+        readonly setConfigOption: "session/set_config_option";
+        readonly prompt: "session/prompt";
+        readonly cancel: "session/cancel";
+    };
+    readonly nes: {
+        readonly start: "nes/start";
+        readonly suggest: "nes/suggest";
+        readonly accept: "nes/accept";
+        readonly reject: "nes/reject";
+        readonly close: "nes/close";
+    };
+    readonly document: {
+        readonly didOpen: "document/didOpen";
+        readonly didChange: "document/didChange";
+        readonly didClose: "document/didClose";
+        readonly didSave: "document/didSave";
+        readonly didFocus: "document/didFocus";
+    };
+};
+/** A Session returned by the host's authorization boundary. */
+export type AuthorizedShiitakeSession = Readonly<{
+    /** Authorized live Session client. */
+    session: ShiitakeSession;
+    /** Durable identity of the authorized Session. */
+    sessionId: string;
+    /** Release this ACP client's authorization lease; retain the durable Session. */
+    close: () => Promise<void>;
+}>;
+/** Directory owner used by ACP lifecycle callbacks. */
+export type AuthorizedShiitakeSessionDirectory = Readonly<{
+    /** Authorize and create a Session with the requested context. */
+    create: (input: {
+        cwd: string;
+        additionalDirectories: readonly string[];
+        mcpServers: readonly acp.McpServer[];
+        signal: AbortSignal;
+    }) => Promise<AuthorizedShiitakeSession>;
+    /** Enumerate only Sessions within this host's authorized directory. */
+    list?: (input: {
+        cwd?: string;
+        cursor?: string;
+        signal: AbortSignal;
+    }) => Promise<acp.ListSessionsResponse>;
+    /** Authorize and open an existing Session with the requested context. */
+    load: (input: {
+        sessionId: string;
+        cwd: string;
+        additionalDirectories: readonly string[];
+        mcpServers: readonly acp.McpServer[];
+        signal: AbortSignal;
+    }) => Promise<AuthorizedShiitakeSession>;
+}>;
+/** Host directory, agent identity and lifecycle options for an ACP adapter. */
+export type ShiitakeAcpAdapterOptions = Readonly<{
+    /** Host-owned Session authorization boundary. */
+    directory: AuthorizedShiitakeSessionDirectory;
+    /** Agent name reported to the editor. */
+    name?: string;
+    /** Host login command, appended by clients that support terminal auth. */
+    terminalAuth?: acp.AuthMethodTerminal;
+    /**
+     * How long `session/close` waits for an active prompt to settle after its
+     * cancel before detaching the prompt's observation. Defaults to 5 seconds.
+     */
+    closeSettleMs?: number;
+}>;
+/**
+ * Projects ACP stable v1 onto Sessions from one host-authorized directory.
+ *
+ * The host directory owns Session creation/loading and authorization. ACP
+ * request IDs are retained for correlation while Shiitake generates its own
+ * idempotency key and returns its own accepted command ID.
+ */
+export declare function createShiitakeAcpAgent(options: ShiitakeAcpAdapterOptions): acp.AgentApp;

package/dist/adapter.js

@@ -0,0 +1,530 @@
+import * as acp from "@agentclientprotocol/sdk";
+/** Maintained ACP method descriptors advertised by this agent adapter. */
+export const agentAcpMethods = acp.methods.agent;
+const DEFAULT_CLOSE_SETTLE_MS = 5_000;
+function isContentParts(content) {
+    return Array.isArray(content);
+}
+function contentBlocks(content) {
+    return !isContentParts(content)
+        ? [acpText(content)]
+        : content.map((part) => part.type === "text"
+            ? acpText(part.text)
+            : { type: "image", data: part.data, mimeType: part.mimeType });
+}
+function textFromAssistant(content) {
+    return content
+        .filter((part) => part.type === "text")
+        .map((part) => part.text)
+        .join("");
+}
+function thinkingFromAssistant(content) {
+    return content
+        .filter((part) => part.type === "thinking")
+        .map((part) => part.thinking)
+        .join("");
+}
+function acpText(text) {
+    return { type: "text", text };
+}
+function notify(client, sessionId, update) {
+    return client.notify(acp.methods.client.session.update, {
+        sessionId,
+        update,
+    });
+}
+/**
+ * Return the part of `next` that extends what was sent. ACP chunks cannot be
+ * retracted, so a revision that does not extend the sent text sends nothing.
+ */
+function unsent(sent, next) {
+    return next.startsWith(sent) ? next.slice(sent.length) : "";
+}
+async function projectMessage(client, sessionId, message, streamed = { text: "", thinking: "" }) {
+    const value = message.value;
+    if (value.role === "system")
+        return;
+    if (value.role === "user") {
+        for (const content of contentBlocks(value.content))
+            await notify(client, sessionId, {
+                sessionUpdate: "user_message_chunk",
+                content,
+            });
+        return;
+    }
+    if (value.role === "assistant") {
+        const thinking = unsent(streamed.thinking, thinkingFromAssistant(value.content));
+        if (thinking)
+            await notify(client, sessionId, {
+                sessionUpdate: "agent_thought_chunk",
+                content: acpText(thinking),
+            });
+        const text = unsent(streamed.text, textFromAssistant(value.content));
+        if (text)
+            await notify(client, sessionId, {
+                sessionUpdate: "agent_message_chunk",
+                content: acpText(text),
+            });
+        for (const part of value.content) {
+            if (part.type !== "toolCall")
+                continue;
+            await notify(client, sessionId, {
+                sessionUpdate: "tool_call",
+                toolCallId: part.id,
+                title: part.name,
+                kind: "other",
+                status: "in_progress",
+                rawInput: part.arguments,
+            });
+        }
+        return;
+    }
+    const toolResult = value;
+    await notify(client, sessionId, {
+        sessionUpdate: "tool_call_update",
+        toolCallId: toolResult.toolCallId,
+        status: toolResult.isError ? "failed" : "completed",
+        content: contentBlocks(toolResult.content).map((content) => ({
+            type: "content",
+            content,
+        })),
+        rawOutput: toolResult.details,
+    });
+}
+async function projectProgress(client, sessionId, progress, turn) {
+    if (turn.projected.has(progress.messageId))
+        return;
+    const sent = turn.streamed.get(progress.messageId) ?? {
+        text: "",
+        thinking: "",
+    };
+    const thinking = unsent(sent.thinking, progress.thinking);
+    const text = unsent(sent.text, progress.text);
+    turn.streamed.set(progress.messageId, {
+        text: sent.text + text,
+        thinking: sent.thinking + thinking,
+    });
+    if (thinking)
+        await notify(client, sessionId, {
+            sessionUpdate: "agent_thought_chunk",
+            content: acpText(thinking),
+        });
+    if (text)
+        await notify(client, sessionId, {
+            sessionUpdate: "agent_message_chunk",
+            content: acpText(text),
+        });
+}
+async function projectTurnMessages(client, sessionId, messages, turn) {
+    for (const message of messages) {
+        if (message.commandId !== turn.commandId)
+            continue;
+        if (turn.projected.has(message.id))
+            continue;
+        turn.projected.add(message.id);
+        // The ACP client sent this turn's prompt; echoing it would duplicate it.
+        if (message.value.role === "user")
+            continue;
+        await projectMessage(client, sessionId, message, turn.streamed.get(message.id));
+        turn.streamed.delete(message.id);
+    }
+}
+async function projectFrame(client, sessionId, frame, turn) {
+    if (frame.kind === "progress") {
+        await projectProgress(client, sessionId, frame.progress, turn);
+        return [];
+    }
+    if (frame.kind === "reset") {
+        // A reset replaces the baseline mid-turn. Project this turn's messages
+        // that were not already sent; everything else is history. Later progress
+        // frames carry cumulative text, so live progress resumes from its delta.
+        await projectTurnMessages(client, sessionId, frame.baseline.messages, turn);
+        return frame.baseline.terminals;
+    }
+    await projectTurnMessages(client, sessionId, frame.messages, turn);
+    return frame.terminals;
+}
+function stopReason(outcome) {
+    if (outcome === "completed")
+        return "end_turn";
+    if (outcome === "cancelled")
+        return "cancelled";
+    throw new Error(`Session turn ended with ${outcome}`);
+}
+function assertSessionId(sessionId) {
+    if (sessionId.length === 0)
+        throw new Error("The Session owner returned an empty identity");
+}
+function promptInput(prompt) {
+    const text = [];
+    const images = [];
+    for (const block of prompt) {
+        switch (block.type) {
+            case "text":
+                text.push(block.text);
+                break;
+            case "image":
+                images.push({
+                    type: "image",
+                    data: block.data,
+                    mimeType: block.mimeType,
+                });
+                break;
+            case "resource_link":
+                text.push(`\nReferenced resource ${JSON.stringify(block.name)}: ${JSON.stringify(block.uri)}\n`);
+                break;
+            case "resource": {
+                const resource = block.resource;
+                text.push(`\nResource ${JSON.stringify(resource.uri)} (${resource.mimeType ?? "unspecified"}):\n`);
+                if ("text" in resource)
+                    text.push(resource.text);
+                else if (resource.mimeType?.startsWith("image/") === true)
+                    images.push({
+                        type: "image",
+                        data: resource.blob,
+                        mimeType: resource.mimeType,
+                    });
+                else
+                    throw acp.RequestError.invalidParams(undefined, "Binary resources require a supported image MIME type; send other context as text");
+                text.push("\nEnd resource\n");
+                break;
+            }
+            case "audio":
+                throw acp.RequestError.invalidParams(undefined, "Audio prompts are unsupported");
+        }
+    }
+    return { text: text.join(""), images };
+}
+/** Resolve true when `work` settles within `ms`, false when the bound passes. */
+function settlesWithin(work, ms) {
+    let timer;
+    return Promise.race([
+        work.then(() => true),
+        new Promise((resolve) => {
+            timer = setTimeout(() => {
+                resolve(false);
+            }, ms);
+        }),
+    ]).finally(() => {
+        clearTimeout(timer);
+    });
+}
+function asError(cause) {
+    return cause instanceof Error ? cause : new Error(String(cause));
+}
+function closeWatchOnce(closed, watch) {
+    const existing = closed.get(watch);
+    if (existing)
+        return existing;
+    const closing = Promise.resolve().then(() => watch.close());
+    closed.set(watch, closing);
+    return closing;
+}
+/** Stop observing a turn; its prompt request then ends as detached. */
+function detach(turn, closedWatches) {
+    turn.detached = true;
+    if (turn.watch === undefined)
+        return Promise.resolve({ kind: "closed" });
+    return closeWatchOnce(closedWatches, turn.watch).then(() => ({ kind: "closed" }), (cause) => ({ kind: "failed", error: asError(cause) }));
+}
+/** Re-read teardown state after an asynchronous owner operation. */
+function assertPromptAttached(turn, state) {
+    if (turn.detached || state.closed !== undefined)
+        throw new Error("The ACP connection closed before prompt admission");
+}
+function closeOnce(closed, binding) {
+    const existing = closed.get(binding);
+    if (existing)
+        return existing;
+    const closing = Promise.resolve().then(() => binding.close());
+    closed.set(binding, closing);
+    return closing;
+}
+/**
+ * Projects ACP stable v1 onto Sessions from one host-authorized directory.
+ *
+ * The host directory owns Session creation/loading and authorization. ACP
+ * request IDs are retained for correlation while Shiitake generates its own
+ * idempotency key and returns its own accepted command ID.
+ */
+export function createShiitakeAcpAgent(options) {
+    const { directory } = options;
+    const closeSettleMs = options.closeSettleMs ?? DEFAULT_CLOSE_SETTLE_MS;
+    const closedBindings = new WeakMap();
+    const closedWatches = new WeakMap();
+    const app = acp.agent({ name: options.name ?? "Shiitake" });
+    let connectionLease;
+    function stateFor() {
+        const state = connectionLease?.state;
+        if (!state || !connectionLease?.accepting)
+            throw new Error("The ACP connection is not active");
+        return state;
+    }
+    /** Retain a binding, or release it when the connection closed meanwhile. */
+    async function retain(state, binding) {
+        if (state.closed) {
+            await closeOnce(closedBindings, binding);
+            throw new Error("The ACP connection closed");
+        }
+        state.sessions.set(binding.sessionId, binding);
+    }
+    async function closeConnection(state) {
+        if (state.closed)
+            return state.closed;
+        state.closed = (async () => {
+            const watchOutcomes = await Promise.all([...state.active.values()].map((turn) => detach(turn, closedWatches)));
+            const leaseOutcomes = await Promise.all([...state.sessions.values()].map((binding) => closeOnce(closedBindings, binding).then(() => ({ kind: "closed" }), (cause) => ({
+                kind: "failed",
+                error: asError(cause),
+            }))));
+            state.active.clear();
+            state.sessions.clear();
+            const failures = [...watchOutcomes, ...leaseOutcomes]
+                .filter((outcome) => outcome.kind === "failed")
+                .map((outcome) => outcome.error);
+            const firstFailure = failures[0];
+            if (failures.length === 1 && firstFailure !== undefined)
+                throw firstFailure;
+            if (firstFailure !== undefined) {
+                throw new AggregateError(failures, "ACP connection cleanup failed", {
+                    cause: firstFailure,
+                });
+            }
+        })();
+        return state.closed;
+    }
+    app.onConnect(async (connection) => {
+        const previous = connectionLease;
+        if (previous) {
+            if (!previous.cleanup) {
+                connection.close(new Error("This ACP AgentApp already has a connection"));
+                return;
+            }
+            previous.accepting = false;
+            await previous.cleanup;
+            if (connectionLease && connectionLease !== previous) {
+                connection.close(new Error("This ACP AgentApp already has a connection"));
+                return;
+            }
+        }
+        const state = {
+            sessions: new Map(),
+            active: new Map(),
+            closed: undefined,
+        };
+        const lease = {
+            state,
+            cleanup: undefined,
+            accepting: true,
+        };
+        connectionLease = lease;
+        let finished;
+        const finish = () => {
+            if (finished)
+                return finished;
+            lease.accepting = false;
+            finished = closeConnection(state).then(() => {
+                if (connectionLease === lease)
+                    connectionLease = undefined;
+            });
+            lease.cleanup = finished;
+            return finished;
+        };
+        connection.signal.addEventListener("abort", () => void finish(), {
+            once: true,
+        });
+        void connection.closed.then(finish);
+    });
+    app.onRequest(acp.methods.agent.initialize, (ctx) => {
+        const sessionCapabilities = { close: {} };
+        if (directory.list !== undefined)
+            sessionCapabilities.list = {};
+        return {
+            protocolVersion: acp.PROTOCOL_VERSION,
+            authMethods: options.terminalAuth !== undefined &&
+                ctx.params.clientCapabilities?.auth?.terminal === true
+                ? [{ ...options.terminalAuth, type: "terminal" }]
+                : [],
+            agentCapabilities: {
+                loadSession: true,
+                sessionCapabilities,
+                promptCapabilities: {
+                    image: true,
+                    audio: false,
+                    embeddedContext: true,
+                },
+            },
+        };
+    });
+    if (directory.list !== undefined) {
+        const list = directory.list;
+        app.onRequest(acp.methods.agent.session.list, (ctx) => {
+            const input = { signal: ctx.signal };
+            if (ctx.params.cwd != null)
+                input.cwd = ctx.params.cwd;
+            if (ctx.params.cursor != null)
+                input.cursor = ctx.params.cursor;
+            return list(input);
+        });
+    }
+    app.onRequest(acp.methods.agent.session.new, async (ctx) => {
+        const state = stateFor();
+        const binding = await directory.create({
+            cwd: ctx.params.cwd,
+            additionalDirectories: ctx.params.additionalDirectories ?? [],
+            mcpServers: ctx.params.mcpServers,
+            signal: ctx.signal,
+        });
+        assertSessionId(binding.sessionId);
+        if (state.sessions.has(binding.sessionId)) {
+            await closeOnce(closedBindings, binding);
+            throw new Error("The Session owner returned a duplicate Session identity");
+        }
+        await retain(state, binding);
+        return { sessionId: binding.sessionId };
+    });
+    app.onRequest(acp.methods.agent.session.load, async (ctx) => {
+        const state = stateFor();
+        const binding = await directory.load({
+            sessionId: ctx.params.sessionId,
+            cwd: ctx.params.cwd,
+            additionalDirectories: ctx.params.additionalDirectories ?? [],
+            mcpServers: ctx.params.mcpServers,
+            signal: ctx.signal,
+        });
+        assertSessionId(binding.sessionId);
+        if (binding.sessionId !== ctx.params.sessionId) {
+            await closeOnce(closedBindings, binding);
+            throw new Error("The Session owner returned a different Session identity");
+        }
+        const existing = state.sessions.get(binding.sessionId);
+        if (existing && state.active.has(binding.sessionId)) {
+            if (existing !== binding)
+                await closeOnce(closedBindings, binding);
+            throw new Error("This ACP Session has an active prompt");
+        }
+        try {
+            const snapshot = await binding.session.read();
+            if (snapshot.sessionId !== binding.sessionId)
+                throw new Error("The Session returned a different identity");
+            for (const message of snapshot.messages)
+                await projectMessage(ctx.client, binding.sessionId, message);
+        }
+        catch (error) {
+            await closeOnce(closedBindings, binding);
+            throw error;
+        }
+        if (existing && existing !== binding)
+            await closeOnce(closedBindings, existing);
+        await retain(state, binding);
+        return {};
+    });
+    app.onRequest(acp.methods.agent.session.prompt, async (ctx) => {
+        const state = stateFor();
+        const binding = state.sessions.get(ctx.params.sessionId);
+        if (!binding)
+            throw new Error("The requested Session is not authorized");
+        if (state.active.has(binding.sessionId))
+            throw new Error("This ACP Session already has an active prompt");
+        let finish;
+        const done = new Promise((resolve) => {
+            finish = resolve;
+        });
+        const turn = {
+            binding,
+            commandId: undefined,
+            cancelRequested: false,
+            detached: false,
+            watch: undefined,
+            done,
+            finish,
+        };
+        state.active.set(binding.sessionId, turn);
+        try {
+            const watch = await binding.session.watch();
+            turn.watch = watch;
+            // Disconnect may have detached the turn while its watch was opening.
+            // The finally block closes this late watch without admitting a prompt.
+            assertPromptAttached(turn, state);
+            if (watch.snapshot.sessionId !== binding.sessionId)
+                throw new Error("The Session returned a different identity");
+            // Do not use the ACP JSON-RPC ID as Shiitake's idempotency key. The host
+            // owns that correlation boundary; this call lets Shiitake generate it.
+            const input = promptInput(ctx.params.prompt);
+            const accepted = await binding.session.send(input.text, input.images.length === 0 ? undefined : { images: input.images });
+            turn.commandId = accepted.commandId;
+            if (turn.cancelRequested)
+                await binding.session.cancel({ commandId: accepted.commandId });
+            const projection = {
+                commandId: accepted.commandId,
+                streamed: new Map(),
+                projected: new Set(),
+            };
+            for await (const frame of watch.changes) {
+                const terminals = await projectFrame(ctx.client, binding.sessionId, frame, projection);
+                const terminal = terminals.find((candidate) => candidate.commandId === accepted.commandId);
+                if (terminal)
+                    return { stopReason: stopReason(terminal.outcome) };
+            }
+            if (turn.detached)
+                throw new Error("ACP observation detached before terminal settlement");
+            throw new Error("Session observation ended before terminal settlement");
+        }
+        finally {
+            if (state.active.get(binding.sessionId) === turn)
+                state.active.delete(binding.sessionId);
+            try {
+                if (turn.watch !== undefined)
+                    await closeWatchOnce(closedWatches, turn.watch);
+            }
+            finally {
+                turn.finish();
+            }
+        }
+    });
+    app.onRequest(acp.methods.agent.session.close, async (ctx) => {
+        const state = stateFor();
+        const binding = state.sessions.get(ctx.params.sessionId);
+        if (!binding)
+            throw new Error("The requested Session is not authorized");
+        const turn = state.active.get(binding.sessionId);
+        let watchClose = { kind: "closed" };
+        if (turn) {
+            turn.cancelRequested = true;
+            const { commandId } = turn;
+            const settled = await settlesWithin((async () => {
+                if (commandId !== undefined)
+                    await binding.session.cancel({ commandId });
+                await turn.done;
+            })(), closeSettleMs);
+            // The owner did not settle the cancel in time: stop observing so the
+            // close completes; the prompt request ends as detached.
+            if (!settled)
+                watchClose = await detach(turn, closedWatches);
+        }
+        state.sessions.delete(binding.sessionId);
+        const leaseClose = await closeOnce(closedBindings, binding).then(() => ({ kind: "closed" }), (cause) => ({ kind: "failed", error: asError(cause) }));
+        if (watchClose.kind === "failed") {
+            if (leaseClose.kind === "failed") {
+                throw new AggregateError([watchClose.error, leaseClose.error], "ACP watch and session lease cleanup failed", { cause: watchClose.error });
+            }
+            throw watchClose.error;
+        }
+        if (leaseClose.kind === "failed")
+            throw leaseClose.error;
+        return {};
+    });
+    app.onNotification(acp.methods.agent.session.cancel, async (ctx) => {
+        const state = stateFor();
+        const binding = state.sessions.get(ctx.params.sessionId);
+        if (!binding)
+            return;
+        const turn = state.active.get(binding.sessionId);
+        if (!turn)
+            return;
+        turn.cancelRequested = true;
+        if (turn.commandId !== undefined)
+            await binding.session.cancel({ commandId: turn.commandId });
+    });
+    return app;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./adapter.js";
+export * from "./session-directory.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from "./adapter.js";
+export * from "./session-directory.js";

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import { type AuthorizedShiitakeSessionDirectory } from "./adapter.js";
+/** Streamable HTTP adapter and its connection cleanup owner. */
+export type ShiitakeAcpServer = Readonly<{
+    /** Handle one ACP HTTP request using the supplied authorized directory. */
+    handleRequest(request: Request): Promise<Response>;
+    /** Close the server and release its connection leases. */
+    close(): Promise<void>;
+}>;
+/**
+ * Host stable ACP over the maintained Streamable HTTP transport.
+ *
+ * Each accepted connection gets its own ACP adapter state. The supplied
+ * directory remains the authorization boundary and Shiitake remains the
+ * Session/transcript owner.
+ */
+export declare function createShiitakeAcpServer(directory: AuthorizedShiitakeSessionDirectory): ShiitakeAcpServer;

package/dist/server.js

@@ -0,0 +1,18 @@
+import { AcpServer } from "@agentclientprotocol/sdk/experimental/server";
+import { createShiitakeAcpAgent, } from "./adapter.js";
+/**
+ * Host stable ACP over the maintained Streamable HTTP transport.
+ *
+ * Each accepted connection gets its own ACP adapter state. The supplied
+ * directory remains the authorization boundary and Shiitake remains the
+ * Session/transcript owner.
+ */
+export function createShiitakeAcpServer(directory) {
+    const server = new AcpServer({
+        createAgent: () => createShiitakeAcpAgent({ directory }),
+    });
+    return {
+        handleRequest: (request) => server.handleRequest(request),
+        close: () => server.close(),
+    };
+}

package/dist/session-directory.d.ts

@@ -0,0 +1,27 @@
+import type { McpServer } from "@agentclientprotocol/sdk";
+import type { ShiitakeAgent } from "@fungi.computer/shiitake/client";
+import type { AuthorizedShiitakeSessionDirectory } from "./adapter.js";
+/** Host-authorized Agent client and the release action for its lease. */
+export type ShiitakeClientLease = Readonly<{
+    /** Authorized Agent client used to create and load Sessions. */
+    client: ShiitakeAgent;
+    /** Release the host authorization lease without deleting Sessions. */
+    close: () => Promise<void>;
+}>;
+/** Client leasing and context validation supplied by the host. */
+export type ShiitakeSessionDirectoryOptions = Readonly<{
+    /** Acquire a fresh authorized client lease for each create or load. */
+    openClient: () => Promise<ShiitakeClientLease>;
+    /** Reject context outside the host's allowed directories or MCP servers. */
+    validateContext?: (input: {
+        cwd: string;
+        additionalDirectories: readonly string[];
+        mcpServers: readonly McpServer[];
+    }) => void;
+}>;
+/**
+ * Adapt one host-authorized Shiitake client factory to ACP Session ownership.
+ * Every create/load gets its own client lease; closing ACP releases that lease
+ * without deleting the durable Session.
+ */
+export declare function createAuthorizedShiitakeSessionDirectory(options: ShiitakeSessionDirectoryOptions): AuthorizedShiitakeSessionDirectory;

package/dist/session-directory.js

@@ -0,0 +1,74 @@
+import { defineIdFamily } from "@fungi.computer/cairn/id";
+const createRequests = defineIdFamily({
+    family: "acp-session-create-request",
+    version: 1,
+    kinds: { request: { prefix: "request" } },
+});
+function abortError() {
+    return new DOMException("The ACP Session operation was cancelled", "AbortError");
+}
+async function abortable(task, signal) {
+    if (signal.aborted)
+        throw abortError();
+    let onAbort;
+    const cancelled = new Promise((_, reject) => {
+        onAbort = () => {
+            reject(abortError());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+    return Promise.race([task, cancelled]).finally(() => {
+        if (onAbort)
+            signal.removeEventListener("abort", onAbort);
+    });
+}
+function binding(lease, sessionId) {
+    return {
+        session: lease.client.session(sessionId),
+        sessionId,
+        close: lease.close,
+    };
+}
+/**
+ * Adapt one host-authorized Shiitake client factory to ACP Session ownership.
+ * Every create/load gets its own client lease; closing ACP releases that lease
+ * without deleting the durable Session.
+ */
+export function createAuthorizedShiitakeSessionDirectory(options) {
+    const validate = (input) => options.validateContext?.(input);
+    return {
+        async create(input) {
+            validate(input);
+            const lease = await options.openClient();
+            try {
+                if (input.signal.aborted)
+                    throw abortError();
+                // ACP create requests carry no stable retry identity of their own.
+                const requestId = createRequests.request.generate();
+                const sessionId = await abortable(lease.client.createSession(requestId), input.signal);
+                return binding(lease, sessionId);
+            }
+            catch (error) {
+                await lease.close();
+                throw error;
+            }
+        },
+        async load(input) {
+            validate(input);
+            const lease = await options.openClient();
+            try {
+                if (input.signal.aborted)
+                    throw abortError();
+                const session = lease.client.session(input.sessionId);
+                const snapshot = await abortable(session.read(), input.signal);
+                if (snapshot.sessionId !== input.sessionId)
+                    throw new Error("The Agent returned a different Session identity");
+                return { session, sessionId: input.sessionId, close: lease.close };
+            }
+            catch (error) {
+                await lease.close();
+                throw error;
+            }
+        },
+    };
+}

package/docs/api/README.md

@@ -0,0 +1,27 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+**@fungi.computer/graft**
+
+---
+
+# Graft API overview
+
+| Import                         | Export                                     | Purpose                                                                       |
+| ------------------------------ | ------------------------------------------ | ----------------------------------------------------------------------------- |
+| `@fungi.computer/graft`        | `createShiitakeAcpAgent`                   | Project an authorized Shiitake Session through ACP.                           |
+| `@fungi.computer/graft`        | `createAuthorizedShiitakeSessionDirectory` | Adapt a host-authorized client lease factory to Session creation and loading. |
+| `@fungi.computer/graft`        | `AuthorizedShiitakeSessionDirectory`       | Let the host authorize Session creation and loading.                          |
+| `@fungi.computer/graft`        | `agentAcpMethods`                          | Expose the maintained ACP agent methods.                                      |
+| `@fungi.computer/graft/server` | `createShiitakeAcpServer`                  | Serve the same adapter through Streamable HTTP.                               |
+
+The host supplies authorization. Shiitake owns Session state and the durable
+transcript. Close connections to release their client leases and observations;
+closing a lease does not delete the Session. The generated module pages below
+include the option, lease and server types.
+
+## Modules
+
+| Module              | Description |
+| ------------------- | ----------- |
+| [index](index.md)   | -           |
+| [server](server.md) | -           |

package/docs/api/index.md

@@ -0,0 +1,136 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/graft**](README.md)
+
+---
+
+[@fungi.computer/graft](README.md) / index
+
+# index
+
+## Type Aliases
+
+### AuthorizedShiitakeSession
+
+```ts
+type AuthorizedShiitakeSession = Readonly<{
+  session: ShiitakeSession;
+  sessionId: string;
+  close: () => Promise<void>;
+}>;
+```
+
+A Session returned by the host's authorization boundary.
+
+---
+
+### AuthorizedShiitakeSessionDirectory
+
+```ts
+type AuthorizedShiitakeSessionDirectory = Readonly<{
+  create: (input) => Promise<AuthorizedShiitakeSession>;
+  list?: (input) => Promise<acp.ListSessionsResponse>;
+  load: (input) => Promise<AuthorizedShiitakeSession>;
+}>;
+```
+
+Directory owner used by ACP lifecycle callbacks.
+
+---
+
+### ShiitakeAcpAdapterOptions
+
+```ts
+type ShiitakeAcpAdapterOptions = Readonly<{
+  directory: AuthorizedShiitakeSessionDirectory;
+  name?: string;
+  terminalAuth?: acp.AuthMethodTerminal;
+  closeSettleMs?: number;
+}>;
+```
+
+Host directory, agent identity and lifecycle options for an ACP adapter.
+
+---
+
+### ShiitakeClientLease
+
+```ts
+type ShiitakeClientLease = Readonly<{
+  client: ShiitakeAgent;
+  close: () => Promise<void>;
+}>;
+```
+
+Host-authorized Agent client and the release action for its lease.
+
+---
+
+### ShiitakeSessionDirectoryOptions
+
+```ts
+type ShiitakeSessionDirectoryOptions = Readonly<{
+  openClient: () => Promise<ShiitakeClientLease>;
+  validateContext?: (input) => void;
+}>;
+```
+
+Client leasing and context validation supplied by the host.
+
+## Variables
+
+### agentAcpMethods
+
+```ts
+const agentAcpMethods: object = acp.methods.agent;
+```
+
+Maintained ACP method descriptors advertised by this agent adapter.
+
+## Functions
+
+### createShiitakeAcpAgent()
+
+```ts
+function createShiitakeAcpAgent(options): AgentApp;
+```
+
+Projects ACP stable v1 onto Sessions from one host-authorized directory.
+
+The host directory owns Session creation/loading and authorization. ACP request
+IDs are retained for correlation while Shiitake generates its own idempotency
+key and returns its own accepted command ID.
+
+#### Parameters
+
+| Parameter | Type                                                      |
+| --------- | --------------------------------------------------------- |
+| `options` | [`ShiitakeAcpAdapterOptions`](#shiitakeacpadapteroptions) |
+
+#### Returns
+
+`AgentApp`
+
+---
+
+### createAuthorizedShiitakeSessionDirectory()
+
+```ts
+function createAuthorizedShiitakeSessionDirectory(
+  options,
+): AuthorizedShiitakeSessionDirectory;
+```
+
+Adapt one host-authorized Shiitake client factory to ACP Session ownership.
+Every create/load gets its own client lease; closing ACP releases that lease
+without deleting the durable Session.
+
+#### Parameters
+
+| Parameter | Type                                                                  |
+| --------- | --------------------------------------------------------------------- |
+| `options` | [`ShiitakeSessionDirectoryOptions`](#shiitakesessiondirectoryoptions) |
+
+#### Returns
+
+[`AuthorizedShiitakeSessionDirectory`](#authorizedshiitakesessiondirectory)

package/docs/api/server.md

@@ -0,0 +1,46 @@
+<!-- Generated by Botanical API docs (TypeDoc + typedoc-plugin-markdown). Do not edit. -->
+
+[**@fungi.computer/graft**](README.md)
+
+---
+
+[@fungi.computer/graft](README.md) / server
+
+# server
+
+## Type Aliases
+
+### ShiitakeAcpServer
+
+```ts
+type ShiitakeAcpServer = Readonly<{
+  handleRequest: Promise<Response>;
+  close: Promise<void>;
+}>;
+```
+
+Streamable HTTP adapter and its connection cleanup owner.
+
+## Functions
+
+### createShiitakeAcpServer()
+
+```ts
+function createShiitakeAcpServer(directory): ShiitakeAcpServer;
+```
+
+Host stable ACP over the maintained Streamable HTTP transport.
+
+Each accepted connection gets its own ACP adapter state. The supplied directory
+remains the authorization boundary and Shiitake remains the Session/transcript
+owner.
+
+#### Parameters
+
+| Parameter   | Type                                                                                |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `directory` | [`AuthorizedShiitakeSessionDirectory`](index.md#authorizedshiitakesessiondirectory) |
+
+#### Returns
+
+[`ShiitakeAcpServer`](#shiitakeacpserver)

package/package.json

@@ -1,6 +1,68 @@
 {
   "name": "@fungi.computer/graft",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "ACP v1 projection for an authorized Shiitake Session",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/api",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.7.0",
+    "@fungi.computer/cairn": "0.0.1",
+    "@fungi.computer/mule": "0.0.2",
+    "@fungi.computer/shiitake": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "botanical": {
+    "role": "package",
+    "operations": {
+      "lint": "required",
+      "typecheck": "required",
+      "build": "required",
+      "test": "required",
+      "docs": "required",
+      "pack": "required",
+      "smoke": "required",
+      "stranger": "required"
+    }
+  },
+  "license": "MIT",
+  "author": "Levi <levi@technomancy.dev>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fungi-computer/graft.git"
+  },
+  "scripts": {
+    "lint": "eslint src test --max-warnings=0 && ../../node_modules/.bin/oxlint --config ../../oxlint.config.ts --deny-warnings src test",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "build": "pnpm run clean && tsc -p tsconfig.build.json",
+    "clean": "node --input-type=module --eval \"import { rm } from 'node:fs/promises'; await rm('dist', { recursive: true, force: true });\"",
+    "test": "vitest run",
+    "format:check": "node ../../tooling/repository/scripts/format-package-check.mjs",
+    "lint:anti-slop": "node ../../tooling/repository/scripts/lint-package-anti-slop.mjs",
+    "docs": "tsx ../../tooling/repository/src/docs/cli.ts check --root ../..",
+    "docs:write": "tsx ../../tooling/repository/src/docs/cli.ts write --root ../..",
+    "pack": "mkdir -p ../../.botanical/graft-pack && pnpm pack --pack-destination ../../.botanical/graft-pack",
+    "smoke": "node test/stranger/runtime.mjs",
+    "stranger": "tsx ../../tooling/repository/src/artifacts/cli.ts --repo-root ../.. ."
+  }
 }