@plurnk/plurnk-service 1.8.0 → 1.9.0

package/dist/server/Daemon.js

@@ -19,11 +19,11 @@ import LogEntry from "./logEntry.js";
 import Envelope from "./envelope.js";
 import ClientInput from "./client-input.js";
 import Turn from "../core/Turn.js";
-import LoopDocs from "./loopDocs.js";
-import SkillDocs from "./skillDocs.js";
+import SkillsFunctionality from "./SkillsFunctionality.js";
 import GitMembership from "../core/git-membership.js";
 import Fork from "../core/fork.js";
 import WorkerName from "../core/WorkerName.js";
+import WorkerControlAddress from "../core/WorkerControlAddress.js";
 import LoopLifecycle from "../core/LoopLifecycle.js";
 import { promptLoopPrefix } from "../core/plurnk-uri.js";
 import { contentWeight } from "../core/content-weight.js";
@@ -33,7 +33,9 @@ import { resolveLoopRoute } from "./loop-model.js";
 import LoopFlagsReader from "../core/LoopFlagsReader.js";
 import Results, { OperationFailureError } from "../core/results.js";
 import WorkspaceGate from "../core/WorkspaceGate.js";
+import WorkerResidency from "./WorkerResidency.js";
 import BranchBatches from "./BranchBatches.js";
