✨ feat(cli): xmd run drives agents through ACPX (acp-stack 10)

.github/workflows/ci.yml

@@ -82,6 +82,12 @@ jobs:
  - name: Smoke test the compiled binary as a test agent
  run: ./dist/xmd test smoke-test/test-agent/README.md --raw
 
+ - name: Smoke test xmd run through ACPX
+ run: |
+ ./dist/xmd test smoke-test/agent/README.md \
+ --component-dir smoke-test/agent/components \
+ --raw
+
  site:
  runs-on: ubuntu-latest
  steps:

.github/workflows/publish-packages.yml

@@ -104,7 +104,7 @@ jobs:
  version: ${{ needs.version.outputs.value }}
 
  cli:
- needs: [version, core, durable-streams, test-agent, testing]
+ needs: [version, acp, core, durable-streams, runtime, test-agent, testing]
  uses: ./.github/workflows/publish-one.yml
  with:
  package: packages/cli

packages/acp/mod.ts

@@ -18,3 +18,5 @@ export type {
  ProbeCapableRuntime,
  SessionRoutingContext,
 } from "./src/provider.ts";
+/** The agent ACPX selects when nothing else is configured. */
+export { DEFAULT_AGENT_NAME } from "acpx/runtime";

packages/acp/src/session-key.ts

@@ -3,8 +3,12 @@
  *
  * 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), and the
- * directory digest keeps keys short and filesystem-safe.
+ * 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
@@ -27,14 +31,19 @@ export interface SessionCandidate {
  cwd: string;
 }
 
+function digest(value: string): string {
+ return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+
 export function deriveSessionKey(agentCommand: string, dir: string, name?: string): string {
- const digest = createHash("sha256").update(resolve(dir)).digest("hex").slice(0, 16);
+ // The unnamed session keeps a literal marker so it stays recognisable
+ // and distinct from any given name.
  return [
  "xmd",
  "v1",
-encodeURIComponent(agentCommand),
- digest,
-encodeURIComponent(name ?? "default"),
+digest(agentCommand),
+ digest(resolve(dir)),
+ name === undefined ? "default" : digest(name),
  ].join(":");
 }
 

packages/acp/tests/session-key.test.ts

@@ -26,16 +26,39 @@ function* useStatWorld(existing: Record<string, "file" | "dir">): Operation<void
 }
 
 describe("Tier SK — session identity", () => {
- it("SK1: keys are namespaced, encoded, digested, and name-scoped", function* () {
+ it("SK1: keys are namespaced, digested, and name-scoped", function* () {
  const key = deriveSessionKey("codex --acp", "/repo", "review");
  const parts = key.split(":");
  expect(parts.slice(0, 2)).toEqual(["xmd", "v1"]);
- expect(parts[2]).toBe(encodeURIComponent("codex --acp"));
+ expect(parts[2]).toMatch(/^[0-9a-f]{16}$/);
  expect(parts[3]).toMatch(/^[0-9a-f]{16}$/);
- expect(parts[4]).toBe("review");
- expect(deriveSessionKey("codex --acp", "/repo")).not.toBe(key);
- expect(deriveSessionKey("codex --acp", "/repo").endsWith(":default")).toBe(true);
+ expect(parts[4]).toMatch(/^[0-9a-f]{16}$/);
  expect(deriveSessionKey("codex --acp", "/other", "review")).not.toBe(key);
+ expect(deriveSessionKey("claude --acp", "/repo", "review")).not.toBe(key);
+ });
+
+ it("SK8: the unnamed session is distinct from any given name", function* () {
+ const unnamed = deriveSessionKey("codex --acp", "/repo");
+ expect(unnamed.endsWith(":default")).toBe(true);
+ expect(unnamed).not.toBe(deriveSessionKey("codex --acp", "/repo", "review"));
+ expect(unnamed).not.toBe(deriveSessionKey("codex --acp", "/repo", "default"));
+ expect(deriveSessionKey("codex --acp", "/repo", "review")).not.toBe(
+ deriveSessionKey("codex --acp", "/repo", "release"),
+ );
+ });
+
+ it("SK9: long commands and long names stay usable as file names", function* () {
+ const command = `'${"/very/long/path".repeat(20)}/xmd' test-agent --connect 127.0.0.1:50049/${"a".repeat(64)}`;
+ const name = "session-".repeat(50);
+ for (const key of [
+ deriveSessionKey(command, "/repo", "review"),
+ deriveSessionKey("codex", `/${"deep".repeat(60)}`, "review"),
+ deriveSessionKey("codex", "/repo", name),
+ deriveSessionKey(command, `/${"deep".repeat(60)}`, name),
+ ]) {
+ expect(key.length).toBeLessThan(80);
+ expect(encodeURIComponent(key).length).toBeLessThan(255);
+ }
  });
 
  it("SK2: candidates walk from cwd to the git root, nearest first", function* () {

packages/cli/package.json

@@ -9,8 +9,10 @@
  "exports": "./src/cli.ts",
  "dependencies": {
  "@effectionx/stream-helpers": "0.8.3",
+ "@executablemd/acp": "workspace:*",
  "@executablemd/core": "workspace:*",
  "@executablemd/durable-streams": "workspace:*",
+ "@executablemd/runtime": "workspace:*",
  "@executablemd/test-agent": "workspace:*",
  "@executablemd/testing": "workspace:*",
  "configliere": "^0.2.3",

packages/cli/src/agent-config.ts

@@ -0,0 +1,74 @@
+/**
+ * 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;
+}
+
+/** `digits` or `digits "." digits` — nothing else is a number of seconds. */
+const SECONDS = /^\d+(\.\d+)?$/;
+
+function parseTimeout(value: string): number | { error: string } {
+ 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: AgentFlags): AgentConfig | { error: string } {
+ 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: PermissionMode = flags.approveAll
+ ? "approve-all"
+ : flags.denyAll
+ ? "deny-all"
+ : "approve-reads";
+
+ let timeoutMs: number | undefined;
+ if (flags.timeout !== undefined) {
+ const parsed = parseTimeout(flags.timeout);
+ if (typeof parsed !== "number") {
+ return parsed;
+ }
+ timeoutMs = parsed;
+ }
+
+ return { permissionMode, defaultAgent: flags.defaultAgent, timeoutMs };
+}