@stratusagent/gateway 0.12.5 → 0.13.0

package/dist/index.js

@@ -9,8 +9,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, workItemState, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, imagesWithinReplayBudget, matchesToolAllowlist, } from '@stratusagent/core';
-import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, loadStratusSkill, STRATUS_SKILL_PATH, } from '@stratusagent/agents';
+import { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, workItemState, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, sessionTrustOf, sessionWriteTrust, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, imagesWithinReplayBudget, matchesToolAllowlist, } from '@stratusagent/core';
+import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, DELEGATE_TOOL_NAME, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DEFAULT_MAX_DELEGATION_DEPTH, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, loadStratusSkill, STRATUS_SKILL_PATH, } from '@stratusagent/agents';
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { ShardedSessionStore } from "./sessions.js";
 export { claimHome, homeLockPath, HomeClaimedError, } from "./lock.js";
@@ -85,6 +85,22 @@ export class IntakePausedError extends Error {
         this.name = 'IntakePausedError';
     }
 }
+/**
+ * A dispatch refused because the daemon is restarting or stopping. Channels
+ * stay connected while a restart drains, so they hear people during it, and
+ * this is what tells them the message reached a daemon on its way down: a
+ * channel can say so and keep the message for the next one. Matched by name
+ * there, as channel packages do not import the gateway.
+ */
+export class GatewayStoppingError extends Error {
+    /** True for a restart, which comes back on its own; false for a stop. */
+    restarting;
+    constructor(message, restarting) {
+        super(message);
+        this.name = 'GatewayStoppingError';
+        this.restarting = restarting;
+    }
+}
 /**
  * The intake state a previous process left, or open when there is none.
  *
@@ -104,7 +120,7 @@ const readIntakeState = async (env, warn) => {
             return { paused: false };
         }
         warn(`intake: ${file} could not be read (${error.message}); starting paused. Resume intake to clear it.`);
-        return { paused: true, since: new Date().toISOString() };
+        return { paused: true, since: new Date().toISOString(), unreadable: true };
     }
     try {
         const parsed = JSON.parse(raw);
@@ -113,7 +129,7 @@ const readIntakeState = async (env, warn) => {
         // rule as an unreadable file applies.
         if (typeof parsed !== 'object' || parsed === null || parsed.paused !== true) {
             warn(`intake: ${file} does not hold a pause record; starting paused. Resume intake to clear it.`);
-            return { paused: true, since: new Date().toISOString() };
+            return { paused: true, since: new Date().toISOString(), unreadable: true };
         }
         return {
             paused: true,
@@ -123,7 +139,7 @@ const readIntakeState = async (env, warn) => {
     }
     catch {
         warn(`intake: ${file} is not valid JSON; starting paused. Resume intake to clear it.`);
-        return { paused: true, since: new Date().toISOString() };
+        return { paused: true, since: new Date().toISOString(), unreadable: true };
     }
 };
 /**
@@ -267,6 +283,27 @@ class CrossIdentityError extends Error {
 const crossIdentityError = (sessionId, owner, claimed) => new CrossIdentityError(sessionId, owner, claimed);
 /** Where the session's tool calls ran: `local-command`, or a contributed executor's registered name. */
 export const EXECUTOR_METADATA_KEY = 'executor';
