@plurnk/plurnk-agui 1.7.0 → 1.9.0

package/dist/Module.js

@@ -1,5 +1,5 @@
 // {§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
+// activates: registerModule(aguiModule(opts)) hands this the ApplicationPort handle; it opens
 // the AG-UI+ HTTP/SSE listener and owns the client interface from there.
 //
 // This is the single external client interface:
@@ -15,11 +15,11 @@ var _a;
 import { createServer } from "node:http";
 import Portal from "./Portal.js";
 import { stateSnapshot, parseAction, actionResult } from "./AguiPlus.js";
-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 { Problems, Validator } from "@plurnk/plurnk-contracts";
+import { Problems, PlurnkParser, UNKNOWN_POSITION, Validator, } from "@plurnk/plurnk-contracts";
+import { AGUI_BUILTIN_ACTIONS, AGUI_NOTIFICATIONS, } from "./AguiSurface.js";
 import { resolveModuleOptions } from "./config.js";
 const actionFailure = (code, detail, status = 400, extensions = {}) => ({
     ok: false,
@@ -95,50 +95,62 @@ class Module {
     #http;
     #threads = new Map(); // threadId → envelope
     #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. Only these kinds bind a workspace.
-    static #WORLD_SCOPED = Object.freeze(new Set([
-        "workspace.workers", "log.read", "loop.inject", "loop.cancel", "workspace.prompts", "workspace.rename",
-        "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", "loop/interaction", "notice/event",
-        "stream/event", "stream/concluded", "workspace/branch-batch",
-    ]);
+    #actions = new Map();
     constructor(seam, opts) {
         this.#seam = seam;
         this.#opts = resolveModuleOptions(opts);
-        this.#moduleActions();
+        this.#registerActions();
         this.#portal = new Portal(seam);
         this.#http = createServer((req, res) => { void this.#route(req, res); });
     }
-    #moduleActions() {
-        const actions = new Map();
+    #registerActions() {
+        for (const [name, contract] of Object.entries(AGUI_BUILTIN_ACTIONS)) {
+            this.#actions.set(name, {
+                ...contract,
+                execute: (params, env, conversationWorkerId) => this.#executeBuiltin(name, params, env, conversationWorkerId),
+            });
+        }
         for (const descriptor of this.#seam.listModuleActions()) {
-            const { name, scope } = descriptor;
-            if (_a.#BUILTIN_ACTIONS.has(name)) {
-                throw new Error(`module action '${name}' collides with AG-UI built-in action`);
-            }
-            if (scope !== "worldless" && scope !== "workspace") {
+            const { name, scope, inputSchema, outputSchema } = descriptor;
+            if (this.#actions.has(name))
+                throw new Error(`AG-UI action '${name}' is registered more than once`);
+            if (scope !== "worldless" && scope !== "workspace" && scope !== "worker") {
                 throw new Error(`module action '${name}' has invalid scope '${String(scope)}'`);
             }
-            if (actions.has(name))
-                throw new Error(`module action '${name}' is registered more than once`);
-            actions.set(name, descriptor);
+            this.#actions.set(name, {
+                scope,
+                inputSchema,
+                outputSchema,
+                execute: async (params, env, conversationWorkerId) => {
+                    if (scope === "worldless") {
+                        return {
+                            ok: true,
+                            result: await this.#seam.invokeModuleAction(name, params, { scope }),
+                        };
+                    }
+                    const { workspaceId } = _a.#requireWorkspace(name, env);
+                    if (scope === "workspace") {
+                        return {
+                            ok: true,
+                            result: await this.#seam.invokeModuleAction(name, params, { scope, workspaceId }),
+                        };
+                    }
+                    const workerId = conversationWorkerId ?? await this.#seam.ensureModelWorker(workspaceId);
+                    return {
+                        ok: true,
+                        result: await this.#seam.invokeModuleAction(name, params, { scope, workspaceId, workerId }),
+                    };
+                },
+            });
         }
-        return actions;
     }
