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

package/types/src/net.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The Node↔Effection boundary for line-framed TCP (specs/test-agent-spec.md
+ * §Controller and worker). A server that owns its listener and dispatches
+ * connections, a socket whose inbound lines are an Effection stream, and a
+ * client that shares the same socket adapter — so callers work with
+ * operations and streams, never raw `.on`/`.once`/Promise plumbing.
+ */
+import type { Operation, Stream } from "effection";
+import type { Socket } from "node:net";
+export interface LineSocket {
+    /** Inbound newline-framed lines; closes when the socket ends. */
+    lines: Stream<string, unknown>;
+    /** Write one already-framed line. */
+    send(line: string): void;
+    /** Graceful half-close: flush pending writes, then send FIN. */
+    end(): void;
+    /**
+     * Resolves when the socket closes — EOF, error, or teardown. Consumers
+     * race their line loop against this: `fromReadable` closes the line
+     * stream on `end` but not on an abrupt reset, so without it an
+     * `each(lines)` loop would block forever on a peer that vanishes.
+     */
+    closed: Operation<void>;
+}
+/** Adapt a connected socket: inbound bytes become a line stream; the socket
+ * is destroyed on teardown. */
+export declare function useLineSocket(socket: Socket): Operation<LineSocket>;
+export interface LineServer {
+    port: number;
+}
+/**
+ * A localhost line-protocol server as a resource. It listens, then accepts
+ * each connection, adapts it with {@link useLineSocket}, and runs
+ * `onConnection` for it in its own task — so a caller never spawns or
+ * touches a raw socket. The per-connection task is what lets simultaneous
+ * connections run concurrently (`each` itself is sequential).
+ */
+export declare function useLineServer(host: string, onConnection: (connection: LineSocket) => Operation<void>): Operation<LineServer>;
+export interface LineClient<T> {
+    send(line: string): void;
+    /** The next parsed inbound message; throws once the connection closes. */
+    next(): Operation<T>;
+    /** Resolves when the connection closes. */
+    closed: Operation<void>;
+}
+/**
+ * Connect to a line-protocol server. Shares {@link useLineSocket}, adds the
+ * connect handshake and a parsed inbound queue behind `next()` — all as
+ * operations. `parse` returning `undefined` drops an unparseable line.
+ */
+export declare function useLineClient<T>(host: string, port: number, parse: (line: string) => T | undefined): Operation<LineClient<T>>;

