@executablemd/acp 0.0.0-bootstrap.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taras Mankovski
+
+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/esm/mod.js

@@ -0,0 +1,14 @@
+/**
+ * @module
+ * ACPX agent provider for Executable.md (specs/acp-client-spec.md).
+ *
+ * `createAcpxProvider()` returns an `AgentProviderFactory` that drives
+ * coding agents over the Agent Client Protocol through the pinned `acpx`
+ * runtime. Supply it directly to core's agent vocabulary through the
+ * `rootProvider` option:
+ * `installAgentVocabulary({ rootProvider: { factory: createAcpxProvider(), options } })`.
+ */
+export { createAcpxProvider, useAcpxProviderState } from "./src/provider.js";
+export { useSerialQueues } from "./src/serial-queue.js";
+/** The agent ACPX selects when nothing else is configured. */
+export { DEFAULT_AGENT_NAME } from "acpx/runtime";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/src/events.js

@@ -0,0 +1,62 @@
+/**
+ * Turn event normalization (specs/acp-client-spec.md §Prompt).
+ *
+ * `consumeTurn` receives an already-started ACPX turn and the resolved
+ * identity, and produces the normalized public event sequence: exactly
+ * one `started`, then `text_delta` events for output-stream deltas only,
+ * then exactly one `terminal`, then the channel closes with the complete
+ * concatenated text — including partial text on failure. Thought,
+ * status, tool, usage, and raw ACP events stay private.
+ */
+import { each, stream, until } from "effection";
+export function* consumeTurn(turn, identity, channel, markCompleted) {
+    yield* channel.send({ type: "started", agent: identity.agent, session: identity.session });
+    let text = "";
+    let terminal;
+    try {
+        for (const event of yield* each(stream(turn.events))) {
+            if (event.type === "text_delta" && (event.stream ?? "output") === "output") {
+                text += event.text;
+                yield* channel.send({ type: "text_delta", text: event.text });
+            }
+            yield* each.next();
+        }
+        terminal = mapResult(yield* until(turn.result));
+    }
+    catch (error) {
+        terminal = {
+            type: "terminal",
+            status: "failed",
+            error: error instanceof Error ? error : new Error(String(error)),
+        };
+    }
+    yield* channel.send(terminal);
+    markCompleted();
+    yield* channel.close(text);
+}
+function mapResult(result) {
+    if (result.status === "completed") {
+        // ACP defines end_turn as the only successful stop reason. An absent
+        // stop reason on a completed turn is treated as end_turn — some
+        // adapters omit it on normal completion.
+        const stopReason = result.stopReason ?? "end_turn";
+        if (stopReason === "end_turn") {
+            return { type: "terminal", status: "completed", stopReason };
+        }
+        return {
+            type: "terminal",
+            status: "failed",
+            stopReason,
+            error: new Error(`agent prompt failed with stop reason "${stopReason}"`),
+        };
+    }
+    if (result.status === "cancelled") {
+        const terminal = { type: "terminal", status: "cancelled" };
+        if (result.stopReason !== undefined) {
+            terminal.stopReason = result.stopReason;
+        }
+        return terminal;
+    }
+    const failure = new Error(result.error.message);
+    return { type: "terminal", status: "failed", error: failure };
+}

package/esm/src/permission-bridge.js

