@plurnk/plurnk-agui 1.3.12 → 1.4.0

package/dist/Module.js

@@ -1,32 +1,105 @@
-// The in-process transport module (plurnk-agui#2) — what the daemon's boot plug-point
+// {§agui-daemon-client} The in-process transport module is what the daemon's boot plug-point
 // activates: registerModule(aguiModule(opts)) hands this the CoreSeam handle; it opens
 // the AG-UI+ HTTP/SSE listener and owns the client interface from there.
 //
-// This is the SINGLE-INTERFACE surface (AG-UI+), not the legacy bridge dialect:
+// This is the single external client interface:
 //   POST /  — the only endpoint. A worker streams SSE. HITL is terminate-resume: a
 //   stopped-world emits a request_approval/request_user_input TOOL_CALL and finishes
-//   with an AG-UI interrupt outcome (the loop stays paused in-engine); the next run's
+//   with an AG-UI interrupt outcome (the loop stays paused in-engine); the next AG-UI Run's
 //   standard resume entries resolve the durable proposal and continue the exact loop.
-//   Reads ride STATE_SNAPSHOT on RUN_STARTED; no /plurnk/rpc, no /resolve.
-// An AG-UI threadId IS a plurnk workspace (`<prefix>-<threadId>`); the envelope's
-// modelWorkerId binds the thread (no lazy inference — createWorkspace returns it).
+//   Reads ride STATE_SNAPSHOT on RUN_STARTED; there are no side-channel action
+//   or proposal-resolution endpoints.
+// An AG-UI threadId names one conversation worker inside the explicitly forwarded
+// workspace ({§agui-thread-binding}); no prefix or inferred workspace is minted.
 var _a;
 import { createServer } from "node:http";
 import Portal from "./Portal.js";
 import { stateSnapshot, parseAction, actionResult } from "./AguiPlus.js";
-import { PlurnkParser } from "@plurnk/plurnk-grammar";
-import { authorize as mcpAuthorize, poll as mcpPoll } from "@plurnk/plurnk-execs-mcp";
+import { PlurnkParser, UNKNOWN_POSITION } from "@plurnk/plurnk-contracts";
 import { EventType } from "./types.js";
+import { aguiRouteTemplate, observed } from "./observe.js";
 import { RunAgentInputSchema } from "@ag-ui/core";
 import { logEntryIdFromToolCallId, proposalInterrupt } from "./AguiPlus.js";
+import { Problems, Validator } from "@plurnk/plurnk-contracts";
+import { resolveModuleOptions } from "./config.js";
+const actionFailure = (code, detail, status = 400, extensions = {}) => ({
+    ok: false,
+    problem: Problems.create("agui:action", code, status, detail, {
+        stage: status < 500 ? "action-validation" : "action-execution",
+        retryable: false,
+        ...extensions,
+    }),
+});
+const httpProblem = (code, status, detail, extensions = {}) => Problems.create("agui:http", code, status, detail, extensions);
+class HttpProblemError extends Error {
+    problem;
+    constructor(problem) {
+        super(problem.detail);
+        this.name = "HttpProblemError";
+        this.problem = problem;
+    }
+}
+const problemFromError = (error) => {
+    if (error instanceof HttpProblemError)
+        return error.problem;
+    if (typeof error !== "object" || error === null)
+        return null;
+    const result = error.result;
+    if (result !== undefined) {
+        try {
+            return Validator.assertOperationResult(result).problem ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const problem = error.problem;
+    if (problem !== undefined) {
+        try {
+            return Validator.assertProblemDetails(problem);
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+};
+const operationOutcome = (result) => {
+    const exact = Validator.assertOperationResult(result);
+    return exact.problem === undefined
+        ? { ok: true, result: exact }
+        : { ok: false, problem: exact.problem };
+};
+const parseFailureResult = ({ detail, line, column, source, severity, }) => ({
+    status: 400,
+    problem: Problems.create("agui:action", "parse-failed", 400, detail, {
+        line,
+        column,
+        source,
+        severity,
+        stage: "parsing",
+        retryable: false,
+    }),
+});
+const writeHttpProblem = (res, problem) => {
+    res.writeHead(problem.status, { "content-type": "application/problem+json" });
+    res.end(JSON.stringify(problem));
+};
+const runErrorEvents = (problem) => [
+    { type: EventType.CUSTOM, name: "plurnk.problem", value: problem },
+    { type: EventType.RUN_ERROR, message: problem.detail, code: problem.type },
+];
 class Module {
     #seam;
     #opts;
     #portal;
     #http;
     #threads = new Map(); // threadId → envelope
-    #threadRuns = new Map(); // threadId → conversation workerId
-    // The control plane vs the world. A RUN lives in a world (a conversation, or an action
+    #threadWorkers = new Map(); // threadId → conversation workerId
+    static #CONTROL_ACTIONS = Object.freeze([
+        "ping", "discover", "providers.list", "workspace.list", "workspace.create", "workspace.attach",
+    ]);
+    // The control plane vs the world. An AG-UI Run lives in a world (a conversation, or an action
     // that reads/writes a workspace's log); a control-plane action (list/create/attach/discover/
     // auth) does NOT — so it must not bind or forge a workspace (operator ruling 2026-07-10:
     // "every worker/thread requires a world, not everything"). Only these kinds bind a workspace.
@@ -35,18 +108,41 @@ class Module {
         "workspace.constrain", "workspace.unconstrain", "workspace.constraints", "entry.read",
         "workspace.derivation", "op.exec", "op.parse", "workspace.members", "op.look", "run.fork",
     ]));
+    static #BUILTIN_ACTIONS = Object.freeze(new Set([
+        ...this.#CONTROL_ACTIONS,
+        ...this.#WORLD_SCOPED,
+    ]));
+    static #NOTIFICATIONS = Object.freeze([
+        "log/entry", "loop/terminated", "loop/proposal", "notice/event",
+        "stream/event", "stream/concluded", "workspace/branch-batch",
+    ]);
     constructor(seam, opts) {
         this.#seam = seam;
-        this.#opts = opts;
+        this.#opts = resolveModuleOptions(opts);
+        this.#moduleActionNames();
         this.#portal = new Portal(seam);
         this.#http = createServer((req, res) => { void this.#route(req, res); });
     }
