@stratusagent/gateway 0.4.0 → 0.7.0

package/dist/index.js

@@ -2,10 +2,11 @@ import { createHash, randomUUID } from 'node:crypto';
 import { chmodSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { DatabaseSync } from 'node:sqlite';
-import { AgentRegistry, AgentRunner, EventBus, RunAbortedError, ToolRegistry, readPendingApproval, } from '@stratusagent/core';
+import { AgentRegistry, AgentRunner, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, readPendingApproval, } from '@stratusagent/core';
 import { createDelegateTool, createRememberTool, } from '@stratusagent/agents';
 import { createLocalCommandExecutor } from '@stratusagent/executor-local';
-import { createDemoTool, createFileMemoryStore, createRuntimeProvider, DEFAULT_STRATUS_AGENT, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, memoryFilePath, migrateLegacyMemory, ConfigFileError, loadConfigFile, readNonEmptyString, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, stratusHomePath, withLegacyDefaultMemories, } from '@stratusagent/state';
+import { loadPlugins, } from '@stratusagent/plugins';
+import { createDemoTool, createFileMemoryStore, createRuntimeProvider, DEFAULT_STRATUS_AGENT, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, memoryFilePath, migrateLegacyMemory, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, applySoulPins, stratusHomePath, workspacesDirPath, withLegacyDefaultMemories, } from '@stratusagent/state';
 const SESSIONS_DB_FILENAME = 'sessions.db';
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 /**
@@ -107,11 +108,74 @@ export class SqliteSessionStore {
             .all(status);
         return rows.map((row) => row.id);
     }
-    /** Newest-first session listing for one agent (or all agents). */
-    list(agentId) {
+    /**
+     * When each agent last did anything, and how many of its sessions are live
+     * right now.
+     *
+     * One aggregate over the indexed columns — no conversation body is
+     * deserialized, for the same reason `listIdsByStatus` returns ids: a
+     * roster view asks this on every load, and it must not cost a JSON parse
+     * per session to answer.
+     *
+     * Both halves are needed and neither is sufficient. `lastActiveAt` alone
+     * reads a turn parked on a human as idle, because the save that recorded
+     * the park is the last thing that touched the row — and a turn waiting
+     * twenty minutes on an approval is exactly when someone wants to see the
+     * agent lit. `activeSessions` alone loses an agent that finished a moment
+     * ago. The caller decides what window counts as "recent"; a daemon that
+     * baked one in would need upgrading to change it.
+     */
+    /**
+     * How many sessions are in each state.
+     *
+     * A grouped count, not a listing that gets counted. The table grows for the
+     * life of an install and a health endpoint is polled, so materialising one
+     * object per historical session to produce five numbers gets steadily
+     * slower at exactly the thing meant to report that the daemon is fine.
+     */
+    countByStatus() {
+        const rows = this.db
+            .prepare('SELECT status, COUNT(*) AS total FROM sessions GROUP BY status')
+            .all();
+        const counts = {};
+        for (const row of rows) {
+            counts[row.status] = Number(row.total);
+        }
+        return counts;
+    }
+    lastActivityByAgent() {
+        const rows = this.db
+            .prepare(`
+        SELECT agent_id,
+               MAX(updated_at) AS last_active_at,
+               SUM(CASE WHEN status IN ('running', 'pending_approval') THEN 1 ELSE 0 END) AS active_sessions
+        FROM sessions
+        GROUP BY agent_id
+      `)
+            .all();
+        const activity = {};
+        for (const row of rows) {
+            activity[row.agent_id] = {
+                lastActiveAt: row.last_active_at,
+                activeSessions: Number(row.active_sessions),
+            };
+        }
+        return activity;
+    }
+    /**
+     * Newest-first session listing for one agent (or all agents).
+     *
+     * `limit` is not decoration: this table grows for the life of an install,
+     * and a surface that renders "recent conversations" would otherwise pull
+     * every session anyone has ever had to show ten of them.
+     */
+    list(agentId, limit) {
+        // -1 is SQLite's "no limit", so one prepared statement serves both cases
+        // rather than four.
+        const bound = limit !== undefined && Number.isInteger(limit) && limit >= 0 ? limit : -1;
         const rows = (agentId
-            ? this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions WHERE agent_id = ? ORDER BY updated_at DESC').all(agentId)
-            : this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions ORDER BY updated_at DESC').all());
+            ? this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions WHERE agent_id = ? ORDER BY updated_at DESC LIMIT ?').all(agentId, bound)
+            : this.db.prepare('SELECT id, agent_id, status, created_at, updated_at FROM sessions ORDER BY updated_at DESC LIMIT ?').all(bound));
         return rows.map((row) => ({
             id: row.id,
             agentId: row.agent_id,
@@ -125,64 +189,15 @@ export class SqliteSessionStore {
     }
 }
 /**
- * Apply a soul's provider/model pins to a selection, demoting the
- * daemon-wide defaults the pins outrank.
+ * A soul's provider/model pins, and the daemon-wide defaults they demote.
  *
- * Exported because this is not only dispatch logic: anything that wants to
- * know what a served agent will actually resolve to — a startup billing
- * check, a diagnostic — has to normalize the same way, and a second copy
- * of these rules drifts from this one.
+ * The implementation lives in `@stratusagent/state`, beside the resolver
+ * whose precedence it manipulates — it never had a gateway dependency. It is
+ * re-exported here because this is where callers were told to import it from,
+ * and because "what will a served agent actually resolve to" is a gateway
+ * question even when the rule answering it is not gateway code.
  */
-export const applySoulPins = (pins, selection, env, context) => {
-    selection.presetSoul = pins;
-    if (!pins.provider && !pins.model) {
-        return { selection, env };
-    }
-    const processEnv = { ...(env.processEnv ?? process.env) };
-    // The daemon-wide default can come from the selection, the environment,
-    // or the config file. A config with no provider key predates the
-    // anthropic option and is openai-specific (the resolver treats it that
-    // way), so a real file without the key still names openai as the
-    // default. Env values normalize exactly as the resolver normalizes
-    // them: an empty or whitespace-padded STRATUS_PROVIDER is no default at
-    // all, not a mismatching one.
-    const defaultProvider = context.selectionProvider
-        ?? readNonEmptyString(processEnv.STRATUS_PROVIDER)
-        ?? readNonEmptyString(processEnv.STRATUSCLAW_PROVIDER)
-        ?? context.configProvider
-        ?? (context.configPresent ? 'openai' : undefined);
-    if (pins.provider) {
-        delete selection.provider;
-        delete processEnv.STRATUS_PROVIDER;
-        delete processEnv.STRATUSCLAW_PROVIDER;
-        if (defaultProvider !== undefined && defaultProvider !== 'demo' && pins.provider !== defaultProvider) {
-            // The default model, endpoint, and generic credentials were all
-            // chosen for the default provider — none may ride along to the
-            // soul's: a base URL would point the pinned provider at the wrong
-            // service, and a generic API key would be sent to it. With NO
-            // default selected anywhere — or the credential-less demo provider
-            // as the default — there is nothing those values could have been
-            // chosen for except whatever provider the soul selects — exactly
-            // the resolver's own reading of a generic credential — so they stay.
-            delete selection.model;
-            delete processEnv.STRATUS_MODEL;
-            delete processEnv.STRATUSCLAW_MODEL;
-            delete selection.baseUrl;
-            delete processEnv.STRATUS_BASE_URL;
-            delete processEnv.STRATUSCLAW_BASE_URL;
-            delete processEnv.STRATUS_API_KEY;
-            delete processEnv.STRATUSCLAW_API_KEY;
-            delete processEnv.STRATUS_API_KEY_ENV;
-            delete processEnv.STRATUSCLAW_API_KEY_ENV;
-        }
-    }
-    if (pins.model) {
-        delete selection.model;
-        delete processEnv.STRATUS_MODEL;
-        delete processEnv.STRATUSCLAW_MODEL;
-    }
-    return { selection, env: { ...env, processEnv } };
-};
+export { applySoulPins } from '@stratusagent/state';
 /**
  * Recorded on a turn the previous process was still running when it died.
  *
@@ -298,7 +313,7 @@ export const createGateway = (options = {}) => {
             // Identity, not presence: a request that already settled is gone from
             // the registry, and comparing against this exact function is what
             // makes every ending — click, timeout, abort, shutdown — idempotent.
-            if (pendingApprovals.get(requestId) !== settle) {
+            if (pendingApprovals.get(requestId)?.settle !== settle) {
                 return;
             }
             pendingApprovals.delete(requestId);
@@ -318,13 +333,31 @@ export const createGateway = (options = {}) => {
             approvalEmissions.add(emitted);
             void emitted.finally(() => approvalEmissions.delete(emitted));
         };
-        pendingApprovals.set(requestId, settle);
         // What is left of the window, not a fresh one: a re-asked request
         // carries when it originally parked, and the elapsed time counts.
+        // Computed before registration because the summary below quotes the
+        // deadline, and a listing that disagreed with the announcing event about
+        // when a request expires would be worse than one that said nothing.
         const alreadyWaitedMs = request.parkedAt ? Date.now() - Date.parse(request.parkedAt) : 0;
         const remainingTimeoutMs = effectiveApprovalTimeoutMs > 0
             ? effectiveApprovalTimeoutMs - (Number.isFinite(alreadyWaitedMs) ? Math.max(0, alreadyWaitedMs) : 0)
             : 0;
+        const expiresAt = remainingTimeoutMs > 0
+            ? new Date(Date.now() + remainingTimeoutMs).toISOString()
+            : undefined;
+        pendingApprovals.set(requestId, {
+            settle,
+            pending: {
+                requestId,
+                sessionId: request.session.id,
+                agentId: request.session.agent.id,
+                call: request.call,
+                risk: request.risk,
+                parkedAt: request.parkedAt ?? new Date().toISOString(),
+                ...(expiresAt ? { expiresAt } : {}),
+                ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
+            },
+        });
         if (effectiveApprovalTimeoutMs > 0 && remainingTimeoutMs <= 0) {
             // Nothing left to wait with. Settled here rather than armed with a
             // zero timer, which `setTimeout` would still run a tick later — long
@@ -366,9 +399,7 @@ export const createGateway = (options = {}) => {
             call: request.call,
             risk: request.risk,
             ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
-            ...(remainingTimeoutMs > 0
-                ? { expiresAt: new Date(Date.now() + remainingTimeoutMs).toISOString() }
-                : {}),
+            ...(expiresAt ? { expiresAt } : {}),
         });
         // Drained at shutdown alongside the resolutions: a channel that has not
         // yet been told a request exists cannot be told it was denied either.
@@ -379,11 +410,11 @@ export const createGateway = (options = {}) => {
         });
     });
     const resolveApproval = (input) => {
-        const settle = pendingApprovals.get(input.requestId);
-        if (!settle) {
+        const parked = pendingApprovals.get(input.requestId);
+        if (!parked) {
             return false;
         }
-        settle(input.answer, input.reason ?? 'decided', input.actor);
+        parked.settle(input.answer, input.reason ?? 'decided', input.actor);
         return true;
     };
     /**
@@ -525,20 +556,37 @@ export const createGateway = (options = {}) => {
         lastDefaultAgentId = id;
         return id;
     };
+    /**
+     * Build the roster from what is on disk right now.
+     *
+     * Runs at start and again on every `reloadRoster()`, which is why it
+     * tracks what it registered rather than only adding: a soul file deleted
+     * since the last pass has to stop being dispatchable, and re-registering
+     * the survivors over a map nothing removes from would leave it addressable
+     * — by id, and from every channel — for the rest of the daemon's life.
+     */
     const loadRoster = async () => {
+        const seen = new Set();
+        const registerFresh = (source) => {
+            registerSource(source);
+            seen.add(source.definition.id);
+        };
         // The built-in id is reserved BEFORE ordinary roster entries load: a
         // roster file that happens to declare id "stratus" must not hijack
         // the documented built-in fallback for agentId-less dispatches — the
         // guard below skips it with a warning. Only the explicitly
         // configured default soul may take the id over (defaultAgentId
         // replaces a pathless source).
-        registerSource({ definition: { ...DEFAULT_STRATUS_AGENT } });
+        registerFresh({ definition: { ...DEFAULT_STRATUS_AGENT } });
         // Throws on two roster files claiming one id: that is a collision with
         // no correct winner, and refusing to serve beats letting sort order
         // decide whose sessions, memory, and credentials an agent inherits.
         const entries = await loadRosterSouls(env, warn);
         for (const entry of entries) {
-            if (sources.has(entry.soul.agent.id)) {
+            // Against ids claimed by THIS pass, not by any earlier one: a reload
+            // must be free to re-register the agent it just re-read, and only the
+            // built-in above can legitimately block a roster file.
+            if (seen.has(entry.soul.agent.id)) {
                 // Only reachable for the reserved built-in id now — roster-vs-
                 // roster duplicates never get this far. Reserved is not the same
                 // failure as duplicated: a soul may not take the fallback over,
@@ -546,11 +594,52 @@ export const createGateway = (options = {}) => {
                 warn(`agent id ${entry.soul.agent.id} is reserved for the built-in agent; ignoring ${entry.path}`);
                 continue;
             }
-            registerSource({ definition: entry.soul.agent, soulPath: entry.path, soul: entry.soul });
+            registerFresh({ definition: entry.soul.agent, soulPath: entry.path, soul: entry.soul });
         }
         // The configured default soul is part of the roster too — it is what
-        // an agentId-less dispatch answers as.
-        await defaultAgentId();
+        // an agentId-less dispatch answers as. It may live outside the agents
+        // directory, and it survives a read failure by name, so what it
+        // resolves to is kept whether or not this pass re-registered it.
+        seen.add(await defaultAgentId());
+        for (const id of [...sources.keys()]) {
+            if (!seen.has(id)) {
+                sources.delete(id);
+                registry.unregister(id);
+            }
+        }
+        // Advisory, per the skills spec: a skill may say which toolsets its
+        // procedure expects (`requires:`), and an agent enabling it without
+        // them gets a warning at load — never a refusal, because a skill is
+        // prose and can degrade. The check itself is the kernel's
+        // (`missingSkillRequirements`), shared with the CLI's local runs so
+        // both hosts warn about the same configuration.
+        for (const agent of registry.list()) {
+            for (const { skill, missing } of missingSkillRequirements(agent, skillCatalog)) {
+                warn(`agent ${agent.id} enables skill ${skill.id}, which expects tools the agent is not allowed: ${missing.join(', ')}`);
+            }
+        }
+    };
+    /**
+     * Roster rebuilds, one at a time.
+     *
+     * `loadRoster` prunes by comparing the registry against the ids *this pass*
+     * saw, so two overlapping passes destroy each other's work: the older one
+     * snapshots a roster without agent B, the newer one registers B and
+     * finishes, and then the older one reaches its prune and unregisters B —
+     * which two clients creating agents at once will do, each having been told
+     * 201 for an agent that is no longer dispatchable.
+     *
+     * A chain rather than a lock: a reload is idempotent, so a caller arriving
+     * mid-rebuild wants the *next* complete one, and waiting for it is exactly
+     * what this gives them.
+     */
+    let reloads = Promise.resolve();
+    const reloadsInOrder = async () => {
+        const next = reloads.then(loadRoster, loadRoster);
+        // Swallowed for the chain only — the caller still sees the rejection, but
+        // a roster that failed to load must not block every reload after it.
+        reloads = next.catch(() => undefined);
+        await next;
     };
     /**
      * A session pins its agent id, never a snapshot of the agent: the soul
@@ -592,8 +681,23 @@ export const createGateway = (options = {}) => {
     };
     // ---- runner pool --------------------------------------------------------
     const tools = new ToolRegistry();
+    // Which package each tool came from. Kernel tools are absent from this
+    // map, which is how `tools()` reports them as the kernel's.
+    const toolProvenance = new Map();
+    let loadedPlugins = [];
+    let pluginFailures = [];
+    const skillCatalog = new SkillRegistry();
+    let operatorSkills = [];
     tools.register(createDemoTool());
     tools.register(createRememberTool(memory));
+    // Registered here rather than left to the first runner, so `tools()`
+    // lists the reader before anything dispatches. The allowlist resolver
+    // mirrors the runner's own sourcing — the definition travelling with the
+    // session, then the roster — so the tool refuses exactly what the
+    // runner's gates refuse.
+    tools.register(createSkillReadTool(skillCatalog, {
+        allowlistFor: (session) => session.agent.skills ?? registry.get(session.agent.id)?.skills,
+    }));
     // Delegation is dispatcher-backed, not runner-capturing: the target agent
     // runs through the same per-provider routing as a direct dispatch, so a
     // delegated specialist uses their own provider and credentials.
@@ -647,6 +751,7 @@ export const createGateway = (options = {}) => {
             store,
             bus,
             agents: registry,
+            skills: skillCatalog,
             memory,
             streaming: true,
             ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
@@ -840,6 +945,16 @@ export const createGateway = (options = {}) => {
     const sessionChains = new Map();
     const inflight = new Set();
     let stopping = false;
+    /**
+     * The turn id running on each session, for callers that named one.
+     *
+     * Set when the chained work actually starts — not when the dispatch was
+     * queued — because a message waiting behind another turn has not begun,
+     * and stamping events with it would attribute the running turn's output to
+     * the queued one. Single-flight per session is what makes one entry per
+     * session sufficient.
+     */
+    const activeTurns = new Map();
     /**
      * The runtime one agent would run on right now — config snapshot, soul
      * pins, degradation and all.
@@ -1154,7 +1269,137 @@ export const createGateway = (options = {}) => {
         if (stopping) {
             throw new Error('The gateway is stopping and no longer accepts new work.');
         }
-        return onSessionChain(input.sessionId, () => dispatchInternal(input));
+        const { turnId } = input;
+        if (turnId === undefined) {
+            return onSessionChain(input.sessionId, () => dispatchInternal(input));
+        }
+        return onSessionChain(input.sessionId, async () => {
+            activeTurns.set(input.sessionId, turnId);
+            try {
+                return await dispatchInternal(input);
+            }
+            finally {
+                // Unconditional, and safe to be: the chain guarantees no other turn
+                // for this session ran between the set above and here, so this can
+                // only ever be clearing its own entry.
+                activeTurns.delete(input.sessionId);
+            }
+        });
+    };
+    /**
+     * Load what the config asked for, and say what did not load.
+     *
+     * A plugin that fails is a warning rather than a refusal to start: a
+     * daemon that will not boot because of a mistyped package name takes the
+     * whole fleet down over one line of config, and the agents whose tools
+     * did load are still worth serving. What is never degraded is the
+     * security half — an undeclared name or a collision refuses that plugin
+     * whole, inside the loader.
+     */
+    const startPlugins = async () => {
+        const configured = options.plugins ?? {};
+        if (Object.keys(configured).length === 0) {
+            return;
+        }
+        const result = await loadPlugins({
+            config: configured,
+            host: options.pluginHost ?? {
+                resolve: (specifier) => import.meta.resolve(specifier),
+                import: (specifier) => import(specifier),
+            },
+            tools,
+            skills: skillCatalog,
+            bus,
+            workspaceRoot: workspacesDirPath(env),
+        });
+        loadedPlugins = result.loaded;
+        pluginFailures = result.failures;
+        for (const plugin of result.loaded) {
+            for (const tool of plugin.tools) {
+                toolProvenance.set(tool.name, { package: plugin.package, trusted: plugin.trusted });
+            }
+            const contributed = [
+                ...plugin.tools.map((tool) => `${tool.name} (${tool.risk})`),
+                ...plugin.skills.map((skill) => `skill ${skill.id}`),
+            ];
+            log(`plugin ${plugin.package} loaded — ${contributed.join(', ') || 'no tools'}`);
+        }
+        for (const failure of result.failures) {
+            warn(`plugin ${failure.package} did not load: ${failure.reason}`);
+        }
+    };
+    /**
+     * Load the operator's `~/.stratus/skills/` into the catalog. Before the
+     * plugins, deliberately: an operator's bare id outranks a plugin's bare
+     * alias for the same name, and the plugin's skill stays reachable by its
+     * qualified `<package>:<skill>` form.
+     */
+    const startSkills = async () => {
+        operatorSkills = await loadOperatorSkills(env, skillCatalog, warn);
+        for (const skill of operatorSkills) {
+            log(`skill ${skill.id} loaded from ${skill.path}`);
+        }
+    };
+    /**
+     * Everything after the plugins: the roster, the channels, and the sweeps
+     * that need both. Split out so `start()` can wrap it in the cleanup a
+     * failure here requires — see the call site.
+     */
+    const startServing = async () => {
+        await loadRoster();
+        const named = registry.list().map((agent) => agent.name).join(', ');
+        log(`stratusd ready — ${registry.list().length} agent(s): ${named}`);
+        // Read before anything can dispatch, so this is exactly what the
+        // last process left running and not a turn of ours caught in flight.
+        // Applied further down, once there is somewhere for the failure to
+        // be heard.
+        const abandoned = await listAbandonedTurns();
+        // Channels come up after the roster so their first inbound message
+        // already has agents to dispatch to. One failing adapter must not
+        // keep the rest (or the gateway) down.
+        for (const adapter of options.channels ?? []) {
+            try {
+                await adapter.start(gateway);
+                startedChannels.push(adapter);
+            }
+            catch (error) {
+                warn(`channel ${adapter.name} failed to start: ${error instanceof Error ? error.message : String(error)}`);
+                // A start() that rejected may still hold sockets or listeners it
+                // acquired before failing; it never reaches startedChannels, so
+                // this is its only cleanup.
+                try {
+                    await adapter.stop();
+                }
+                catch (stopError) {
+                    warn(`channel ${adapter.name} cleanup after failed start also failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                }
+            }
+        }
+        // Last, and not awaited: recovery re-asks, so it needs the channels
+        // above already listening — but a turn parked behind a slow approver
+        // must not hold up start(), or a daemon with one outstanding request
+        // would refuse to finish booting.
+        void recoverParkedTurns().catch((error) => {
+            warn(`recovering parked turns failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        // Not awaited for the same reason, and independent of the sweep
+        // above: these sessions are not parked, so the two never touch the
+        // same one.
+        void failAbandonedTurns(abandoned).catch((error) => {
+            warn(`failing abandoned turns failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    };
+    /** Release what the plugins acquired, reporting rather than throwing. */
+    const disposePlugins = async () => {
+        await Promise.allSettled(loadedPlugins.map(async (plugin) => {
+            try {
+                await plugin.instance.dispose?.();
+            }
+            catch (error) {
+                warn(`plugin ${plugin.package} failed to shut down: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }));
+        loadedPlugins = [];
     };
     const startedChannels = [];
     const gateway = {
@@ -1162,48 +1407,26 @@ export const createGateway = (options = {}) => {
         store,
         async start() {
             await migrateLegacyMemory(env);
-            await loadRoster();
-            const named = registry.list().map((agent) => agent.name).join(', ');
-            log(`stratusd ready — ${registry.list().length} agent(s): ${named}`);
-            // Read before anything can dispatch, so this is exactly what the
-            // last process left running and not a turn of ours caught in flight.
-            // Applied further down, once there is somewhere for the failure to
-            // be heard.
-            const abandoned = await listAbandonedTurns();
-            // Channels come up after the roster so their first inbound message
-            // already has agents to dispatch to. One failing adapter must not
-            // keep the rest (or the gateway) down.
-            for (const adapter of options.channels ?? []) {
-                try {
-                    await adapter.start(gateway);
-                    startedChannels.push(adapter);
-                }
-                catch (error) {
-                    warn(`channel ${adapter.name} failed to start: ${error instanceof Error ? error.message : String(error)}`);
-                    // A start() that rejected may still hold sockets or listeners it
-                    // acquired before failing; it never reaches startedChannels, so
-                    // this is its only cleanup.
-                    try {
-                        await adapter.stop();
-                    }
-                    catch (stopError) {
-                        warn(`channel ${adapter.name} cleanup after failed start also failed: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
-                    }
-                }
+            // Before the roster and before channels: a turn must never arrive for
+            // an agent whose soul lists a tool the daemon has not registered yet,
+            // which would refuse the call as "not permitted" and blame the soul.
+            // Skills first for the same reason — and before the plugins, so the
+            // operator's bare ids win their aliases (see startSkills).
+            await startSkills();
+            await startPlugins();
+            try {
+                await startServing();
+            }
+            catch (error) {
+                // Everything after the plugins loaded is inside that try for one
+                // reason: a `start()` that rejects never reaches its caller's
+                // shutdown path — `stratus serve` awaits it *before* the try/finally
+                // that calls `stop()` — so a duplicate agent id in the roster would
+                // leave a plugin's browser, socket, or subscription held for the
+                // life of a process that is on its way out.
+                await disposePlugins();
+                throw error;
             }
-            // Last, and not awaited: recovery re-asks, so it needs the channels
-            // above already listening — but a turn parked behind a slow approver
-            // must not hold up start(), or a daemon with one outstanding request
-            // would refuse to finish booting.
-            void recoverParkedTurns().catch((error) => {
-                warn(`recovering parked turns failed: ${error instanceof Error ? error.message : String(error)}`);
-            });
-            // Not awaited for the same reason, and independent of the sweep
-            // above: these sessions are not parked, so the two never touch the
-            // same one.
-            void failAbandonedTurns(abandoned).catch((error) => {
-                warn(`failing abandoned turns failed: ${error instanceof Error ? error.message : String(error)}`);
-            });
         },
         // Drain: channels stop taking messages, in-flight turns finish, new
         // dispatches are refused, then the database closes. SIGTERM handling
@@ -1217,8 +1440,8 @@ export const createGateway = (options = {}) => {
             // outstanding approval timeout — a shutdown would hang for as long as
             // the longest request had left. Each denial is a real decision the
             // turn continues from, so the drain below still finishes those turns.
-            for (const settle of [...pendingApprovals.values()]) {
-                settle('deny', 'cancelled');
+            for (const parked of [...pendingApprovals.values()]) {
+                parked.settle('deny', 'cancelled');
             }
             // Let those resolutions reach their subscribers before the channels
             // go down, or a channel that renders approvals never learns to
@@ -1227,13 +1450,137 @@ export const createGateway = (options = {}) => {
             await Promise.allSettled(startedChannels.map((adapter) => adapter.stop()));
             startedChannels.length = 0;
             await Promise.allSettled([...inflight]);
+            // After the turns that might still be using them. A plugin holding a
+            // browser is the reason this exists, and closing it out from under a
+            // running screenshot would fail that turn rather than tidy up.
+            await disposePlugins();
             store.close();
             log('stratusd stopped');
         },
         dispatch,
+        async sessionRouting(sessionId) {
+            const session = await store.get(sessionId);
+            return session
+                ? { agentId: session.agent.id, metadata: session.metadata ?? {} }
+                : undefined;
+        },
         agents() {
             return registry.list();
         },
+        async reloadRoster() {
+            await reloadsInOrder();
+            const roster = registry.list();
+            log(`roster reloaded — ${roster.length} agent(s): ${roster.map((agent) => agent.name).join(', ')}`);
+            return roster;
+        },
+        activeTurnId(sessionId) {
+            return activeTurns.get(sessionId);
+        },
+        pendingApprovals() {
+            return [...pendingApprovals.values()]
+                .map((parked) => parked.pending)
+                .sort((a, b) => a.parkedAt.localeCompare(b.parkedAt));
+        },
+        tools() {
+            // From the registry, not from the load records: the risk reported is
+            // the one a call will actually be judged at, floor applied, and a
+            // second list assembled from manifests would drift from it the first
+            // time a floor was raised.
+            return tools.describe().map((descriptor) => {
+                const provenance = toolProvenance.get(descriptor.name);
+                return {
+                    name: descriptor.name,
+                    ...(descriptor.description ? { description: descriptor.description } : {}),
+                    risk: descriptor.risk ?? 'gated',
+                    ...(provenance ? { package: provenance.package, trusted: provenance.trusted } : {}),
+                };
+            });
+        },
+        skills() {
+            // From the registry, not from the load records: the registry is the
+            // live answer for which bare aliases still resolve — a plugin loaded
+            // later can have retired one a record still remembers.
+            const provenance = new Map();
+            for (const info of operatorSkills) {
+                provenance.set(info.id, { path: info.path });
+            }
+            for (const plugin of loadedPlugins) {
+                for (const skill of plugin.skills) {
+                    provenance.set(skill.id, { package: plugin.package, path: skill.path });
+                }
+            }
+            return skillCatalog.list().map((skill) => {
+                const alias = skillCatalog.idsFor(skill.id).find((id) => id !== skill.id);
+                const from = provenance.get(skill.id);
+                return {
+                    id: skill.id,
+                    name: skill.name,
+                    description: skill.description,
+                    ...(alias !== undefined ? { alias } : {}),
+                    ...(from?.package !== undefined ? { package: from.package } : {}),
+                    ...(from !== undefined ? { path: from.path } : {}),
+                };
+            });
+        },
+        plugins() {
+            const loaded = loadedPlugins.map((plugin) => ({
+                package: plugin.package,
+                name: plugin.name,
+                trusted: plugin.trusted,
+                tools: plugin.tools.map((tool) => ({
+                    name: tool.name,
+                    ...(tool.description ? { description: tool.description } : {}),
+                    risk: tool.risk,
+                    package: plugin.package,
+                    trusted: plugin.trusted,
+                })),
+                // The alias comes from the live registry, exactly as `skills()`
+                // derives it: a plugin loaded later can have retired it, and this
+                // listing must not advertise a bare id `skill.read` would refuse.
+                skills: plugin.skills.map((skill) => {
+                    const alias = skillCatalog.idsFor(skill.id).find((id) => id !== skill.id);
+                    return {
+                        id: skill.id,
+                        name: skill.name,
+                        description: skill.description,
+                        ...(alias !== undefined ? { alias } : {}),
+                        package: plugin.package,
+                        path: skill.path,
+                    };
+                }),
+            }));
+            const failed = pluginFailures.map((failure) => ({
+                package: failure.package,
+                error: failure.reason,
+            }));
+            return [...loaded, ...failed];
+        },
+        async servedSouls() {
+            // From the registry rather than `sources` directly, so the order and
+            // the membership are the roster's own — one entry per agent `agents()`
+            // reports, and no entry for a source the registry no longer serves.
+            return Promise.all(registry.list().map(async (agent) => {
+                const source = sources.get(agent.id);
+                // Re-read, not re-registered: this is a read, and a caller asking
+                // what the daemon would bill must not reshape the roster as a side
+                // effect. `refreshAgent` still owns that on the dispatch path.
+                const fresh = source?.soulPath
+                    ? await loadSoulFile(source.soulPath).catch(() => undefined)
+                    : undefined;
+                if (fresh && fresh.agent.id !== agent.id) {
+                    // The file was given to another agent. `refreshAgent` refuses every
+                    // dispatch for this id until the roster reloads, so there is no
+                    // runtime being served under it — reporting the cached pins would
+                    // claim billing for turns that cannot run, and reporting no soul at
+                    // all would claim the daemon-wide default instead. It is omitted.
+                    return undefined;
+                }
+                // Unreadable is the one case the cache answers for: the gateway goes
+                // on dispatching from the soul it loaded, so those pins are live.
+                const soul = fresh ?? source?.soul;
+                return { id: agent.id, ...(soul ? { soul } : {}) };
+            })).then((entries) => entries.filter((entry) => entry !== undefined));
+        },
         resolveApproval,
     };
     return gateway;