@@ -0,0 +1,195 @@
+/**
+ * Permission bridge (specs/acp-client-spec.md §Permissions).
+ *
+ * ## Routing
+ *
+ * ACPX delivers a permission request to `onPermissionRequest` keyed by
+ * `params.sessionId` — the ACP session id (`acpSessionId`) of the
+ * prompting turn. Each active turn registers its subscribing scope, an
+ * initial id, and a `refresh` operation that reloads its ACPX record by
+ * `acpxRecordId`. The id map is a cache: before routing, the bridge
+ * refreshes and verifies a direct candidate; on a miss it refreshes all
+ * active registrations and routes only when exactly one matches the
+ * request id. This tracks ACPX's reconnect fallback, which updates
+ * `record.acpSessionId` and checkpoints the record before running the
+ * prompt. The public `Session.agentSessionId` is updated from the
+ * refreshed record.
+ *
+ * ## Fail closed
+ *
+ * The decision resolves `{ outcome: "cancel" }` — never `undefined`
+ * (which would let ACPX fall back to its mode resolver) and never
+ * another scope — on: store errors during refresh, zero or multiple
+ * matching registrations, a stale or torn-down prompt scope, a policy
+ * error, an unknown selected option id, and an abort (before or during
+ * evaluation).
+ */
+import { on, race } from "effection";
+import { Agent } from "@executablemd/core";
+const CANCEL = { outcome: "cancel" };
+export function createPermissionBridge() {
+    const turns = new Map();
+    function rekey(entry, newId) {
+        // A deferred refresh must not resurrect an unregistered entry.
+        if (!entry.active || newId === entry.currentId) {
+            return;
+        }
+        if (turns.get(entry.currentId) === entry) {
+            turns.delete(entry.currentId);
+        }
+        entry.currentId = newId;
+        turns.set(newId, entry);
+    }
+    // Reload one registration's record, apply the current agent session id
+    // to the public Session, rekey on a changed ACP session id, and return
+    // that ACP session id. `undefined` means "does not currently match"
+    // (missing record) — a thrown store error propagates to fail closed.
+    function* refreshEntry(entry) {
+        const record = yield* entry.refresh();
+        if (!record) {
+            return undefined;
+        }
+        if (typeof record.agentSessionId === "string") {
+            entry.session.agentSessionId = record.agentSessionId;
+        }
+        if (typeof record.acpSessionId === "string") {
+            rekey(entry, record.acpSessionId);
+            return record.acpSessionId;
+        }
+        return entry.currentId;
+    }
+    function* resolveTarget(sessionId) {
+        const direct = turns.get(sessionId);
+        if (direct && direct.active) {
+            const refreshed = yield* refreshEntry(direct);
+            if (refreshed === sessionId) {
+                return direct;
+            }
+        }
+        const matches = [];
+        for (const entry of new Set(turns.values())) {
+            if (!entry.active) {
+                continue;
+            }
+            const refreshed = yield* refreshEntry(entry);
+            if (refreshed === sessionId) {
+                matches.push(entry);
+            }
+        }
+        return matches.length === 1 ? matches[0] : undefined;
+    }
+    return {
+        register(acpSessionId, scope, session, refresh) {
+            const entry = {
+                scope,
+                session,
+                refresh,
+                currentId: acpSessionId,
+                active: true,
+            };
+            turns.set(acpSessionId, entry);
+            return {
+                unregister() {
+                    entry.active = false;
+                    if (turns.get(entry.currentId) === entry) {
+                        turns.delete(entry.currentId);
+                    }
+                },
+            };
+        },
+        *decision(request, signal) {
+            // Subscribe to abort BEFORE any policy work and recheck, so a
+            // synchronous abort during evaluation is never lost.
+            const aborts = yield* on(signal, "abort");
+            if (signal.aborted) {
+                return CANCEL;
+            }
+            let target;
+            try {
+                target = yield* resolveTarget(request.sessionId);
+            }
+            catch {
+                // Store errors during refresh fail closed.
+                return CANCEL;
+            }
+            if (!target) {
+                return CANCEL;
+            }
+            const registered = target;
+            try {
+                // Policy errors are contained INSIDE the task: an unhandled
+                // task failure would propagate into the prompt scope itself.
+                // Halts are unaffected — try/catch does not intercept them.
+                const task = registered.scope.run(function* () {
+                    try {
+                        const permissionRequest = toPermissionRequest(request, registered.session);
+                        const outcome = yield* Agent.operations.requestPermission(permissionRequest);
+                        return toDecision(outcome, permissionRequest.options);
+                    }
+                    catch {
+                        return CANCEL;
+                    }
+                });
+                return yield* race([
+                    task,
+                    (function* () {
+                        yield* aborts.next();
+                        yield* task.halt();
+                        return CANCEL;
+                    })(),
+                ]);
+            }
+            catch {
+                // Torn-down prompt scopes cancel — never fall through to
+                // another policy or ACPX's mode resolver.
+                return CANCEL;
+            }
+        },
+    };
+}
+const OPTION_KINDS = ["allow_once", "allow_always", "reject_once", "reject_always"];
+function parseOptionKind(value) {
+    if (value === "allow_once" || value === "allow_always") {
+        return value;
+    }
+    if (value === "reject_once" || value === "reject_always") {
+        return value;
+    }
+    return undefined;
+}
+function toPermissionRequest(request, session) {
+    const raw = request.raw;
+    const options = [];
+    for (const option of raw.options) {
+        // ACP's PermissionOptionKind is an open union; options whose kind is
+        // outside the stable Executable.md shape are not offered.
+        const kind = parseOptionKind(option.kind);
+        if (kind) {
+            options.push({ optionId: String(option.optionId), name: option.name, kind });
+        }
+    }
+    const toolCall = {
+        toolCallId: String(raw.toolCall.toolCallId),
+    };
+    if (typeof raw.toolCall.title === "string") {
+        toolCall.title = raw.toolCall.title;
+    }
+    const kind = raw.toolCall.kind ?? request.inferredKind;
+    if (typeof kind === "string") {
+        toolCall.kind = kind;
+    }
+    if (raw.toolCall.rawInput !== undefined) {
+        toolCall.rawInput = raw.toolCall.rawInput;
+    }
+    return { session, toolCall, options };
+}
+function toDecision(outcome, options) {
+    if (outcome.outcome === "cancelled") {
+        return CANCEL;
+    }
+    const selected = options.find((option) => option.optionId === outcome.optionId);
+    if (!selected || !OPTION_KINDS.includes(selected.kind)) {
+        return CANCEL;
+    }
+    return { outcome: selected.kind };
+}