package/types/src/protocol.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Controller ↔ worker wire protocol (specs/test-agent-spec.md
+ * §Controller and worker): newline-delimited JSON over localhost TCP.
+ * Every inbound line is parsed into a validated type — malformed,
+ * unknown, and directionally invalid messages are rejected, never cast.
+ */
+import type { DurableEvent } from "@executablemd/durable-streams";
+/** The validated journal-event wire shape; structurally a DurableEvent. */
+export type WireDurableEvent = DurableEvent;
+export type WorkerMessage = {
+    t: "attach";
+    token: string;
+    instance: string;
+} | {
+    t: "journal";
+    seq: number;
+    event: WireDurableEvent;
+} | {
+    t: "read";
+    path: string;
+} | {
+    t: "stat";
+    path: string;
+} | {
+    t: "turn-failure";
+    kind: "mismatch" | "exhausted" | "config";
+    expected?: string;
+    actual: string;
+} | {
+    t: "fatal";
+    message: string;
+};
+export type ControllerMessage = {
+    t: "config";
+    mode: "probe";
+} | {
+    t: "config";
+    mode: "scenario";
+    doc: {
+        path: string;
+        source: string;
+    };
+    journal: WireDurableEvent[];
+} | {
+    t: "ack";
+    seq: number;
+} | {
+    t: "recorded";
+} | {
+    t: "read";
+    path: string;
+    source?: string;
+    missing: boolean;
+} | {
+    t: "stat";
+    path: string;
+    exists: boolean;
+    isFile: boolean;
+} | {
+    t: "error";
+    message: string;
+};
+export declare function encodeMessage(message: WorkerMessage | ControllerMessage): string;
+export type ParseResult<T> = {
+    ok: true;
+    message: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseWorkerMessage(line: string): ParseResult<WorkerMessage>;
+export declare function parseControllerMessage(line: string): ParseResult<ControllerMessage>;
+/** Incremental newline splitter: feed chunks, receive complete lines. */
+export declare function createLineSplitter(): {
+    feed(chunk: string): string[];
+};
+export interface ParsedRoute {
+    host: string;
+    port: number;
+    token: string;
+    instance: string;
+}
+/**
+ * Routes are opaque to ACPX and workers alike; this is the one place
+ * that knows the encoding: host:port/token/instance.
+ */
+export declare function formatRoute(route: ParsedRoute): string;
+export declare function parseRoute(value: string): ParseResult<ParsedRoute>;
+export declare const PROBE_INSTANCE = "probe";

package/types/src/state.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Per-boundary ACPX state for `<TestAgent>` (specs/test-agent-spec.md
+ * §Scenario instances): the production provider state composed with an
+ * in-memory session store and a dynamic registry whose resolve() embeds
+ * the pending instance route into the worker command. Routing flows
+ * through the provider's `sessionRouting` seam: the global route slot is
+ * held only across the provider's registry-dependent work (preparation
+ * and ensure/session validation + turn start), released while the
+ * provider waits on the per-session queue and during turn consumption.
+ */
+import type { Operation } from "effection";
+import type { AcpxProviderSeams, AcpxProviderState, SessionRoutingContext } from "@executablemd/acp";
+import type { AcpSessionStore } from "acpx/runtime";
+export interface TestAgentAcpx {
+    state: AcpxProviderState;
+}
+export declare function createMemorySessionStore(): AcpSessionStore;
+export interface TestAgentAcpxOptions {
+    defaultAgent: string;
+    agents: string[];
+    workerCommand: string[];
+    probeRoute: string;
+    /** Map a routing context to the instance route pinned for its work. */
+    routeFor(context: SessionRoutingContext): string;
+    seams?: AcpxProviderSeams;
+}
+export declare function useTestAgentAcpx(options: TestAgentAcpxOptions): Operation<TestAgentAcpx>;

