@executablemd/cli 0.4.2 → 0.5.1

package/esm/deno.js

@@ -1,12 +1,13 @@
 export default {
     "name": "@executablemd/cli",
-    "version": "0.4.2",
+    "version": "0.5.1",
     "exports": "./src/cli.ts",
     "imports": {
         "@types/node": "npm:@types/node@^24.5.2",
         "@durable-streams/client": "npm:@durable-streams/client@^0.2.2",
-        "@effectionx/bdd/node": "file:///home/runner/work/executable.md/executable.md/test-support/bdd.ts",
-        "@effectionx/bdd/expect": "file:///home/runner/work/executable.md/executable.md/test-support/expect.ts",
+        "@durable-streams/server": "npm:@durable-streams/server@^0.3.8",
+        "@effectionx/bdd/node": "file:///home/runner/work/executable.md/executable.md/packages/test-support/bdd.ts",
+        "@effectionx/bdd/expect": "file:///home/runner/work/executable.md/executable.md/packages/test-support/expect.ts",
         "@effectionx/test-adapter": "npm:@effectionx/test-adapter@0.7.4",
         "effection": "npm:effection@4.1.0-alpha.7",
         "effection/experimental": "npm:effection@4.1.0-alpha.7/experimental",
@@ -30,15 +31,19 @@ export default {
         "oxlint-tsgolint": "npm:oxlint-tsgolint@^0.17",
         "unist-util-select": "npm:unist-util-select@^5",
         "mdast-util-to-string": "npm:mdast-util-to-string@^4",
-        "@executablemd/core": "npm:@executablemd/core@^0.4.2",
-        "@executablemd/core/": "npm:@executablemd/core@^0.4.2/",
-        "@executablemd/durable-streams": "npm:@executablemd/durable-streams@^0.4.2",
-        "@executablemd/durable-streams/": "npm:@executablemd/durable-streams@^0.4.2/",
-        "@executablemd/runtime": "npm:@executablemd/runtime@^0.4.2",
-        "@executablemd/runtime/": "npm:@executablemd/runtime@^0.4.2/",
-        "@executablemd/testing": "npm:@executablemd/testing@^0.4.2",
-        "@executablemd/testing/": "npm:@executablemd/testing@^0.4.2/",
-        "@executablemd/code-review-agent": "npm:@executablemd/code-review-agent@^0.4.2",
-        "@executablemd/code-review-agent/": "npm:@executablemd/code-review-agent@^0.4.2/"
+        "@executablemd/acp": "npm:@executablemd/acp@^0.5.1",
+        "@executablemd/acp/": "npm:@executablemd/acp@^0.5.1/",
+        "@executablemd/code-review-agent": "npm:@executablemd/code-review-agent@^0.5.1",
+        "@executablemd/code-review-agent/": "npm:@executablemd/code-review-agent@^0.5.1/",
+        "@executablemd/core": "npm:@executablemd/core@^0.5.1",
+        "@executablemd/core/": "npm:@executablemd/core@^0.5.1/",
+        "@executablemd/durable-streams": "npm:@executablemd/durable-streams@^0.5.1",
+        "@executablemd/durable-streams/": "npm:@executablemd/durable-streams@^0.5.1/",
+        "@executablemd/runtime": "npm:@executablemd/runtime@^0.5.1",
+        "@executablemd/runtime/": "npm:@executablemd/runtime@^0.5.1/",
+        "@executablemd/test-agent": "npm:@executablemd/test-agent@^0.5.1",
+        "@executablemd/test-agent/": "npm:@executablemd/test-agent@^0.5.1/",
+        "@executablemd/testing": "npm:@executablemd/testing@^0.5.1",
+        "@executablemd/testing/": "npm:@executablemd/testing@^0.5.1/"
     }
 };

package/esm/src/agent-config.js

@@ -0,0 +1,45 @@
+/**
+ * Agent flag parsing for `xmd run` (specs/acp-client-spec.md
+ * §Command-line configuration).
+ *
+ * A pure function over the parsed flags: it reads no Context Apis, no
+ * environment, and no configuration. The `DEFAULT_AGENT_NAME` lookup and
+ * every install step stay in the CLI, so the flag-to-configuration
+ * mapping can be asserted on its own.
+ */
+/** `digits` or `digits "." digits` — nothing else is a number of seconds. */
+const SECONDS = /^\d+(\.\d+)?$/;
+function parseTimeout(value) {
+    const invalid = {
+        error: `--timeout must be a positive number of seconds, got "${value}"`,
+    };
+    const trimmed = value.trim();
+    if (!SECONDS.test(trimmed)) {
+        return invalid;
+    }
+    const seconds = Number(trimmed);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        return invalid;
+    }
+    return seconds * 1000;
+}
+export function resolveAgentConfig(flags) {
+    const selected = [flags.approveAll, flags.approveReads, flags.denyAll].filter(Boolean);
+    if (selected.length > 1) {
+        return { error: "--approve-all, --approve-reads, and --deny-all are mutually exclusive" };
+    }
+    const permissionMode = flags.approveAll
+        ? "approve-all"
+        : flags.denyAll
+            ? "deny-all"
+            : "approve-reads";
+    let timeoutMs;
+    if (flags.timeout !== undefined) {
+        const parsed = parseTimeout(flags.timeout);
+        if (typeof parsed !== "number") {
+            return parsed;
+        }
+        timeoutMs = parsed;
+    }
+    return { permissionMode, defaultAgent: flags.defaultAgent, timeoutMs };
+}