package/esm/src/provider.js

@@ -0,0 +1,271 @@
+/**
+ * ACPX agent provider (specs/acp-client-spec.md §ACPX provider).
+ *
+ * The factory owns every resource it starts. The shared runtime is
+ * created lazily on first use with the contextual cwd and validated
+ * contextual timeout — nothing spawns at install time. Availability
+ * validation uses a disposable probe runtime per agent: ACPX 0.12.0's
+ * `probeAvailability()` only updates internal health, so `doctor()` is
+ * used and `report.ok` inspected explicitly; ACPX closes the probe
+ * client internally on both success and failure.
+ *
+ * Prompt subscriptions follow a fixed sequence — resolve identity,
+ * acquire the session's FIFO lock, register permission routing, resolve
+ * the effective timeout, start the turn — registering unconditional
+ * cleanup for each resource as soon as it is acquired, and conditional
+ * cancellation only once the turn exists. Provider teardown attempts
+ * every remaining cancellation and every distinct handle close with an
+ * all-settled strategy and throws the recorded failures from the
+ * provider scope.
+ */
+import { createChannel, ensure, spawn, until, useScope } from "effection";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { Agent, timeout as contextualTimeout } from "@executablemd/core";
+import { createAcpRuntime, createAgentRegistry, createRuntimeStore } from "acpx/runtime";
+import { createPermissionBridge } from "./permission-bridge.js";
+import { consumeTurn } from "./events.js";
+import { resolveSessionPlacement } from "./session-key.js";
+import { useSerialQueues } from "./serial-queue.js";
+import { cwd } from "@executablemd/runtime";
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}
+export function createAcpxProvider(seams) {
+    return function* (providerOptions) {
+        const state = yield* useAcpxProviderState(providerOptions, seams);
+        yield* Agent.around({
+            *agent([name], _next) {
+                return yield* state.agent(name);
+            },
+            *session([name], _next) {
+                return yield* state.session(name);
+            },
+            *prompt([content, options], _next) {
+                return state.promptStream(content, options);
+            },
+        }, { at: "min" });
+    };
+}
+export function* useAcpxProviderState(providerOptions, seams) {
+    const createRuntime = seams?.createRuntime ?? createAcpRuntime;
+    const store = seams?.sessionStore ?? createRuntimeStore({ stateDir: join(homedir(), ".acpx") });
+    const registry = seams?.agentRegistry ?? createAgentRegistry();
+    const sessionRouting = seams?.sessionRouting ?? ((_c, op) => op());
+    const bridge = createPermissionBridge();
+    const stateScope = yield* useScope();
+    const turns = yield* useSerialQueues();
+    let runtime;
+    const validatedAgents = new Set();
+    const managed = new Map();
+    const activeTurns = new Set();
+    const cleanupErrors = [];
+    function* runtimeOptions() {
+        const dir = yield* cwd();
+        const timeoutMs = yield* contextualTimeout;
+        return {
+            cwd: dir,
+            sessionStore: store,
+            agentRegistry: registry,
+            permissionMode: providerOptions.permissionMode,
+            nonInteractivePermissions: "deny",
+            timeoutMs,
+        };
+    }
+    function* getRuntime() {
+        if (!runtime) {
+            const base = yield* runtimeOptions();
+            runtime = createRuntime({
+                ...base,
+                // The acpx callback boundary: `scope.run` returns a Promise-compatible
+                // Future over the operation-based bridge decision.
+                onPermissionRequest: (request, ctx) => stateScope.run(() => bridge.decision(request, ctx.signal)),
+            });
+        }
+        return runtime;
+    }
+    function* resolveAgent(name) {
+        const selected = name ?? providerOptions.defaultAgent;
+        if (!validatedAgents.has(selected)) {
+            const base = yield* runtimeOptions();
+            const probe = createRuntime({ ...base, probeAgent: selected });
+            const report = yield* until(probe.doctor());
+            if (!report.ok) {
+                const code = report.code ? ` [${report.code}]` : "";
+                const details = report.details?.length ? ` (${report.details.join("; ")})` : "";
+                throw new Error(`agent "${selected}" is unavailable${code}: ${report.message}${details}`);
+            }
+            validatedAgents.add(selected);
+        }
+        return selected;
+    }
+    // Read-only session resolution. For a Session value it validates the
+    // existing managed entry; otherwise it derives the placement (the
+    // nearest-existing session), so the RESOLVED sessionKey — not the
+    // caller cwd — becomes the session-queue key.
+    function* prepare(agentName, option, callerCwd) {
+        if (typeof option === "object") {
+            const entry = managed.get(option.sessionKey);
+            if (!entry) {
+                throw new Error(`unknown or stale agent session "${option.sessionKey}" — a Session value must ` +
+                    `come from this provider's session()`);
+            }
+            const agentCommand = registry.resolve(agentName);
+            if (agentCommand !== entry.agentCommand) {
+                throw new Error(`agent "${agentName}" (${agentCommand}) does not match session ` +
+                    `"${option.sessionKey}" (${entry.agentCommand})`);
+            }
+            return { kind: "existing", sessionKey: option.sessionKey, entry };
+        }
+        const agentCommand = registry.resolve(agentName);
+        const placement = yield* resolveSessionPlacement(store, agentCommand, callerCwd, option);
+        return { kind: "placement", sessionKey: placement.sessionKey, agentCommand, placement };
+    }
+    function* ensureFromPrepared(agentName, prepared) {
+        if (prepared.kind === "existing") {
+            return prepared.entry;
+        }
+        const acp = yield* getRuntime();
+        const handle = yield* until(acp.ensureSession({
+            sessionKey: prepared.placement.sessionKey,
+            agent: agentName,
+            mode: "persistent",
+            cwd: prepared.placement.cwd,
+        }));
+        const session = {
+            sessionKey: prepared.placement.sessionKey,
+            cwd: prepared.placement.cwd,
+        };
+        if (handle.agentSessionId !== undefined) {
+            session.agentSessionId = handle.agentSessionId;
+        }
+        const entry = {
+            handle,
+            agentCommand: prepared.agentCommand,
+            cwd: prepared.placement.cwd,
+            session,
+        };
+        managed.set(prepared.sessionKey, entry);
+        return entry;
+    }
+    function promptStream(content, options) {
+        return {
+            *[Symbol.iterator]() {
+                const agentName = yield* Agent.operations.agent(options?.agent);
+                const callerCwd = resolve(yield* cwd());
+                const context = {
+                    agentName,
+                    session: options?.session,
+                    cwd: callerCwd,
+                };
+                const prepared = yield* sessionRouting(context, () => prepare(agentName, options?.session, callerCwd));
+                yield* turns.slot(prepared.sessionKey);
+                return yield* sessionRouting(context, function* () {
+                    const entry = yield* ensureFromPrepared(agentName, prepared);
+                    const scope = yield* useScope();
+                    const recordKey = entry.handle.acpxRecordId ?? entry.session.sessionKey;
+                    // Route by the record's ACP session id, refreshed on demand so
+                    // a reconnect that updates the record mid-turn (ACPX
+                    // checkpoints it before the prompt runs) still routes to this
+                    // scope's policy.
+                    const refresh = () => (function* () {
+                        const record = yield* until(store.load(recordKey));
+                        if (!record) {
+                            return undefined;
+                        }
+                        return { acpSessionId: record.acpSessionId, agentSessionId: record.agentSessionId };
+                    })();
+                    const initial = yield* refresh();
+                    if (initial?.agentSessionId !== undefined) {
+                        entry.session.agentSessionId = initial.agentSessionId;
+                    }
+                    const activeSessionId = initial?.acpSessionId ?? entry.handle.backendSessionId;
+                    if (activeSessionId !== undefined) {
+                        const registration = bridge.register(activeSessionId, scope, entry.session, refresh);
+                        yield* ensure(() => {
+                            registration.unregister();
+                        });
+                    }
+                    const timeoutMs = options?.timeout ?? (yield* contextualTimeout);
+                    const acp = yield* getRuntime();
+                    const turn = acp.startTurn({
+                        handle: entry.handle,
+                        text: content,
+                        mode: "prompt",
+                        requestId: randomUUID(),
+                        timeoutMs,
+                    });
+                    activeTurns.add(turn);
+                    let completed = false;
+                    yield* ensure(function* () {
+                        activeTurns.delete(turn);
+                        if (!completed) {
+                            try {
+                                yield* until(turn.cancel());
+                            }
+                            catch (error) {
+                                cleanupErrors.push(toError(error));
+                            }
+                        }
+                    });
+                    const channel = createChannel();
+                    const subscription = yield* channel;
+                    yield* spawn(() => consumeTurn(turn, { agent: agentName, session: entry.session }, channel, () => {
+                        completed = true;
+                    }));
+                    return subscription;
+                });
+            },
+        };
+    }
+    yield* ensure(function* () {
+        for (const turn of [...activeTurns]) {
+            activeTurns.delete(turn);
+            try {
+                yield* until(turn.cancel());
+            }
+            catch (error) {
+                cleanupErrors.push(toError(error));
+            }
+        }
+        if (runtime) {
+            const closedHandles = new Set();
+            for (const entry of managed.values()) {
+                const handleKey = entry.handle.acpxRecordId ?? entry.handle.sessionKey;
+                if (closedHandles.has(handleKey)) {
+                    continue;
+                }
+                closedHandles.add(handleKey);
+                try {
+                    yield* until(runtime.close({ handle: entry.handle, reason: "scope teardown" }));
+                }
+                catch (error) {
+                    cleanupErrors.push(toError(error));
+                }
+            }
+        }
+        if (cleanupErrors.length === 1) {
+            throw cleanupErrors[0];
+        }
+        if (cleanupErrors.length > 1) {
+            throw new AggregateError(cleanupErrors, "agent provider teardown failed");
+        }
+    });
+    return {
+        *agent(name) {
+            return yield* resolveAgent(name);
+        },
+        *session(option) {
+            const agentName = yield* Agent.operations.agent();
+            const callerCwd = resolve(yield* cwd());
+            const context = { agentName, session: option, cwd: callerCwd };
+            const prepared = yield* sessionRouting(context, () => prepare(agentName, option, callerCwd));
+            return yield* turns.withSlot(prepared.sessionKey, () => sessionRouting(context, function* () {
+                const entry = yield* ensureFromPrepared(agentName, prepared);
+                return entry.session;
+            }));
+        },
+        promptStream,
+    };
+}