+/**
+ * Marks a sub-agent's session (roadmap 24). Reserved: it is what makes the
+ * daemon deny the session's gated calls without asking anyone, so a caller
+ * that could set it could also clear it.
+ */
+export const SUB_AGENT_METADATA_KEY = 'subAgent';
+export const SUB_AGENT_SESSION_ID_MARKER = ':subagent:';
+/** How many sub-agents one parent turn runs at once unless the host says otherwise. */
+export const DEFAULT_SUB_AGENTS_PER_TURN = 4;
+export const isSubAgentSession = (session) => session.metadata?.[SUB_AGENT_METADATA_KEY] === true && session.id.includes(SUB_AGENT_SESSION_ID_MARKER);
+/**
+ * Tools a sub-agent never gets, whatever its parent holds. `agent.spawn`
+ * would fan out inside a fan-out; `agent.delegate` runs a roster agent
+ * under that agent's own allowlist, which is the way out of a narrowed
+ * slice; `memory.*` would let it persist what nobody reviewed; and
+ * `credential.request` asks a person, which a sub-agent never does.
+ */
+const subAgentNeverGets = (name) => name === 'agent.spawn'
+    || name === DELEGATE_TOOL_NAME
+    || name.startsWith('memory.')
+    || name === CREDENTIAL_REQUEST_TOOL_NAME;
 export const RESERVED_SESSION_METADATA_KEYS = [
     PENDING_APPROVAL_METADATA_KEY,
     FALLBACK_ACTIVE_METADATA_KEY,
@@ -292,6 +329,7 @@ export const RESERVED_SESSION_METADATA_KEYS = [
     // no messages and, once it grows past that index, silently stops sending
     // its own earliest turns, with no overflow and no trim event to say so.
     CONTEXT_FLOOR_METADATA_KEY,
+    SUB_AGENT_METADATA_KEY,
 ];
 /**
  * The first reserved key `metadata` carries, or undefined when it carries
@@ -489,7 +527,35 @@ export const createGateway = (options = {}) => {
         }
         return { agentId: root.agent.id, sessionId: root.id, ...(root.metadata ? { metadata: root.metadata } : {}) };
     };
+    /**
+     * Which sessions are sub-agents, as the host knows it rather than as the
+     * session says (roadmap 24). Every tool in a slice is handed the same
+     * mutable Session, so the metadata marker and the id are claims a tool
+     * can rewrite. The ids are the ones `subAgents.run` minted, held while
+     * the sub-agent runs. A session object's id is read once, by the
+     * executor on its first tool call, before any tool has been handed it,
+     * so a session a tool renamed is still known by the id it ran under.
+     */
+    const liveSubAgentIds = new Set();
+    const idAtFirstCall = new WeakMap();
+    const hostIdOf = (session) => idAtFirstCall.get(session) ?? session.id;
+    const isHostSubAgent = (session) => liveSubAgentIds.has(hostIdOf(session)) || isSubAgentSession(session);
     const requestApproval = async (request) => {
+        // A sub-agent asks no one (roadmap 24): its parent turn is the one a
+        // person is accountable for, and that turn gets the refusal back as a
+        // result and decides what to do. Denied as undeliverable, since nobody
+        // was asked, and announced only as a resolution, so no channel renders
+        // a question nobody may answer.
+        if (isHostSubAgent(request.session)) {
+            void bus.emit({
+                type: 'tool.approval-resolved',
+                sessionId: request.session.id,
+                requestId: randomUUID(),
+                answer: 'deny',
+                reason: 'undeliverable',
+            });
+            return { answer: 'deny' };
+        }
         const delegatedFrom = await delegationOriginOf(request.session);
         return requestApprovalFrom(request, delegatedFrom);
     };
@@ -533,6 +599,10 @@ export const createGateway = (options = {}) => {
          * all and its denial should not wait on an emission that never runs.
          */
         let announced = Promise.resolve();
+        // Read when the request is made, from the scheduler's own records: a
+        // live firing of a schedule approved with a destination, nothing else.
+        // Delegated work is not included yet; its sub-session is not a firing.
+        const scheduleDestination = scheduler.approvalDestinationFor(request.session);
         // Work one agent does for another is allowed one call at a time. The
         // people asked are the delegating conversation's, and a standing grant
         // would widen what the other agent may do on its own work for good —
@@ -594,6 +664,7 @@ export const createGateway = (options = {}) => {
                 ...(expiresAt ? { expiresAt } : {}),
                 ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
                 ...(delegatedFrom ? { delegatedFrom } : {}),
+                ...(scheduleDestination ? { scheduleDestination } : {}),
             },
         });
         if (effectiveApprovalTimeoutMs > 0 && remainingTimeoutMs <= 0) {
@@ -641,6 +712,7 @@ export const createGateway = (options = {}) => {
             ...(always !== undefined ? { always } : {}),
             ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
             ...(delegatedFrom ? { delegatedFrom } : {}),
+            ...(scheduleDestination ? { scheduleDestination } : {}),
             ...(expiresAt ? { expiresAt } : {}),
         });
         // Drained at shutdown alongside the resolutions: a channel that has not
@@ -719,6 +791,21 @@ export const createGateway = (options = {}) => {
                     return channelCarrying(kind, agentId, (candidate) => candidate.accountFor !== undefined)
                         .adapter?.accountFor?.(agentId);
                 },
+                conversationKindFor: async (agentId, destination) => {
+                    const separator = destination.indexOf(':');
+                    if (separator <= 0) {
+                        return undefined;
+                    }
+                    const kind = destination.slice(0, separator);
+                    const adapter = channelCarrying(kind, agentId, (candidate) => candidate.conversationKindFor !== undefined).adapter;
+                    try {
+                        return await adapter?.conversationKindFor?.(agentId, destination.slice(separator + 1));
+                    }
+                    catch {
+                        // Unknown, so the call asks: never a reason to allow.
+                        return undefined;
+                    }
+                },
             },
             contributorOf: (toolName) => toolProvenance().get(toolName)?.package,
         })
@@ -1107,10 +1194,12 @@ export const createGateway = (options = {}) => {
     const runtimeContextFor = (source, config, onFallback, 
     // The turn's own metadata, where a channel records who can read the
     // conversation now; a recovered turn has none and passes the session's.
-    metadata) => {
+    metadata, 
+    // A sub-agent has no soul of its own, and its parent's is not its to edit.
+    subAgent = false) => {
         const conversation = conversationContextFrom(metadata);
         return {
-            ...(source.soulPath !== undefined ? { soulPath: source.soulPath, soulReloads: true } : {}),
+            ...(source.soulPath !== undefined && !subAgent ? { soulPath: source.soulPath, soulReloads: true } : {}),
             workspace: agentWorkspaces.forAgent(source.definition.id),
             ...(config.language !== undefined ? { language: config.language } : {}),
             model: describeServingModel(config, onFallback),
@@ -1473,6 +1562,229 @@ export const createGateway = (options = {}) => {
             ...(input.signal ? { signal: input.signal } : {}),
         }),
     }));
