@executablemd/test-agent 0.0.0-bootstrap.0 → 0.5.0

package/esm/src/template.js

@@ -0,0 +1,138 @@
+/**
+ * WhenPrompt template matching (specs/test-agent-spec.md §WhenPrompt
+ * templates). Pure functions — no Effection — so every rule is unit
+ * testable: whole-prompt anchoring, `{?name}` captures, `{binding}`
+ * constraints, repeated-capture agreement, and adjacent-capture
+ * ambiguity.
+ */
+const CAPTURE_HOLE = /^\{\?([A-Za-z_$][A-Za-z0-9_$]*)\}/;
+const BINDING_HOLE = /^\{([A-Za-z_$][A-Za-z0-9_$]*(?:\.[A-Za-z_$][A-Za-z0-9_$]*)*)\}/;
+const MALFORMED_CAPTURE = /^\{\?/;
+export function parseTemplate(source) {
+    const tokens = [];
+    const captureNames = [];
+    let literal = "";
+    let position = 0;
+    const flushLiteral = () => {
+        if (literal) {
+            tokens.push({ kind: "literal", text: literal });
+            literal = "";
+        }
+    };
+    while (position < source.length) {
+        const rest = source.slice(position);
+        const capture = CAPTURE_HOLE.exec(rest);
+        if (capture) {
+            flushLiteral();
+            const previous = tokens.at(-1);
+            if (previous && previous.kind !== "literal") {
+                return {
+                    ok: false,
+                    error: "adjacent capture holes without literal text between them are ambiguous: " +
+                        `"${source}"`,
+                };
+            }
+            const name = capture[1];
+            if (!captureNames.includes(name)) {
+                captureNames.push(name);
+            }
+            tokens.push({ kind: "capture", name });
+            position += capture[0].length;
+            continue;
+        }
+        if (MALFORMED_CAPTURE.test(rest)) {
+            return { ok: false, error: `malformed capture hole at position ${position}: "${source}"` };
+        }
+        const binding = BINDING_HOLE.exec(rest);
+        if (binding) {
+            flushLiteral();
+            const previous = tokens.at(-1);
+            if (previous && previous.kind === "capture") {
+                // A binding resolves to arbitrary text before matching, so a
+                // capture directly followed by a binding has no fixed delimiter
+                // either — same ambiguity as two adjacent captures.
+                return {
+                    ok: false,
+                    error: "a capture hole directly followed by another hole is ambiguous: " + `"${source}"`,
+                };
+            }
+            tokens.push({ kind: "binding", path: binding[1] });
+            position += binding[0].length;
+            continue;
+        }
+        literal += source[position];
+        position++;
+    }
+    flushLiteral();
+    return { ok: true, template: { source, tokens, captureNames } };
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function resolveBinding(path, env) {
+    const segments = path.split(".");
+    let current = env;
+    for (const segment of segments) {
+        if (!isRecord(current)) {
+            return undefined;
+        }
+        current = current[segment];
+    }
+    return typeof current === "string" ? current : undefined;
+}
+export function matchPrompt(template, prompt, env) {
+    let pattern = "^";
+    const groupIndexByName = new Map();
+    let groupCount = 0;
+    for (const token of template.tokens) {
+        if (token.kind === "literal") {
+            pattern += escapeRegExp(token.text);
+        }
+        else if (token.kind === "capture") {
+            const existing = groupIndexByName.get(token.name);
+            if (existing === undefined) {
+                groupCount++;
+                groupIndexByName.set(token.name, groupCount);
+                pattern += "([\\s\\S]+?)";
+            }
+            else {
+                // A repeated capture must match the same text as its first use.
+                pattern += `\\${existing}`;
+            }
+        }
+        else {
+            const resolved = resolveBinding(token.path, env);
+            if (resolved === undefined) {
+                return {
+                    ok: false,
+                    kind: "config",
+                    expected: template.source,
+                    actual: prompt,
+                    message: `template "${template.source}" references "{${token.path}}", ` +
+                        "which is not a bound string value — an unresolved binding is a " +
+                        "configuration error, never an implicit capture",
+                };
+            }
+            pattern += escapeRegExp(resolved);
+        }
+    }
+    pattern += "$";
+    const match = new RegExp(pattern).exec(prompt);
+    if (!match) {
+        return {
+            ok: false,
+            kind: "mismatch",
+            expected: template.source,
+            actual: prompt,
+            message: `prompt did not match the active stage.\nexpected template: ${template.source}\nactual prompt: ${prompt}`,
+        };
+    }
+    const captures = {};
+    for (const [name, index] of groupIndexByName) {
+        captures[name] = match[index];
+    }
+    return { ok: true, captures };
+}

package/esm/src/vocabulary.js

@@ -0,0 +1,287 @@
+/**
+ * The `<TestAgent>` vocabulary (specs/test-agent-spec.md §TestAgent).
+ *
+ * `installTestAgentVocabulary` must be installed BEFORE
+ * `installAgentVocabulary` in the same scope: in-scope middleware runs
+ * in install order, so the global `<Prompt>` interceptor here sees the
+ * invocation first, forces `throwOnError` only when both `<TestAgent>`
+ * and `<Test>` are active, and otherwise delegates unchanged.
+ *
+ * Each `<Test>` receives fresh ACPX state keyed by its lease EvalScope;
+ * the state is provisioned by a suspended task spawned into that scope,
+ * so halting the lease tears the provider down (canceling turns and
+ * closing workers) and removes the map entry on normal and failure
+ * paths alike. Outside a `<Test>`, the `<TestAgent>` scope itself is
+ * the isolation boundary.
+ *
+ * Scenario instances are resources held by suspended tasks spawned into
+ * their boundary scope, so a boundary halt releases them. Because
+ * acquiring one is an operation but the provider's route resolver is a
+ * synchronous callback, every instance is provisioned by the `session`
+ * and `prompt` seams before the provider routes, and `routeFor` is a
+ * pure lookup.
+ */
+import { createContext, scoped, spawn, suspend, useScope, withResolvers } from "effection";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { Agent, Component, evalScope } from "@executablemd/core";
+import { cwd as contextualCwd, readTextFile } from "@executablemd/runtime";
+import { Test } from "@executablemd/testing";
+import { useTestAgentController } from "./controller.js";
+import { useTestAgentAcpx } from "./state.js";
+const TestAgentCtx = createContext("testAgent.session", undefined);
+function configError(source, message) {
+    return { type: "error", message: `<${source}> ${message}`, source };
+}
+function scenarioKey(agent, sessionName) {
+    // JSON encoding keeps the key textual and collision-safe for any
+    // agent/session values.
+    return JSON.stringify([agent, sessionName]);
+}
+function instanceKeyFor(agent, sessionName, dir) {
+    return JSON.stringify([scenarioKey(agent, sessionName ?? ""), dir]);
+}
+function describeMapping(agentName, sessionName) {
+    return `agent "${agentName}" and session "${sessionName ?? "(default)"}"`;
+}
+/**
+ * Resolve a pinned session for the agent using it. The registry routes
+ * every agent through the same worker command, so the provider's own
+ * ownership check cannot tell two agents apart — a session stays owned
+ * by the agent that created it.
+ */
+function resolvePinned(bySessionKey, sessionKey, agentName) {
+    const pinned = bySessionKey.get(sessionKey);
+    if (!pinned) {
+        throw new Error(`unknown or stale agent session "${sessionKey}"`);
+    }
+    if (pinned.agent !== agentName) {
+        throw new Error(`agent "${agentName}" does not match session "${sessionKey}" (agent "${pinned.agent}")`);
+    }
+    return pinned;
+}
+export function* installTestAgentVocabulary(options) {
+    function* expandTestAgent(invocation, ctx) {
+        if (!(yield* Test.operations.sessionActive)) {
+            return [
+                configError("TestAgent", "is valid only in an active testing session created by xmd test or useTesting()."),
+            ];
+        }
+        const agentProp = invocation.props.agent;
+        if (agentProp !== undefined && typeof agentProp !== "string") {
+            return [configError("TestAgent", 'the "agent" prop must be a string literal.')];
+        }
+        const defaultAgent = typeof agentProp === "string" ? agentProp : "test";
+        return yield* scoped(function* () {
+            const controller = yield* useTestAgentController();
+            const scenarios = new Map();
+            const boundaries = new Map();
+            function* resolveInstance(state, agentName, sessionName, dir) {
+                const scenario = scenarios.get(scenarioKey(agentName, sessionName ?? ""));
+                if (!scenario) {
+                    throw new Error(`no <TestAgent.Scenario> maps ${describeMapping(agentName, sessionName)}`);
+                }
+                if (scenario.duplicate) {
+                    throw new Error(`duplicate <TestAgent.Scenario> mappings for ${describeMapping(agentName, sessionName)}`);
+                }
+                const key = instanceKeyFor(agentName, sessionName, dir);
+                const existing = state.instances.get(key);
+                if (existing) {
+                    return existing;
+                }
+                const inFlight = state.pending.get(key);
+                if (inFlight) {
+                    return yield* inFlight;
+                }
+                // Publish the shared future before acquiring so concurrent
+                // callers await this acquisition instead of starting their own.
+                const ready = withResolvers();
+                state.pending.set(key, ready.operation);
+                yield* state.boundaryScope.spawn(function* () {
+                    let instance;
+                    try {
+                        instance = yield* controller.useInstance({
+                            doc: scenario.doc,
+                            scenarioDir: scenario.scenarioDir,
+                        });
+                    }
+                    catch (error) {
+                        // Nothing consumes this task's failure yet, so it is
+                        // reported through the future the callers are waiting on.
+                        state.pending.delete(key);
+                        ready.reject(error instanceof Error ? error : new Error(String(error)));
+                        return;
+                    }
+                    state.instances.set(key, instance);
+                    state.pending.delete(key);
+                    ready.resolve(instance);
+                    // Held, not caught: the future has settled, so a later
+                    // failure must reach the boundary scope to fail the test.
+                    yield* suspend();
+                });
+                return yield* ready.operation;
+            }
+            function* provisionState() {
+                // The maps exist before useTestAgentAcpx so the route resolver
+                // can close over them.
+                const instances = new Map();
+                const bySessionKey = new Map();
+                const routeFor = (context) => {
+                    if (typeof context.session === "object") {
+                        return resolvePinned(bySessionKey, context.session.sessionKey, context.agentName)
+                            .instance.route;
+                    }
+                    const instance = instances.get(instanceKeyFor(context.agentName, context.session, context.cwd));
+                    if (!instance) {
+                        throw new Error(`no <TestAgent.Scenario> maps ${describeMapping(context.agentName, context.session)}`);
+                    }
+                    return instance.route;
+                };
+                const acpx = yield* useTestAgentAcpx({
+                    defaultAgent,
+                    agents: [defaultAgent],
+                    workerCommand: options.workerCommand,
+                    probeRoute: controller.probeRoute,
+                    routeFor,
+                });
+                return {
+                    acpx,
+                    boundaryScope: yield* useScope(),
+                    instances,
+                    pending: new Map(),
+                    bySessionKey,
+                };
+            }
+            // The <TestAgent> scope itself is the fallback isolation boundary.
+            const fallback = yield* provisionState();
+            boundaries.set("test-agent-scope", fallback);
+            function* boundary() {
+                const within = yield* Test.operations.inTest;
+                const lease = yield* evalScope;
+                const key = within && lease ? lease : "test-agent-scope";
+                const existing = boundaries.get(key);
+                if (existing) {
+                    return existing;
+                }
+                if (key === "test-agent-scope") {
+                    return fallback;
+                }
+                const published = withResolvers();
+                yield* key.eval(function* () {
+                    return yield* spawn(function* () {
+                        try {
+                            const state = yield* provisionState();
+                            boundaries.set(key, state);
+                            published.resolve(state);
+                            yield* suspend();
+                        }
+                        catch (error) {
+                            published.reject(error instanceof Error ? error : new Error(String(error)));
+                        }
+                        finally {
+                            boundaries.delete(key);
+                        }
+                    });
+                });
+                return yield* published.operation;
+            }
+            const session = { defaultAgent, controller, scenarios, boundary };
+            yield* TestAgentCtx.set(session);
+            yield* Agent.around({
+                *agent([name], _next) {
+                    const state = yield* boundary();
+                    return yield* state.acpx.state.agent(name);
+                },
+                *session([name], _next) {
+                    const state = yield* boundary();
+                    const agentName = yield* Agent.operations.agent();
+                    const dir = resolve(yield* contextualCwd());
+                    const instance = yield* resolveInstance(state, agentName, name, dir);
+                    // The provider's session() drives the route seam itself;
+                    // it maps this same context back to the instance route.
+                    const resolved = yield* state.acpx.state.session(name);
+                    state.bySessionKey.set(resolved.sessionKey, { agent: agentName, instance });
+                    return resolved;
+                },
+                *prompt([content, promptOptions], _next) {
+                    // Routing flows through the provider's sessionRouting seam,
+                    // whose resolver is synchronous — so the instance it will
+                    // look up is provisioned here, once the stream is subscribed.
+                    return {
+                        *[Symbol.iterator]() {
+                            const state = yield* boundary();
+                            const pinned = promptOptions?.session;
+                            const agentName = yield* Agent.operations.agent(promptOptions?.agent);
+                            if (typeof pinned === "object") {
+                                // Already provisioned by session(); resolving it again
+                                // would mis-key it as the unnamed session.
+                                resolvePinned(state.bySessionKey, pinned.sessionKey, agentName);
+                            }
+                            else {
+                                const dir = resolve(yield* contextualCwd());
+                                yield* resolveInstance(state, agentName, pinned, dir);
+                            }
+                            const stream = state.acpx.state.promptStream(content, promptOptions);
+                            return yield* stream;
+                        },
+                    };
+                },
+            }, { at: "min" });
+            const segments = yield* ctx.expand(invocation.children);
+            return segments;
+        });
+    }
+    function* expandScenario(invocation) {
+        const session = yield* TestAgentCtx.expect();
+        if (session === undefined) {
+            return [configError("TestAgent.Scenario", "is valid only inside <TestAgent>.")];
+        }
+        const { agent, session: sessionProp, src } = invocation.props;
+        if (typeof src !== "string" || src.length === 0) {
+            return [configError("TestAgent.Scenario", 'requires a "src" prop.')];
+        }
+        if (agent !== undefined && typeof agent !== "string") {
+            return [configError("TestAgent.Scenario", 'the "agent" prop must be a string literal.')];
+        }
+        if (sessionProp !== undefined && typeof sessionProp !== "string") {
+            return [configError("TestAgent.Scenario", 'the "session" prop must be a string literal.')];
+        }
+        const declaredIn = invocation.position?.path;
+        const baseDir = declaredIn ? dirname(declaredIn) : ".";
+        const srcPath = isAbsolute(src) ? src : resolve(baseDir, src);
+        const source = yield* readTextFile(srcPath);
+        const agentName = typeof agent === "string" ? agent : session.defaultAgent;
+        const key = scenarioKey(agentName, typeof sessionProp === "string" ? sessionProp : "");
+        const existing = session.scenarios.get(key);
+        if (existing) {
+            existing.duplicate = true;
+            return [];
+        }
+        session.scenarios.set(key, {
+            agent: agentName,
+            sessionName: typeof sessionProp === "string" ? sessionProp : "",
+            scenarioDir: dirname(srcPath),
+            doc: { path: basename(srcPath), source },
+            duplicate: false,
+        });
+        return [];
+    }
+    yield* Component.around({
+        *expandInvocation([invocation, ctx], next) {
+            if (invocation.name === "TestAgent") {
+                return { segments: yield* expandTestAgent(invocation, ctx) };
+            }
+            if (invocation.name === "TestAgent.Scenario") {
+                return { segments: yield* expandScenario(invocation) };
+            }
+            if (invocation.name === "Prompt") {
+                const session = yield* TestAgentCtx.expect();
+                if (session !== undefined &&
+                    (yield* Test.operations.inTest) &&
+                    invocation.props.throwOnError !== true) {
+                    return yield* next({ ...invocation, props: { ...invocation.props, throwOnError: true } }, ctx);
+                }
+            }
+            return yield* next(invocation, ctx);
+        },
+    });
+}

package/esm/src/worker/acp-server.js

@@ -0,0 +1,138 @@
+/**
+ * ACP-on-stdio serving for `xmd test-agent` (specs/test-agent-spec.md
+ * §Controller and worker). stdout carries only JSON-RPC lines; all
+ * logging goes to stderr. The worker is stateless but advertises and
+ * serves session/load: all state loads from the controller, so a load
+ * simply reuses the prior session id over the rehydrated document.
+ */
+import { ensure, resource, until, useScope } from "effection";
+import { randomUUID } from "node:crypto";
+import process from "node:process";
+import * as acp from "@agentclientprotocol/sdk";
+function extractText(prompt) {
+    let text = "";
+    for (const block of prompt) {
+        if (block.type === "text") {
+            text += block.text;
+        }
+    }
+    return text;
+}
+export function* serveAcp(worker, streams) {
+    const scope = yield* useScope();
+    // The SDK awaits the handler's return. A scope.run task that throws raises
+    // into the worker scope, so failures are trapped to a Result (task outcome
+    // stays Ok — the worker survives) and re-surfaced as a rejection, which the
+    // SDK maps to the JSON-RPC error. On halt the task's own future rejects, so
+    // the returned promise always settles — no stranded handler.
+    function handle(op) {
+        return scope
+            .run(function* () {
+            try {
+                return { ok: true, value: yield* op() };
+            }
+            catch (error) {
+                return { ok: false, error };
+            }
+        })
+            .then((result) => {
+            if (result.ok) {
+                return result.value;
+            }
+            throw result.error;
+        });
+    }
+    const connection = yield* useAcpConnection(worker, handle, streams);
+    // Settles on EOF/error (which close the input stream, closing the
+    // connection), explicit connection closure, and worker cancellation (this
+    // scope halts, tearing the connection down).
+    yield* until(connection.closed);
+}
+function useAcpConnection(worker, handle, streams) {
+    return resource(function* (provide) {
+        const connection = acp
+            .agent({ name: "xmd-test-agent" })
+            .onRequest("initialize", () => ({
+            protocolVersion: acp.PROTOCOL_VERSION,
+            agentCapabilities: { loadSession: true },
+        }))
+            .onRequest("session/new", () => handle(function* () {
+            yield* worker.ready();
+            return { sessionId: randomUUID() };
+        }))
+            .onRequest("session/load", () => handle(function* () {
+            yield* worker.ready();
+            return {};
+        }))
+            .onRequest("session/prompt", (ctx) => handle(function* () {
+            const result = yield* worker.runTurn(extractText(ctx.params.prompt));
+            if (result.cancelled) {
+                return { stopReason: "cancelled" };
+            }
+            yield* until(ctx.client.notify(acp.methods.client.session.update, {
+                sessionId: ctx.params.sessionId,
+                update: {
+                    sessionUpdate: "agent_message_chunk",
+                    content: { type: "text", text: result.text },
+                },
+            }));
+            return { stopReason: "end_turn" };
+        }))
+            .onNotification("session/cancel", () => {
+            worker.cancel();
+        })
+            .connect(acp.ndJsonStream(streams.output, streams.input));
+        yield* ensure(() => connection.close());
+        yield* provide(connection);
+    });
+}
+// The only process-coupled piece. Named handlers with explicit ownership:
+// end/close close the input stream idempotently; error errors the input
+// stream, which closes the SDK connection; teardown removes every owned
+// listener. connection.closed resolves regardless of the close reason, so
+// serveAcp completes normally on a transport error.
+export function useProcessStdio() {
+    return resource(function* (provide) {
+        const output = new WritableStream({
+            write(chunk) {
+                process.stdout.write(chunk);
+            },
+        });
+        let controller;
+        const input = new ReadableStream({
+            start(c) {
+                controller = c;
+            },
+        });
+        const onData = (chunk) => controller?.enqueue(new Uint8Array(chunk));
+        const closeInput = () => {
+            try {
+                controller?.close();
+            }
+            catch {
+                // already closed — end and close may both fire
+            }
+        };
+        const onEnd = () => closeInput();
+        const onClose = () => closeInput();
+        const onError = (error) => {
+            try {
+                controller?.error(error);
+            }
+            catch {
+                // already settled
+            }
+        };
+        process.stdin.on("data", onData);
+        process.stdin.on("end", onEnd);
+        process.stdin.on("close", onClose);
+        process.stdin.on("error", onError);
+        yield* ensure(() => {
+            process.stdin.off("data", onData);
+            process.stdin.off("end", onEnd);
+            process.stdin.off("close", onClose);
+            process.stdin.off("error", onError);
+        });
+        yield* provide({ input, output });
+    });
+}

package/esm/src/worker/bridge.js

@@ -0,0 +1,84 @@
+/**
+ * The worker bridge (specs/test-agent-spec.md §Behavior documents): one
+ * ordered channel carries output chunks, matcher suspensions, EOF, and
+ * document failure, so the final output chunk of a turn always precedes
+ * the suspension/EOF signal that ends it. Prompt offers flow the other
+ * way, one at a time, to whichever matcher is suspended.
+ */
+import { createChannel, withResolvers } from "effection";
+export function createTurnBridge() {
+    const events = createChannel();
+    const offers = [];
+    const waiters = [];
+    function drop(queue, entry) {
+        const index = queue.indexOf(entry);
+        if (index !== -1) {
+            queue.splice(index, 1);
+        }
+    }
+    return {
+        events,
+        *offer(text) {
+            const outcome = withResolvers();
+            const offer = { text, respond: outcome.resolve };
+            const waiter = waiters.shift();
+            if (waiter) {
+                waiter(offer);
+            }
+            else {
+                offers.push(offer);
+            }
+            try {
+                return yield* outcome.operation;
+            }
+            finally {
+                // A halted offer must not linger in the queue for a later
+                // nextOffer() to deliver as if it were live.
+                drop(offers, offer);
+            }
+        },
+        *nextOffer() {
+            const queued = offers.shift();
+            if (queued) {
+                return queued;
+            }
+            const arrival = withResolvers();
+            waiters.push(arrival.resolve);
+            try {
+                return yield* arrival.operation;
+            }
+            finally {
+                // A halted waiter must not be handed a later offer, which would
+                // deliver the prompt to a dead operation and hang the offerer.
+                drop(waiters, arrival.resolve);
+            }
+        },
+    };
+}
+/**
+ * Read bridge events until the current turn ends, concatenating output.
+ * Returns the terminal signal so callers distinguish the next matcher,
+ * EOF, and document failure.
+ */
+export function* collectTurn(subscription) {
+    let text = "";
+    while (true) {
+        const next = yield* subscription.next();
+        if (next.done) {
+            return { text, end: "eof" };
+        }
+        const event = next.value;
+        if (event.kind === "output") {
+            text += event.text;
+        }
+        else if (event.kind === "suspended") {
+            return { text, end: "suspended", stage: event.stage };
+        }
+        else if (event.kind === "failed") {
+            return { text, end: "failed", error: event.error };
+        }
+        else {
+            return { text, end: "eof" };
+        }
+    }
+}