package/esm/src/serial-queue.js

@@ -0,0 +1,72 @@
+/**
+ * Keyed serial queues: each key gets one spawned drain loop that
+ * grants slots strictly in arrival order and waits for the holder to
+ * finish before granting the next. A slot is a resource — it releases
+ * when the acquiring scope exits, on normal, failure, and halt paths
+ * alike, including a request halted while it is still queued.
+ */
+import { createChannel, resource, useScope, withResolvers } from "effection";
+export function* useSerialQueues() {
+    const owner = yield* useScope();
+    const queues = new Map();
+    function* queueFor(key) {
+        const existing = queues.get(key);
+        if (existing) {
+            return existing;
+        }
+        const channel = createChannel();
+        // The subscription must belong to the loop task itself — created in
+        // a slot holder's scope it would die with that holder. The ready
+        // gate keeps sends from racing the subscribe, and the queue is
+        // registered before any suspension so concurrent first callers
+        // never create duplicate loops.
+        const ready = withResolvers();
+        const queue = { channel, ready: ready.operation };
+        queues.set(key, queue);
+        yield* owner.spawn(function* () {
+            const subscription = yield* channel;
+            ready.resolve();
+            while (true) {
+                const next = yield* subscription.next();
+                if (next.done) {
+                    break;
+                }
+                next.value.grant();
+                yield* next.value.done;
+            }
+        });
+        return queue;
+    }
+    return {
+        slot(key) {
+            return resource(function* (provide) {
+                const queue = yield* queueFor(key);
+                yield* queue.ready;
+                const granted = withResolvers();
+                const done = withResolvers();
+                try {
+                    yield* queue.channel.send({ grant: granted.resolve, done: done.operation });
+                    yield* granted.operation;
+                    yield* provide();
+                }
+                finally {
+                    done.resolve();
+                }
+            });
+        },
+        *withSlot(key, op) {
+            const queue = yield* queueFor(key);
+            yield* queue.ready;
+            const granted = withResolvers();
+            const done = withResolvers();
+            try {
+                yield* queue.channel.send({ grant: granted.resolve, done: done.operation });
+                yield* granted.operation;
+                return yield* op();
+            }
+            finally {
+                done.resolve();
+            }
+        },
+    };
+}