-    #isWorkspaceAction(kind) {
-        return _a.#WORLD_SCOPED.has(kind) || this.#moduleActions().get(kind)?.scope === "workspace";
+    #requiresWorkspace(kind) {
+        return this.#actions.get(kind)?.scope !== "worldless";
+    }
+    static #requireWorkspace(kind, env) {
+        if (env === null)
+            throw new Error(`action '${kind}' operates within a workspace, but none is bound`);
+        return env;
     }
     static init(opts) {
         return {
@@ -267,15 +279,20 @@ class Module {
         return { env, reattached };
     }
     // Resolve the thread's conversation worker within its world. Cached per threadId;
-    // worker names are immutable so the binding can't rot.
-    async #conversationWorker(threadId, env) {
+    // worker names are immutable so the binding can't rot. {§worker-settings} — the
+    // client's per-run declaration (forwardedProps.plurnk.requestUserInput) rides the
+    // resolution, so a client can change its mind between loops.
+    async #conversationWorker(threadId, env, settings) {
         const cached = this.#threadWorkers.get(threadId);
-        if (cached !== undefined)
+        if (cached !== undefined) {
+            if (settings !== undefined)
+                await this.#seam.setWorkerSettings({ workspaceId: env.workspaceId, workerId: cached, settings });
             return cached;
+        }
         const workerId = threadId === env.workspaceName
-            ? await this.#seam.ensureModelWorker(env.workspaceId)
+            ? await this.#seam.ensureModelWorker(env.workspaceId, settings)
             : (await this.#seam.listWorkers(env.workspaceId)).find((r) => r.name === threadId)?.id
-                ?? (await this.#seam.createConversationWorker({ workspaceId: env.workspaceId, name: threadId })).workerId;
+                ?? (await this.#seam.createConversationWorker({ workspaceId: env.workspaceId, name: threadId, ...(settings === undefined ? {} : { settings }) })).workerId;
         this.#threadWorkers.set(threadId, workerId);
         return workerId;
     }
@@ -301,7 +318,7 @@ class Module {
         // unknown kind, which is no worker at all) answers without binding — or forging — a
         // workspace. Only world-scoped actions and conversations reach #envelope below.
         const action = parseAction(input.forwardedProps);
-        if (action !== null && !this.#isWorkspaceAction(action.kind)) {
+        if (action !== null && !this.#requiresWorkspace(action.kind)) {
             return await this.#controlRun(action, input, res);
         }
         let prompt = null;
@@ -322,7 +339,9 @@ class Module {
         // 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.#conversationWorker(input.threadId, env);
+        const plurnk = forwarded?.plurnk;
+        const requestUserInput = plurnk?.requestUserInput;
+        const workerId = await this.#conversationWorker(input.threadId, env, typeof requestUserInput === "boolean" ? { requestUserInput } : undefined);
         res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", "connection": "keep-alive" });
         let finished = false;
         const interrupts = [];
@@ -434,20 +453,15 @@ class Module {
                 ...(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.
-                ...(forwarded !== undefined && Object.hasOwn(forwarded, "alias")
-                    ? { alias: forwarded.alias }
-                    : {}),
-                ...(forwarded !== undefined && Object.hasOwn(forwarded, "model")
-                    ? { model: forwarded.model }
+                // {§methods-loop-run-model} The client may still forward one explicit
+                // alias-or-provider/model selector. The daemon
+                // persists an explicit selection onto the worker and snapshots it on the
+                // loop; an omitted selector continues the worker's durable model.
+                ...(forwarded !== undefined && Object.hasOwn(forwarded, "selector")
+                    ? { selector: forwarded.selector }
                     : {}),
-                ...(forwarded !== undefined && Object.hasOwn(forwarded, "childAlias")
-                    ? { childAlias: forwarded.childAlias }
-                    : {}),
-                ...(forwarded !== undefined && Object.hasOwn(forwarded, "childModel")
-                    ? { childModel: forwarded.childModel }
+                ...(forwarded !== undefined && Object.hasOwn(forwarded, "childSelector")
+                    ? { childSelector: forwarded.childSelector }
                     : {}),
             });
             // A dropped SSE on a live AG-UI Run cancels the loop (hangup is the abort). A stream we
@@ -493,38 +507,72 @@ class Module {
         emit({ type: EventType.RUN_FINISHED, threadId: input.threadId, runId: input.runId, outcome: { type: "success" } });
         res.end();
     }
-    // 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.
+    // Discovery is a projection of the executable registry, not a second inventory.
     async #capabilities() {
-        const methods = {};
-        for (const k of [
-            ..._a.#CONTROL_ACTIONS,
-            ..._a.#WORLD_SCOPED,
-            ...this.#moduleActions().keys(),
-        ]) {
-            if (methods[k])
-                throw new Error(`AG-UI action '${k}' is registered more than once`);
-            methods[k] = true;
-        }
-        const notifications = {};
-        for (const n of _a.#NOTIFICATIONS)
-            notifications[n] = true;
+        const actions = Object.fromEntries([...this.#actions].map(([name, action]) => [
+            name,
+            {
+                scope: action.scope,
+                inputSchema: action.inputSchema,
+                outputSchema: action.outputSchema,
+            },
+        ]));
         const display = Validator.assertClientDisplayCapabilities(await this.#seam.listClientDisplayCapabilities());
-        return { methods, notifications, display };
+        return Validator.assertAguiDiscovery({
+            schemaVersion: 1,
+            actions,
+            notifications: AGUI_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, conversationWorkerId) {
-        const p = a.params;
-        const moduleAction = this.#moduleActions().get(a.kind);
+        const action = this.#actions.get(a.kind);
+        if (action === undefined) {
+            return actionFailure("unknown-action", `Action '${a.kind}' is not registered.`, 404, {
+                requestedAction: a.kind,
+                recovery: "Use an action advertised by discover.",
+            });
+        }
+        const admitted = Validator.validateJsonSchemaInstance(action.inputSchema, a.params);
+        if (!admitted.valid) {
+            return actionFailure("invalid-action-parameters", `Action '${a.kind}' received parameters outside its advertised input schema.`, 400, {
+                issues: admitted.errors,
+                recovery: "Conform the action parameters to discover.actions[<name>].inputSchema.",
+            });
+        }
+        try {
+            if (action.scope !== "worldless")
+                _a.#requireWorkspace(a.kind, env);
+            const outcome = await action.execute(a.params, env, conversationWorkerId);
+            if (!outcome.ok)
+                return outcome;
+            const projected = Validator.validateJsonSchemaInstance(action.outputSchema, outcome.result);
+            if (!projected.valid) {
+                throw new Error(`AG-UI action '${a.kind}' produced output outside its advertised schema: ${JSON.stringify(projected.errors)}`);
+            }
+            return outcome;
+        }
+        catch (err) {
+            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);
+        }
+    }
+    // The built-in implementation half of the declarative registry. The registry
+    // owns membership, scope, admission, projection, and discovery; this dispatch
+    // owns only the corresponding daemon operation.
+    async #executeBuiltin(kind, p, env, conversationWorkerId) {
         try {
-            // The control plane — worldless verbs (no bound workspace; #WORLD_SCOPED gates this).
-            switch (a.kind) {
+            // Worldless actions never bind or forge a workspace.
+            switch (kind) {
                 case "ping": return { ok: true, result: {} };
                 case "discover": return { ok: true, result: await this.#capabilities() };
                 case "providers.list": return { ok: true, result: this.#seam.listProviders() };
+                case "models.list": {
+                    return { ok: true, result: this.#seam.listModels(Validator.assertModelCatalogQuery(p)) };
+                }
                 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
@@ -567,35 +615,14 @@ class Module {
                     return { ok: true, result: { id: att.workspaceId, name: att.workspaceName, workerId: att.workerId } };
                 }
             }
-            if (moduleAction?.scope === "worldless") {
-                return {
-                    ok: true,
-                    result: await this.#seam.invokeModuleAction(a.kind, p, { scope: "worldless" }),
-                };
-            }
-            // 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) && moduleAction?.scope !== "workspace") {
-                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`);
-            if (moduleAction?.scope === "workspace") {
-                return {
-                    ok: true,
-                    result: await this.#seam.invokeModuleAction(a.kind, p, { scope: "workspace", workspaceId: env.workspaceId }),
-                };
-            }
-            switch (a.kind) {
-                case "workspace.workers": return { ok: true, result: { workers: await this.#seam.listWorkers(typeof p.id === "number" ? p.id : env.workspaceId) } };
+            const world = _a.#requireWorkspace(kind, env);
+            switch (kind) {
+                case "workspace.workers": return { ok: true, result: { workers: await this.#seam.listWorkers(typeof p.id === "number" ? p.id : world.workspaceId) } };
                 case "log.read": {
                     // Default worker: the conversation; p.workerId pins another.
-                    const readWorkerId = typeof p.workerId === "number" ? p.workerId : conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId);
+                    const readWorkerId = typeof p.workerId === "number" ? p.workerId : conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId);
                     const entries = await this.#seam.readLog({
-                        workspaceId: env.workspaceId,
+                        workspaceId: world.workspaceId,
                         workerId: readWorkerId,
                         ...(Object.hasOwn(p, "limit") ? { limit: p.limit } : {}),
                         ...(Object.hasOwn(p, "sinceId") ? { sinceId: p.sinceId } : {}),
@@ -611,38 +638,38 @@ class Module {
                     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 });
+                    const ack = await this.#seam.runLoop({ workspaceId: world.workspaceId, workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.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(conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId)) } };
+                case "loop.cancel": return { ok: true, result: { cancelled: this.#seam.cancelDrain(conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId), typeof p.reason === "string" ? p.reason : undefined) } };
                 case "workspace.prompts": return {
                     ok: true,
                     result: {
-                        prompts: await this.#seam.listPrompts(env.workspaceId, Object.hasOwn(p, "limit") ? p.limit : undefined),
+                        prompts: await this.#seam.listPrompts(world.workspaceId, Object.hasOwn(p, "limit") ? p.limit : undefined),
                     },
                 };
                 case "workspace.rename": {
                     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) };
+                    return { ok: true, result: await this.#seam.renameWorkspace(world.workspaceId, p.name) };
                 }
                 case "workspace.constrain": {
                     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) };
+                    return { ok: true, result: await this.#seam.constrain(world.workspaceId, p.effect, p.glob) };
                 }
                 case "workspace.unconstrain": {
                     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) };
+                    return { ok: true, result: await this.#seam.unconstrain(world.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 "workspace.constraints": return { ok: true, result: { constraints: await this.#seam.listConstraints(world.workspaceId) } };
+                case "workspace.derivation": return { ok: true, result: { status: this.#seam.workspaceDerivationStatus(world.workspaceId) } };
                 case "entry.read": {
                     if (typeof p.target !== "string") {
                         return actionFailure("invalid-action-parameters", "entry.read requires a string target.", 400, { field: "target", recovery: "Provide an entry URI." });
@@ -652,10 +679,10 @@ class Module {
                         return actionFailure("invalid-action-parameters", "entry.read workerId must be a positive integer.", 400, { field: "workerId", recovery: "Use the workerId supplied with the entry notification." });
                     }
                     const result = Validator.assertEntryReadResult(await this.#seam.readEntry({
-                        workspaceId: env.workspaceId,
+                        workspaceId: world.workspaceId,
                         workerId: typeof p.workerId === "number"
                             ? p.workerId
-                            : conversationWorkerId ?? await this.#seam.ensureModelWorker(env.workspaceId),
+                            : conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
                         target: p.target,
                         ...(Object.hasOwn(p, "channel") ? { channel: p.channel } : {}),
                         ...(Object.hasOwn(p, "offset") ? { offset: p.offset } : {}),
@@ -669,12 +696,18 @@ class Module {
                         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,
+                        op: "EXEC", delimiter: "", annotation: null, 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] });
+                    // only LOOPS live in the model worker) and execute in the attached Worker's
+                    // Functionality ({§actor-boundary-attached-functionality}).
+                    const [result] = await this.#seam.dispatchClientAction({
+                        workspaceId: world.workspaceId,
+                        workerId: world.workerId,
+                        functionalityWorkerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                        statements: [statement],
+                    });
                     if (result === undefined)
                         throw new Error("op.exec dispatch returned no operation result");
                     return operationOutcome(result);
@@ -715,7 +748,12 @@ class Module {
                     }
                     const dispatched = statements.length === 0
                         ? []
-                        : await this.#seam.dispatchClientAction({ workspaceId: env.workspaceId, workerId: env.workerId, statements });
+                        : await this.#seam.dispatchClientAction({
+                            workspaceId: world.workspaceId,
+                            workerId: world.workerId,
+                            functionalityWorkerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                            statements,
+                        });
                     let index = 0;
                     for (let i = 0; i < results.length; i++) {
                         if (results[i] === null)
@@ -723,7 +761,7 @@ class Module {
                     }
                     return { ok: true, result: { results } };
                 }
-                case "workspace.members": return { ok: true, result: await this.#seam.listMembers(env.workspaceId) };
+                case "workspace.members": return { ok: true, result: await this.#seam.listMembers(world.workspaceId) };
                 case "op.look": {
                     // {§agui-op-look}
                     if (typeof p.text !== "string" || p.text.length === 0) {
@@ -767,20 +805,82 @@ class Module {
                         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 operationOutcome(await this.#seam.look({ workspaceId: env.workspaceId, workerId: env.workerId, statement }));
+                    return operationOutcome(await this.#seam.look({
+                        workspaceId: world.workspaceId,
+                        workerId: world.workerId,
+                        functionalityWorkerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                        statement,
+                    }));
                 }
-                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.",
-                });
+                case "run.fork": return { ok: true, result: await this.#seam.forkWorker({ workspaceId: world.workspaceId, workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId), ...(typeof p.name === "string" ? { name: p.name } : {}) }) };
+                case "worker.model.get": {
+                    const { model, spawnModel } = await this.#seam.readWorkerModel({
+                        workspaceId: world.workspaceId,
+                        workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                    });
+                    return { ok: true, result: { model, spawnModel } };
+                }
+                case "worker.model.set": {
+                    if (typeof p.selector !== "string" || p.selector.length === 0) {
+                        return actionFailure("invalid-action-parameters", "worker.model.set requires a selector.", 400, { recovery: "Provide a declared alias or provider/model route." });
+                    }
+                    return { ok: true, result: await this.#seam.setWorkerModel({
+                            workspaceId: world.workspaceId,
+                            workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                            selector: p.selector,
+                        }) };
+                }
+                case "worker.child.set": {
+                    if (!Object.hasOwn(p, "selector")
+                        || (p.selector !== null && (typeof p.selector !== "string" || p.selector.length === 0))) {
+                        return actionFailure("invalid-action-parameters", "worker.child.set requires a selector.", 400, { recovery: "Provide a declared alias or provider/model route; null means inherit." });
+                    }
+                    return { ok: true, result: await this.#seam.setWorkerSpawnModel({
+                            workspaceId: world.workspaceId,
+                            workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                            selector: p.selector,
+                        }) };
+                }
+                case "worker.reasoning.get": {
+                    return { ok: true, result: await this.#seam.readWorkerReasoning({
+                            workspaceId: world.workspaceId,
+                            workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                        }) };
+                }
+                case "worker.reasoning.set": {
+                    if (!Object.hasOwn(p, "policy")) {
+                        return actionFailure("invalid-action-parameters", "worker.reasoning.set requires a policy.", 400, { recovery: "Provide a reasoning policy." });
+                    }
+                    return { ok: true, result: await this.#seam.setWorkerReasoning({
+                            workspaceId: world.workspaceId,
+                            workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                            policy: p.policy,
+                        }) };
+                }
+                case "worker.settings.get": {
+                    return { ok: true, result: await this.#seam.readWorkerSettings({
+                            workspaceId: world.workspaceId,
+                            workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                        }) };
+                }
+                case "worker.settings.set": {
+                    if (typeof p.settings !== "object" || p.settings === null || Array.isArray(p.settings)) {
+                        return actionFailure("invalid-action-parameters", "worker.settings.set requires a settings object.", 400, { recovery: "Provide a settings object, e.g. { requestUserInput: true }." });
+                    }
+                    return { ok: true, result: await this.#seam.setWorkerSettings({
+                            workspaceId: world.workspaceId,
+                            workerId: conversationWorkerId ?? await this.#seam.ensureModelWorker(world.workspaceId),
+                            settings: p.settings,
+                        }) };
+                }
+                default: throw new Error(`AG-UI built-in '${kind}' has no executor`);
             }
         }
         catch (err) {
             const problem = problemFromError(err);
             if (problem !== null)
                 return { ok: false, problem };
-            console.error(`AG-UI action '${a.kind}' failed:`, err);
+            console.error(`AG-UI action '${kind}' failed:`, err);
             return actionFailure("action-failed", "The action failed unexpectedly.", 500);
         }
     }