-    // The boot-plug-point init: `daemon.registerModule(Module.init(opts))`.
+    #moduleActionNames() {
+        const names = this.#seam.listModuleActions();
+        const seen = new Set();
+        for (const name of names) {
+            if (_a.#BUILTIN_ACTIONS.has(name)) {
+                throw new Error(`module action '${name}' collides with AG-UI built-in action`);
+            }
+            if (seen.has(name))
+                throw new Error(`module action '${name}' is registered more than once`);
+            seen.add(name);
+        }
+        return names;
+    }
     static init(opts) {
-        return async (seam) => {
-            const m = new _a(seam, opts);
-            await m.listen();
-            return m;
+        return {
+            start: async (seam) => {
+                const module = new _a(seam, opts);
+                await module.listen();
+                return module;
+            },
         };
     }
     async listen() {
@@ -68,6 +164,10 @@ class Module {
         await new Promise((resolve, reject) => this.#http.close((e) => (e ? reject(e) : resolve())));
     }
     async #route(req, res) {
+        return observed(// {§observability-boundary} — only a bounded route class leaves the perimeter.
+        "agui.http", { route: aguiRouteTemplate(req.method, req.url) }, () => this.#routeSettled(req, res));
+    }
+    async #routeSettled(req, res) {
         try {
             res.setHeader("access-control-allow-origin", "*");
             res.setHeader("access-control-allow-headers", "content-type, authorization");
@@ -75,44 +175,65 @@ class Module {
                 res.writeHead(204).end();
                 return;
             }
-            // The perimeter (§governance): bearer check before any body read.
+            // The perimeter ({§agui-http-authorization}): bearer check before any body read.
             const token = this.#opts.token ?? "";
             if (token.length > 0 && req.headers.authorization !== `Bearer ${token}`) {
-                res.writeHead(401, { "content-type": "application/json" }).end(JSON.stringify({ error: "bearer token required" }));
+                writeHttpProblem(res, httpProblem("bearer-token-required", 401, "The request did not provide the required bearer token.", {
+                    stage: "authorization",
+                    recovery: "Provide the configured bearer token.",
+                    retryable: false,
+                }));
                 return;
             }
             if (req.method === "POST" && (req.url === "/" || req.url === "/agui"))
                 return await this.#run(req, res);
-            res.writeHead(404, { "content-type": "application/json" }).end(JSON.stringify({ error: "POST / (AG-UI run) is the interface" }));
+            writeHttpProblem(res, httpProblem("route-not-found", 404, "The requested HTTP route does not exist.", {
+                method: req.method ?? null,
+                path: req.url ?? null,
+                stage: "routing",
+                retryable: false,
+            }));
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
+            const exactProblem = problemFromError(err);
+            if (exactProblem === null) {
+                console.error("AG-UI request failed:", err);
+            }
+            const problem = exactProblem ?? httpProblem("request-failed", 500, "The AG-UI request failed unexpectedly.", {
+                stage: "request",
+                retryable: false,
+            });
             if (!res.headersSent) {
-                res.writeHead(500, { "content-type": "application/json" });
-                res.end(JSON.stringify({ error: message }));
+                writeHttpProblem(res, problem);
                 return;
             }
-            // Post-headers throw (svc#480): the SSE is already open, so a JSON body is
-            // invisible to the event parser — the stream reads as a silent death. Emit a
-            // legible terminal RUN_ERROR frame instead (501 for the no-model case), then end.
-            const code = /no provider configured|no model|unknown alias/i.test(message) ? "501" : "500";
-            res.write(`data: ${JSON.stringify({ type: EventType.RUN_ERROR, message, code })}\n\n`);
+            // {§agui-http-failure} The SSE is already open, so a JSON body is
+            // invisible to the event parser. Preserve a contract Problem exactly when
+            // one exists; unexpected exceptions become one generic boundary failure.
+            for (const event of runErrorEvents(problem)) {
+                res.write(`data: ${JSON.stringify(event)}\n\n`);
+            }
             res.end();
         }
     }
     // THE PLURNK PARADIGM (operator ruling 2026-07-10): the name IS the identity,
-    // verbatim. The SESSION is the WORLD (service SPEC, machine-processes) — selected by name via
+    // verbatim. The workspace is the world ({§agui-thread-binding}) — selected by name via
     // `forwardedProps.plurnk.workspace`; attach it if it exists, create it with EXACTLY that
     // name if it doesn't. No prefixes, no forged names, no dual lookup. The workspace is
     // REQUIRED: a worker has no existence without a world, so its absence is a contract
     // violation the client must fix — never a workspace forged from the threadId.
     // The threadId is the CONVERSATION over that world — resolved to a worker by
-    // #conversationRun (svc#366 landed: the three doors are ensureModelWorker, forkWorker,
+    // #conversationWorker ({§agui-thread-binding}: the three doors are ensureModelWorker, forkWorker,
     // createConversationWorker).
     async #envelope(threadId, forwarded) {
         const workspace = forwarded?.workspace;
-        if (typeof workspace !== "string" || workspace.length === 0)
-            throw new Error("forwardedProps.plurnk.workspace (a workspace name) is required");
+        if (typeof workspace !== "string" || workspace.length === 0) {
+            throw new HttpProblemError(httpProblem("workspace-required", 400, "forwardedProps.plurnk.workspace must name a workspace.", {
+                stage: "request-validation",
+                recovery: "Provide a non-empty workspace name.",
+                retryable: false,
+            }));
+        }
         const cached = this.#threads.get(threadId);
         if (cached !== undefined)
             return { env: cached, reattached: true };
@@ -127,9 +248,15 @@ class Module {
             const opts = forwarded ?? {};
             env = await this.#seam.createWorkspace({
                 name: workspace,
-                ...(typeof opts.projectRoot === "string" ? { projectRoot: opts.projectRoot } : {}),
-                ...(Array.isArray(opts.constraints) ? { constraints: opts.constraints } : {}),
-                ...(typeof opts.settings === "object" && opts.settings !== null ? { settings: JSON.stringify(opts.settings) } : {}),
+                ...(Object.hasOwn(opts, "projectRoot")
+                    ? { projectRoot: opts.projectRoot }
+                    : {}),
+                ...(Object.hasOwn(opts, "constraints")
+                    ? { constraints: opts.constraints }
+                    : {}),
+                ...(Object.hasOwn(opts, "settings")
+                    ? { settings: opts.settings }
+                    : {}),
             });
         }
         this.#threads.set(threadId, env);