package/esm/src/session-key.js

@@ -0,0 +1,81 @@
+/**
+ * Session identity (specs/acp-client-spec.md §Session).
+ *
+ * Keys are namespaced `xmd:v1:` so they can never collide with sessions
+ * owned by other ACPX consumers (ACPX's only key convention is an
+ * optional `agent:<name>:` prefix, which this scheme avoids). Every
+ * variable-length identity component — the agent command, the directory
+ * and an explicit session name — is digested, so a key stays bounded and
+ * filesystem-safe however long its inputs are. A session store may use
+ * the key as a file name and encode it again, which an undigested
+ * component overruns.
+ *
+ * Session resolution walks candidates from the contextual cwd toward the
+ * Git repository root and reuses the nearest candidate whose record
+ * already exists — checked through the ACPX session store, never through
+ * `ensureSession()`, which would create one. ACPX only reuses a record
+ * when the cwd matches, so the matched candidate's directory (not the
+ * caller cwd) becomes the session cwd. When nothing exists yet, the
+ * session is created for the exact contextual cwd.
+ */
+import { until } from "effection";
+import { createHash } from "node:crypto";
+import { dirname, join, resolve } from "node:path";
+import { stat } from "@executablemd/runtime";
+function digest(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+export function deriveSessionKey(agentCommand, dir, name) {
+    // The unnamed session keeps a literal marker so it stays recognisable
+    // and distinct from any given name.
+    return [
+        "xmd",
+        "v1",
+        digest(agentCommand),
+        digest(resolve(dir)),
+        name === undefined ? "default" : digest(name),
+    ].join(":");
+}
+/**
+ * One candidate per directory from the contextual cwd up to the Git
+ * repository root, nearest first. `.git` may be a directory or a file
+ * (worktrees). Outside a repository the exact cwd is the only candidate.
+ */
+export function* sessionCandidates(agentCommand, cwdPath, name) {
+    const start = resolve(cwdPath);
+    const chain = [];
+    let gitRoot;
+    let current = start;
+    while (true) {
+        chain.push(current);
+        const dotGit = yield* stat(join(current, ".git"));
+        if (dotGit.exists) {
+            gitRoot = current;
+            break;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            break;
+        }
+        current = parent;
+    }
+    const dirs = gitRoot === undefined ? [start] : chain;
+    return dirs.map((dir) => ({ sessionKey: deriveSessionKey(agentCommand, dir, name), cwd: dir }));
+}
+/**
+ * Select where a session lives: the nearest candidate whose ACPX record
+ * exists for the same agent command and directory, or the exact
+ * contextual cwd when none does.
+ */
+export function* resolveSessionPlacement(store, agentCommand, cwdPath, name) {
+    const candidates = yield* sessionCandidates(agentCommand, cwdPath, name);
+    for (const candidate of candidates) {
+        const record = yield* until(store.load(candidate.sessionKey));
+        if (record &&
+            record.agentCommand === agentCommand &&
+            resolve(record.cwd) === resolve(candidate.cwd)) {
+            return candidate;
+        }
+    }
+    return candidates[0];
+}

package/package.json

@@ -1,14 +1,32 @@
 {
   "name": "@executablemd/acp",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Bootstrap reservation for ACPX agent provider for executable.md documents: drives coding agents over the Agent Client Protocol..",
-  "license": "MIT",
+  "version": "0.5.0",
+  "description": "ACPX agent provider for executable.md documents: drives coding agents over the Agent Client Protocol.",
+  "homepage": "https://executable.md",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/taras/executable.md.git"
   },
-  "homepage": "https://executable.md",
-  "files": [
-    "README.md"
-  ]
-}
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/taras/executable.md/issues"
+  },
+  "module": "./esm/mod.js",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/mod.d.ts",
+        "default": "./esm/mod.js"
+      }
+    }
+  },
+  "scripts": {},
+  "dependencies": {
+    "@executablemd/core": "^0.5.0",
+    "@executablemd/runtime": "^0.5.0",
+    "acpx": "0.12.0",
+    "effection": "4.1.0-alpha.7"
+  },
+  "_generatedBy": "dnt@dev"
+}