+    // ---- sub-agents (roadmap 24) -------------------------------------------
+    /**
+     * Running sub-agents per parent session, and who waits for a slot. A
+     * parent session runs one turn at a time, so this is per turn.
+     */
+    const maxSubAgentsPerTurn = options.subAgents?.maxConcurrentPerTurn ?? DEFAULT_SUB_AGENTS_PER_TURN;
+    // NaN, 0, a fraction or Infinity would queue every sub-agent forever or
+    // defeat the cap, so refuse it here instead of failing later in a turn.
+    if (!Number.isInteger(maxSubAgentsPerTurn) || maxSubAgentsPerTurn < 1) {
+        throw new Error(`subAgents.maxConcurrentPerTurn must be a whole number of at least 1 (got ${String(maxSubAgentsPerTurn)}).`);
+    }
+    const subAgentSlots = new Map();
+    let subAgentCount = 0;
+    /**
+     * The session object each in-flight tool call was handed, with that
+     * call's turn signal. `subAgents.run` accepts only a parent found here:
+     * the session a running tool was given, by identity, never an id, so a
+     * plugin cannot start sub-agents of another turn (another agent's
+     * included) just because that turn is running. The signal is how the
+     * parent's cancel reaches its sub-agents whether or not the plugin
+     * passes one.
+     */
+    const toolCallsInFlight = new Map();
+    const bindToolCalls = (inner) => ({
+        async execute(call, tool, session, context) {
+            if (!idAtFirstCall.has(session)) {
+                idAtFirstCall.set(session, session.id);
+            }
+            const entry = toolCallsInFlight.get(session) ?? [];
+            toolCallsInFlight.set(session, entry);
+            const signal = context?.signal;
+            entry.push(signal);
+            try {
+                return await inner.execute(call, tool, session, context);
+            }
+            finally {
+                entry.splice(entry.indexOf(signal), 1);
+                if (entry.length === 0) {
+                    toolCallsInFlight.delete(session);
+                }
+            }
+        },
+    });
+    const subAgentSlot = (parentId, signal) => new Promise((resolve, reject) => {
+        const entry = subAgentSlots.get(parentId) ?? { running: 0, waiting: [] };
+        subAgentSlots.set(parentId, entry);
+        const release = () => {
+            entry.running -= 1;
+            const next = entry.waiting.shift();
+            if (next) {
+                next();
+            }
+            else if (entry.running === 0) {
+                subAgentSlots.delete(parentId);
+            }
+        };
+        const take = () => {
+            entry.running += 1;
+            resolve(release);
+        };
+        if (entry.running < maxSubAgentsPerTurn) {
+            take();
+            return;
+        }
+        const onAbort = () => {
+            const at = entry.waiting.indexOf(waiter);
+            if (at >= 0) {
+                entry.waiting.splice(at, 1);
+            }
+            reject(abortErrorFor(signal));
+        };
+        const waiter = () => {
+            signal?.removeEventListener('abort', onAbort);
+            take();
+        };
+        entry.waiting.push(waiter);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+    /** Why this slice cannot be a sub-agent's, or undefined when it can. */
+    const subAgentSliceProblem = (parent, requested) => {
+        if (!Array.isArray(requested) || requested.some((name) => typeof name !== 'string' || name.length === 0)) {
+            return 'A sub-agent\'s tools are a list of tool names.';
+        }
+        const allowlist = parent.agent.tools;
+        for (const name of requested) {
+            if (/[*?]/.test(name)) {
+                return `A sub-agent's tools are exact names, and ${name} is a pattern.`;
+            }
+            if (subAgentNeverGets(name)) {
+                return `${name} is never given to a sub-agent, even by an agent that holds it.`;
+            }
+            if (!tools.get(name)) {
+                return `There is no tool named ${name}.`;
+            }
+            // The parent's allowlist as its running turn holds it: a slice can
+            // only narrow what that turn may already do.
+            if (allowlist !== undefined && !matchesToolAllowlist(name, allowlist)) {
+                return `${name} is not one of ${parent.agent.id}'s tools, so a sub-agent of it cannot have it.`;
+            }
+        }
+        return undefined;
+    };
+    const subAgents = {
+        async run(request) {
+            // Copied before the first await, and only the copy is read from here
+            // on: the plugin keeps its own objects and can change them while this
+            // request is checked or waits for a slot, and a slice changed after
+            // it was checked must not be the slice the sub-agent runs with.
+            const handed = request?.parent;
+            const callSignals = handed ? toolCallsInFlight.get(handed) : undefined;
+            if (!callSignals) {
+                throw new Error('subAgents.run starts sub-agents only for the session your tool was handed, while that call is running. Pass that session object as "parent".');
+            }
+            // The parent turn's own stop, and the caller's as an extra one: a
+            // plugin that passes no signal still has its sub-agents cancelled
+            // with the turn.
+            const stops = [...callSignals, request.signal].filter((signal) => signal !== undefined);
+            const input = {
+                parent: { id: hostIdOf(handed) },
+                instruction: request?.instruction,
+                tools: Array.isArray(request?.tools) ? [...request.tools] : request?.tools,
+                model: request?.model,
+                signal: stops.length === 0 ? undefined : stops.length === 1 ? stops[0] : AbortSignal.any(stops),
+            };
+            const parentId = typeof input.parent.id === 'string' ? input.parent.id : '';
+            if (!parentId) {
+                throw new Error('subAgents.run needs the session of the turn asking.');
+            }
+            const instruction = typeof input.instruction === 'string' ? input.instruction.trim() : '';
+            if (!instruction) {
+                throw new Error('subAgents.run needs an instruction.');
+            }
+            if (input.model !== undefined) {
+                throw new Error('A sub-agent\'s model cannot be chosen yet: it runs on its parent\'s. Leave "model" out.');
+            }
+            const parent = await store.get(parentId);
+            if (!parent) {
+                throw new Error(`There is no session ${parentId} to start a sub-agent from.`);
+            }
+            if (isHostSubAgent(handed) || isSubAgentSession(parent)) {
+                throw new Error('A sub-agent cannot start sub-agents.');
+            }
+            if (parent.status !== 'running') {
+                throw new Error(`Session ${parentId} is not running a turn, and sub-agents start only from one.`);
+            }
+            const depth = typeof parent.metadata?.[DELEGATION_DEPTH_METADATA_KEY] === 'number'
+                ? parent.metadata[DELEGATION_DEPTH_METADATA_KEY]
+                : 0;
+            if (depth >= DEFAULT_MAX_DELEGATION_DEPTH) {
+                throw new Error(`Delegation depth limit reached (${DEFAULT_MAX_DELEGATION_DEPTH}).`);
+            }
+            const problem = subAgentSliceProblem(parent, input.tools);
+            if (problem) {
+                throw new Error(problem);
+            }
+            if (input.signal?.aborted) {
+                throw abortErrorFor(input.signal);
+            }
+            const release = await subAgentSlot(parent.id, input.signal);
+            subAgentCount += 1;
+            const sessionId = `${parent.id}${SUB_AGENT_SESSION_ID_MARKER}${depth + 1}:${subAgentCount}-${randomUUID().slice(0, 8)}`;
+            // The parent agent, narrowed: its id, provider and credentials, the
+            // slice for tools, and nothing else — no instructions (the persona),
+            // no skills, no delegates.
+            const definition = {
+                id: parent.agent.id,
+                name: parent.agent.name,
+                tools: [...new Set(input.tools)],
+                skills: [],
+                delegates: [],
+                ...(parent.agent.credentials !== undefined ? { credentials: [...parent.agent.credentials] } : {}),
+            };
+            let session;
+            liveSubAgentIds.add(sessionId);
+            try {
+                session = await onSessionChain(sessionId, () => dispatchInternal({
+                    sessionId,
+                    agentId: parent.agent.id,
+                    userMessage: instruction,
+                    metadata: {
+                        [SUB_AGENT_METADATA_KEY]: true,
+                        [DELEGATION_DEPTH_METADATA_KEY]: depth + 1,
+                        [DELEGATED_BY_METADATA_KEY]: parent.agent.id,
+                        [ROOT_SESSION_ID_METADATA_KEY]: typeof parent.metadata?.[ROOT_SESSION_ID_METADATA_KEY] === 'string'
+                            ? parent.metadata[ROOT_SESSION_ID_METADATA_KEY]
+                            : parent.id,
+                        // The instruction is the parent's text, at the parent's label:
+                        // a tainted parent must not hand a stranger's words to a
+                        // session that has seen nothing.
+                        [SENDER_TRUST_METADATA_KEY]: sessionWriteTrust(parent),
+                        // On the runtime serving the parent's turn: a parent that has
+                        // switched to its sticky fallback must not have its helpers
+                        // retry the primary it left.
+                        ...(parent.metadata?.[FALLBACK_ACTIVE_METADATA_KEY] === true ? { [FALLBACK_ACTIVE_METADATA_KEY]: true } : {}),
+                    },
+                    ...(input.signal ? { signal: input.signal } : {}),
+                }, [], definition));
+            }
+            catch (error) {
+                if (input.signal?.aborted) {
+                    throw error;
+                }
+                // The error text may be the provider quoting what it refused,
+                // which is this sub-agent's context: labelled as nobody can vouch.
+                return { status: 'error', error: error instanceof Error ? error.message : String(error), sessionId, trust: 'unknown' };
+            }
+            finally {
+                liveSubAgentIds.delete(sessionId);
+                release();
+            }
+            const trust = sessionTrustOf(session);
+            if (session.status === 'failed') {
+                return { status: 'error', error: session.lastError ?? 'The sub-agent failed.', sessionId, trust: 'unknown' };
+            }
+            const reply = [...session.messages]
+                .reverse()
+                .find((message) => message.role === 'assistant' && message.content.trim().length > 0);
+            const outcome = reply
+                ? { status: 'result', text: reply.content, sessionId, trust }
+                : { status: 'empty', sessionId, trust };
+            return outcome;
+        },
+    };
     const runners = new Map();
     // Every provider-construction input participates in the key — model,
     // endpoint, credentials, system prompt, fallback config. A rotated
@@ -1484,13 +1796,17 @@ export const createGateway = (options = {}) => {
         const { soul: _soul, soulPath: _soulPath, fetch: _fetch, ...providerInputs } = config;
         return createHash('sha256').update(JSON.stringify(providerInputs)).digest('hex');
     };
-    const runnerFor = (config, agentId) => {
+    // A sub-agent's runner has no memory store, so no turn of it injects or
+    // reads the agent's memory; no skill catalog, so its prompt is its
+    // instruction and its tools; and grants nothing to every agent, since
+    // the credential request asks a person.
+    const runnerFor = (config, agentId, subAgent = false) => {
         // The budget is a provider-construction input too (the harness
         // runtimes take it as their inner limit), so it is part of the key:
         // two agents on one model with different budgets get their own runners.
         const maxTurns = options.maxTurnsFor?.(agentId) ?? options.maxTurns;
         const autoContinue = options.autoContinueFor?.(agentId);
-        const key = `${runnerKeyFor(config)}:${maxTurns ?? 'default'}:${autoContinue ?? 'off'}`;
+        const key = `${runnerKeyFor(config)}:${maxTurns ?? 'default'}:${autoContinue ?? 'off'}${subAgent ? ':sub' : ''}`;
         const existing = runners.get(key);
         if (existing) {
             return existing;
@@ -1515,16 +1831,15 @@ export const createGateway = (options = {}) => {
             // Runners are built on dispatch, after the plugins loaded and the
             // selection below ran, so a contributed executor is in place for
             // the first turn.
-            executor: selectedExecutor ?? createLocalCommandExecutor(),
+            executor: bindToolCalls(selectedExecutor ?? createLocalCommandExecutor()),
             ...(approvals ? { approvals } : {}),
             store,
             bus,
             agents: registry,
             // Asking a person for a key is harmless to grant: they decide
             // everything after the question, so no soul has to list it.
-            grantedToEveryAgent: [CREDENTIAL_REQUEST_TOOL_NAME],
-            skills: skillCatalog,
-            memory,
+            grantedToEveryAgent: subAgent ? [] : [CREDENTIAL_REQUEST_TOOL_NAME],
+            ...(subAgent ? {} : { skills: skillCatalog, memory }),
             streaming: true,
             ...(maxTurns !== undefined ? { maxTurns } : {}),
             ...(autoContinue !== undefined
@@ -1613,7 +1928,7 @@ export const createGateway = (options = {}) => {
             // No watchdog and nobody outside to cancel it — but still a turn an
             // announced restart must be able to cut short at the window.
             const idle = new AbortController();
-            turnControllers.add(idle);
+            trackTurn(sessionId, idle);
             if (abortingWith !== undefined) {
                 idle.abort(new RunAbortedError(abortingWith));
             }
@@ -1621,11 +1936,11 @@ export const createGateway = (options = {}) => {
                 return await run(idle.signal);
             }
             finally {
-                turnControllers.delete(idle);
+                untrackTurn(sessionId, idle);
             }
         }
         const controller = new AbortController();
-        turnControllers.add(controller);
+        trackTurn(sessionId, controller);
         if (abortingWith !== undefined) {
             controller.abort(new RunAbortedError(abortingWith));
         }
@@ -1783,7 +2098,7 @@ export const createGateway = (options = {}) => {
             unsubscribeObserver();
             unsubscribeDrain();
             suspendWatchdog.delete(sessionId);
-            turnControllers.delete(controller);
+            untrackTurn(sessionId, controller);
             external?.removeEventListener('abort', onExternalAbort);
         }
     };
@@ -1803,6 +2118,11 @@ export const createGateway = (options = {}) => {
     // Open until `startServing` reads what the last process left, which it
     // does before any channel or the scheduler can deliver work.
     let intakeState = { paused: false };
+    // A copy for callers, saying while paused whether this is the pause an
+    // unreadable file started (see `IntakeState.unreadable`).
+    const intakeView = () => (intakeState.paused
+        ? { ...intakeState, unreadable: intakeState.unreadable === true }
+        : { ...intakeState });
     let heldState = options.held === true;
     /** What a held start left for `promote()`: the channels it did not start, and the sweeps it did not run. */
     let deferredStart;
@@ -1821,9 +2141,27 @@ export const createGateway = (options = {}) => {
      * window ends by aborting these — the same signal the watchdog fires —
      * so a turn that outlives the window fails as aborted, its session
      * saved, instead of being cut off by a process exit and found as
-     * abandoned by the next one.
+     * abandoned by the next one. Keyed by session, so a stop for one
+     * conversation (`abortTurns`) reaches every turn running there, a
+     * recovered one included, and nothing else.
      */
-    const turnControllers = new Set();
+    const turnControllers = new Map();
+    const trackTurn = (sessionId, controller) => {
+        const running = turnControllers.get(sessionId);
+        if (running) {
+            running.add(controller);
+        }
+        else {
+            turnControllers.set(sessionId, new Set([controller]));
+        }
+    };
+    const untrackTurn = (sessionId, controller) => {
+        const running = turnControllers.get(sessionId);
+        running?.delete(controller);
+        if (running?.size === 0) {
+            turnControllers.delete(sessionId);
+        }
+    };
     /**
      * Set once a restart's or a stop's window has closed and the turns in it
      * were aborted, to the reason they were aborted with. A turn that starts
@@ -1845,9 +2183,9 @@ export const createGateway = (options = {}) => {
     let serving = false;
     /** Set once `restart()` announced; the refusal a caller reads says why. */
     let restartStatus;
-    const refusal = () => new Error(restartStatus
-        ? 'stratusd is restarting and will accept new work once it is back up.'
-        : 'The gateway is stopping and no longer accepts new work.');
+    const refusal = () => restartStatus
+        ? new GatewayStoppingError('stratusd is restarting and will accept new work once it is back up.', true)
+        : new GatewayStoppingError('The gateway is stopping and no longer accepts new work.', false);
     /**
      * The turn id running on each session, for callers that named one.
      *
@@ -1978,7 +2316,12 @@ export const createGateway = (options = {}) => {
             ? runsOnHarness(fallback)
             : runsOnHarness(config) || (fallback !== undefined && runsOnHarness(fallback));
     };
-    const dispatchInternal = async (input, absorbedKeys = []) => {
+    /**
+     * `subAgent` is the narrowed definition `subAgents.run` built: the turn
+     * runs as that, on the parent's resolved provider, with no memory and no
+     * soul. Only that path passes it.
+     */
+    const dispatchInternal = async (input, absorbedKeys = [], subAgent) => {
         // Re-read on every turn, not once at start: a newer build that stamps
         // the home while this daemon is serving has formats this build does not
         // understand, and a daemon that kept writing into them would be the
@@ -2001,7 +2344,10 @@ export const createGateway = (options = {}) => {
         const existing = await store.get(input.sessionId);
         const agentId = input.agentId ?? existing?.agent.id ?? await defaultAgentId();
         const source = await refreshAgent(agentId);
-        const agent = source.definition;
+        const agent = subAgent ?? source.definition;
+        if (subAgent !== undefined && existing) {
+            throw new Error(`Session ${input.sessionId} already exists; a sub-agent's session is new every time.`);
+        }
         // An archived transcript is the record of a conversation that has moved
         // on. Continuing it would revive a session the operator deliberately
         // left behind, under an id nothing routes to any more.
@@ -2010,7 +2356,7 @@ export const createGateway = (options = {}) => {
             throw new Error(`Session ${input.sessionId} was rolled over; it is an archived transcript and the conversation continues as ${continuedAs}.`);
         }
         const config = await runtimeForAgent(source);
-        const runner = runnerFor(config, source.definition.id);
+        const runner = runnerFor(config, source.definition.id, subAgent !== undefined);
         // Which executor the turn's tool calls run through — the built-in
         // under the name `stratus run` has always recorded, a contributed one
         // under its registered name — so a transcript says where a command
@@ -2030,7 +2376,8 @@ export const createGateway = (options = {}) => {
         if (existing && existing.agent.id !== agent.id) {
             throw crossIdentityError(input.sessionId, existing.agent.id, agent.id);
         }
-        const { switchedToFallback, effectiveStreams, fallbackStreams } = watchdogStreamsFor(existing, config);
+        // A sub-agent's session is new, but may start on its parent's fallback.
+        const { switchedToFallback, effectiveStreams, fallbackStreams } = watchdogStreamsFor(existing ?? (subAgent !== undefined ? { metadata } : undefined), config);
         // Recorded with a keyed message so a restart judges the turn by what it
         // could have run on, not by whatever the config resolves to by then.
         // The fallback counts: a turn can switch to it mid-run. Once a session
@@ -2057,6 +2404,13 @@ export const createGateway = (options = {}) => {
                 if (isDelegatedSession(existing) && existing.metadata) {
                     existing.metadata = withoutDelegation(existing.metadata);
                 }
+                // The same for a sub-agent's session, continued as the agent itself:
+                // the marker that denies its approvals unasked comes off with the
+                // delegation markers it carries.
+                if (isSubAgentSession(existing) && existing.metadata) {
+                    const { [SUB_AGENT_METADATA_KEY]: _subAgent, ...rest } = withoutDelegation(existing.metadata);
+                    existing.metadata = rest;
+                }
                 // The executor record follows the daemon, not the session's first
                 // turn: a restart that selected another executor runs this turn's
                 // commands there, and a session from before the record existed
@@ -2106,7 +2460,7 @@ export const createGateway = (options = {}) => {
                 ...(hostedLoop ? { hostedLoop } : {}),
                 ...(input.earlier !== undefined && input.earlier.length > 0 ? { earlier: input.earlier } : {}),
                 metadata,
-                runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata),
+                runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata, subAgent !== undefined),
                 signal,
             });
         });
@@ -2220,6 +2574,14 @@ export const createGateway = (options = {}) => {
             // Whether it IS an orphan was decided before the channels started
             // (`listOrphanedDelegations`), from the parent's transcript, which
             // a message arriving since may already have rewritten.
+            // A sub-agent never parks (nobody is asked for it), and if one ever
+            // did, its parent's turn died with the last process: nothing would
+            // read its answer, and recovering it would run it as the full agent.
+            if (isSubAgentSession(session) && session.status === 'pending_approval') {
+                log(`${sessionId}: a sub-agent parked when the last stratusd stopped; failing it`);
+                await failParked(session, ABANDONED_TURN_ERROR);
+                return;
+            }
             if (orphaned && isDelegatedSession(session) && session.status === 'pending_approval' && record) {
                 log(`${sessionId}: parked on ${record.call.toolName} for a delegating turn the last stratusd was still running; failing it`);
                 await failOrphanedDelegation(session);
@@ -2255,15 +2617,21 @@ export const createGateway = (options = {}) => {
             await store.save(session);
             const recoveredConfig = await runtimeForAgent(source);
             const runner = runnerFor(recoveredConfig, source.definition.id);
-            // Tracked like a dispatched turn's controller: a recovered turn
-            // that runs on past its approval is a turn like any other, and a
-            // restart's window has to be able to cut it short with the same
-            // reason — or it runs unseen to the second window and the restart
-            // reports undrained for a turn it could have finished cleanly.
+            // Tracked like a dispatched turn's controller: a recovered turn that
+            // runs on past its approval is a turn like any other, so a restart's
+            // window has to be able to cut it short with the same reason (or it
+            // runs unseen to the second window and the restart reports
+            // undrained), and a stop for the session has to find it. Only once
+            // the checkpoint has been read on this chain, right before the runner
+            // takes it: a stop counted then always ends in the turn's own
+            // outcome. A stop sent during the reads above finds nothing running
+            // and reaches the session as an ordinary message, queued behind it.
             const controller = new AbortController();
-            turnControllers.add(controller);
-            if (abortingWith !== undefined) {
-                controller.abort(new RunAbortedError(abortingWith));
+            if (record) {
+                trackTurn(sessionId, controller);
+                if (abortingWith !== undefined) {
+                    controller.abort(new RunAbortedError(abortingWith));
+                }
             }
             try {
                 await runner.recoverPendingApproval(sessionId, {
@@ -2273,7 +2641,7 @@ export const createGateway = (options = {}) => {
                 });
             }
             finally {
-                turnControllers.delete(controller);
+                untrackTurn(sessionId, controller);
                 // A recovered firing's row outlived the process that would have
                 // retired it, and the firing is over either way — a recovery that
                 // failed has durably failed its session, which is as finished as
@@ -2449,6 +2817,12 @@ export const createGateway = (options = {}) => {
      * completes it first.)
      */
     const continueAbandonedTurn = async (session) => {
+        // Its parent's turn died with the last process, and continuing it here
+        // would run it as the full agent. (Sub-agent turns carry no key today,
+        // so this is a guard, not a path.)
+        if (isSubAgentSession(session)) {
+            return failAbandoned(session);
+        }
         // Settled either way: a turn whose agent left the roster, or whose
         // provider no longer resolves, must not stay `running` for every later
         // start and every redelivery to find unfinished and trip over again.
@@ -3091,6 +3465,7 @@ export const createGateway = (options = {}) => {
             // not only on a stderr the service manager owns.
             log,
             warn,
+            subAgents,
         });
         loadedPlugins = result.loaded;
         pluginFailures = result.failures;
@@ -3260,6 +3635,18 @@ export const createGateway = (options = {}) => {
             }
             try {
                 await adapter.start(gateway);
+                // A shutdown that gave up waiting on this start has already stopped
+                // the channels it could see; one that comes up after that is
+                // stopped here, or it would stay connected beside the next daemon.
+                if (channelsClosed) {
+                    try {
+                        await adapter.stop();
+                    }
+                    catch (stopError) {
+                        warn(`channel ${adapter.name} started after the shutdown stopped the channels, and failed to stop: ${stopError instanceof Error ? stopError.message : String(stopError)}`);
+                    }
+                    return;
+                }
                 startedChannels.push(adapter);
             }
             catch (error) {
@@ -3407,6 +3794,8 @@ export const createGateway = (options = {}) => {
         return released;
     };
     const startedChannels = [];
+    /** Set once a shutdown has stopped the started channels; a start that finishes after it stops its own. */
+    let channelsClosed = false;
     /** Resolves with `true` when `work` settles before `ms` elapse. */
     const settlesWithin = (work, ms) => new Promise((resolve) => {
         const timer = setTimeout(() => resolve(false), ms);
@@ -3461,22 +3850,43 @@ export const createGateway = (options = {}) => {
         // the same messages. Reported, and for a restart, counted as not
         // drained; a plain stop goes on closing either way.
         let channelsReleased = true;
+        // Once, whichever path gets there first: the end of the drain, or the
+        // window giving up on a turn that ignores its abort.
+        let channelsStopping;
+        const stopChannels = () => {
+            channelsStopping ??= (async () => {
+                channelsClosed = true;
+                const stopping = [...startedChannels];
+                startedChannels.length = 0;
+                const stops = await Promise.allSettled(stopping.map((adapter) => adapter.stop()));
+                stops.forEach((result, index) => {
+                    if (result.status === 'rejected') {
+                        channelsReleased = false;
+                        warn(`channel ${stopping[index]?.name} failed to stop: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+                    }
+                });
+            })();
+            return channelsStopping;
+        };
         const drain = (async () => {
             // A promotion still connecting channels finishes first, so every
             // channel it started is in the list stopped below; seeing `stopping`,
             // it starts nothing after that.
             await promoting?.catch(() => undefined);
             await Promise.allSettled([...approvalEmissions]);
-            const stopping = [...startedChannels];
-            const stops = await Promise.allSettled(stopping.map((adapter) => adapter.stop()));
-            stops.forEach((result, index) => {
-                if (result.status === 'rejected') {
-                    channelsReleased = false;
-                    warn(`channel ${stopping[index]?.name} failed to stop: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
-                }
-            });
-            startedChannels.length = 0;
-            await Promise.allSettled([...inflight]);
+            // The turns first, with the channels still connected. A channel that
+            // disconnects at the start of a drain cannot hear anyone for as long
+            // as the drain lasts, and a long turn makes that minutes: a message
+            // sent then reached no daemon at all, with no reply and no log line.
+            // Connected, it is refused with `GatewayStoppingError`, which the
+            // channel can answer and keep for the next daemon. Until the set stays
+            // empty: a turn queued behind one that finished joins it.
+            while (inflight.size > 0) {
+                await Promise.allSettled([...inflight]);
+            }
+            // Then the channels, whose stop awaits the rendering they still have
+            // in flight: the outcomes of the turns that just finished.
+            await stopChannels();
         })();
         // One deadline for the whole bounded shutdown: the drain window, then
         // one more window that everything after it shares (the aborted turns'
@@ -3501,12 +3911,20 @@ export const createGateway = (options = {}) => {
             // Before the loop, so a turn queued behind one aborted here, which
             // starts as soon as that one settles, is aborted the same way.
             abortingWith = kind === 'stop' ? STOPPING_TURN_ERROR : RESTARTING_TURN_ERROR;
-            for (const controller of turnControllers) {
-                controller.abort(new RunAbortedError(abortingWith));
+            for (const running of turnControllers.values()) {
+                for (const controller of running) {
+                    controller.abort(new RunAbortedError(abortingWith));
+                }
             }
             drained = await settlesWithin(drain, remaining());
             if (!drained) {
                 warn(`${kind}: ${inflight.size} turn(s) did not stop after being aborted; shutting down around them`);
+                // The drain never got to the channels. Stopped here instead, so a
+                // host that goes on to start the next daemon does not find this one
+                // still connected beside it; a channel's stop takes its intake down
+                // before it waits on anything, so this ends what it can hear even if
+                // it never settles.
+                await settlesWithin(stopChannels(), remaining());
             }
             drained = drained && channelsReleased;
         }
@@ -3662,35 +4080,10 @@ export const createGateway = (options = {}) => {
                 || (message.role === 'tool' && message.toolResult !== undefined && filePathsOf(message.toolResult).length > 0);
             const spokeIndex = session.messages.findLastIndex(spoken);
             const lastSpokeAt = spokeIndex >= 0 ? session.messages[spokeIndex]?.createdAt : undefined;
-            // The attention anchor is narrower than the thread rule's: the newest
-            // reply to a turn somebody ASKED for — one whose message was not
-            // overheard. A reply the agent chose to give on a turn nobody asked
-            // for is speaking, for the thread rule, and not an anchor, or a
-            // judge that likes the sound of its own voice would never drift out.
-            // The trigger of a reply is the nearest user message before it.
-            let answeredIndex = -1;
-            for (let index = session.messages.length - 1; index >= 0 && answeredIndex < 0; index -= 1) {
-                const message = session.messages[index];
-                if (!message || !spoken(message)) {
-                    continue;
-                }
-                const trigger = session.messages.slice(0, index).findLast((earlier) => earlier.role === 'user');
-                if (trigger !== undefined && trigger.overheard !== true) {
-                    answeredIndex = index;
-                }
-            }
-            const lastAnsweredAt = answeredIndex >= 0 ? session.messages[answeredIndex]?.createdAt : undefined;
-            // The messages after that answer: what it has heard, judged, or been
-            // asked and not answered since — the other half of the window.
-            const heardSinceAnswered = session.messages
-                .slice(answeredIndex + 1)
-                .filter((message) => message.role === 'user').length;
             return {
                 agentId: session.agent.id,
                 metadata: session.metadata ?? {},
                 ...(lastSpokeAt !== undefined ? { lastSpokeAt } : {}),
-                ...(lastAnsweredAt !== undefined ? { lastAnsweredAt } : {}),
-                heardSinceAnswered,
                 ...(reply !== undefined ? { reply } : {}),
                 ...(isUnaddressedTurn(session) ? { unaddressed: true } : {}),
             };
@@ -3837,6 +4230,15 @@ export const createGateway = (options = {}) => {
         activeTurnId(sessionId) {
             return activeTurns.get(sessionId);
         },
+        abortTurns(sessionId, reason) {
+            const running = turnControllers.get(sessionId) ?? new Set();
+            for (const controller of running) {
+                if (!controller.signal.aborted) {
+                    controller.abort(new RunAbortedError(reason));
+                }
+            }
+            return running.size;
+        },
         pendingApprovals() {
             return [...pendingApprovals.values()]
                 .map((parked) => parked.pending)
@@ -3960,7 +4362,7 @@ export const createGateway = (options = {}) => {
         },
         resolveApproval,
         intake() {
-            return { ...intakeState };
+            return intakeView();
         },
         async pauseIntake(input = {}) {
             let message;
@@ -3985,7 +4387,7 @@ export const createGateway = (options = {}) => {
                 await writeIntakeState(env, next);
                 intakeState = next;
                 log('intake paused: new work will be refused until it resumes');
-                return { ...intakeState };
+                return intakeView();
             });
         },
         held() {
@@ -3999,7 +4401,7 @@ export const createGateway = (options = {}) => {
                     log('intake resumed');
                 }
                 intakeState = { paused: false };
-                return { ...intakeState };
+                return intakeView();
             });
         },
         provideCredential,