+import Functionality from "./Functionality.js";
 import { observed, observedSync } from "../observe/spans.js";
 import { listModelCatalog } from "./model-catalog.js";
 const clientActionFailure = (error) => {
@@ -64,16 +66,17 @@ export default class Daemon {
     #nodeModulesPath;
     #discoveryCwd;
     #started = false; // {§module-lifecycle}: one discovery/module boot; no listener
-    #capabilitiesPublished = false;
     #modules = [];
     #moduleClosers = [];
     #moduleActions = new Map();
-    #workspaceCapabilityProviders = new Map();
+    #residency;
+    #functionality;
+    #skills;
     // {§methods-event-subscribe} — the broadcast's in-process event source. A transport
     // module (plurnk-agui) subscribes and fans out to its OWN clients; core emits, never owns
     // client transport or connection state.
     #eventSubscribers = new Set();
-    constructor({ db, schemes, mimetypes, provider, nodeModulesPath, }) {
+    constructor({ db, schemes, mimetypes, provider, nodeModulesPath, skills, }) {
         this.#db = db;
         this.#lifecycle = new LoopLifecycle(db);
         this.#schemes = schemes ?? new SchemeRegistry();
@@ -104,6 +107,26 @@ export default class Daemon {
             });
             return row !== undefined;
         });
+        // {§module-worker-residency} — residency, activation/cooling, and
+        // capability replacement live in their one owner; the Daemon delegates.
+        this.#residency = new WorkerResidency({
+            db,
+            engine: () => this.#engine,
+            workspaceGate: this.#workspaceGate,
+            normalizeRuntime: (registration) => this.#normalizeRuntime(registration),
+        });
+        // {§functionality-coordinator} — the one owner above every family
+        // adapter; Core hosts it, modules register adapters through the seam.
+        this.#functionality = new Functionality({
+            registerModuleAction: (registration) => this.registerModuleAction(registration),
+            registerWorkerCapabilityProvider: (owner, provider) => this.registerWorkerCapabilityProvider(owner, provider),
+            readWorkerModuleState: (workerId, owner) => this.readWorkerModuleState(workerId, owner),
+            replaceWorkerCapabilities: (replacement, options) => this.replaceWorkerCapabilities(replacement, options),
+            retainWorker: (workerId) => this.#residency.retain(workerId),
+        });
+        // {§skills-functionality} — Core's own family: standard Agent Skills.
+        this.#skills = new SkillsFunctionality({ db, ...skills });
+        this.#skills.attach(this.#functionality.register(this.#skills));
         this.#branchBatches = new BranchBatches(db, this.#workspaceGate, {
             settleWorkspace: async (workspaceId) => this.#engine.drainWorkspaceDerivations(workspaceId),
             createChild: async ({ workspaceId, parentWorkerId, parentLoopId, op, name, prompt, flags, origin }) => {
@@ -111,12 +134,13 @@ export default class Daemon {
                 const providerSpec = parentPolicy.childProviderSpec ?? parentPolicy.providerSpec;
                 const workerName = WorkerName.assert(name);
                 const workerId = op === "FORK"
-                    ? await Fork.fork(this.#db, parentWorkerId, workerName)
+                    ? await Fork.fork(this.#db, parentWorkerId, workerName, (scheme) => this.#schemes.entryInheritanceForStoredScheme(scheme, parentWorkerId))
                     : (await this.#db.fork_insert_worker.get({
                         workspace_id: workspaceId,
                         name: workerName,
                         parent_worker_id: parentWorkerId,
                         origin,
+                        fork_snapshot: 0,
                     }))?.id;
                 if (workerId === undefined)
                     throw new Error("Branch worker insert returned no row");
@@ -128,9 +152,11 @@ export default class Daemon {
                     spawn_model_route_id: null,
                     reasoning_policy: parentPolicy.reasoningPolicy,
                 });
+                const source = await this.#workerPromptSource(workspaceId, parentWorkerId, workerId);
                 const loopId = await this.#drains.enqueueFreshLoop({
                     workerId,
                     prompt,
+                    ...(source === undefined ? {} : { source }),
                     providerSpec,
                     reasoningPolicy: parentPolicy.reasoningPolicy,
                     childProviderSpec: parentPolicy.childProviderSpec,
@@ -164,13 +190,16 @@ export default class Daemon {
             // model-independent. Request-shaped token facts stay provider-owned.
             weigh: contentWeight,
             streamEventNotify: (workspaceId, event) => this.notifyStreamEvent(workspaceId, event),
+            reasoningEventNotify: (workspaceId, event) => this.notifyReasoningEvent(workspaceId, event),
             wakeWorkerNotify: (payload) => this.#drains.notifyWakeWorker(payload),
             // worker:// loop-start primitive — spawn/fork/irc deliver through
             // Daemon.inject (active sister → fold; idle → enqueue + drain). The
             // daemon owns provider + the law-file system prompt; the worker scheme
             // handler carries neither. Fire-and-forget: the returned drain runs
             // independently (the sister is its own worker). {§machine-processes}
-            injectWorker: async ({ workspaceId, workerId, prompt, flags, parentLoopId }) => {
+            injectWorker: async ({ workspaceId, workerId, sourceWorkerId, prompt, flags, parentLoopId }) => {
+                await this.#assertModelWorker(workspaceId, workerId);
+                const source = await this.#workerPromptSource(workspaceId, sourceWorkerId, workerId);
                 const systemPrompt = await readFile(Paths.instructionsSystem, "utf8");
                 let providerSpec;
                 let childProviderSpec;
@@ -207,6 +236,7 @@ export default class Daemon {
                     workspaceId,
                     workerId,
                     prompt,
+                    ...(source === undefined ? {} : { source }),
                     providerSpec,
                     reasoningPolicy,
                     childProviderSpec,
@@ -218,11 +248,11 @@ export default class Daemon {
             branchWorker: async (args) => this.#branchBatches.enqueue(args),
             branchCompletionGate: async (workerId) => this.#branchBatches.completionGate(workerId),
             acquireWorkspaceTurn: async (workspaceId, workerId) => this.#workspaceGate.acquireTurn(workspaceId, workerId),
-            // {§skills-materialization} — filesystem installers operate out of
-            // band. Refresh under the workspace turn gate before packet assembly
-            // so the first subsequent model turn sees their exact result.
-            workspaceTurnStarting: async ({ workspaceId }) => {
-                await SkillDocs.refreshIfChanged(this.#engine, this.#db, workspaceId);
+            // {§skills-hotload} — filesystem installers operate out of band.
+            // Republish under the workspace turn gate before packet assembly so
+            // the first subsequent model turn sees their exact result.
+            workspaceTurnStarting: async ({ workspaceId, workerId }) => {
+                await this.#skills.refreshIfChanged({ workspaceId, workerId });
             },
             workspaceTurnCompleted: async ({ turnId }) => {
                 await this.#branchBatches.sealTurn(turnId);
@@ -236,7 +266,7 @@ export default class Daemon {
         this.#drains = new DrainSupervisor({
             db,
             lifecycle: this.#lifecycle,
-            injectPrompt: (workerId, prompt, openPaths) => this.#engine.inject(workerId, prompt, openPaths),
+            injectPrompt: (workerId, prompt, openPaths, source) => this.#engine.inject(workerId, prompt, openPaths, source),
             assertInjectionCompatibility: async ({ workerId, loopId, providerSpec, providerSpecExplicit, reasoningPolicy, childProviderSpec, turnCeiling, flags, }) => {
                 await this.#assertFoldPosture(workerId, flags, loopId);
                 // An omitted selector keeps the loop's durable provider; only an
@@ -252,21 +282,34 @@ export default class Daemon {
             },
             reconcilePrompts: (workerId, endedLoopId) => this.#reconcileOrphanedPrompts(workerId, endedLoopId),
             runLoop: async ({ workspaceId, workerId, loopId, maxTurns, prompt, systemPrompt, signal, onDispatch, }) => {
-                const { provider, childProvider } = await this.#providersForLoop(loopId);
-                return this.#engine.runLoop({
-                    provider,
-                    childProvider,
-                    workspaceId,
-                    workerId,
-                    loopId,
-                    maxTurns,
-                    messages: [
-                        { role: "system", content: systemPrompt },
-                        { role: "user", content: prompt },
-                    ],
-                    signal,
-                    onDispatch,
-                });
+                // The drain callback is the final provider/model boundary. Every
+                // admission path, including boot recovery, terminates here.
+                await this.#assertModelWorker(workspaceId, workerId);
+                const releaseCapabilities = await this.#residency.acquire(workspaceId, workerId);
+                try {
+                    // Worker settings can change while Functionality remains
+                    // resident. Reconcile the worker-private discovery surface
+                    // at the same pre-inference boundary used for activation.
+                    await this.#residency.reconcile(workspaceId, workerId);
+                    const { provider, childProvider } = await this.#providersForLoop(loopId);
+                    return await this.#engine.runLoop({
+                        provider,
+                        childProvider,
+                        workspaceId,
+                        workerId,
+                        loopId,
+                        maxTurns,
+                        messages: [
+                            { role: "system", content: systemPrompt },
+                            { role: "user", content: prompt },
+                        ],
+                        signal,
+                        onDispatch,
+                    });
+                }
+                finally {
+                    releaseCapabilities();
+                }
             },
             loopUsage: (loopId) => this.#engine.loopUsage(loopId),
             loopAttributions: (loopId) => this.#engine.loopAttributions(loopId),
@@ -333,7 +376,9 @@ export default class Daemon {
     async runLoop(args) {
         const workspaceId = ClientInput.assertId("runLoop", "workspaceId", args.workspaceId);
         const workerId = ClientInput.assertId("runLoop", "workerId", args.workerId);
+        await this.#assertModelWorker(workspaceId, workerId);
         const prompt = ClientInput.assertPrompt("runLoop", args.prompt);
+        const source = ClientInput.assertOptionalSource("runLoop", args.source);
         const requestedMaxTurns = ClientInput.assertMaxTurns("runLoop", args.maxTurns);
         const openPaths = ClientInput.assertOpenPaths("runLoop", args.openPaths);
         const selector = ClientInput.assertOptionalSelector("runLoop", "selector", args.selector);
@@ -356,28 +401,6 @@ export default class Daemon {
         // {§methods-loop-run-child-provider} — the worker's persistent spawn override.
         const childSelection = await this.#resolveWorkerSpawnModel(workerId, childSelector);
         const systemPrompt = await readFile(Paths.instructionsSystem, "utf8");
-        // {§machine-processes} — the model NEVER runs in a client-origin worker (its packets would carry
-        // client-action rows). The module resolves the model worker via ensureModelWorker and passes it (or a
-        // fork); a client worker here is a caller error, refused loudly rather than silently rehomed.
-        const target = await this.#db.envelope_get_worker_by_id.get({ id: workerId });
-        if (target === undefined) {
-            throw daemonFailure("daemon:worker", "worker-not-found", 404, `Worker ${workerId} does not exist.`, { workerId });
-        }
-        if (target.workspace_id !== workspaceId) {
-            throw daemonFailure("daemon:worker", "workspace-mismatch", 409, `Worker ${workerId} does not belong to workspace ${workspaceId}.`, {
-                workerId,
-                workspaceId,
-                actualWorkspaceId: target.workspace_id,
-                retryable: false,
-            });
-        }
-        if (target.origin === "client") {
-            throw daemonFailure("daemon:worker", "model-worker-required", 409, `Worker ${workerId} is not a model worker.`, {
-                workerId,
-                recovery: "Select or create a model worker for this loop.",
-                retryable: false,
-            });
-        }
         // {§operator-config-max-turns-ceiling} — the operator ceiling clamps a per-call maxTurns; a
         // seam caller must not bypass operator policy (inject only DEFAULTS from env, never clamps).
         const ceiling = Number(process.env.PLURNK_SERVICE_MAX_TURNS ?? "-1");
@@ -391,6 +414,7 @@ export default class Daemon {
             workspaceId,
             workerId,
             prompt,
+            ...(source === undefined ? {} : { source }),
             ...(flags !== undefined ? { flags } : {}),
             ...(openPaths !== undefined ? { openPaths } : {}),
             turnCeiling,
@@ -819,24 +843,71 @@ export default class Daemon {
             throw daemonFailure("daemon:worker", "workspace-mismatch", 409, `Worker ${workerId} does not belong to workspace ${workspaceId}.`, { workerId, workspaceId, actualWorkspaceId: owner.workspace_id });
         }
     }
+    // {§machine-processes} — provider inference is an exclusive capability of a
+    // model worker. The same assertion is used by early client admissions and
+    // the final drain callback, so recovery and internal callers cannot bypass it.
+    async #assertModelWorker(workspaceId, workerId) {
+        const worker = await this.#db.envelope_get_worker_by_id.get({ id: workerId });
+        if (worker === undefined) {
+            throw daemonFailure("daemon:worker", "worker-not-found", 404, `Worker ${workerId} does not exist.`, { workerId });
+        }
+        if (worker.workspace_id !== workspaceId) {
+            throw daemonFailure("daemon:worker", "workspace-mismatch", 409, `Worker ${workerId} does not belong to workspace ${workspaceId}.`, {
+                workerId,
+                workspaceId,
+                actualWorkspaceId: worker.workspace_id,
+                retryable: false,
+            });
+        }
+        if (worker.origin !== "model") {
+            throw daemonFailure("daemon:worker", "model-worker-required", 409, `Worker ${workerId} is not a model worker.`, {
+                workerId,
+                actualOrigin: worker.origin,
+                recovery: "Select or create a model worker for this loop.",
+                retryable: false,
+            });
+        }
+    }
+    async #workerPromptSource(workspaceId, sourceWorkerId, targetWorkerId) {
+        if (sourceWorkerId === targetWorkerId)
+            return undefined;
+        const source = await this.#db.envelope_get_worker_by_id.get({ id: sourceWorkerId });
+        if (source === undefined || source.workspace_id !== workspaceId) {
+            throw new Error(`Worker prompt source ${sourceWorkerId} does not belong to workspace ${workspaceId}.`);
+        }
+        return WorkerControlAddress.render(source.name);
+    }
     // {§methods-op-mirror} — execute parsed ops on behalf of a client as a
     // client-origin turn (the log is core's, a client op is a first-class citizen), dispatched through
     // the engine, then emitted as log/entry on the event source. One seam op backs the whole op_*
     // family (read/edit/copy/find/fold/look/move/open/send/exec); the module parses at its edge with the
     // grammar package and hands over the statement, then fans the emitted entry out to its own clients.
+    // {§functionality-model-mutation} — await every queued Functionality
+    // publication (a Worker's accepted mutation publishes at its turn boundary).
+    async settleFunctionality(workerId) {
+        await this.#functionality.settle(workerId);
+    }
     async dispatchAsClient(args) {
         const workspaceId = ClientInput.assertId("operation.dispatch", "workspaceId", args.workspaceId);
         const workerId = ClientInput.assertId("operation.dispatch", "workerId", args.workerId);
+        const functionalityWorkerId = ClientInput.assertId("operation.dispatch", "functionalityWorkerId", args.functionalityWorkerId);
         const { statement } = args;
-        const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
+        await this.#assertWorkerOwned(workspaceId, functionalityWorkerId);
+        const releaseCapabilities = await this.#residency.acquire(workspaceId, functionalityWorkerId);
         try {
-            const result = await this.#dispatchClientStatement({ workspaceId, workerId, loopId: clientLoopId, statement });
-            await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
-            return result;
+            const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
+            try {
+                const result = await this.#dispatchClientStatement({ workspaceId, workerId, functionalityWorkerId, loopId: clientLoopId, statement });
+                await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
+                return result;
+            }
+            catch (error) {
+                await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
+                throw error;
+            }
         }
-        catch (error) {
-            await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
-            throw error;
+        finally {
+            releaseCapabilities();
         }
     }
     // The client-interface action contract: one AG-UI action owns one administrative
@@ -846,25 +917,35 @@ export default class Daemon {
     async dispatchClientAction(args) {
         const workspaceId = ClientInput.assertId("operation.dispatch-batch", "workspaceId", args.workspaceId);
         const workerId = ClientInput.assertId("operation.dispatch-batch", "workerId", args.workerId);
+        const functionalityWorkerId = ClientInput.assertId("operation.dispatch-batch", "functionalityWorkerId", args.functionalityWorkerId);
         const { statements } = args;
         if (statements.length === 0)
             return [];
-        const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
+        await this.#assertWorkerOwned(workspaceId, functionalityWorkerId);
+        // {§actor-boundary-attached-functionality} — the attached Worker's
+        // Functionality is what the client operation executes in.
+        const releaseCapabilities = await this.#residency.acquire(workspaceId, functionalityWorkerId);
         try {
-            const results = [];
-            for (const statement of statements) {
-                results.push(await this.#dispatchClientStatement({ workspaceId, workerId, loopId: clientLoopId, statement }));
+            const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
+            try {
+                const results = [];
+                for (const statement of statements) {
+                    results.push(await this.#dispatchClientStatement({ workspaceId, workerId, functionalityWorkerId, loopId: clientLoopId, statement }));
+                }
+                await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
+                return results;
+            }
+            catch (error) {
+                await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
+                throw error;
             }
-            await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
-            return results;
         }
-        catch (error) {
-            await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
-            throw error;
+        finally {
+            releaseCapabilities();
         }
     }
     async #dispatchClientStatement(args) {
-        const { workspaceId, workerId, loopId, statement } = args;
+        const { workspaceId, workerId, functionalityWorkerId, loopId, statement } = args;
         const release = await this.#workspaceGate.acquireTurn(workspaceId, workerId);
         try {
             const { id: turnId } = await Turn.open(this.#db, {
@@ -876,7 +957,7 @@ export default class Daemon {
             try {
                 const entryIds = [];
                 const result = await this.#engine.dispatch({
-                    statement, workspaceId, workerId, loopId, turnId, sequence: 1,
+                    statement, workspaceId, workerId, functionalityWorkerId, loopId, turnId, sequence: 1,
                     origin: "client", onDispatch: (logEntryId) => { entryIds.push(logEntryId); },
                 });
                 await Turn.complete(this.#db, turnId, result.status);
@@ -913,20 +994,30 @@ export default class Daemon {
     async look(args) {
         const workspaceId = ClientInput.assertId("operation.look", "workspaceId", args.workspaceId);
         const workerId = ClientInput.assertId("operation.look", "workerId", args.workerId);
+        const functionalityWorkerId = ClientInput.assertId("operation.look", "functionalityWorkerId", args.functionalityWorkerId);
         const { statement } = args;
-        const release = await this.#workspaceGate.acquireTurn(workspaceId, workerId);
-        const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
+        await this.#assertWorkerOwned(workspaceId, functionalityWorkerId);
+        const releaseCapabilities = await this.#residency.acquire(workspaceId, functionalityWorkerId);
         try {
-            const result = await this.#engine.look({ statement, workspaceId, workerId, loopId: clientLoopId });
-            await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
-            return result;
-        }
-        catch (error) {
-            await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
-            throw error;
+            const releaseWorkspace = await this.#workspaceGate.acquireTurn(workspaceId, workerId);
+            try {
+                const clientLoopId = await Envelope.ensureClientLoop(this.#db, workerId);
+                try {
+                    const result = await this.#engine.look({ statement, workspaceId, workerId, functionalityWorkerId, loopId: clientLoopId });
+                    await Envelope.closeClientLoop(this.#db, clientLoopId, { status: 200 });
+                    return result;
+                }
+                catch (error) {
+                    await Envelope.closeClientLoop(this.#db, clientLoopId, clientActionFailure(error));
+                    throw error;
+                }
+            }
+            finally {
+                releaseWorkspace();
+            }
         }
         finally {
-            release();
+            releaseCapabilities();
         }
     }
     // {§methods-log-read} — a workspace's journal, the module's primary render input. The worker is
@@ -1030,8 +1121,60 @@ export default class Daemon {
         return Validator.assertClientDisplayCapabilities([...schemes, ...mimetypes]);
     }
     listWorkspaces() { return Envelope.listWorkspaces(this.#db); }
-    listWorkers(workspaceId) {
-        return Envelope.listWorkersForWorkspace(this.#db, ClientInput.assertId("workspace.workers", "workspaceId", workspaceId));
+    listWorkers(workspaceId, query = {}) {
+        const origin = query.origin;
+        if (origin !== undefined && !["model", "client", "_plurnk"].includes(origin)) {
+            throw daemonFailure("daemon:worker", "origin-invalid", 400, `Worker origin '${String(origin)}' is invalid.`, { origin, retryable: false });
+        }
+        const parentWorkerId = query.parentWorkerId === undefined
+            ? undefined
+            : query.parentWorkerId === null
+                ? null
+                : ClientInput.assertId("workspace.workers", "parentWorkerId", query.parentWorkerId);
+        // {§methods-worker-list} — an omitted parent filter must stay absent:
+        // the envelope keys the filter on the property's presence, not its value.
+        return Envelope.listWorkersForWorkspace(this.#db, ClientInput.assertId("workspace.workers", "workspaceId", workspaceId), {
+            ...(origin === undefined ? {} : { origin }),
+            ...(parentWorkerId === undefined ? {} : { parentWorkerId }),
+        });
+    }
+    async readWorker(args) {
+        const workspaceId = ClientInput.assertId("worker.read", "workspaceId", args.workspaceId);
+        const hasId = Object.hasOwn(args.identity, "id");
+        const hasName = Object.hasOwn(args.identity, "name");
+        if (hasId === hasName) {
+            throw daemonFailure("daemon:worker", "identity-invalid", 400, "Worker observation requires exactly one id or name.", { retryable: false });
+        }
+        const row = hasId
+            ? await this.#db.envelope_get_worker_by_id.get({
+                id: ClientInput.assertId("worker.read", "id", args.identity.id),
+            })
+            : await this.#db.envelope_get_worker_by_name.get({
+                workspace_id: workspaceId,
+                name: ClientInput.assertOptionalWorkerName("worker.read", "name", args.identity.name),
+            });
+        if (row === undefined || row.workspace_id !== workspaceId)
+            return null;
+        const { workspace_id: _workspaceId, ...projection } = row;
+        return projection;
+    }
+    async listWorkerLoops(args) {
+        const workspaceId = ClientInput.assertId("worker.loops", "workspaceId", args.workspaceId);
+        const workerId = ClientInput.assertId("worker.loops", "workerId", args.workerId);
+        await this.#assertWorkerOwned(workspaceId, workerId);
+        const rows = await this.#db.application_list_worker_loops.all({ worker_id: workerId });
+        return rows.map((row) => ({
+            id: row.id,
+            workerId: row.workerId,
+            sequence: row.sequence,
+            status: row.status,
+            prompt: row.prompt,
+            promptSource: row.promptSource,
+            terminatedAt: row.terminatedAt,
+            terminalResult: row.terminalResult === null
+                ? null
+                : Validator.assertOperationResult(JSON.parse(row.terminalResult)),
+        }));
     }
     // {§methods-workspace-prompts}: root-conversation loop seeds, newest-first.
     listPrompts(workspaceId, limit) {
@@ -1058,7 +1201,7 @@ export default class Daemon {
     }
     // {§methods-workspace-create}: the module owns protocol decoding; core validates the typed seam
     // inputs and owns the envelope, its reserved-name + name-uniqueness invariants,
-    // membership resolution, warmWorkspaceDerivations, and the workspace/created emit. No connection state
+    // membership resolution and the workspace/created emit. No connection state
     // (which client is on which workspace) lives here — that's the module's.
     async createWorkspace(args) {
         // The seam fails hard on malformed semantic input so every module inherits one wall:
@@ -1078,26 +1221,18 @@ export default class Daemon {
             }
             if (constraints.length > 0)
                 await GitMembership.resolveGitMembership(this.#db, envelope.workspaceId, undefined);
-            for (const provider of this.#workspaceCapabilityProviders.values()) {
-                await provider.hydrate(envelope.workspaceId);
-            }
-            await LoopDocs.materialize(this.#engine, this.#db, envelope.workspaceId);
-            await SkillDocs.materialize(this.#engine, this.#db, envelope.workspaceId);
-            void this.#engine.warmWorkspaceDerivations(envelope.workspaceId).catch(() => { });
             this.#broadcast("all", "workspace/created", { id: envelope.workspaceId, name: envelope.workspaceName, projectRoot: envelope.projectRoot });
             return envelope;
         });
     }
     async attachWorkspace(args) {
-        // attachToWorkspace owns the reserved-name + worker-ownership invariants; the seam just delegates + warms.
+        // attachToWorkspace owns the reserved-name + worker-ownership invariants; the seam just delegates.
         const workspaceId = ClientInput.assertId("workspace.attach", "workspaceId", args.workspaceId);
         const workerId = args.workerId === undefined
             ? undefined
             : ClientInput.assertId("workspace.attach", "workerId", args.workerId);
         const workerName = ClientInput.assertOptionalWorkerName("workspace.attach", "workerName", args.workerName);
-        const envelope = await Envelope.attachToWorkspace(this.#db, workspaceId, { workerId, workerName });
-        void this.#engine.warmWorkspaceDerivations(envelope.workspaceId).catch(() => { });
-        return envelope;
+        return Envelope.attachToWorkspace(this.#db, workspaceId, { workerId, workerName });
     }
     async renameWorkspace(workspaceId, name) {
         const checkedWorkspaceId = ClientInput.assertId("workspace.rename", "workspaceId", workspaceId);
@@ -1116,7 +1251,7 @@ export default class Daemon {
             // Members may have just landed — begin warming now, but return the constraint response
             // immediately so prompts do not wait for the complete derivation corpus.
             void this.#engine.warmWorkspaceDerivations(checkedWorkspaceId).catch(() => { });
-            return { effect, glob };
+            return { effect, glob, source: "explicit" };
         }
         finally {
             release();
@@ -1163,8 +1298,10 @@ export default class Daemon {
                 retryable: false,
             });
         }
-        const release = await this.#workspaceGate.acquireTurn(workspaceId, workerId);
+        const releaseCapabilities = await this.#residency.acquire(workspaceId, workerId);
+        let releaseWorkspace;
         try {
+            releaseWorkspace = await this.#workspaceGate.acquireTurn(workspaceId, workerId);
             let parsed;
             try {
                 parsed = parsePath(args.target);
@@ -1215,6 +1352,7 @@ export default class Daemon {
                 workspace_id: workspaceId,
                 owner_id: location.ownerId,
                 scheme: location.scheme,
+                authority: location.authority,
                 pathname: location.pathname,
             });
             if (row === undefined) {
@@ -1262,7 +1400,8 @@ export default class Daemon {
             });
         }
         finally {
-            release();
+            releaseWorkspace?.();
+            releaseCapabilities();
         }
     }
     // {§methods-conversation-worker}: a fresh conversation is a model-origin root worker with an empty private log.
@@ -1289,9 +1428,9 @@ export default class Daemon {
     // {§worker-scheme-fork} — branch a worker's log while sharing the workspace world.
     // Core owns the workspace check and immutable worker-name admission.
     async forkWorker(args) {
-        const workspaceId = ClientInput.assertId("worker.fork", "workspaceId", args.workspaceId);
-        const workerId = ClientInput.assertId("worker.fork", "workerId", args.workerId);
-        const name = ClientInput.assertOptionalWorkerName("worker.fork", "name", args.name);
+        const workspaceId = ClientInput.assertId("run.fork", "workspaceId", args.workspaceId);
+        const workerId = ClientInput.assertId("run.fork", "workerId", args.workerId);
+        const name = ClientInput.assertOptionalWorkerName("run.fork", "name", args.name);
         const owner = await this.#db.envelope_get_worker_by_id.get({ id: workerId });
         if (owner === undefined) {
             throw daemonFailure("daemon:worker", "worker-not-found", 404, `Worker ${workerId} does not exist.`, { workerId });
@@ -1310,32 +1449,23 @@ export default class Daemon {
                 throw daemonFailure("daemon:worker", "name-conflict", 409, `Worker name '${name}' is already in use in workspace ${workspaceId}.`, { workspaceId, name, recovery: "Choose another worker name.", retryable: false });
             }
         }
-        const branchWorkerId = await Fork.fork(this.#db, workerId, name);
+        const branchWorkerId = await Fork.fork(this.#db, workerId, name, (scheme) => this.#schemes.entryInheritanceForStoredScheme(scheme, workerId));
         const branch = await this.#db.envelope_get_worker_by_id.get({ id: branchWorkerId });
         return { workerId: branchWorkerId, workerName: branch?.name ?? null, parentWorkerId: workerId };
     }
     async registerRuntimes(registrations) {
         const normalized = registrations.map((registration) => this.#normalizeRuntime(registration));
         this.#engine.registerRuntimes(normalized);
-        if (this.#capabilitiesPublished) {
-            for (const workspace of await Envelope.listWorkspaces(this.#db)) {
-                await LoopDocs.materialize(this.#engine, this.#db, workspace.id);
-                await SkillDocs.materialize(this.#engine, this.#db, workspace.id);
-            }
-        }
+        await this.#residency.rematerializeActive();
     }
     async registerRuntime(registration) {
         await this.registerRuntimes([registration]);
     }
     async registerScheme(name, handler) {
         this.#schemes.register(name, handler);
-        if (this.#capabilitiesPublished) {
+        if (this.#residency.published)
             await this.#schemes.ready();
-            for (const workspace of await Envelope.listWorkspaces(this.#db)) {
-                await LoopDocs.materialize(this.#engine, this.#db, workspace.id);
-                await SkillDocs.materialize(this.#engine, this.#db, workspace.id);
-            }
-        }
+        await this.#residency.rematerializeActive();
     }
     #normalizeRuntime({ namespaceOwner, decl, executor, availability, scheme }) {
         if (typeof namespaceOwner !== "string" || namespaceOwner.trim().length === 0) {
@@ -1360,12 +1490,26 @@ export default class Daemon {
         };
     }
     registerModuleAction(registration) {
-        const { name, scope, handler } = registration;
+        const { name, scope, inputSchema, outputSchema, handler } = registration;
         if (name.length === 0)
             throw new Error("registerModuleAction: action name must not be empty");
-        if (scope !== "worldless" && scope !== "workspace") {
+        if (scope !== "worldless" && scope !== "workspace" && scope !== "worker") {
             throw new Error(`module action '${name}' has invalid scope '${String(scope)}'`);
         }
+        if (inputSchema === null || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+            throw new Error(`module action '${name}' has no input schema`);
+        }
+        if (outputSchema === null || typeof outputSchema !== "object" || Array.isArray(outputSchema)) {
+            throw new Error(`module action '${name}' has no output schema`);
+        }
+        for (const [role, schema] of [["input", inputSchema], ["output", outputSchema]]) {
+            try {
+                Validator.validateJsonSchemaInstance(schema, {});
+            }
+            catch (cause) {
+                throw new Error(`module action '${name}' has an invalid ${role} schema`, { cause });
+            }
+        }
         if (typeof handler !== "function")
             throw new Error(`module action '${name}' has no handler`);
         if (this.#moduleActions.has(name))
@@ -1374,7 +1518,12 @@ export default class Daemon {
     }
     listModuleActions() {
         return [...this.#moduleActions.values()]
-            .map(({ name, scope }) => ({ name, scope }))
+            .map(({ name, scope, inputSchema, outputSchema }) => ({
+            name,
+            scope,
+            inputSchema,
+            outputSchema,
+        }))
             .toSorted((left, right) => left.name.localeCompare(right.name));
     }
     async invokeModuleAction(name, params, context) {
@@ -1384,131 +1533,38 @@ export default class Daemon {
         if (registration.scope !== context.scope) {
             throw new Error(`module action '${name}' requires ${registration.scope} context, not ${context.scope}`);
         }
+        let releaseCapabilities;
         if (context.scope === "workspace") {
             ClientInput.assertId(`module action '${name}'`, "workspaceId", context.workspaceId);
         }
-        return registration.handler(params, context);
-    }
-    registerWorkspaceCapabilityProvider(namespaceOwner, provider) {
-        if (namespaceOwner.trim().length === 0) {
-            throw new Error("workspace capability provider requires a non-empty namespace owner");
-        }
-        if (this.#workspaceCapabilityProviders.has(namespaceOwner)) {
-            throw new Error(`workspace capability provider '${namespaceOwner}' is already registered`);
-        }
-        this.#workspaceCapabilityProviders.set(namespaceOwner, provider);
-    }
-    async readWorkspaceModuleState(workspaceId, namespaceOwner) {
-        const checkedWorkspaceId = ClientInput.assertId("workspace module state", "workspaceId", workspaceId);
-        if (namespaceOwner.trim().length === 0) {
-            throw new Error("workspace module state requires a non-empty namespace owner");
-        }
-        const row = await this.#db.workspace_module_state_get.get({
-            workspace_id: checkedWorkspaceId,
-            namespace_owner: namespaceOwner,
-        });
-        return row === undefined ? null : JSON.parse(row.state);
-    }
-    async replaceWorkspaceCapabilities({ workspaceId, namespaceOwner, state, runtimes, }) {
-        const checkedWorkspaceId = ClientInput.assertId("workspace capability replacement", "workspaceId", workspaceId);
-        if (namespaceOwner.trim().length === 0) {
-            throw new Error("workspace capability replacement requires a non-empty namespace owner");
-        }
-        const workspace = await this.#db.envelope_get_workspace.get({ id: checkedWorkspaceId });
-        if (workspace === undefined) {
-            throw daemonFailure("daemon:workspace-capability", "workspace-not-found", 404, `Workspace ${checkedWorkspaceId} does not exist.`, { workspaceId: checkedWorkspaceId, retryable: false });
-        }
-        const encoded = state === null ? null : JSON.stringify(state);
-        if (state !== null && encoded === undefined) {
-            throw daemonFailure("daemon:workspace-capability", "state-not-json", 400, "Workspace module state is not JSON-serializable.", { namespaceOwner, retryable: false });
-        }
-        if (encoded !== null)
-            JSON.parse(encoded);
-        const normalized = runtimes.map((registration) => {
-            if (registration.namespaceOwner !== namespaceOwner) {
-                throw new Error(`workspace runtime owner '${registration.namespaceOwner}' does not match '${namespaceOwner}'`);
+        else if (context.scope === "worker") {
+            const workspaceId = ClientInput.assertId(`module action '${name}'`, "workspaceId", context.workspaceId);
+            const workerId = ClientInput.assertId(`module action '${name}'`, "workerId", context.workerId);
+            const worker = await this.#db.envelope_get_worker_by_id.get({ id: workerId });
+            if (worker === undefined || worker.workspace_id !== workspaceId) {
+                throw daemonFailure("daemon:module-action", "worker-not-found", 404, `Worker ${workerId} does not exist in workspace ${workspaceId}.`, { workspaceId, workerId, retryable: false });
             }
-            return this.#normalizeRuntime(registration);
-        });
-        const gate = this.#workspaceGate.tryExclusive(checkedWorkspaceId);
-        if (gate === null) {
-            throw daemonFailure("daemon:workspace-capability", "workspace-busy", 409, `Workspace ${checkedWorkspaceId} is running an operation or another capability change.`, {
-                workspaceId: checkedWorkspaceId,
-                namespaceOwner,
-                recovery: "Settle the current operation and retry the capability change.",
-                retryable: true,
-            });
+            releaseCapabilities = await this.#residency.acquire(workspaceId, workerId);
         }
-        await gate.acquired;
-        const prior = await this.#db.workspace_module_state_get.get({
-            workspace_id: checkedWorkspaceId,
-            namespace_owner: namespaceOwner,
-        });
-        let rollbackRuntimes;
-        let stateChanged = false;
         try {
-            const commitRuntimes = await this.#engine.prepareWorkspaceRuntimes(checkedWorkspaceId, namespaceOwner, normalized);
-            if (encoded === null) {
-                await this.#db.workspace_module_state_delete.run({
-                    workspace_id: checkedWorkspaceId,
-                    namespace_owner: namespaceOwner,
-                });
-            }
-            else {
-                await this.#db.workspace_module_state_put.run({
-                    workspace_id: checkedWorkspaceId,
-                    namespace_owner: namespaceOwner,
-                    state: encoded,
-                });
-            }
-            stateChanged = true;
-            rollbackRuntimes = commitRuntimes();
-            if (this.#capabilitiesPublished) {
-                await LoopDocs.materialize(this.#engine, this.#db, checkedWorkspaceId);
-                await SkillDocs.materialize(this.#engine, this.#db, checkedWorkspaceId);
-            }
-        }
-        catch (cause) {
-            rollbackRuntimes?.();
-            const rollbackErrors = [];
-            if (stateChanged) {
-                try {
-                    if (prior === undefined) {
-                        await this.#db.workspace_module_state_delete.run({
-                            workspace_id: checkedWorkspaceId,
-                            namespace_owner: namespaceOwner,
-                        });
-                    }
-                    else {
-                        await this.#db.workspace_module_state_put.run({
-                            workspace_id: checkedWorkspaceId,
-                            namespace_owner: namespaceOwner,
-                            state: prior.state,
-                        });
-                    }
-                }
-                catch (rollbackCause) {
-                    rollbackErrors.push(rollbackCause);
-                }
-                if (this.#capabilitiesPublished) {
-                    try {
-                        await LoopDocs.materialize(this.#engine, this.#db, checkedWorkspaceId);
-                        await SkillDocs.materialize(this.#engine, this.#db, checkedWorkspaceId);
-                    }
-                    catch (rollbackCause) {
-                        rollbackErrors.push(rollbackCause);
-                    }
-                }
-            }
-            if (rollbackErrors.length > 0) {
-                throw new AggregateError([cause, ...rollbackErrors], "Workspace capability replacement and rollback failed");
-            }
-            throw cause;
+            return await registration.handler(params, context);
         }
         finally {
-            gate.release();
+            releaseCapabilities?.();
         }
     }
+    registerWorkerCapabilityProvider(namespaceOwner, provider) {
+        this.#residency.registerProvider(namespaceOwner, provider);
+    }
+    registerFunctionalityAdapter(adapter) {
+        return this.#functionality.register(adapter);
+    }
+    async readWorkerModuleState(workerId, namespaceOwner) {
+        return this.#residency.readModuleState(workerId, namespaceOwner);
+    }
+    async replaceWorkerCapabilities(replacement, options = {}) {
+        await this.#residency.replace(replacement, options);
+    }
     get engine() { return this.#engine; }
     get provider() { return this.#provider; }
     get schemes() { return this.#schemes; }
@@ -1534,6 +1590,7 @@ export default class Daemon {
         // shell is the default runtime, so its executor must boot usable.
         const executors = await ExecutorRegistry.build({ defaultRuntime: "sh", cwd: this.#discoveryCwd });
         this.#engine.setExecutors(executors);
+        this.#engine.setFunctionalityDocuments((workerId) => this.#functionality.documents(workerId));
         // {§question-tool} — the native request-user-input runtime, process-wide;
         // per-worker admission gates its doc visibility and dispatch ({§worker-settings}).
         await this.#engine.registerRuntimes([{
@@ -1574,20 +1631,8 @@ export default class Daemon {
                 this.#moduleClosers.push(module);
             await module.setup?.(setupSeam);
         }
-        for (const workspace of await Envelope.listWorkspaces(this.#db)) {
-            for (const provider of this.#workspaceCapabilityProviders.values()) {
-                await provider.hydrate(workspace.id);
-            }
-        }
         await this.#schemes.ready();
-        // Reconcile the kernel-published documentation surface once per existing workspace.
-        // Installed capabilities and operator configuration are now fully known; model loops
-        // consume this workspace state but never republish it.
-        for (const workspace of await Envelope.listWorkspaces(this.#db)) {
-            await LoopDocs.materialize(this.#engine, this.#db, workspace.id);
-            await SkillDocs.materialize(this.#engine, this.#db, workspace.id);
-        }
-        this.#capabilitiesPublished = true;
+        this.#residency.publish();
         await this.#recoverLifecycle();
         // {§module-lifecycle} — the daemon opens no transport. Modules start their listeners only
         // after capability publication and durable lifecycle recovery are complete.
@@ -1610,11 +1655,24 @@ export default class Daemon {
         await this.#db.recovery_resume_unblocked_parks.run({});
         await this.#branchBatches.recover();
         const orphanSources = await this.#db.recovery_orphan_prompt_sources.all({});
+        const invalidOrphan = orphanSources.find(({ origin }) => origin !== "model");
+        if (invalidOrphan !== undefined) {
+            throw new Error(`Orphaned provider work belongs to ${invalidOrphan.origin} worker ${invalidOrphan.worker_id}; only model workers may enter inference.`);
+        }
         for (const source of orphanSources) {
             await this.#drains.reconcileOrphanedPrompts(source.worker_id, source.loop_id);
         }
         const systemPrompt = await readFile(Paths.instructionsSystem, "utf8");
         const queued = await this.#db.recovery_queued_workers.all({});
+        const invalidQueued = queued.find(({ origin }) => origin !== "model");
+        if (invalidQueued !== undefined) {
+            throw new Error(`Queued provider work belongs to ${invalidQueued.origin} worker ${invalidQueued.worker_id}; only model workers may enter inference.`);
+        }
+        const parked = await this.#db.recovery_parked_workers.all({});
+        const invalidParked = parked.find(({ origin }) => origin !== "model");
+        if (invalidParked !== undefined) {
+            throw new Error(`Parked provider work belongs to ${invalidParked.origin} worker ${invalidParked.worker_id}; only model workers may enter inference.`);
+        }
         for (const row of queued) {
             const started = await this.#drains.ensureDrain({
                 workspaceId: row.workspace_id,
@@ -1622,10 +1680,11 @@ export default class Daemon {
                 systemPrompt,
             });
             started?.drainPromise.catch((err) => {
-                console.error(`recovered drain failed for worker ${row.worker_id}:`, err);
+                if (this.#started) {
+                    console.error(`recovered drain failed for worker ${row.worker_id}:`, err);
+                }
             });
         }
-        const parked = await this.#db.recovery_parked_workers.all({});
         for (const row of parked) {
             await this.#drains.schedulePollWake(row.workspace_id, row.worker_id, systemPrompt);
         }
@@ -1644,6 +1703,15 @@ export default class Daemon {
         if (!this.#started)
             return;
         this.#started = false;
+        // Stop every producer before refusing capability acquisition. A drain
+        // already between queue claim and activation must observe its own abort,
+        // not misclassify orderly shutdown as a capability failure.
+        const derivationAbort = new DOMException("daemon stopping", "AbortError");
+        this.#engine.cancelAllProposals("daemon_stopping");
+        this.#engine.cancelDerivations(derivationAbort);
+        this.#branchBatches.beginStop();
+        this.#drains.beginStop("daemon_stopping");
+        this.#residency.beginStop();
         const stopDeadlineMs = Daemon.#stopDeadlineMs();
         const deadline = Date.now() + stopDeadlineMs;
         const settle = (label, wait) => new Promise((resolve) => {
@@ -1677,11 +1745,6 @@ export default class Daemon {
         // Settle the stopped world FIRST: a drain paused at a pending proposal awaits a resolution
         // that will never arrive once clients are gone — allSettled(drains) below would deadlock
         // the stop forever (a daemon with a pending HITL proposal could not shut down).
-        const derivationAbort = new DOMException("daemon stopping", "AbortError");
-        this.#engine.cancelAllProposals("daemon_stopping");
-        this.#engine.cancelDerivations(derivationAbort);
-        this.#branchBatches.beginStop();
-        this.#drains.beginStop("daemon_stopping");
         // {§crash-only-stop} — the settle sequence is DEADLINE-BOUNDED: a child
         // that never closes (a wedged MCP server, a stuck stream) must not hang
         // the daemon forever. Past the deadline the waits are abandoned; the
@@ -1689,6 +1752,9 @@ export default class Daemon {
         // leak as a live-but-wedged tree.
         const branchResult = await settle("branch batches idle", () => this.#branchBatches.idle());
         const drainResult = await settle("drains idle", () => this.#drains.idle());
+        // A boundary publication queued behind the last turn settles before
+        // modules close and before the DB goes away ({§functionality-publication}).
+        const functionalityResult = await settle("functionality publications", () => this.#functionality.settle());
         const moduleResult = await settle("modules close", async () => {
             const results = await moduleClose;
             if (results.some((r) => r.status === "rejected"))
@@ -1706,6 +1772,7 @@ export default class Daemon {
         const wakeResult = await settle("drains idle (wake)", () => this.#drains.idle());
         const closeErrors = [
             moduleResult,
+            functionalityResult,
             branchResult,
             drainResult,
             streamingResult,
@@ -1736,6 +1803,10 @@ export default class Daemon {
     notifyStreamEvent(workspaceId, event) {
         this.#broadcast({ workspaceId }, "stream/event", event);
     }
+    /** Emit transient readable reasoning for an in-flight model call. */
+    notifyReasoningEvent(workspaceId, event) {
+        this.#broadcast({ workspaceId }, "reasoning/event", event);
+    }
     /**
      * Emit a transient notice scoped to the workspace containing the loop.
      */
@@ -1781,6 +1852,7 @@ export default class Daemon {
             worker_id: workerId,
             sequence: seqRow.next,
             prompt: first.body,
+            prompt_source: first.prompt_source,
             flags: first.flags,
             model_route_id: first.model_route_id,
             spawn_model_route_id: first.spawn_model_route_id,
@@ -1807,6 +1879,12 @@ export default class Daemon {
     cancelDrain(workerId, reason = "user_cancelled") {
         return this.#drains.cancel(workerId, reason);
     }
+    async cancelWorker(args) {
+        const workspaceId = ClientInput.assertId("worker.cancel", "workspaceId", args.workspaceId);
+        const workerId = ClientInput.assertId("worker.cancel", "workerId", args.workerId);
+        await this.#assertWorkerOwned(workspaceId, workerId);
+        await this.#drains.cancelWorkerTree(workerId, args.reason ?? "user_cancelled");
+    }
     // Process-local stream activity is supplied to the drain owner through the
     // scheme registry rather than exposing that registry across the boundary.
     #workerHasActiveStreams(workerId) {