package/types/mod.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @module
+ * ACPX agent provider for Executable.md (specs/acp-client-spec.md).
+ *
+ * `createAcpxProvider()` returns an `AgentProviderFactory` that drives
+ * coding agents over the Agent Client Protocol through the pinned `acpx`
+ * runtime. Supply it directly to core's agent vocabulary through the
+ * `rootProvider` option:
+ * `installAgentVocabulary({ rootProvider: { factory: createAcpxProvider(), options } })`.
+ */
+export { createAcpxProvider, useAcpxProviderState } from "./src/provider.js";
+export { useSerialQueues } from "./src/serial-queue.js";
+export type { SerialQueues } from "./src/serial-queue.js";
+export type { AcpxProviderSeams, AcpxProviderState, ProbeCapableRuntime, SessionRoutingContext, } from "./src/provider.js";
+/** The agent ACPX selects when nothing else is configured. */
+export { DEFAULT_AGENT_NAME } from "acpx/runtime";

package/types/src/events.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Turn event normalization (specs/acp-client-spec.md §Prompt).
+ *
+ * `consumeTurn` receives an already-started ACPX turn and the resolved
+ * identity, and produces the normalized public event sequence: exactly
+ * one `started`, then `text_delta` events for output-stream deltas only,
+ * then exactly one `terminal`, then the channel closes with the complete
+ * concatenated text — including partial text on failure. Thought,
+ * status, tool, usage, and raw ACP events stay private.
+ */
+import type { Channel, Operation } from "effection";
+import type { AgentPromptEvent, Session } from "@executablemd/core";
+import type { AcpRuntimeTurn } from "acpx/runtime";
+export interface TurnIdentity {
+    agent: string;
+    session: Session;
+}
+export declare function consumeTurn(turn: AcpRuntimeTurn, identity: TurnIdentity, channel: Channel<AgentPromptEvent, string>, markCompleted: () => void): Operation<void>;