package/types/src/template.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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.
+ */
+export type TemplateToken = {
+    kind: "literal";
+    text: string;
+} | {
+    kind: "capture";
+    name: string;
+} | {
+    kind: "binding";
+    path: string;
+};
+export interface ParsedTemplate {
+    source: string;
+    tokens: TemplateToken[];
+    captureNames: string[];
+}
+export type TemplateParseResult = {
+    ok: true;
+    template: ParsedTemplate;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseTemplate(source: string): TemplateParseResult;
+export type TemplateMatchResult = {
+    ok: true;
+    captures: Record<string, string>;
+} | {
+    ok: false;
+    kind: "mismatch" | "config";
+    expected: string;
+    actual: string;
+    message: string;
+};
+export declare function matchPrompt(template: ParsedTemplate, prompt: string, env: Record<string, unknown>): TemplateMatchResult;

package/types/src/vocabulary.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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 type { Operation } from "effection";
+export interface TestAgentVocabularyOptions {
+    /** Command segments that relaunch this xmd as `test-agent`. */
+    workerCommand: string[];
+}
+export declare function installTestAgentVocabulary(options: TestAgentVocabularyOptions): Operation<void>;

package/types/src/worker/acp-server.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 type { Operation } from "effection";
+export type TurnResult = {
+    cancelled: true;
+} | {
+    cancelled: false;
+    text: string;
+};
+export interface WorkerAgent {
+    /** Resolves once the behavior document reached its first matcher. */
+    ready(): Operation<void>;
+    runTurn(text: string): Operation<TurnResult>;
+    cancel(): void;
+}
+/** The byte transport the ACP connection is served over. */
+export interface AcpByteStreams {
+    input: ReadableStream<Uint8Array>;
+    output: WritableStream<Uint8Array>;
+}
+export declare function serveAcp(worker: WorkerAgent, streams: AcpByteStreams): Operation<void>;
+export declare function useProcessStdio(): Operation<AcpByteStreams>;

package/types/src/worker/bridge.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 type { Channel, Operation, Subscription } from "effection";
+import type { TemplateMatchResult } from "../template.js";
+export type BridgeEvent = {
+    kind: "output";
+    text: string;
+} | {
+    kind: "suspended";
+    stage: string;
+} | {
+    kind: "eof";
+} | {
+    kind: "failed";
+    error: string;
+};
+export interface PromptOffer {
+    text: string;
+    respond(outcome: TemplateMatchResult): void;
+}
+export interface TurnBridge {
+    events: Channel<BridgeEvent, never>;
+    offer(text: string): Operation<TemplateMatchResult>;
+    nextOffer(): Operation<PromptOffer>;
+}
+export declare function createTurnBridge(): TurnBridge;
+/**
+ * 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 declare function collectTurn(subscription: Subscription<BridgeEvent, never>): Operation<{
+    text: string;
+    end: "suspended" | "eof" | "failed";
+    stage?: string;
+    error?: string;
+}>;

package/types/src/worker/profile.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Deterministic worker profile (specs/test-agent-spec.md §Deterministic
+ * runtime): a capability policy, not a security sandbox. Process and
+ * Fetch are denied, env() is undefined, cwd() is the virtual scenario
+ * root, and the filesystem is limited to controller-backed reads and
+ * stats. Reading a .ts component candidate raises the explicit
+ * unsupported-TypeScript error before it could ever be materialized or
+ * imported; stats stay honest so an earlier Name.md wins and a missing
+ * Name.ts falls through to Name/index.md. Eval blocks are inline-only:
+ * core strips static imports into options.imports before compiling, so
+ * a non-empty list is rejected, and the transformed source is parsed
+ * with acorn to reject dynamic import expressions before compilation.
+ */
+import type { Operation } from "effection";
+import type { StatResult } from "@executablemd/runtime";
+export interface WorkerFilesystem {
+    read(path: string): Operation<string | undefined>;
+    stat(path: string): Operation<StatResult>;
+}
+export declare function installWorkerProfile(filesystem: WorkerFilesystem): Operation<void>;

package/types/src/worker/run.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `xmd test-agent` worker runtime (specs/test-agent-spec.md §Controller
+ * and worker). The worker attaches to its controller, rehydrates the
+ * behavior document and journal, and serves ACP on stdio.
+ *
+ * A stage's buffered durable-event suffix — everything through the next
+ * suspension point or the final root Close — is forwarded and
+ * acknowledged before the ACP result is returned; a crash inside that
+ * final delivery window is outside the supported recovery guarantee.
+ *
+ * Cancellation is transactional from the controller journal's
+ * perspective: a cancelled turn commits nothing — the scenario runtime
+ * is halted and rebuilt from the last acknowledged journal before
+ * another turn is accepted, so the next prompt re-enters the same
+ * stage deterministically.
+ */
+import type { Operation } from "effection";
+export declare function runTestAgentWorker(options: {
+    connect: string;
+}): Operation<void>;

package/types/src/worker/when-prompt.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The `<WhenPrompt>` vocabulary (specs/test-agent-spec.md §Behavior
+ * documents). Each matcher signals the bridge that the previous stage's
+ * rendering is complete, then suspends until an offered prompt matches.
+ * A match is one durable `when_prompt` operation whose record restores
+ * the matched prompt and captures on replay, so a rehydrated worker
+ * advances to the active matcher without re-matching.
+ */
+import type { Operation } from "effection";
+import type { TurnBridge } from "./bridge.js";
+export declare function installWhenPromptVocabulary(bridge: TurnBridge): Operation<void>;

package/README.md

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