@@ -137,19 +264,34 @@ class Module {
     }
     // Resolve the thread's conversation worker within its world. Cached per threadId;
     // worker names are immutable so the binding can't rot.
-    async #conversationRun(threadId, env) {
-        const cached = this.#threadRuns.get(threadId);
+    async #conversationWorker(threadId, env) {
+        const cached = this.#threadWorkers.get(threadId);
         if (cached !== undefined)
             return cached;
         const workerId = threadId === env.workspaceName
             ? await this.#seam.ensureModelWorker(env.workspaceId)
             : (await this.#seam.listWorkers(env.workspaceId)).find((r) => r.name === threadId)?.id
                 ?? (await this.#seam.createConversationWorker({ workspaceId: env.workspaceId, name: threadId })).workerId;
-        this.#threadRuns.set(threadId, workerId);
+        this.#threadWorkers.set(threadId, workerId);
         return workerId;
     }
     async #run(req, res) {
-        const input = RunAgentInputSchema.parse(JSON.parse(await _a.#body(req)));
+        let decoded;
+        try {
+            decoded = JSON.parse(await _a.#body(req));
+        }
+        catch {
+            throw new HttpProblemError(httpProblem("invalid-json", 400, "The request body is not valid JSON.", { stage: "request-validation", retryable: false }));
+        }
+        const parsed = RunAgentInputSchema.safeParse(decoded);
+        if (!parsed.success) {
+            throw new HttpProblemError(httpProblem("invalid-run-input", 400, "The request body does not satisfy the AG-UI RunAgentInput contract.", {
+                stage: "request-validation",
+                issues: parsed.error.issues,
+                retryable: false,
+            }));
+        }
+        const input = parsed.data;
         const forwarded = input.forwardedProps?.plurnk;
         // Control plane FIRST: a management action that doesn't live in a world (and an
         // unknown kind, which is no worker at all) answers without binding — or forging — a
@@ -157,21 +299,31 @@ class Module {
         const action = parseAction(input.forwardedProps);
         if (action !== null && !_a.#WORLD_SCOPED.has(action.kind))
             return await this.#controlRun(action, input, res);
+        let prompt = null;
+        if (action === null && input.resume === undefined) {
+            const lastUser = [...input.messages].reverse().find((message) => message.role === "user");
+            if (lastUser === undefined || typeof lastUser.content !== "string" || lastUser.content.length === 0) {
+                throw new HttpProblemError(httpProblem("user-message-required", 400, "A new AG-UI Run requires a non-empty textual user message.", {
+                    stage: "request-validation",
+                    recovery: "Provide a non-empty user message.",
+                    retryable: false,
+                }));
+            }
+            prompt = lastUser.content;
+        }
         const { env, reattached } = await this.#envelope(input.threadId, forwarded);
         const workspaceId = env.workspaceId;
-        // THREAD ↔ RUN (svc#366): the threadId is the CONVERSATION — a worker over the
+        // {§agui-thread-binding} The threadId is the conversation over the
         // world. threadId == workspace name binds the model worker (the default conversation);
         // a distinct threadId names its own worker: found by name, else minted via
         // createConversationWorker. The name is the identity at BOTH levels.
-        const workerId = await this.#conversationRun(input.threadId, env);
+        const workerId = await this.#conversationWorker(input.threadId, env);
         res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", "connection": "keep-alive" });
         let finished = false;
         const interrupts = [];
-        // The heartbeat (agui#3): a long model generation emits NO events, and consumer
-        // stacks kill silent bodies (undici's default 300s bodyTimeout — bench's
-        // 'terminated' deaths at 371s/711s = last event + 300s). An SSE comment frame
-        // every few seconds keeps every consumer fed; parsers skip comments by spec.
-        const cadence = this.#opts.heartbeatMs ?? 15_000;
+        // {§agui-configuration}: long generations can emit no events; SSE comments keep
+        // consumers fed without adding protocol events.
+        const cadence = this.#opts.heartbeatMs;
         const heartbeat = cadence > 0 ? setInterval(() => { res.write(": hb\n\n"); }, cadence) : null;
         const finish = () => {
             if (finished)
@@ -186,7 +338,7 @@ class Module {
             for (const e of events) {
                 res.write(`data: ${JSON.stringify(e)}\n\n`);
                 // Terminate-resume, the terminate half: a proposal tool-call ENDS this
-                // run (the loop stays paused in-engine awaiting the resume run).
+                // AG-UI Run (the loop stays paused in-engine awaiting the resume Run).
                 if (e.type === "TOOL_CALL_END") {
                     const logEntryId = logEntryIdFromToolCallId(e.toolCallId);
                     if (logEntryId !== null)
@@ -214,17 +366,17 @@ class Module {
         if (finished)
             return;
         try {
-            // §3 — a management ACTION run (forwardedProps.plurnk.action): execute via the
+            // §3 — a management-action AG-UI Run (forwardedProps.plurnk.action): execute via the
             // seam; the outcome rides the workspace's CURRENT thread binding (Portal.finishRun),
             // never this closure — a proposal-gated action (op.exec → 202) terminates THIS
-            // run and completes after the resume run rebinds the stream.
+            // AG-UI Run and completes after the resume AG-UI Run rebinds the stream.
             if (action !== null) {
                 const finishAction = (outcome) => {
                     const events = [actionResult(action.kind, outcome)];
                     // Plain action (stream still open): answer on OUR OWN stream — concurrent
                     // actions share a workspace, and the workspace binding is whoever bound last
                     // (results would cross streams). Only a proposal-pause (this stream already
-                    // terminated) hands off to the workspace binding, which the resume run rebinds.
+                    // terminated) hands off to the workspace binding, which the resume AG-UI Run rebinds.
                     if (!finished) {
                         this.#portal.finishThread(boundRun, events);
                         return;
@@ -237,7 +389,13 @@ class Module {
                     // bookkeeping arms BEFORE the finish decision (then stream/concluded,
                     // not a timer, releases any deferral).
                     .then(async (outcome) => { await new Promise((r) => setImmediate(r)); finishAction(outcome); })
-                    .catch((err) => finishAction({ ok: false, error: err instanceof Error ? err.message : String(err) }));
+                    .catch((err) => {
+                    console.error(`AG-UI action '${action.kind}' failed:`, err);
+                    const problem = problemFromError(err);
+                    finishAction(problem === null
+                        ? actionFailure("action-failed", "The action failed unexpectedly.", 500)
+                        : { ok: false, problem });
+                });
                 res.on("close", () => {
                     if (finished)
                         return;
@@ -246,38 +404,44 @@ class Module {
                 });
                 return;
             }
-            // AG-UI interrupt resume: this is a NEW run on the same thread. Bind it
+            // AG-UI interrupt resume: this is a new AG-UI Run on the same thread. Bind it
             // to the durable continuation before releasing the proposal.
             if (input.resume !== undefined) {
                 await this.#portal.resolve(workspaceId, boundRun, input.resume);
-                res.on("close", finish); // client hangup on a resume just detaches; the loop already runs
+                res.on("close", finish); // client hangup on a resume just detaches; the loop is already active
                 return;
             }
-            const lastUser = [...input.messages].reverse().find((m) => m.role === "user");
-            if (lastUser === undefined)
-                throw new Error("RunAgentInput.messages must carry a user message");
-            if (typeof lastUser.content !== "string")
-                throw new Error("PLURNK currently requires textual user message content");
-            if (lastUser.content.length === 0)
-                throw new Error("RunAgentInput.messages must carry a non-empty user message");
+            if (prompt === null)
+                throw new Error("conversation AG-UI Run reached dispatch without a validated prompt");
             if (reattached) {
                 const history = await this.#seam.readLog({ workspaceId, workerId, limit: 1000 }).catch(() => null);
                 if (history !== null)
-                    emit([...this.#threadRouterReplay(workspaceId, history)]);
+                    emit(this.#portal.replay(boundRun, history));
             }
             await this.#portal.run(boundRun, {
-                workspaceId, workerId, prompt: lastUser.content,
-                ...(typeof forwarded?.maxTurns === "number" ? { maxTurns: forwarded.maxTurns } : this.#opts.maxTurns !== undefined ? { maxTurns: this.#opts.maxTurns } : {}),
-                ...(typeof forwarded?.flags === "object" && forwarded.flags !== null ? { flags: forwarded.flags } : {}),
-                // #414 — per-loop model selection: the client sends alias+model on every loop
-                // (model = client-resolved <provider>/<model>, #90); forward both, the daemon's
+                workspaceId, workerId, prompt,
+                ...(forwarded !== undefined && Object.hasOwn(forwarded, "maxTurns")
+                    ? { maxTurns: forwarded.maxTurns }
+                    : this.#opts.maxTurns !== undefined ? { maxTurns: this.#opts.maxTurns } : {}),
+                ...(forwarded !== undefined && Object.hasOwn(forwarded, "flags")
+                    ? { flags: forwarded.flags }
+                    : {}),
+                ...(forwarded !== undefined && Object.hasOwn(forwarded, "openPaths")
+                    ? { openPaths: forwarded.openPaths }
+                    : {}),
+                // {§methods-loop-run-model} The client sends alias and model on every loop;
+                // model is the client-resolved <provider>/<model>. Forward both, and the daemon's
                 // runLoop applies precedence (model wins) and resolves the provider per loop.
-                ...(typeof forwarded?.alias === "string" && forwarded.alias.length > 0 ? { alias: forwarded.alias } : {}),
-                ...(typeof forwarded?.model === "string" && forwarded.model.length > 0 ? { model: forwarded.model } : {}),
+                ...(forwarded !== undefined && Object.hasOwn(forwarded, "alias")
+                    ? { alias: forwarded.alias }
+                    : {}),
+                ...(forwarded !== undefined && Object.hasOwn(forwarded, "model")
+                    ? { model: forwarded.model }
+                    : {}),
             });
-            // A dropped SSE on a LIVE run cancels the loop (hangup is the abort). A worker we
+            // A dropped SSE on a live AG-UI Run cancels the loop (hangup is the abort). A stream we
             // finished ourselves — terminal event or proposal-terminate — leaves the engine
-            // alone (the paused loop is exactly what the resume run needs).
+            // alone (the paused loop is exactly what the resume AG-UI Run needs).
             res.on("close", () => {
                 if (finished)
                     return;
@@ -286,65 +450,94 @@ class Module {
             });
         }
         catch (err) {
-            // Post-headers throw INSIDE the run (svc#480, completed): the frame alone is
+            // {§agui-http-failure} After headers, the frame alone is
             // not enough — the heartbeat interval and the Portal binding are live, and a
             // throw that escapes past finish() leaks them forever (the drill-hang). emit()
             // writes the terminal frame AND finish()es on RUN_ERROR — one door out.
-            const message = err instanceof Error ? err.message : String(err);
-            const code = /no provider configured|no model|unknown alias/i.test(message) ? "501" : "500";
-            emit([{ type: EventType.RUN_ERROR, message, code }]);
+            const exactProblem = problemFromError(err);
+            if (exactProblem === null)
+                console.error("AG-UI Run failed:", err);
+            const problem = exactProblem ?? httpProblem("run-failed", 500, "The AG-UI Run failed unexpectedly.", {
+                stage: "run",
+                retryable: false,
+            });
+            emit(runErrorEvents(problem));
         }
     }
-    // A control-plane run: no world bound. Open the SSE, run the worldless verb, answer on
+    // A control-plane AG-UI Run: no world bound. Open the SSE, execute the worldless verb, answer on
     // our own stream. No Portal thread, no model worker — nothing to forge (operator ruling:
     // workspace-plane actions must not spin an ephemeral workspace).
     async #controlRun(action, input, res) {
         res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", "connection": "keep-alive" });
         const emit = (e) => { res.write(`data: ${JSON.stringify(e)}\n\n`); };
         emit({ type: EventType.RUN_STARTED, threadId: input.threadId, runId: input.runId });
-        const outcome = await this.#action(action, null).catch((err) => ({ ok: false, error: err instanceof Error ? err.message : String(err) }));
+        const outcome = await this.#action(action, null)
+            .catch((err) => {
+            console.error(`AG-UI action '${action.kind}' failed:`, err);
+            const problem = problemFromError(err);
+            return problem === null
+                ? actionFailure("action-failed", "The action failed unexpectedly.", 500)
+                : { ok: false, problem };
+        });
         emit(actionResult(action.kind, outcome));
         emit({ type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId, outcome: { type: "success" } });
         res.end();
     }
-    // The capability manifest a client probes (`discover`) to detect a daemon older than
-    // itself. The methods ARE the action surface; the notifications are the daemon-shape
-    // events the client un-projects. Built from the real surface — never a hand-kept list.
-    #capabilities() {
+    // The capability manifest a client probes (`discover`) for exact action/event membership.
+    // The built-ins come from the same inventories routing uses; extension names come from core.
+    async #capabilities() {
         const methods = {};
-        for (const k of ["ping", "discover", "providers.list", "workspace.list", "workspace.create", "workspace.attach", "auth.authorize", "auth.authorize.poll", ..._a.#WORLD_SCOPED])
+        for (const k of [
+            ..._a.#CONTROL_ACTIONS,
+            ..._a.#WORLD_SCOPED,
+            ...this.#moduleActionNames(),
+        ]) {
+            if (methods[k])
+                throw new Error(`AG-UI action '${k}' is registered more than once`);
             methods[k] = true;
+        }
         const notifications = {};
-        for (const n of ["log/entry", "loop/terminated", "loop/proposal", "telemetry/event", "stream/event", "stream/concluded"])
+        for (const n of _a.#NOTIFICATIONS)
             notifications[n] = true;
-        return { methods, notifications };
+        const display = Validator.assertClientDisplayCapabilities(await this.#seam.listClientDisplayCapabilities());
+        return { methods, notifications, display };
     }
     // The action executor — the verb surface. The control plane runs worldless; everything
     // below the guard operates within a bound workspace. An unknown kind is an honest error,
     // never a silent pass-through. loop.inject rides here too (§4): the seam's unified
     // runLoop folds a prompt into the active drain; the steered effect streams on the SSE.
-    async #action(a, env, convRun) {
+    async #action(a, env, conversationWorkerId) {
         const p = a.params;
+        const moduleActions = this.#moduleActionNames();
         try {
             // The control plane — worldless verbs (no bound workspace; #WORLD_SCOPED gates this).
             switch (a.kind) {
                 case "ping": return { ok: true, result: {} };
-                case "discover": return { ok: true, result: this.#capabilities() };
+                case "discover": return { ok: true, result: await this.#capabilities() };
                 case "providers.list": return { ok: true, result: this.#seam.listProviders() };
                 case "workspace.list": return { ok: true, result: { workspaces: await this.#seam.listWorkspaces() } };
                 case "workspace.create": {
                     // The name IS the identity: an explicit name creates/attaches EXACTLY
                     // that workspace; no name = the daemon names it and the real name binds.
-                    if (typeof p.name === "string" && p.name.length > 0) {
+                    if (Object.hasOwn(p, "name") && (typeof p.name !== "string" || p.name.length === 0)) {
+                        return actionFailure("invalid-action-parameters", "workspace.create name is not a non-empty string.", 400, { field: "name", recovery: "Provide a non-empty workspace name or omit it." });
+                    }
+                    if (typeof p.name === "string") {
                         // The name IS the world here — feed it as the workspace so #envelope
                         // creates/attaches exactly it (p carries no `workspace` of its own).
                         const { env: created } = await this.#envelope(p.name, { ...p, workspace: p.name });
                         return { ok: true, result: { id: created.workspaceId, name: created.workspaceName, workerId: created.workerId } };
                     }
                     const created = await this.#seam.createWorkspace({
-                        ...(typeof p.projectRoot === "string" ? { projectRoot: p.projectRoot } : {}),
-                        ...(Array.isArray(p.constraints) ? { constraints: p.constraints } : {}),
-                        ...(typeof p.settings === "object" && p.settings !== null ? { settings: JSON.stringify(p.settings) } : {}),
+                        ...(Object.hasOwn(p, "projectRoot")
+                            ? { projectRoot: p.projectRoot }
+                            : {}),
+                        ...(Object.hasOwn(p, "constraints")
+                            ? { constraints: p.constraints }
+                            : {}),
+                        ...(Object.hasOwn(p, "settings")
+                            ? { settings: p.settings }
+                            : {}),
                     });
                     this.#threads.set(created.workspaceName, created);
                     return { ok: true, result: { id: created.workspaceId, name: created.workspaceName, workerId: created.workerId } };
@@ -353,94 +546,132 @@ class Module {
                     // A REAL attach: rebind the thread map to the chosen workspace and hand
                     // back its envelope — the picker does what it says (the unwired kind +
                     // a nil-masking fallback produced the 2026-07-10 front-door disaster).
-                    if (typeof p.id !== "number")
-                        return { ok: false, error: "workspace.attach requires id" };
+                    if (typeof p.id !== "number") {
+                        return actionFailure("invalid-action-parameters", "workspace.attach requires a numeric workspace id.", 400, {
+                            field: "id",
+                            recovery: "Provide a workspace id returned by workspace.list.",
+                        });
+                    }
                     const att = await this.#seam.attachWorkspace({ workspaceId: p.id, ...(typeof p.workerId === "number" ? { workerId: p.workerId } : {}) });
                     this.#threads.set(att.workspaceName, att);
-                    return { ok: true, result: { id: att.workspaceId, name: att.workspaceName, workerId: att.workerId, modelWorkerId: att.modelWorkerId } };
-                }
-                case "auth.authorize": {
-                    // Stateless relay to the execs-mcp driver (settled: no auth seam — the
-                    // driver owns its mechanics; the bearer overlays its own config registry).
-                    if (typeof p.target !== "string" || p.target.length === 0)
-                        return { ok: false, error: "auth.authorize requires target" };
-                    return { ok: true, result: await mcpAuthorize(p.target) };
-                }
-                case "auth.authorize.poll": {
-                    if (typeof p.target !== "string" || p.target.length === 0)
-                        return { ok: false, error: "auth.authorize.poll requires target" };
-                    return { ok: true, result: await mcpPoll(p.target, { device: p.device }) };
+                    return { ok: true, result: { id: att.workspaceId, name: att.workspaceName, workerId: att.workerId } };
                 }
             }
+            if (moduleActions.includes(a.kind)) {
+                return { ok: true, result: await this.#seam.invokeModuleAction(a.kind, p) };
+            }
             // Below this line lives IN a world. An unknown kind is no worker at all; a
             // world-scoped kind with no bound workspace is a routing bug — both surface plainly.
-            if (!_a.#WORLD_SCOPED.has(a.kind))
-                return { ok: false, error: `unknown action '${a.kind}'` };
+            if (!_a.#WORLD_SCOPED.has(a.kind)) {
+                return actionFailure("unknown-action", `Action '${a.kind}' is not registered.`, 404, {
+                    requestedAction: a.kind,
+                    recovery: "Use an action advertised by discover.",
+                });
+            }
             if (env === null)
                 throw new Error(`action '${a.kind}' operates within a workspace, but none is bound`);
             switch (a.kind) {
                 case "workspace.workers": return { ok: true, result: { workers: await this.#seam.listWorkers(typeof p.id === "number" ? p.id : env.workspaceId) } };
                 case "log.read": {
-                    // Default run: the conversation (model worker); p.workerId pins another.
-                    const readRun = typeof p.workerId === "number" ? p.workerId : convRun ?? await this.#seam.ensureModelWorker(env.workspaceId);
-                    const entries = await this.#seam.readLog({ workspaceId: env.workspaceId, workerId: readRun, ...(typeof p.limit === "number" ? { limit: p.limit } : {}), ...(typeof p.sinceId === "number" ? { sinceId: p.sinceId } : {}), ...(typeof p.loopId === "number" ? { loopId: p.loopId } : {}), ...(typeof p.turnId === "number" ? { turnId: p.turnId } : {}), ...(typeof p.loopSeq === "number" ? { loopSeq: p.loopSeq } : {}), ...(typeof p.turnSeq === "number" ? { turnSeq: p.turnSeq } : {}), ...(typeof p.sequence === "number" ? { sequence: p.sequence } : {}) });
+                    // Default worker: the conversation; p.workerId pins another.
+                    const readWorkerId = typeof p.workerId === "number" ? p.workerId : conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId);
+                    const entries = await this.#seam.readLog({
+                        workspaceId: env.workspaceId,
+                        workerId: readWorkerId,
+                        ...(Object.hasOwn(p, "limit") ? { limit: p.limit } : {}),
+                        ...(Object.hasOwn(p, "sinceId") ? { sinceId: p.sinceId } : {}),
+                        ...(Object.hasOwn(p, "loopId") ? { loopId: p.loopId } : {}),
+                        ...(Object.hasOwn(p, "turnId") ? { turnId: p.turnId } : {}),
+                        ...(Object.hasOwn(p, "loopSeq") ? { loopSeq: p.loopSeq } : {}),
+                        ...(Object.hasOwn(p, "turnSeq") ? { turnSeq: p.turnSeq } : {}),
+                        ...(Object.hasOwn(p, "sequence") ? { sequence: p.sequence } : {}),
+                    });
                     return { ok: true, result: { entries } };
                 }
                 case "loop.inject": {
-                    if (typeof p.prompt !== "string" || p.prompt.length === 0)
-                        return { ok: false, error: "loop.inject requires prompt" };
-                    const ack = await this.#seam.runLoop({ workspaceId: env.workspaceId, workerId: convRun ?? await this.#seam.ensureModelWorker(env.workspaceId), prompt: p.prompt });
-                    return { ok: true, result: ack };
+                    if (typeof p.prompt !== "string" || p.prompt.length === 0) {
+                        return actionFailure("invalid-action-parameters", "loop.inject requires a non-empty prompt.", 400, { field: "prompt", recovery: "Provide the prompt to inject." });
+                    }
+                    const ack = await this.#seam.runLoop({ workspaceId: env.workspaceId, workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId), prompt: p.prompt });
+                    return operationOutcome(ack);
                 }
                 // The stop button (TUI /stop + Ctrl-C, nvim :PlurnkStop): abort the model
                 // worker's active drain. Mirrors the SSE-hangup abort, addressable as a verb.
-                case "loop.cancel": return { ok: true, result: { cancelled: this.#seam.cancelDrain(convRun ?? await this.#seam.ensureModelWorker(env.workspaceId)) } };
-                case "workspace.prompts": return { ok: true, result: { prompts: await this.#seam.listPrompts(env.workspaceId, typeof p.limit === "number" ? p.limit : undefined) } };
+                case "loop.cancel": return { ok: true, result: { cancelled: this.#seam.cancelDrain(conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId)) } };
+                case "workspace.prompts": return {
+                    ok: true,
+                    result: {
+                        prompts: await this.#seam.listPrompts(env.workspaceId, Object.hasOwn(p, "limit") ? p.limit : undefined),
+                    },
+                };
                 case "workspace.rename": {
-                    if (typeof p.name !== "string" || p.name.length === 0)
-                        return { ok: false, error: "workspace.rename requires name" };
+                    if (typeof p.name !== "string" || p.name.length === 0) {
+                        return actionFailure("invalid-action-parameters", "workspace.rename requires a non-empty name.", 400, { field: "name", recovery: "Provide the new workspace name." });
+                    }
                     return { ok: true, result: await this.#seam.renameWorkspace(env.workspaceId, p.name) };
                 }
                 case "workspace.constrain": {
-                    if (typeof p.effect !== "string" || typeof p.glob !== "string")
-                        return { ok: false, error: "workspace.constrain requires effect + glob" };
+                    if (typeof p.effect !== "string" || typeof p.glob !== "string") {
+                        return actionFailure("invalid-action-parameters", "workspace.constrain requires string effect and glob parameters.", 400, { fields: ["effect", "glob"], recovery: "Provide both constraint parameters." });
+                    }
                     return { ok: true, result: await this.#seam.constrain(env.workspaceId, p.effect, p.glob) };
                 }
                 case "workspace.unconstrain": {
-                    if (typeof p.effect !== "string" || typeof p.glob !== "string")
-                        return { ok: false, error: "workspace.unconstrain requires effect + glob" };
+                    if (typeof p.effect !== "string" || typeof p.glob !== "string") {
+                        return actionFailure("invalid-action-parameters", "workspace.unconstrain requires string effect and glob parameters.", 400, { fields: ["effect", "glob"], recovery: "Provide both constraint parameters." });
+                    }
                     return { ok: true, result: await this.#seam.unconstrain(env.workspaceId, p.effect, p.glob) };
                 }
                 case "workspace.constraints": return { ok: true, result: { constraints: await this.#seam.listConstraints(env.workspaceId) } };
                 case "workspace.derivation": return { ok: true, result: { status: this.#seam.workspaceDerivationStatus(env.workspaceId) } };
                 case "entry.read": {
-                    if (typeof p.target !== "string")
-                        return { ok: false, error: "entry.read requires target" };
-                    return { ok: true, result: await this.#seam.readEntry({ workspaceId: env.workspaceId, target: p.target, ...(typeof p.channel === "string" ? { channel: p.channel } : {}), ...(typeof p.offset === "number" ? { offset: p.offset } : {}) }) };
+                    if (typeof p.target !== "string") {
+                        return actionFailure("invalid-action-parameters", "entry.read requires a string target.", 400, { field: "target", recovery: "Provide an entry URI." });
+                    }
+                    const result = Validator.assertEntryReadResult(await this.#seam.readEntry({
+                        workspaceId: env.workspaceId,
+                        workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId),
+                        target: p.target,
+                        ...(Object.hasOwn(p, "channel") ? { channel: p.channel } : {}),
+                        ...(Object.hasOwn(p, "offset") ? { offset: p.offset } : {}),
+                    }));
+                    return operationOutcome(result);
                 }
                 case "op.exec": {
                     // EXEC constructed structurally (no DSL text): the model-facing shape,
                     // proposal-gated by the engine like any client op.
-                    if (typeof p.command !== "string" || p.command.length === 0)
-                        return { ok: false, error: "op.exec requires command" };
-                    const statement = { op: "EXEC", suffix: "", signal: null, target: null, lineMarker: null, body: p.command, position: { line: 1, col: 1 } };
-                    // Client ops journal as client-origin turns in the CLIENT run (run-split:
+                    if (typeof p.command !== "string" || p.command.length === 0) {
+                        return actionFailure("invalid-action-parameters", "op.exec requires a non-empty command.", 400, { field: "command", recovery: "Provide the command to execute." });
+                    }
+                    const statement = {
+                        op: "EXEC", suffix: "", signal: null, target: null,
+                        lineMarker: null, body: p.command, position: UNKNOWN_POSITION,
+                    };
+                    // Client ops journal as client-origin turns in the client worker (worker split:
                     // only LOOPS live in the model worker).
                     const [result] = await this.#seam.dispatchClientAction({ workspaceId: env.workspaceId, workerId: env.workerId, statements: [statement] });
-                    return { ok: true, result };
+                    if (result === undefined)
+                        throw new Error("op.exec dispatch returned no operation result");
+                    return operationOutcome(result);
                 }
                 case "op.parse": {
-                    // Raw DSL parsed at the module's edge (the grammar is a family-internal
-                    // runtime dep, operator-approved) → each statement dispatched; parse
-                    // failures return as 400 results, mirroring the legacy op.parse.
-                    if (typeof p.text !== "string" || p.text.length === 0)
-                        return { ok: false, error: "op.parse requires text" };
+                    // Raw DSL is parsed at the module's edge; statements and parser facts project
+                    // through one ordered result contract. {§agui-op-parse}
+                    if (typeof p.text !== "string" || p.text.length === 0) {
+                        return actionFailure("invalid-action-parameters", "op.parse requires non-empty PLURNK text.", 400, { field: "text", recovery: "Provide PLURNK statements to parse." });
+                    }
                     const parsed = PlurnkParser.parseClient(p.text);
                     const results = [];
                     const statements = [];
                     for (const item of parsed.items) {
                         if (item.kind === "error") {
-                            results.push({ status: 400, error: String(item.error.message ?? item.error) });
+                            results.push(parseFailureResult({
+                                detail: item.error.message,
+                                line: item.error.line,
+                                column: item.error.column,
+                                source: item.error.source,
+                                severity: item.error.severity,
+                            }));
                             continue;
                         }
                         if (item.kind !== "statement")
@@ -448,6 +679,15 @@ class Module {
                         statements.push(item.statement);
                         results.push(null);
                     }
+                    if (parsed.unparsedTail !== undefined) {
+                        results.push(parseFailureResult({
+                            detail: parsed.unparsedTail.reason,
+                            line: parsed.unparsedTail.from.line,
+                            column: parsed.unparsedTail.from.column,
+                            source: "grammar",
+                            severity: "error",
+                        }));
+                    }
                     const dispatched = statements.length === 0
                         ? []
                         : await this.#seam.dispatchClientAction({ workspaceId: env.workspaceId, workerId: env.workerId, statements });
@@ -460,37 +700,64 @@ class Module {
                 }
                 case "workspace.members": return { ok: true, result: await this.#seam.listMembers(env.workspaceId) };
                 case "op.look": {
-                    // Parse at the edge; LOOK is the wire spelling of the read-projection —
-                    // rewrite to READ (Engine.look enforces READ-only).
-                    if (typeof p.text !== "string" || p.text.length === 0)
-                        return { ok: false, error: "op.look requires text" };
+                    // {§agui-op-look}
+                    if (typeof p.text !== "string" || p.text.length === 0) {
+                        return actionFailure("invalid-action-parameters", "op.look requires non-empty PLURNK text.", 400, { field: "text", recovery: "Provide one PLURNK statement to observe." });
+                    }
                     const parsed = PlurnkParser.parseClient(p.text);
-                    const item = parsed.items.find((i) => i.kind === "statement");
-                    if (item === undefined || item.kind !== "statement")
-                        return { ok: false, error: "op.look: no statement parsed" };
+                    const diagnostic = parsed.items.find((item) => item.kind === "error");
+                    if (diagnostic !== undefined && diagnostic.kind === "error") {
+                        return operationOutcome(parseFailureResult({
+                            detail: diagnostic.error.message,
+                            line: diagnostic.error.line,
+                            column: diagnostic.error.column,
+                            source: diagnostic.error.source,
+                            severity: diagnostic.error.severity,
+                        }));
+                    }
+                    if (parsed.unparsedTail !== undefined) {
+                        return operationOutcome(parseFailureResult({
+                            detail: parsed.unparsedTail.reason,
+                            line: parsed.unparsedTail.from.line,
+                            column: parsed.unparsedTail.from.column,
+                            source: "grammar",
+                            severity: "error",
+                        }));
+                    }
+                    const textItem = parsed.items.find((item) => item.kind === "text");
+                    if (textItem !== undefined && textItem.kind === "text") {
+                        return actionFailure("invalid-action-parameters", "op.look parsed text outside the statement; only surrounding whitespace is allowed.", 400, {
+                            field: "text",
+                            line: textItem.position.line,
+                            column: textItem.position.column,
+                            recovery: "Remove text outside the LOOK statement.",
+                        });
+                    }
+                    const statements = parsed.items.filter((item) => item.kind === "statement");
+                    if (statements.length !== 1) {
+                        return actionFailure("invalid-action-parameters", `op.look parsed ${statements.length} statements; exactly one LOOK statement is required.`, 400, { field: "text", recovery: "Provide exactly one valid LOOK statement." });
+                    }
+                    const [item] = statements;
+                    if (item.statement.op !== "LOOK") {
+                        return actionFailure("invalid-action-parameters", `op.look parsed ${item.statement.op}; the single statement must be LOOK.`, 400, { field: "text", recovery: "Use LOOK as the observation operation." });
+                    }
                     const statement = { ...item.statement, op: "READ" };
-                    return { ok: true, result: await this.#seam.look({ workspaceId: env.workspaceId, workerId: env.workerId, statement }) };
+                    return operationOutcome(await this.#seam.look({ workspaceId: env.workspaceId, workerId: env.workerId, statement }));
                 }
-                case "run.fork": return { ok: true, result: await this.#seam.forkWorker({ workspaceId: env.workspaceId, workerId: convRun ?? await this.#seam.ensureModelWorker(env.workspaceId), ...(typeof p.name === "string" ? { name: p.name } : {}) }) };
-                default: return { ok: false, error: `unknown action '${a.kind}'` };
+                case "run.fork": return { ok: true, result: await this.#seam.forkWorker({ workspaceId: env.workspaceId, workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId), ...(typeof p.name === "string" ? { name: p.name } : {}) }) };
+                default: return actionFailure("unknown-action", `Action '${a.kind}' is not registered.`, 404, {
+                    requestedAction: a.kind,
+                    recovery: "Use an action advertised by discover.",
+                });
             }
         }
         catch (err) {
-            return { ok: false, error: err instanceof Error ? err.message : String(err) };
-        }
-    }
-    #threadRouterReplay(workspaceId, entries) {
-        // Replay via the thread's own router (MESSAGES_SNAPSHOT of the model SENDs).
-        const messages = [];
-        for (const e of entries) {
-            if (e.op === "SEND" && e.origin === "model") {
-                const tx = e.tx;
-                const body = tx !== null && typeof tx === "object" && typeof tx.body === "string" ? tx.body : "";
-                if (body.length > 0)
-                    messages.push({ id: String(e.coordinate ?? e.id), role: "assistant", content: body });
-            }
+            const problem = problemFromError(err);
+            if (problem !== null)
+                return { ok: false, problem };
+            console.error(`AG-UI action '${a.kind}' failed:`, err);
+            return actionFailure("action-failed", "The action failed unexpectedly.", 500);
         }
-        return [{ type: EventType.MESSAGES_SNAPSHOT, messages }];
     }
     static #body(req) {
         return new Promise((resolve, reject) => {