package/types/src/permission-bridge.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Permission bridge (specs/acp-client-spec.md §Permissions).
+ *
+ * ## Routing
+ *
+ * ACPX delivers a permission request to `onPermissionRequest` keyed by
+ * `params.sessionId` — the ACP session id (`acpSessionId`) of the
+ * prompting turn. Each active turn registers its subscribing scope, an
+ * initial id, and a `refresh` operation that reloads its ACPX record by
+ * `acpxRecordId`. The id map is a cache: before routing, the bridge
+ * refreshes and verifies a direct candidate; on a miss it refreshes all
+ * active registrations and routes only when exactly one matches the
+ * request id. This tracks ACPX's reconnect fallback, which updates
+ * `record.acpSessionId` and checkpoints the record before running the
+ * prompt. The public `Session.agentSessionId` is updated from the
+ * refreshed record.
+ *
+ * ## Fail closed
+ *
+ * The decision resolves `{ outcome: "cancel" }` — never `undefined`
+ * (which would let ACPX fall back to its mode resolver) and never
+ * another scope — on: store errors during refresh, zero or multiple
+ * matching registrations, a stale or torn-down prompt scope, a policy
+ * error, an unknown selected option id, and an abort (before or during
+ * evaluation).
+ */
+import type { Operation, Scope } from "effection";
+import type { Session } from "@executablemd/core";
+import type { AcpPermissionDecision, AcpPermissionRequest } from "acpx/runtime";
+/** Reloads a registration's record; undefined when the record is gone. */
+export type RefreshRecord = () => Operation<{
+    acpSessionId?: string;
+    agentSessionId?: string;
+} | undefined>;
+export interface Registration {
+    /** Remove this registration; an in-flight refresh cannot reinsert it. */
+    unregister(): void;
+}
+export interface PermissionBridge {
+    /** Register the active turn's scope under its ACP session id. */
+    register(acpSessionId: string, scope: Scope, session: Session, refresh: RefreshRecord): Registration;
+    /**
+     * Decide one permission request. Never undefined — every failure mode
+     * (see the module doc) resolves `{ outcome: "cancel" }`, so ACPX can
+     * never fall back to its own mode resolver.
+     */
+    decision(request: AcpPermissionRequest, signal: AbortSignal): Operation<AcpPermissionDecision>;
+}
+export declare function createPermissionBridge(): PermissionBridge;