package/esm/src/cli.js

@@ -7,20 +7,25 @@
  *   xmd <document.md> [options]        (run is the default command)
  *
  * Examples:
- *   xmd run core/examples/hello-world.md
- *   xmd core/examples/hello-world.md --verbose
- *   xmd run core/examples/hello-world.md --journal events.jsonl
+ *   xmd run packages/core/examples/hello-world.md
+ *   xmd packages/core/examples/hello-world.md --verbose
+ *   xmd run packages/core/examples/hello-world.md --journal events.jsonl
  */
 import { main, exit, spawn, each, createSignal, until } from "effection";
 import { InMemoryStream, } from "@executablemd/durable-streams";
 import { forEach } from "@effectionx/stream-helpers";
 import { open } from "node:fs/promises";
+import { basename, extname } from "node:path";
 import { inspect } from "node:util";
 import process from "node:process";
 import { program, object, field, cli, commands } from "configliere";
 import { z } from "zod";
-import { execute, useNormalizedOutput, useTerminalOutput } from "@executablemd/core";
+import { AgentProviders, Config, execute, installAgentVocabulary, installPermissionMode, registerAgentProvider, useNormalizedOutput, useTerminalOutput, } from "@executablemd/core";
+import { env as readEnv } from "@executablemd/runtime";
+import { createAcpxProvider, DEFAULT_AGENT_NAME } from "@executablemd/acp";
 import { installTestingVocabulary, TestFailureError, useTesting } from "@executablemd/testing";
+import { installTestAgentVocabulary, runTestAgentWorker } from "@executablemd/test-agent";
+import { resolveAgentConfig } from "./agent-config.js";
 import { FileStream } from "./file-stream.js";
 import denoJson from "../deno.js";
 const defaults = (value) => (mods) => ({ ...mods, default: value });
