@plurnk/plurnk-service 1.23.0 → 1.25.0

package/dist/server/Daemon.js

@@ -6,6 +6,7 @@ import Share from "../share/Share.js";
 import Paths from "../Paths.js";
 import Engine from "../core/Engine.js";
 import ExecutorRegistry from "../core/ExecutorRegistry.js";
+import Exec from "../schemes/Exec.js";
 import SchemeRegistry from "../core/SchemeRegistry.js";
 import { Mimetypes } from "@plurnk/plurnk-mimetypes";
 import { RuntimeDeclaration } from "@plurnk/plurnk-execs";
@@ -15,22 +16,27 @@ import EffectPolicy from "../schemes/EffectPolicy.js";
 import QuestionTool, { questionRuntimeDecl } from "../schemes/QuestionTool.js";
 import DrainSupervisor from "./DrainSupervisor.js";
 import Retention, { retentionPolicy } from "./Retention.js";
+import PacketBuilder from "../core/PacketBuilder.js";
 import { Validator } from "@plurnk/plurnk-contracts";
 import LogEntry from "./logEntry.js";
 import Envelope, { projectWorkerRow } from "./envelope.js";
 import ClientInput from "./client-input.js";
 import Turn from "../core/Turn.js";
 import SkillsFunctionality from "./SkillsFunctionality.js";
+import WorkspacePlugins from "./WorkspacePlugins.js";
+import { agentRootScopes, configurationDirectories } from "./AgentRoots.js";
+import ExecEnv from "../schemes/exec-env.js";
 import PlurnkSkill from "./PlurnkSkill.js";
 import Skill from "../schemes/Skill.js";
-import MembersFunctionality from "./MembersFunctionality.js";
+import MembersFunctionality, { modelScope, serviceMembers } from "./MembersFunctionality.js";
+import FileCreationPolicy from "../core/file-creation-policy.js";
 import EnvFunctionality, { ENV_OWNER } from "./EnvFunctionality.js";
 import HostPaths from "../core/HostPaths.js";
 import WorkspaceStorage from "./WorkspaceStorage.js";
 import Fork from "../core/fork.js";
 import WorkerControlAddress from "../core/WorkerControlAddress.js";
 import LoopLifecycle from "../core/LoopLifecycle.js";
-import { Knob } from "@plurnk/plurnk-meta";
+import { ConfigurationError, Knob } from "@plurnk/plurnk-meta";
 import LoopPolicies from "../core/LoopPolicies.js";
 import LoopPolicyReader from "../core/LoopPolicyReader.js";
 import { contentWeight } from "../core/content-weight.js";
@@ -46,6 +52,7 @@ import { listModelCatalog } from "./model-catalog.js";
 import { daemonFailure, modelRouteLabel } from "./daemon-results.js";
 import WorkerModelResolver from "./WorkerModelResolver.js";
 import ClientReads from "./ClientReads.js";