package/types/src/provider.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ACPX agent provider (specs/acp-client-spec.md §ACPX provider).
+ *
+ * The factory owns every resource it starts. The shared runtime is
+ * created lazily on first use with the contextual cwd and validated
+ * contextual timeout — nothing spawns at install time. Availability
+ * validation uses a disposable probe runtime per agent: ACPX 0.12.0's
+ * `probeAvailability()` only updates internal health, so `doctor()` is
+ * used and `report.ok` inspected explicitly; ACPX closes the probe
+ * client internally on both success and failure.
+ *
+ * Prompt subscriptions follow a fixed sequence — resolve identity,
+ * acquire the session's FIFO lock, register permission routing, resolve
+ * the effective timeout, start the turn — registering unconditional
+ * cleanup for each resource as soon as it is acquired, and conditional
+ * cancellation only once the turn exists. Provider teardown attempts
+ * every remaining cancellation and every distinct handle close with an
+ * all-settled strategy and throws the recorded failures from the
+ * provider scope.
+ */
+import type { Operation, Stream } from "effection";
+import type { AgentPromptEvent, AgentProviderFactory, AgentProviderOptions, PromptOptions, Session } from "@executablemd/core";
+import type { AcpAgentRegistry, AcpRuntime, AcpRuntimeDoctorReport, AcpRuntimeOptions, AcpSessionStore } from "acpx/runtime";
+/** The runtime surface the provider needs — ACPX's runtime plus its probe. */
+export interface ProbeCapableRuntime extends AcpRuntime {
+    doctor(): Promise<AcpRuntimeDoctorReport>;
+}
+/** Context for the session-routing seam: the registry-dependent inputs. */
+export interface SessionRoutingContext {
+    agentName: string;
+    session: string | Session | undefined;
+    /** Normalized contextual cwd. */
+    cwd: string;
+}
+export interface AcpxProviderSeams {
+    createRuntime?: (options: AcpRuntimeOptions) => ProbeCapableRuntime;
+    sessionStore?: AcpSessionStore;
+    agentRegistry?: AcpAgentRegistry;
+    /**
+     * Wraps registry-dependent work — session preparation AND
+     * ensure/session validation + turn start — so an embedder can pin its
+     * route for that critical section. `op` runs in the CALLER's scope
+     * (no `scoped()`), so returned prompt resources belong to the
+     * subscriber. The default invokes `op` directly.
+     */
+    sessionRouting?: <T>(context: SessionRoutingContext, op: () => Operation<T>) => Operation<T>;
+}
+/**
+ * The provider's operations, decoupled from the Agent Api install so
+ * embedders (e.g. the test agent) can hold several independent states —
+ * each with its own runtime, sessions, locks, and teardown — in sibling
+ * scopes. Teardown registers in the calling scope.
+ */
+export interface AcpxProviderState {
+    agent(name?: string): Operation<string>;
+    session(option?: string | Session): Operation<Session>;
+    promptStream(content: string, options?: PromptOptions): Stream<AgentPromptEvent, string>;
+}
+export declare function createAcpxProvider(seams?: AcpxProviderSeams): AgentProviderFactory;
+export declare function useAcpxProviderState(providerOptions: AgentProviderOptions, seams?: AcpxProviderSeams): Operation<AcpxProviderState>;

package/types/src/serial-queue.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Keyed serial queues: each key gets one spawned drain loop that
+ * grants slots strictly in arrival order and waits for the holder to
+ * finish before granting the next. A slot is a resource — it releases
+ * when the acquiring scope exits, on normal, failure, and halt paths
+ * alike, including a request halted while it is still queued.
+ */
+import type { Operation } from "effection";
+export interface SerialQueues {
+    /** Hold this key's slot for the calling scope's lifetime. */
+    slot(key: string): Operation<void>;
+    /**
+     * Hold this key's slot only while `op` runs, in the caller's own
+     * scope — for critical sections that must not outlive the operation
+     * and must not capture the resources `op` acquires.
+     */
+    withSlot<T>(key: string, op: () => Operation<T>): Operation<T>;
+}
+export declare function useSerialQueues(): Operation<SerialQueues>;

package/types/src/session-key.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Session identity (specs/acp-client-spec.md §Session).
+ *
+ * Keys are namespaced `xmd:v1:` so they can never collide with sessions
+ * owned by other ACPX consumers (ACPX's only key convention is an
+ * optional `agent:<name>:` prefix, which this scheme avoids). Every
+ * variable-length identity component — the agent command, the directory
+ * and an explicit session name — is digested, so a key stays bounded and
+ * filesystem-safe however long its inputs are. A session store may use
+ * the key as a file name and encode it again, which an undigested
+ * component overruns.
+ *
+ * Session resolution walks candidates from the contextual cwd toward the
+ * Git repository root and reuses the nearest candidate whose record
+ * already exists — checked through the ACPX session store, never through
+ * `ensureSession()`, which would create one. ACPX only reuses a record
+ * when the cwd matches, so the matched candidate's directory (not the
+ * caller cwd) becomes the session cwd. When nothing exists yet, the
+ * session is created for the exact contextual cwd.
+ */
+import type { Operation } from "effection";
+import type { AcpSessionStore } from "acpx/runtime";
+export interface SessionCandidate {
+    sessionKey: string;
+    cwd: string;
+}
+export declare function deriveSessionKey(agentCommand: string, dir: string, name?: string): string;
+/**
+ * One candidate per directory from the contextual cwd up to the Git
+ * repository root, nearest first. `.git` may be a directory or a file
+ * (worktrees). Outside a repository the exact cwd is the only candidate.
+ */
+export declare function sessionCandidates(agentCommand: string, cwdPath: string, name?: string): Operation<SessionCandidate[]>;
+/**
+ * Select where a session lives: the nearest candidate whose ACPX record
+ * exists for the same agent command and directory, or the exact
+ * contextual cwd when none does.
+ */
+export declare function resolveSessionPlacement(store: AcpSessionStore, agentCommand: string, cwdPath: string, name?: string): Operation<SessionCandidate>;

package/README.md

@@ -1,5 +0,0 @@
-# @executablemd/acp
-
-This is a bootstrap reservation for the package name. It contains no
-implementation. Install a stable release from the `latest` dist-tag once
-available.