@@ -47,6 +52,30 @@ const runConfig = object({
         description: "output raw markdown without normalization or terminal formatting",
         ...field(z.boolean(), defaults(false)),
     },
+    agentProvider: {
+        description: "agent provider for agent components",
+        ...field(z.string(), defaults("acpx")),
+    },
+    defaultAgent: {
+        description: "default agent name (overrides DEFAULT_AGENT_NAME)",
+        ...field(z.string().optional()),
+    },
+    timeout: {
+        description: "shared timeout in seconds for process, fetch, and agent operations",
+        ...field(z.union([z.string(), z.number()]).optional()),
+    },
+    approveAll: {
+        description: "approve every agent permission request",
+        ...field(z.boolean(), defaults(false)),
+    },
+    approveReads: {
+        description: "approve read and search agent permissions, ask for the rest (default)",
+        ...field(z.boolean(), defaults(false)),
+    },
+    denyAll: {
+        description: "deny every agent permission request",
+        ...field(z.boolean(), defaults(false)),
+    },
 });
 const testConfig = object({
     docPath: {
@@ -72,10 +101,16 @@ const testConfig = object({
         ...field(z.boolean(), defaults(false)),
     },
 });
+const testAgentConfig = object({
+    connect: {
+        description: "opaque controller route (controller-launched workers only)",
+        ...field(z.string()),
+    },
+});
 const xmd = program({
     name: "xmd",
     version: denoJson.version,
-    config: commands({ run: runConfig, test: testConfig }, { default: "run" }),
+    config: commands({ run: runConfig, test: testConfig, "test-agent": testAgentConfig }, { default: "run" }),
 });
 const pretty = (value) => inspect(value, {
     colors: true,
@@ -129,6 +164,115 @@ function* createJournalFile(filePath) {
     }
     yield* until(handle.close());
 }
+/**
+ * The CLI entry script to hand back to a relaunched runtime. Deno and
+ * Node both report the module they started as `process.argv[1]`: the
+ * source `cli.ts` under `deno run`, the generated bin under npm. Only
+ * the compiled binary carries no entry script, and it never asks.
+ */
+function cliEntrypoint() {
+    const entrypoint = process.argv[1];
+    if (!entrypoint) {
+        throw new Error("cannot start the test-agent worker: this xmd was launched without a CLI entry script, so there is nothing for the worker process to run");
+    }
+    return entrypoint;
+}
+/**
+ * A worker inheriting the parent's `--inspect` would exit immediately on
+ * the debug port the parent already holds, so those options do not carry
+ * across the relaunch. Everything else the parent runs under does.
+ */
+function workerExecArgv() {
+    return process.execArgv.filter((option) => !option.startsWith("--inspect"));
+}
+/**
+ * The command that relaunches this xmd as a test-agent worker. Three
+ * builds reach this: the compiled binary invokes itself, the Deno source
+ * CLI reconstructs `deno run`, and the npm package reconstructs `node`.
+ * `process.execPath` names the running executable under both runtimes —
+ * `Deno.execPath()` exists in neither the Node build nor Node itself.
+ */
+function resolveWorkerCommand() {
+    const execPath = process.execPath;
+    const runtime = basename(execPath, extname(execPath));
+    if (runtime === "deno") {
+        return [execPath, "run", "--allow-all", cliEntrypoint(), "test-agent"];
+    }
+    if (runtime === "node") {
+        return [execPath, ...workerExecArgv(), cliEntrypoint(), "test-agent"];
+    }
+    return [execPath, "test-agent"];
+}
+const AGENT_ONLY_FLAGS = [
+    "--agent-provider",
+    "--default-agent",
+    "--timeout",
+    "--approve-all",
+    "--approve-reads",
+    "--deny-all",
+];
+/**
+ * Agent options belong to `xmd run`. The argument parser ignores options
+ * it does not define rather than rejecting them, so `xmd test` has to
+ * reject these itself instead of silently running without them.
+ */
+function findAgentOnlyFlag(args) {
+    return args.find((arg) => AGENT_ONLY_FLAGS.some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+}
+/**
+ * The text an option carried on the command line. `--timeout` validates
+ * this rather than the parsed value: the parser coerces `1e3` and `0x10`
+ * into numbers and drops `.5`, `+1` and `Infinity`, so forms the grammar
+ * rejects would otherwise reach the stack as valid seconds.
+ */
+function findFlagText(args, flag) {
+    for (const [index, arg] of args.entries()) {
+        if (arg === flag) {
+            return args[index + 1] ?? "";
+        }
+        if (arg.startsWith(`${flag}=`)) {
+            return arg.slice(flag.length + 1);
+        }
+    }
+    return undefined;
+}
+/**
+ * Install the agent stack for `xmd run`: permission mode, contextual
+ * timeout, the ACPX registration, and the vocabulary with the resolved
+ * root provider. Invalid flags and an unknown --agent-provider fail here
+ * — before any document executes. Nothing starts an agent: the provider
+ * validates availability on first use.
+ */
+function* installAgentStack(flags) {
+    const config = resolveAgentConfig(flags);
+    if ("error" in config) {
+        console.error(config.error);
+        yield* exit(1);
+        return;
+    }
+    if (config.timeoutMs !== undefined) {
+        const ms = config.timeoutMs;
+        yield* Config.around({ timeout: () => ms }, { at: "min" });
+    }
+    yield* registerAgentProvider("acpx", createAcpxProvider());
+    const defaultAgent = config.defaultAgent ?? (yield* readEnv("DEFAULT_AGENT_NAME")) ?? DEFAULT_AGENT_NAME;
+    let factory;
+    try {
+        factory = yield* AgentProviders.operations.resolve(flags.agentProvider);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        yield* exit(1);
+        return;
+    }
+    const permissionMode = config.permissionMode;
+    yield* installAgentVocabulary({
+        defaultAgent,
+        permissionMode,
+        rootProvider: { factory, options: { defaultAgent, permissionMode } },
+    });
+    yield* installPermissionMode(permissionMode);
+}
 function* run(config, mode) {
     const { docPath, componentDir, verbose, journal, raw } = config;
     // Every CLI invocation starts from an empty stream. --journal writes
@@ -173,10 +317,19 @@ function* run(config, mode) {
     // additionally activates root testing through a useTesting() session.
     if (mode.testing) {
         yield* useTesting({ verbose });
+        // TestAgent installs before the agent vocabulary so its <Prompt>
+        // interceptor runs first.
+        yield* installTestAgentVocabulary({ workerCommand: resolveWorkerCommand() });
+        yield* installAgentVocabulary();
     }
     else {
         yield* installTestingVocabulary({ verbose });
     }
+    // Agent flags are exclusive to `xmd run` — `xmd test` drives agents
+    // through the deterministic TestAgent stack instead.
+    if (mode.agent) {
+        yield* installAgentStack(mode.agent);
+    }
     const execution = yield* execute({
         docPath,
         stream,
@@ -231,12 +384,34 @@ await main(function* (args) {
                 break;
             }
             switch (parsed.value.name) {
-                case "run":
-                    yield* run(parsed.value.config, { testing: false });
+                case "run": {
+                    const config = parsed.value.config;
+                    yield* run(config, {
+                        testing: false,
+                        agent: {
+                            agentProvider: config.agentProvider,
+                            defaultAgent: config.defaultAgent,
+                            timeout: findFlagText(args, "--timeout"),
+                            approveAll: config.approveAll,
+                            approveReads: config.approveReads,
+                            denyAll: config.denyAll,
+                        },
+                    });
                     break;
-                case "test":
+                }
+                case "test": {
+                    const agentFlag = findAgentOnlyFlag(args);
+                    if (agentFlag) {
+                        console.error(`unrecognized option for xmd test: ${agentFlag} — agent options are exclusive to xmd run`);
+                        yield* exit(1);
+                        break;
+                    }
                     yield* run(parsed.value.config, { testing: true });
                     break;
+                }
+                case "test-agent":
+                    yield* runTestAgentWorker({ connect: parsed.value.config.connect });
+                    break;
             }
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@executablemd/cli",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "description": "The xmd command-line interface for executable.md.",
   "homepage": "https://executable.md",
   "repository": {
@@ -17,9 +17,12 @@
   },
   "dependencies": {
     "@effectionx/stream-helpers": "0.8.3",
-    "@executablemd/core": "^0.4.2",
-    "@executablemd/durable-streams": "^0.4.2",
-    "@executablemd/testing": "^0.4.2",
+    "@executablemd/acp": "^0.5.1",
+    "@executablemd/core": "^0.5.1",
+    "@executablemd/durable-streams": "^0.5.1",
+    "@executablemd/runtime": "^0.5.1",
+    "@executablemd/test-agent": "^0.5.1",
+    "@executablemd/testing": "^0.5.1",
     "configliere": "^0.2.3",
     "effection": "4.1.0-alpha.7",
     "zod": "^4.3.6"

package/types/deno.d.ts

@@ -5,6 +5,7 @@ declare namespace _default {
     let imports: {
         "@types/node": string;
         "@durable-streams/client": string;
+        "@durable-streams/server": string;
         "@effectionx/bdd/node": string;
         "@effectionx/bdd/expect": string;
         "@effectionx/test-adapter": string;
@@ -30,16 +31,20 @@ declare namespace _default {
         "oxlint-tsgolint": string;
         "unist-util-select": string;
         "mdast-util-to-string": string;
+        "@executablemd/acp": string;
+        "@executablemd/acp/": string;
+        "@executablemd/code-review-agent": string;
+        "@executablemd/code-review-agent/": string;
         "@executablemd/core": string;
         "@executablemd/core/": string;
         "@executablemd/durable-streams": string;
         "@executablemd/durable-streams/": string;
         "@executablemd/runtime": string;
         "@executablemd/runtime/": string;
+        "@executablemd/test-agent": string;
+        "@executablemd/test-agent/": string;
         "@executablemd/testing": string;
         "@executablemd/testing/": string;
-        "@executablemd/code-review-agent": string;
-        "@executablemd/code-review-agent/": string;
     };
 }
 export default _default;

package/types/src/agent-config.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Agent flag parsing for `xmd run` (specs/acp-client-spec.md
+ * §Command-line configuration).
+ *
+ * A pure function over the parsed flags: it reads no Context Apis, no
+ * environment, and no configuration. The `DEFAULT_AGENT_NAME` lookup and
+ * every install step stay in the CLI, so the flag-to-configuration
+ * mapping can be asserted on its own.
+ */
+import type { PermissionMode } from "@executablemd/core";
+export interface AgentFlags {
+    agentProvider: string;
+    defaultAgent: string | undefined;
+    /**
+     * The raw `--timeout` text. The argument parser coerces or drops
+     * lexical forms — `1e3`, `0x10`, `.5`, `+1` and `Infinity` all reach a
+     * number-typed field as something this grammar would have rejected —
+     * so the untransformed text is what gets validated.
+     */
+    timeout: string | undefined;
+    approveAll: boolean;
+    approveReads: boolean;
+    denyAll: boolean;
+}
+export interface AgentConfig {
+    permissionMode: PermissionMode;
+    /** The `--default-agent` value; the environment fallback is applied by the caller. */
+    defaultAgent: string | undefined;
+    timeoutMs: number | undefined;
+}
+export declare function resolveAgentConfig(flags: AgentFlags): AgentConfig | {
+    error: string;
+};

package/types/src/cli.d.ts

@@ -7,8 +7,8 @@
  *   xmd <document.md> [options]        (run is the default command)
  *
  * Examples:
- *   xmd run core/examples/hello-world.md
- *   xmd core/examples/hello-world.md --verbose
- *   xmd run core/examples/hello-world.md --journal events.jsonl
+ *   xmd run packages/core/examples/hello-world.md
+ *   xmd packages/core/examples/hello-world.md --verbose
+ *   xmd run packages/core/examples/hello-world.md --journal events.jsonl
  */
 export {};