+import ConfigurationDiagnostics from "./ConfigurationDiagnostics.js";
 const clientActionFailure = (error) => {
     if (error instanceof OperationFailureError)
         return error.result;
@@ -56,8 +63,24 @@ const clientActionFailure = (error) => {
     });
 };
 export default class Daemon {
+    static validateConfiguration() {
+        FileCreationPolicy.serviceScope();
+        EffectPolicy.validateConfiguration();
+        LoopPolicies.validateConfiguration();
+        retentionPolicy();
+        PacketBuilder.validateConfiguration();
+        Exec.validateConfiguration();
+        ExecutorRegistry.validateConfiguration();
+    }
+    static validateWorkspaceConfiguration() {
+        SkillsFunctionality.validateConfiguration();
+        agentRootScopes();
+        serviceMembers();
+        modelScope();
+    }
     #db;
     #dbPath;
+    #hostPaths;
     #engine;
     #workspaceGate;
     #lifecycle;
@@ -73,13 +96,14 @@ export default class Daemon {
     #discoveryCwd;
     #started = false; // {§module-lifecycle}: one discovery/module boot; no listener
     #modules = [];
-    #moduleClosers = [];
+    #moduleLifetimes = [];
     #moduleActions = new Map();
     #residency;
     #functionality;
     // {§retention-policy} — the operator's retention, run on a cadence and at shutdown.
-    #retention;
+    #retention = null;
     #skills;
+    #plugins;
     #members;
     // {§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
@@ -88,10 +112,13 @@ export default class Daemon {
     #workerModels;
     #reads;
     #storage;
-    constructor({ db, schemes, mimetypes, provider, nodeModulesPath, hostPaths = new HostPaths(), skills, http = null, dbPath }) {
+    #configuration;
+    constructor({ db, schemes, mimetypes, provider, nodeModulesPath, hostPaths = new HostPaths(), http = null, dbPath, configuration = new ConfigurationDiagnostics() }) {
         this.#db = db;
+        this.#hostPaths = hostPaths;
         this.#dbPath = dbPath;
         this.#http = http;
+        this.#configuration = configuration;
         this.#storage = new WorkspaceStorage(db, hostPaths);
         this.#lifecycle = new LoopLifecycle(db);
         this.#schemes = schemes ?? new SchemeRegistry();
@@ -111,7 +138,7 @@ export default class Daemon {
             defaultMimetype: "text/markdown",
             discoverOptions: { cwd: this.#discoveryCwd }
         });
-        const bootSpec = resolveActiveRoute();
+        const bootSpec = this.#provider === null ? null : resolveActiveRoute();
         if (this.#provider !== null && bootSpec !== null) {
             ProviderInstantiate.registerInstance(this.#provider, bootSpec);
         }
@@ -140,13 +167,16 @@ export default class Daemon {
             readWorkerModuleState: (workerId, owner) => this.#residency.readWorkerModuleState(workerId, owner),
             replaceWorkerModuleState: (workerId, owner, state) => this.#residency.replaceWorkerModuleState(workerId, owner, state),
             mutateWorkspace: (workspaceId, owner, caller, run) => this.#residency.exclusively(workspaceId, owner, caller === "operation" ? "wait" : "try", run),
-            retainWorkspace: (workspaceId) => this.#residency.retain(workspaceId)
+            retainWorkspace: (workspaceId) => this.#residency.retain(workspaceId),
+            preparationChanged: (workspaceId, preparation) => this.#broadcast({ workspaceId }, "workspace/preparation", { workspaceId, preparation })
         });
         // {§skills-functionality} — Core's own family: standard Agent Skills.
+        this.#plugins = new WorkspacePlugins({ db, hostPaths, nodeModules: this.#nodeModulesPath });
         this.#skills = new SkillsFunctionality({
             db,
+            plugins: this.#plugins,
+            storage: this.#storage,
             hostPaths,
-            ...skills,
             provided: async () => {
                 const tree = await PlurnkSkill.load(this.#nodeModulesPath);
                 return new Map([[tree.document.name, tree]]);
@@ -238,11 +268,12 @@ export default class Daemon {
                 return { action, loopId };
             },
             acquireWorkspaceTurn: async (workspaceId, workerId, signal) => this.#workspaceGate.acquireTurn(workspaceId, workerId, signal),
-            // {§skills-hotload} — filesystem installers operate out of band.
+            // {§functionality-hotload} — skills and plugins change 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 }) => {
-                await this.#skills.refreshIfChanged({ workspaceId });
+                await this.#functionality.refreshChanged({ workspaceId });
+                return [...this.configurationNotices(), ...this.#functionality.configurationNotices(workspaceId), ...this.#plugins.notices(workspaceId)];
             },
             // worker:// KILL (terminate) — cancel the addressed worker subtree and
             // tear down its held streams before the operation completes.
@@ -252,7 +283,6 @@ export default class Daemon {
                 this.#broadcast({ workspaceId }, "loop/packet", payload);
             }
         });
-        this.#retention = new Retention(db, retentionPolicy());
         this.#drains = new DrainSupervisor({
             db,
             lifecycle: this.#lifecycle,
@@ -323,7 +353,7 @@ export default class Daemon {
             const { workspaceId, ...interaction } = event;
             this.#broadcast({ workspaceId }, "loop/interaction", interaction);
         });
-        this.#workerModels = new WorkerModelResolver({ db: this.#db, provider: this.#provider });
+        this.#workerModels = new WorkerModelResolver({ db: this.#db });
         this.#reads = new ClientReads({ db: this.#db, engine: this.#engine, workspaceGate: this.#workspaceGate, residency: this.#residency });
     }
     // {§methods-event-subscribe}. A transport module subscribes to the daemon's in-process
@@ -870,10 +900,19 @@ export default class Daemon {
     // {§methods} — the module's render surface beyond the journal. Thin delegations
     // into core's envelope / membership / provider machinery; the module fans the results into its own views.
     listProviders() {
-        const active = resolveActiveRoute();
+        const active = process.env.PLURNK_MODEL?.toLowerCase();
+        let aliases;
+        try {
+            aliases = parseAliasesFromEnv();
+        }
+        catch (cause) {
+            if (!(cause instanceof ConfigurationError))
+                throw cause;
+            throw new OperationFailureError(Results.configurationFailure(cause), { cause });
+        }
         return {
-            aliases: parseAliasesFromEnv().map((a) => {
-                const isActive = active !== null && active.alias === a.alias;
+            aliases: aliases.map((a) => {
+                const isActive = active === a.alias;
                 return {
                     alias: a.alias, provider: a.provider, model: a.model, active: isActive,
                     inputCapacity: isActive && this.#provider !== null ? this.#provider.inputCapacity : null
@@ -988,6 +1027,9 @@ export default class Daemon {
         const checkedWorkerId = workerId === undefined ? null : ClientInput.assertId("workspace.prompts", "workerId", workerId);
         return Envelope.listPromptsForWorkspace(this.#db, checkedWorkspaceId, checkedLimit ?? Knob.integer("PLURNK_SERVICE_PROMPTS_PAGE", 1), checkedWorkerId);
     }
+    workspacePreparationStatus(workspaceId) {
+        return this.#functionality.preparationStatus(ClientInput.assertId("workspace preparation", "workspaceId", workspaceId));
+    }
     workspaceDerivationStatus(workspaceId) {
         return this.#engine.workspaceDerivationStatus(ClientInput.assertId("workspace.derivation", "workspaceId", workspaceId));
     }
@@ -1142,6 +1184,12 @@ export default class Daemon {
         }
         if (typeof handler !== "function")
             throw new Error(`module action '${name}' has no handler`);
+        if (registration.residency !== "required" && registration.residency !== "none") {
+            throw new Error(`module action '${name}' must declare its residency requirement`);
+        }
+        if (scope === "worldless" && registration.residency !== "none") {
+            throw new Error(`worldless module action '${name}' cannot require workspace residency`);
+        }
         if (this.#moduleActions.has(name))
             throw new Error(`module action '${name}' is already registered`);
         this.#moduleActions.set(name, registration);
@@ -1164,20 +1212,22 @@ export default class Daemon {
             throw new Error(`module action '${name}' requires ${registration.scope} context, not ${context.scope}`);
         }
         let releaseCapabilities;
-        if (context.scope === "workspace") {
-            releaseCapabilities = await this.#residency.acquire(context.workspaceId);
-        }
-        else if (context.scope === "worker") {
+        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 });
             }
-            releaseCapabilities = await this.#residency.acquire(workspaceId);
+        }
+        if (registration.residency === "required" && context.scope !== "worldless") {
+            releaseCapabilities = await this.#residency.acquire(context.workspaceId);
+        }
+        else if (context.scope === "workspace") {
+            await this.#residency.identity(context.workspaceId);
         }
         try {
-            if (context.scope === "worker") {
+            if (registration.residency === "required" && context.scope === "worker") {
                 const release = await this.#workspaceGate.acquireTurn(context.workspaceId, context.workerId);
                 try {
                     await this.#residency.reconcile(context.workspaceId);
@@ -1206,6 +1256,18 @@ export default class Daemon {
     workspaceStateDirectory(workspaceId, namespaceOwner) {
         return this.#storage.directory(workspaceId, namespaceOwner);
     }
+    async workspaceConfigurationDirectories(workspaceId) {
+        const workspace = await this.#db.envelope_get_workspace.get({ id: workspaceId });
+        return configurationDirectories(this.#hostPaths, workspace?.project_root ?? null);
+    }
+    // {§agent-plugins-hosting}
+    readWorkspacePlugins(workspaceId) {
+        return this.#plugins.read(workspaceId);
+    }
+    // {§mcp-launch-environment}
+    operatorEnvironment() {
+        return ExecEnv.withoutOwnSecrets();
+    }
     async readWorkerEnvironment(workspaceId, workerId) {
         await this.#assertWorkerOwned(workspaceId, workerId);
         const shared = await EnvFunctionality.workspace(this.#db, workspaceId);
@@ -1220,6 +1282,7 @@ export default class Daemon {
         await this.#residency.replace(replacement, options);
     }
     get engine() { return this.#engine; }
+    configurationNotices() { return this.#configuration.notices(); }
     get provider() { return this.#provider; }
     get schemes() { return this.#schemes; }
     get mimetypes() { return this.#mimetypes; }
@@ -1231,14 +1294,22 @@ export default class Daemon {
     async start() {
         if (this.#started)
             throw new Error("daemon already started");
+        await this.#configuration.capture("file-creation", () => FileCreationPolicy.serviceScope());
+        await this.#configuration.capture("effect-policy", () => EffectPolicy.validateConfiguration());
+        await this.#configuration.capture("loop-policy", () => LoopPolicies.validateConfiguration());
+        await this.#configuration.capture("packet", () => PacketBuilder.validateConfiguration());
+        await this.#configuration.capture("execution", () => Exec.validateConfiguration());
+        this.#retention = await this.#configuration.capture("retention", () => new Retention(this.#db, retentionPolicy()));
         this.#started = true;
         // {§db-space-reclamation} — the file is brought to the policy's auto-vacuum mode before any work.
-        const storage = await this.#retention.prepareStorage();
-        if (storage.converted) {
-            console.error(`database: converted to auto_vacuum=${this.#retention.policy.autoVacuum} (${storage.pagesBefore} → ${storage.pagesAfter} pages)`);
+        if (this.#retention !== null) {
+            const storage = await this.#retention.prepareStorage();
+            if (storage.converted) {
+                console.error(`database: converted to auto_vacuum=${this.#retention.policy.autoVacuum} (${storage.pagesBefore} → ${storage.pagesAfter} pages)`);
+            }
         }
         this.#drains.start();
-        this.#retention.start((cause) => { console.error("retention pass failed:", cause instanceof Error ? cause.message : String(cause)); });
+        this.#retention?.start((cause) => { console.error("retention pass failed:", cause instanceof Error ? cause.message : String(cause)); });
         // Mimetypes owns its own discovery scan over @plurnk/plurnk-mimetypes-*
         // packages; pre-warm it so first index render doesn't pay the cost.
         await this.#mimetypes.ready();
@@ -1246,9 +1317,11 @@ export default class Daemon {
             console.warn(`mimetype discovery: '${name}' is discovered but untrusted (PLURNK_PLUGINS_TRUSTED_ONLY); not registered`);
         }
         // Discover + probe the installed executor siblings, then hand the
-        // registry to the engine for exec dispatch ({§exec-registry-resolves}). The
-        // shell is the default runtime, so its executor must boot usable.
-        const executors = await ExecutorRegistry.build({ defaultRuntime: "sh", cwd: this.#discoveryCwd });
+        // registry to the engine for exec dispatch ({§exec-registry-resolves}).
+        const executors = await ExecutorRegistry.build({ cwd: this.#discoveryCwd });
+        for (const { runtime, error } of executors.configurationErrors()) {
+            this.#configuration.record(`executor:${runtime}`, error);
+        }
         this.#engine.setExecutors(executors);
         this.#engine.setFunctionalityDocuments((workspaceId) => this.#functionality.documents(workspaceId));
         // {§question-tool} — the native request-user-input runtime, process-wide;
@@ -1266,9 +1339,6 @@ export default class Daemon {
                     detail: "in-process"
                 }
             }]);
-        // {§effect-policy-tunable} — invalid operator policy fails boot, not the first execution.
-        EffectPolicy.validateConfiguration();
-        LoopPolicies.validateConfiguration();
         // {§exec} — mint a scheme per runtime tag so exec output entries address by tag
         // authority (sh:///l/t/s). The "exec" scheme stays for execution dispatch.
         this.#schemes.registerRuntimeSchemes(executors);
@@ -1279,7 +1349,10 @@ export default class Daemon {
         // {§module-discovery} — third-party daemon-module composition: trusted
         // packages declaring `plurnk.kind: "module"` register beside the
         // service's explicit composition before any module setup runs.
-        const discoveredModules = await discoverDaemonModules({ cwd: this.#discoveryCwd });
+        const discoveredModules = await discoverDaemonModules({ cwd: this.#discoveryCwd, hostPaths: this.#hostPaths });
+        for (const cause of discoveredModules.configurationErrors)
+            this.#configuration.record("native-plugins", cause);
+        this.#configuration.pluginReports(discoveredModules.reports);
         for (const packageName of discoveredModules.skipped) {
             console.warn(`module discovery: '${packageName}' is discovered but untrusted (PLURNK_PLUGINS_TRUSTED_ONLY); not registered`);
         }
@@ -1288,8 +1361,8 @@ export default class Daemon {
         }
         const setupSeam = this;
         for (const module of this.#modules) {
-            if (module.close !== undefined)
-                this.#moduleClosers.push(module);
+            if (module.stop !== undefined || module.close !== undefined)
+                this.#moduleLifetimes.push(module);
             await module.setup?.(setupSeam);
         }
         await this.#schemes.ready();
@@ -1300,8 +1373,8 @@ export default class Daemon {
         // lifecycle recovery are complete. None opens a listener of its own.
         for (const module of this.#modules) {
             const started = await module.start?.(this);
-            if (started !== undefined && !this.#moduleClosers.includes(started)) {
-                this.#moduleClosers.push(started);
+            if (started !== undefined && !this.#moduleLifetimes.includes(started)) {
+                this.#moduleLifetimes.push(started);
             }
         }
     }
@@ -1364,7 +1437,7 @@ export default class Daemon {
         // 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.#retention.stop();
+        this.#retention?.stop();
         this.#engine.cancelAllProposals("daemon_stopping");
         this.#engine.cancelDerivations(derivationAbort);
         this.#drains.beginStop("daemon_stopping");
@@ -1386,10 +1459,15 @@ export default class Daemon {
         // Stop accepting external work immediately, but do not await listener
         // closure before cancelling active workers: an SSE connection may itself be
         // waiting for the worker cancellation that follows.
-        const moduleClose = Promise.allSettled(this.#moduleClosers
-            .toReversed()
-            .map((module) => Promise.resolve().then(() => module.close())));
-        this.#moduleClosers = [];
+        const modules = this.#moduleLifetimes.toReversed();
+        this.#moduleLifetimes = [];
+        const modulePhase = async (phase) => {
+            const results = await Promise.allSettled(modules.map((module) => Promise.resolve().then(() => module[phase]?.())));
+            const errors = results.filter((result) => result.status === "rejected").map(({ reason }) => reason);
+            if (errors.length > 0)
+                throw new AggregateError(errors, `module ${phase} failed`);
+        };
+        const moduleStop = settle("modules stop", () => modulePhase("stop"));
         // Drain order: (1) tell the supervisor to abort worker scopes so
         // strike paths don't keep going, (2) await its active drains
         // to completion, (3) drain streaming schemes' background work
@@ -1411,11 +1489,7 @@ export default class Daemon {
         // 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"))
-                throw new AggregateError(results.filter((r) => r.status === "rejected").map((r) => r.reason), "module close failed");
-        });
+        const moduleStopResult = await moduleStop;
         const streamingResult = await settle("streaming schemes idle", () => this.#drainStreamingSchemes());
         const derivationResult = await settle("derivation drain", () => this.#engine.drainDerivations(derivationAbort));
         const mimetypeResult = this.#ownsMimetypes
@@ -1426,13 +1500,15 @@ export default class Daemon {
         // conclusion notifications. Join the supervisor-owned async tails only
         // after those producers settle, before the caller may close SQLite.
         const wakeResult = await settle("drains idle (wake)", () => this.#drains.idle());
+        const moduleCloseResult = await settle("modules close", () => modulePhase("close"));
         // {§db-maintenance-optimize} — the last database step before the caller closes SQLite:
         // planner statistics refreshed on the writer, bounded by SQLite's own analysis limit.
         // {§retention-policy} — the operator's retention runs once more before the statistics.
-        const collectResult = await settle("retention", () => this.#retention.run());
+        const collectResult = await settle("retention", async () => this.#retention?.run());
         const optimizeResult = await settle("database optimize", () => this.#db.maintenance_optimize.run({}));
         const closeErrors = [
-            moduleResult,
+            moduleStopResult,
+            moduleCloseResult,
             functionalityResult,
             drainResult,
             streamingResult,