@stratusagent/gateway 0.13.7 → 0.14.1

package/dist/index.js

@@ -9,17 +9,21 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm } 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, 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, createChannelCreateTool, directMessageReadRefusal, 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 { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, workItemState, leftForNextStart, 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, createChannelArchiveTool, createChannelCreateTool, createChannelInviteTool, createChannelJoinTool, directMessageReadRefusal, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATED_SESSION_ID_MARKER, 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, credentialVariableProblem, } from '@stratusagent/agents';
 import { createFleetReader } from "./fleet.js";
+import { createEventIntake, summarizeEvents, } from "./event-intake.js";
+import { SqliteEventStore } from "./events.js";
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { ShardedSessionStore } from "./sessions.js";
 export { claimHome, homeLockPath, HomeClaimedError, } from "./lock.js";
 export { SqliteSessionStore, ShardedSessionStore, FleetSessionIndex, SessionIdTakenError, tightenSqliteFile, } from "./sessions.js";
 export { SqliteScheduleStore, createSchedulerRuntime, isScheduleSessionId, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
+export { SqliteEventStore, EVENT_BLOCK_MAX_BYTES, EVENT_DEDUP_WINDOW_MS, EVENT_DELIVERY_ROW_CAP, eventCoalescingKey, eventDispatchKey, eventSessionId, renderEventBlock, } from "./events.js";
+export { createEventIntake, mapGithubDelivery, parseStandardWebhookEvent, verifyGithubSignature, verifyStandardWebhookSignature, DEFAULT_EVENT_MAX_BODY_BYTES, EVENT_SOURCE_REQUESTS_PER_MINUTE, } from "./event-intake.js";
 import { createLocalCommandExecutor } from '@stratusagent/executor-local';
 import { loadPlugins, } from '@stratusagent/plugins';
-import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, describeServingModel, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, grantSoulCredential, withSoulFileLock, addNamedCredential, appendCredentialAudit, replaceNamedCredential, NamedCredentialMissingError, namedCredentialSource, NamedCredentialExistsError, CREDENTIAL_NAME_PATTERN, quoteShellArg, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, runsOnHarness, applySoulPins, assertStateCompatible, stratusHomePath, intakeStatePath, fleetDbIn, createAgentWorkspaces, createPluginStateDirectories, createHostProtectedPaths, foldedAgentId, syncDirectory, writeFileSynced, } from '@stratusagent/state';
+import { BUILTIN_EXECUTOR_NAME, BUILTIN_MEMORY_STORE_NAME, BUILTIN_PROVIDER_NAMES, createDemoTool, createFileCredentialResolver, resolveDaemonCredential, createHomeMemoryStore, drainSharedMemory, hasBracketedLegacyStateIn, createRuntimeProvider, describeServingModel, DEFAULT_STRATUS_AGENT, isRegisteredProviderName, loadChannelTransportSecrets, registeredProviderNameOf, loadOperatorSkills, loadRosterSouls, FALLBACK_ACTIVE_METADATA_KEY, loadSoulFile, grantSoulCredential, withSoulFileLock, addNamedCredential, appendCredentialAudit, replaceNamedCredential, NamedCredentialMissingError, namedCredentialSource, NamedCredentialExistsError, CREDENTIAL_NAME_PATTERN, quoteShellArg, migrateLegacyMemory, PROVIDER_STATE_METADATA_KEYS, ConfigFileError, loadConfigFile, resolveConfigLocation, resolveConfiguredSoul, resolveRuntimeConfig, runsOnHarness, applySoulPins, assertStateCompatible, stratusHomePath, intakeStatePath, fleetDbIn, createAgentWorkspaces, createPluginStateDirectories, createHostProtectedPaths, foldedAgentId, syncDirectory, writeFileSynced, } from '@stratusagent/state';
 const DEFAULT_IDLE_TIMEOUT_MS = 120_000;
 /**
  * How long a parked call waits for a person. Long enough to survive a
@@ -53,6 +57,8 @@ export const STOPPING_TURN_ERROR = 'Run aborted: stratusd is stopping';
  * two windows an operator can hit agree.
  */
 export const DEFAULT_RESTART_DRAIN_TIMEOUT_MS = 30_000;
+/** How long a roster reload waits on one channel's `reload()`. */
+export const DEFAULT_CHANNEL_RELOAD_TIMEOUT_MS = 30_000;
 /**
  * How long a stop lets in-flight turns finish before aborting them. The
  * daemon's documented drain ("up to 30 seconds"), and shorter than the
@@ -209,6 +215,24 @@ const allAborted = (signals) => {
     check();
     return controller.signal;
 };
+/**
+ * A value from a form, without the line breaks around it.
+ *
+ * Forms take multi-line values now, so a one-line key copied with the line
+ * break after it would otherwise be stored with it, and fail later inside
+ * whatever header or command it lands in. Only line breaks: a value's own
+ * spaces are its own, as on the CLI.
+ */
+const formCredentialValue = (value) => value.replace(/^[\r\n]+|[\r\n]+$/g, '');
+/**
+ * A PEM block (a private key, a certificate) with no line breaks left, which
+ * is what a one-line field makes of a pasted key file. PEM readers need the
+ * line after the `-----BEGIN …-----` header, so storing it would only move
+ * the failure to the first call that reads the key. Only a value that *is*
+ * one: a PEM inside JSON (a service account file) escapes its line breaks,
+ * so it has none of its own and is fine as sent.
+ */
+const isFlattenedPem = (value) => /^\s*-----BEGIN [A-Z0-9 ]+-----/.test(value) && !value.includes('\n');
 /**
  * Recorded on a turn the previous process was still running when it died.
  *
@@ -393,6 +417,40 @@ export const createGateway = (options = {}) => {
     // The same database sessions live in — one file to back up — through the
     // schedule store's own connection (see its docs for why).
     const scheduleStore = new SqliteScheduleStore(fleetDbIn(stateDir), { stateHome: stateDir });
+    // ---- events (card 590) ---------------------------------------------------
+    // Opened for the first source, so a daemon that never takes events never
+    // grows the tables: at construction for the config's sources, or when the
+    // first plugin feeding a source loads (phase 2), which is at start(),
+    // before the scheduler's start-up pass. Its own connection to fleet.db,
+    // like schedules'.
+    const eventSources = options.events?.sources ?? {};
+    /** Sources plugins feed: source id to the package that declared it, filled as each loads. */
+    const pluginEventSources = new Map();
+    const eventSourceIds = () => [...Object.keys(eventSources), ...pluginEventSources.keys()];
+    let eventStore;
+    let eventIntake;
+    const openEvents = () => {
+        if (!eventStore || !eventIntake) {
+            eventStore = new SqliteEventStore(fleetDbIn(stateDir), { stateHome: stateDir });
+            eventIntake = createEventIntake({
+                store: eventStore,
+                sources: () => eventSources,
+                pluginSources: () => [...pluginEventSources.keys()],
+                // The daemon's own credential, read per delivery: a stored or
+                // rotated secret works on the next one, with no restart.
+                secret: (name) => resolveDaemonCredential(env, name),
+                // The triggers are schedules: `schedule.on` rows on this source.
+                // Late-bound, because the scheduler is built further down.
+                triggers: (sourceId) => scheduler.eventTriggers(sourceId),
+                ...(options.events?.maxBodyBytes !== undefined ? { maxBodyBytes: options.events.maxBodyBytes } : {}),
+                warn,
+            });
+        }
+        return { store: eventStore, intake: eventIntake };
+    };
+    if (Object.keys(eventSources).length > 0) {
+        openEvents();
+    }
     /**
      * The started adapter of one kind that speaks for an agent and has the
      * capability asked for. `carriesOthers` says there were capable adapters
@@ -456,12 +514,28 @@ export const createGateway = (options = {}) => {
             await outboundFor(agentId, destination);
         },
         sessionStatus: async (sessionId) => (await store.get(sessionId))?.status,
+        // Card 858: the previous firing, for the next one's checkpoint. The
+        // reply and its label, never the transcript.
+        previousRun: async (sessionId) => {
+            const session = await store.get(sessionId);
+            if (!session) {
+                return undefined;
+            }
+            const reply = latestTurnReply(session);
+            return {
+                status: session.status,
+                ...(session.stoppedEarly !== undefined ? { stoppedEarly: session.stoppedEarly } : {}),
+                ...(reply !== undefined ? { reply } : {}),
+                trust: sessionWriteTrust(session),
+            };
+        },
         hasAgent: (agentId) => registry.get(agentId) !== undefined,
         ...(options.schedules ? { limits: options.schedules } : {}),
         // The same stamp check every turn runs, before a slot is claimed — see
         // `SchedulerRuntimeOptions.ready`.
         ready: () => assertStateCompatible(env),
         paused: () => intakeState.paused,
+        ...(eventStore ? { events: { store: eventStore, sources: eventSourceIds } } : {}),
         log,
         warn,
     });
@@ -1142,6 +1216,59 @@ export const createGateway = (options = {}) => {
         reloads = next.catch(() => undefined);
         await next;
     };
+    const channelReloadTimeoutMs = options.channelReloadTimeoutMs ?? DEFAULT_CHANNEL_RELOAD_TIMEOUT_MS;
+    /**
+     * After a roster reload, each started channel that can picks up the
+     * agents it carries now (a new agent's stored app, one whose soul or
+     * secrets are gone). One at a time, in start order, so the log reads in
+     * the order an operator configured them. A channel that fails is
+     * logged and the rest still reload: one bad app must not hold back the
+     * others, the rule `startChannels` follows. A channel still reloading
+     * after the bound is left to finish on its own, and what it ends with is
+     * logged then, so a hung Slack call cannot hold every later reload.
+     */
+    const reloadChannels = async () => {
+        const outcomes = [];
+        for (const adapter of [...startedChannels]) {
+            if (stopping || channelsClosed) {
+                return outcomes;
+            }
+            if (typeof adapter.reload !== 'function') {
+                continue;
+            }
+            const reload = adapter.reload.bind(adapter);
+            // Settles with the failure, never rejects: one that comes after the
+            // bound has nobody awaiting it, and would take the daemon down.
+            const settled = (async () => reload())().then(() => undefined, (error) => (error instanceof Error ? error.message : String(error)));
+            let timer;
+            const bound = new Promise((resolve) => {
+                timer = setTimeout(() => resolve('timeout'), channelReloadTimeoutMs);
+                timer.unref?.();
+            });
+            const outcome = await Promise.race([settled.then((failure) => ({ failure })), bound]);
+            clearTimeout(timer);
+            if (outcome === 'timeout') {
+                warn(`channel ${adapter.name} is still reloading after ${channelReloadTimeoutMs} ms; the roster reload goes on without it`);
+                void settled.then((failure) => {
+                    if (failure !== undefined) {
+                        warn(`channel ${adapter.name} could not reload: ${failure}`);
+                    }
+                    else {
+                        log(`channel ${adapter.name} finished reloading`);
+                    }
+                });
+                outcomes.push({ name: adapter.name, outcome: 'still-reloading' });
+                continue;
+            }
+            if (outcome.failure !== undefined) {
+                warn(`channel ${adapter.name} could not reload: ${outcome.failure}`);
+                outcomes.push({ name: adapter.name, outcome: 'failed', reason: outcome.failure });
+                continue;
+            }
+            outcomes.push({ name: adapter.name, outcome: 'reloaded' });
+        }
+        return outcomes;
+    };
     /**
      * A session pins its agent id, never a snapshot of the agent: the soul
      * file is re-read on every dispatch, so an edited persona (or tool
@@ -1294,6 +1421,128 @@ export const createGateway = (options = {}) => {
         }
         return adapter.createConversation({ agentId, ...request });
     }));
+    // Joining and inviting follow the same rule: the asking agent's own app
+    // does it, so membership stays per app and its token stays in the adapter.
+    tools.register(createChannelJoinTool(async ({ agentId, channel, conversation }) => {
+        const { adapter, carriesOthers } = channelCarrying(channel, agentId, (candidate) => candidate.joinConversation !== undefined);
+        if (!adapter?.joinConversation) {
+            throw new Error(carriesOthers
+                ? `No running '${channel}' channel carries agent ${agentId}, so it has no app to join a channel with.`
+                : `No running channel can join '${channel}' conversations.`);
+        }
+        return adapter.joinConversation({ agentId, conversation });
+    }));
+    tools.register(createChannelInviteTool(async ({ agentId, channel, ...request }) => {
+        const { adapter, carriesOthers } = channelCarrying(channel, agentId, (candidate) => candidate.inviteToConversation !== undefined);
+        if (!adapter?.inviteToConversation) {
+            throw new Error(carriesOthers
+                ? `No running '${channel}' channel carries agent ${agentId}, so it has no app to invite anyone with.`
+                : `No running channel can invite people to '${channel}' conversations.`);
+        }
+        return adapter.inviteToConversation({ agentId, ...request });
+    }));
+    /**
+     * Why a `channel.archive` call would archive the conversation its work was
+     * asked from, or can't tell, as a sentence; undefined when it may go on.
+     * That conversation is never archived: the answer to it would have
+     * nowhere to go, and the agent can't unarchive.
+     *
+     * An ordinary session is its own origin. A sub-agent's or a delegated
+     * run's is the root turn that started the chain, read off the id the
+     * host minted for it (each child id is its parent's plus a marker, so the
+     * root is the text before the first one), never off metadata a tool in
+     * the slice could rewrite. The id is the one the session had at its first
+     * tool call, for the same reason. The origin's conversation is asked of
+     * the adapter of this kind that carries the origin's agent. When it can't
+     * be told (the root is gone; no adapter, no `sessionConversation`, a
+     * lookup that fails, or no answer for a session whose id is this
+     * channel's), the call is refused: an archive the agent can't undo
+     * doesn't run on a guess. A session that isn't this channel's at all (an
+     * API call, a schedule, a turn on another transport) has no conversation
+     * here to protect.
+     */
+    const archiveRefusal = async (kind, conversation, session, archiving) => {
+        const unknown = (why) => `${kind} ${conversation} was not archived: ${why}, so Stratus can't tell which conversation this work was asked from, `
+            + 'and that one is never archived. Ask for the archive from a conversation.';
+        const id = hostIdOf(session);
+        const marks = [SUB_AGENT_SESSION_ID_MARKER, DELEGATED_SESSION_ID_MARKER]
+            .map((marker) => id.indexOf(marker))
+            .filter((at) => at >= 0);
+        let origin = { agentId: session.agent.id, sessionId: id };
+        let adapter = archiving;
+        if (marks.length > 0) {
+            const rootId = id.slice(0, Math.min(...marks));
+            let root;
+            try {
+                root = rootId ? await store.get(rootId) : undefined;
+            }
+            catch (error) {
+                warn(`${id}: could not read the root session ${rootId} to check a channel.archive (${error instanceof Error ? error.message : String(error)})`);
+                root = undefined;
+            }
+            if (!root) {
+                return unknown('this run was started by another session that no longer exists');
+            }
+            origin = { agentId: root.agent.id, sessionId: root.id };
+            adapter = channelCarrying(kind, origin.agentId, () => true).adapter;
+        }
+        // Channel session ids lead with their kind (`channelSessionKey`).
+        const onThisChannel = origin.sessionId.startsWith(`${kind}:`);
+        if (!adapter) {
+            return onThisChannel ? unknown(`no running '${kind}' channel carries the agent this work was asked of`) : undefined;
+        }
+        if (!adapter.sessionConversation) {
+            return unknown(`the running '${kind}' channel can't say which conversation a session is in`);
+        }
+        let origins;
+        try {
+            origins = adapter.sessionConversation(origin.agentId, origin.sessionId);
+        }
+        catch (error) {
+            warn(`${id}: could not tell which conversation ${origin.sessionId} is in to check a channel.archive (${error instanceof Error ? error.message : String(error)})`);
+            return unknown(`the running '${kind}' channel couldn't say which conversation this work was asked from`);
+        }
+        if (origins === undefined) {
+            return onThisChannel ? unknown(`the running '${kind}' channel can't say which of its conversations this work was asked from`) : undefined;
+        }
+        return origins === conversation
+            ? `${kind} ${conversation} is the conversation this work was asked from, so it was not archived: `
+                + 'the reply would have nowhere to go. Ask for the archive from another conversation.'
+            : undefined;
+    };
+    const archivingAdapter = (kind, agentId) => channelCarrying(kind, agentId, (candidate) => candidate.archiveConversation !== undefined);
+    const noArchivingAdapter = (kind, agentId, carriesOthers) => carriesOthers
+        ? `No running '${kind}' channel carries agent ${agentId}, so it has no app to archive a channel with.`
+        : `No running channel can archive '${kind}' conversations.`;
+    tools.register(createChannelArchiveTool(async ({ agentId, channel, conversation }, session) => {
+        const { adapter, carriesOthers } = archivingAdapter(channel, agentId);
+        if (!adapter?.archiveConversation) {
+            throw new Error(noArchivingAdapter(channel, agentId, carriesOthers));
+        }
+        const refusal = await archiveRefusal(channel, conversation, session, adapter);
+        if (refusal !== undefined) {
+            throw new Error(refusal);
+        }
+        return adapter.archiveConversation({ agentId, conversation });
+    }, {
+        // The same check before anyone is asked: an approval, Always allow
+        // above all, for an archive that is bound to be refused is a question
+        // with no useful answer. Held as an approval wait, like message.read's,
+        // since it runs before any tool event and may read the store.
+        refusalFor: async ({ agentId, channel, conversation }, session) => {
+            const { adapter, carriesOthers } = archivingAdapter(channel, agentId);
+            if (!adapter?.archiveConversation) {
+                return noArchivingAdapter(channel, agentId, carriesOthers);
+            }
+            const release = holdApprovalWait(session.id);
+            try {
+                return await archiveRefusal(channel, conversation, session, adapter);
+            }
+            finally {
+                release();
+            }
+        },
+    }));
     tools.register(createMessageReadTool(async ({ agentId, source, ...window }) => {
         // The same carrying rule as outbound: a read goes through the app of
         // the agent asking, never whichever adapter of that kind is running,
@@ -1367,11 +1616,26 @@ export const createGateway = (options = {}) => {
             throw new Error(`${JSON.stringify(request.name)} is not a credential name. Use letters, digits, dots, dashes, or underscores, `
                 + 'starting with a letter, the way the tool that needs it spells it: search.apiKey, github.token.');
         }
+        // The stricter rule, for a name the model picked: checked before anyone
+        // is asked, so an approver never sees a form whose binding the store
+        // would refuse, and so a variable that changes what a judged command
+        // does (NODE_OPTIONS) is never offered at all.
+        if (request.env !== undefined) {
+            const problem = credentialVariableProblem(request.env, { requested: true });
+            if (problem !== undefined) {
+                throw new Error(`${problem} Nothing is pending.`);
+            }
+        }
         // A key already stored is not something to ask a person for again: the
         // form only adds, so it could only fail. Say what is actually missing.
         const source = await namedCredentialSource(env, agentId, request.name);
         const stored = source !== undefined;
         const granted = session.agent.credentials?.includes(request.name) === true;
+        // Binding a key the agent already holds asks for no value, and every
+        // form today has a value field, so phase 1 leaves it to the machine.
+        const bindOnMachine = request.env !== undefined
+            ? ` To have your shell read it as ${request.env}, ask your operator to run \`stratus credential env ${request.name} ${request.env} --agent ${quoteShellArg(agentId)}\` on the machine.`
+            : '';
         if (request.replace === true) {
             // Checked here, before anyone is asked, so an approver is never shown
             // a form whose answer could only be refused.
@@ -1394,13 +1658,18 @@ export const createGateway = (options = {}) => {
             }
         }
         else if (stored && granted) {
-            throw new Error(`You already hold ${request.name}; the tools that need it use it for you. To rotate it for a new value, ask again with replace: true.`);
+            throw new Error(`You already hold ${request.name}; the tools that need it use it for you. To rotate it for a new value, ask again with replace: true.${bindOnMachine}`
+                + (request.env !== undefined ? ' Nothing is pending.' : ''));
         }
         else if (stored) {
             throw new Error(`${request.name} is already ${source === 'environment' ? "supplied by the daemon's environment" : 'stored'} but not granted to you. `
-                + 'Ask your operator to add it to the credentials list in your soul; a form would only refuse to store it again.');
+                + `Ask your operator to add it to the credentials list in your soul; a form would only refuse to store it again.${bindOnMachine}`);
         }
-        const onMachine = `\`stratus credential set ${request.name}${request.scope === 'agent' ? ` --agent ${quoteShellArg(agentId)}` : ''}\``;
+        const onMachine = request.env === undefined
+            ? `\`stratus credential set ${request.name}${request.scope === 'agent' ? ` --agent ${quoteShellArg(agentId)}` : ''}\``
+            : request.scope === 'agent'
+                ? `\`stratus credential set ${request.name} --agent ${quoteShellArg(agentId)} --env ${request.env}\``
+                : `\`stratus credential set ${request.name}\`, then \`stratus credential env ${request.name} ${request.env} --agent ${quoteShellArg(agentId)}\``;
         const record = {
             agentId,
             sessionId: session.id,
@@ -1408,6 +1677,7 @@ export const createGateway = (options = {}) => {
             scope: request.scope,
             soulPath,
             ...(request.replace === true ? { replace: true } : {}),
+            ...(request.env !== undefined ? { env: request.env } : {}),
         };
         const announce = async (requestId, via) => {
             await bus.emit({
@@ -1420,6 +1690,7 @@ export const createGateway = (options = {}) => {
                 ...(request.reason !== undefined ? { reason: request.reason } : {}),
                 via,
                 ...(request.replace === true ? { replace: true } : {}),
+                ...(request.env !== undefined ? { env: request.env } : {}),
                 ...(session.metadata ? { metadata: session.metadata } : {}),
             });
         };
@@ -1440,11 +1711,14 @@ export const createGateway = (options = {}) => {
             const kind = session.metadata?.channel;
             const { adapter } = typeof kind === 'string'
                 ? channelCarrying(kind, agentId, (candidate) => candidate.requestCredential !== undefined
-                    && (request.replace !== true || candidate.credentialReplaceForms === true))
+                    && (request.replace !== true || candidate.credentialReplaceForms === true)
+                    // A form that can't say the key will be shell-readable must not
+                    // be the approval for it: a link says it instead.
+                    && (request.env === undefined || candidate.credentialEnvForms === true))
                 : { adapter: undefined };
             if (!adapter?.requestCredential || !session.metadata) {
                 formUnavailable = typeof kind === 'string'
-                    ? `This conversation's channel (${kind}) cannot show your operator a ${request.replace === true ? 'replacement' : 'credential'} form here.`
+                    ? `This conversation's channel (${kind}) cannot show your operator a ${request.replace === true ? 'replacement' : 'credential'} form here${request.env !== undefined ? ' that says which variable your shell will read it from' : ''}.`
                     : 'This conversation is not in a channel that can show your operator a form.';
             }
             else {
@@ -1463,6 +1737,7 @@ export const createGateway = (options = {}) => {
                         scope: request.scope,
                         ...(request.reason !== undefined ? { reason: request.reason } : {}),
                         ...(request.replace === true ? { replace: true } : {}),
+                        ...(request.env !== undefined ? { env: request.env } : {}),
                         metadata: session.metadata,
                     });
                     await announce(requestId, 'form');
@@ -1504,6 +1779,7 @@ export const createGateway = (options = {}) => {
                 name: request.name,
                 scope: request.scope,
                 ...(request.reason !== undefined ? { reason: request.reason } : {}),
+                ...(request.env !== undefined ? { env: request.env } : {}),
             });
         }
         catch (error) {
@@ -1558,6 +1834,7 @@ export const createGateway = (options = {}) => {
                 ...(actor !== undefined ? { actor } : {}),
                 via: request.via ?? 'form',
                 requestedBy: request.agentId,
+                ...(request.env !== undefined ? { env: request.env, bindingFor: request.agentId } : {}),
             });
         }
         catch (error) {
@@ -1600,7 +1877,24 @@ export const createGateway = (options = {}) => {
                 message: `${request.soulPath} now belongs to ${owner}, not ${request.agentId}, so nothing was stored. Ask ${request.agentId} to request it again.`,
             };
         }
-        const store = request.scope === 'agent' ? { agentId: request.agentId } : {};
+        const value = formCredentialValue(input.value);
+        if (isFlattenedPem(value)) {
+            // Refused, not retired: the same form can still take the key whole.
+            const command = request.scope === 'agent'
+                ? `stratus credential set ${request.name} --agent ${quoteShellArg(request.agentId)} < key.pem`
+                : `stratus credential set ${request.name} < key.pem`;
+            return {
+                ok: false,
+                message: 'That looks like a PEM key whose line breaks were lost, so nothing was stored: whatever reads it would fail. '
+                    + `Paste it again from the original file with its line breaks, or store it on the machine: ${command}.`,
+            };
+        }
+        const store = {
+            ...(request.scope === 'agent' ? { agentId: request.agentId } : {}),
+            // The binding the form promised, written with the value, always for
+            // the agent that asked: consent is per agent even for a shared key.
+            ...(request.env !== undefined ? { bind: { agentId: request.agentId, variable: request.env } } : {}),
+        };
         if (request.replace === true) {
             // Re-read under the soul lock, so a grant removed while the form
             // waited (a shared key most of all) is never rotated on its behalf.
@@ -1611,7 +1905,7 @@ export const createGateway = (options = {}) => {
                     if (soul.agent.id !== request.agentId || soul.agent.credentials?.includes(request.name) !== true) {
                         return false;
                     }
-                    await replaceNamedCredential(env, { name: request.name, value: input.value, ...store });
+                    await replaceNamedCredential(env, { name: request.name, value, ...store });
                     return true;
                 });
             }
@@ -1641,6 +1935,7 @@ export const createGateway = (options = {}) => {
                 name: request.name,
                 scope: request.scope,
                 replace: true,
+                ...(request.env !== undefined ? { env: request.env } : {}),
                 ...(input.actor !== undefined ? { actor: input.actor } : {}),
             });
             // The soul already lists it: a replace is only asked for a key held.
@@ -1649,7 +1944,7 @@ export const createGateway = (options = {}) => {
         try {
             await addNamedCredential(env, {
                 name: request.name,
-                value: input.value,
+                value,
                 ...store,
             });
         }
@@ -1699,6 +1994,7 @@ export const createGateway = (options = {}) => {
             requestId: input.requestId,
             name: request.name,
             scope: request.scope,
+            ...(request.env !== undefined ? { env: request.env } : {}),
             ...(input.actor !== undefined ? { actor: input.actor } : {}),
             ...(grantError !== undefined ? { grantError } : {}),
         });
@@ -2092,7 +2388,7 @@ export const createGateway = (options = {}) => {
             const idle = new AbortController();
             trackTurn(sessionId, idle);
             if (abortingWith !== undefined) {
-                idle.abort(new RunAbortedError(abortingWith));
+                idle.abort(shutdownAbort());
             }
             try {
                 return await run(idle.signal);
@@ -2104,7 +2400,7 @@ export const createGateway = (options = {}) => {
         const controller = new AbortController();
         trackTurn(sessionId, controller);
         if (abortingWith !== undefined) {
-            controller.abort(new RunAbortedError(abortingWith));
+            controller.abort(shutdownAbort());
         }
         // The external reason travels: a caller that aborted with its own
         // `RunAbortedError` gets it recorded on the session, like the watchdog's.
@@ -2348,6 +2644,22 @@ export const createGateway = (options = {}) => {
     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);
+    /**
+     * What the caller of a keyed turn the shutdown cut short hears: the same
+     * refusal, since its message is no more answered than one refused at the
+     * door (a channel keeps it for the next start, as it keeps those), and
+     * worded for a turn that ran and will be continued.
+     */
+    const leftForNext = () => restartStatus
+        ? new GatewayStoppingError('stratusd is restarting; this turn was cut short and continues once it is back up.', true)
+        : new GatewayStoppingError('stratusd is stopping; this turn was cut short and continues when it is started again.', false);
+    /**
+     * The abort a stop's or restart's window ends a turn with. Resumable: a
+     * keyed turn is left for the next start to continue once, as a crash
+     * leaves it, rather than failed (`RunAbortedError.resumable`); every
+     * other turn is failed with the reason, as before.
+     */
+    const shutdownAbort = () => new RunAbortedError(abortingWith, { resumable: true });
     /**
      * The turn id running on each session, for callers that named one.
      *
@@ -2478,6 +2790,27 @@ export const createGateway = (options = {}) => {
             ? runsOnHarness(fallback)
             : runsOnHarness(config) || (fallback !== undefined && runsOnHarness(fallback));
     };
+    /**
+     * A keyed turn the shutdown cut short and the runner left for the next
+     * start (`leftForNextStart`): its caller is told so, the way a message
+     * refused at the door is, and keeps it for the next daemon, which
+     * continues the turn. Read back on the chain, so it is this dispatch's
+     * own message the session is still running on.
+     */
+    const settleLeftForNextStart = async (input, turn) => {
+        try {
+            return await turn;
+        }
+        catch (error) {
+            if (input.idempotencyKey !== undefined && error instanceof RunAbortedError && error.resumable) {
+                const left = await store.get(input.sessionId).catch(() => undefined);
+                if (left !== undefined && workItemState(left, input.idempotencyKey) === 'unfinished' && leftForNextStart(left, error)) {
+                    throw leftForNext();
+                }
+            }
+            throw error;
+        }
+    };
     /**
      * `subAgent` is the narrowed definition `subAgents.run` built: the turn
      * runs as that, on the parent's resolved provider, with no memory and no
@@ -2546,7 +2879,7 @@ export const createGateway = (options = {}) => {
         // has switched for good, the primary is never called again, and only
         // the fallback counts.
         const hostedLoop = input.idempotencyKey !== undefined && reachesHarness(config, switchedToFallback);
-        return withWatchdog(input.sessionId, input.signal, effectiveStreams, fallbackStreams, async (signal) => {
+        return settleLeftForNextStart(input, withWatchdog(input.sessionId, input.signal, effectiveStreams, fallbackStreams, async (signal) => {
             // The preflight above (agent refresh, config resolution, session
             // load) awaited filesystem work; the entry check has long passed.
             // Recheck before the runner touches durable state, or a dispatch
@@ -2625,7 +2958,7 @@ export const createGateway = (options = {}) => {
                 runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata, subAgent !== undefined),
                 signal,
             });
-        });
+        }));
     };
     /**
      * Finishes the turns that were parked on a human when this daemon last
@@ -2792,7 +3125,7 @@ export const createGateway = (options = {}) => {
             if (record) {
                 trackTurn(sessionId, controller);
                 if (abortingWith !== undefined) {
-                    controller.abort(new RunAbortedError(abortingWith));
+                    controller.abort(shutdownAbort());
                 }
             }
             try {
@@ -3156,7 +3489,21 @@ export const createGateway = (options = {}) => {
         if (stopping) {
             throw refusal();
         }
-        return onSessionChain(input.sessionId, () => dispatchInternal(input));
+        return onSessionChain(input.sessionId, async () => {
+            // A keyed firing (an event trigger's batch) that the session already
+            // holds is that turn, not a new one: a daemon that died after the
+            // turn and before the firing was recorded re-sends it at the next
+            // start, and must answer with the finished turn (or settle the
+            // unfinished one, as the start-up sweep would) instead of running the
+            // event again. The same check the public door makes, on the chain.
+            if (input.idempotencyKey !== undefined) {
+                const repeated = await settleRepeat(input.sessionId, input.idempotencyKey, input.agentId, input.turnId, input.onRepeat);
+                if (repeated !== undefined) {
+                    return repeated;
+                }
+            }
+            return dispatchInternal(input);
+        });
     };
     const dispatch = async (input) => {
         if (stopping) {
@@ -3642,6 +3989,41 @@ export const createGateway = (options = {}) => {
                 onRead: (method) => log(`fleet read: ${method} by plugin ${packageName}`),
             }),
             providerCallGuards,
+            eventSources: {
+                reserved: Object.keys(eventSources),
+                register: (packageName, sourceIds) => {
+                    if (!eventStore) {
+                        // The first source on a daemon whose config has none: the
+                        // scheduler was built without events, so it takes them now,
+                        // before its start-up pass reads what is waiting. First, so a
+                        // store that won't open refuses the plugin with no source left
+                        // behind.
+                        scheduler.attachEvents({ store: openEvents().store, sources: eventSourceIds });
+                    }
+                    for (const sourceId of sourceIds) {
+                        pluginEventSources.set(sourceId, packageName);
+                    }
+                },
+                ingest: async (packageName, sourceId, event) => {
+                    if (pluginEventSources.get(sourceId) !== packageName) {
+                        throw new Error(`Plugin ${packageName} does not feed event source "${sourceId}" on this daemon.`);
+                    }
+                    // The store closes last in a stop. Until then an event is kept
+                    // and goes out from the next start; after, refused, so a poller
+                    // keeps its cursor where it was.
+                    if (storesClosed) {
+                        throw new Error('stratusd has stopped, so this event was not stored. Feed it again once the daemon is back.');
+                    }
+                    const answer = openEvents().intake.ingest(sourceId, event);
+                    // Sent now rather than at the next tick; the scheduler decides
+                    // hold or fire, and does nothing while it is stopped or not yet
+                    // started.
+                    if (answer.status === 'matched') {
+                        scheduler.kickEvents();
+                    }
+                    return answer;
+                },
+            },
         });
         loadedPlugins = result.loaded;
         pluginFailures = result.failures;
@@ -3654,6 +4036,7 @@ export const createGateway = (options = {}) => {
                 ...plugin.contributions.memory.map((name) => `memory store ${name}`),
                 ...plugin.contributions.executors.map((name) => `executor ${name}`),
                 ...(plugin.providerCallGuards > 0 ? ['guards model calls'] : []),
+                ...plugin.eventSources.map((sourceId) => `event source ${sourceId}`),
             ];
             log(`plugin ${plugin.package} loaded — ${contributed.join(', ') || 'no tools'}`);
         }
@@ -3948,6 +4331,7 @@ export const createGateway = (options = {}) => {
         }
         storesClosed = true;
         scheduleStore.close();
+        eventStore?.close();
         store.close();
     };
     /**
@@ -4085,12 +4469,15 @@ export const createGateway = (options = {}) => {
             // The watchdog's own mechanism: the runner fails each session with
             // the reason on the signal, saves it, and emits session.failed —
             // so the next daemon finds a finished turn, not an abandoned one.
+            // Except a keyed turn, which the resumable abort leaves running for
+            // the next daemon to continue once, as a crash would have left it
+            // (`shutdownAbort`); its caller is refused (`leftForNext`).
             // 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 running of turnControllers.values()) {
                 for (const controller of running) {
-                    controller.abort(new RunAbortedError(abortingWith));
+                    controller.abort(shutdownAbort());
                 }
             }
             drained = await settlesWithin(drain, remaining());
@@ -4332,12 +4719,23 @@ export const createGateway = (options = {}) => {
             return registry.list();
         },
         async reloadRoster() {
-            // Under the soul lock, so a repoint cannot land between a credential
-            // grant's check of the served path and its write (`grantSoulCredential`).
-            await reloadsInOrder(() => withSoulFileLock(loadRoster));
-            const roster = registry.list();
-            log(`roster reloaded — ${roster.length} agent(s): ${roster.map((agent) => agent.name).join(', ')}`);
-            return roster;
+            return (await gateway.reloadRosterAndChannels()).agents;
+        },
+        async reloadRosterAndChannels() {
+            let roster = [];
+            let channels = [];
+            await reloadsInOrder(async () => {
+                // Under the soul lock, so a repoint cannot land between a credential
+                // grant's check of the served path and its write (`grantSoulCredential`).
+                await withSoulFileLock(loadRoster);
+                roster = registry.list();
+                log(`roster reloaded — ${roster.length} agent(s): ${roster.map((agent) => agent.name).join(', ')}`);
+                // Outside the soul lock, which guards files and must not wait on a
+                // network; inside the reload chain, so two reloads never interleave
+                // their channel work (the bound keeps one from holding it).
+                channels = await reloadChannels();
+            });
+            return { agents: roster, channels };
         },
         async reloadSkills() {
             try {
@@ -4425,6 +4823,35 @@ export const createGateway = (options = {}) => {
         cancelSchedule(scheduleId) {
             return scheduler.cancel(scheduleId);
         },
+        async receiveEvent(request) {
+            if (!eventIntake) {
+                return { status: 404, body: { error: 'unknown_source', message: 'No event source is configured at this path.' } };
+            }
+            const answer = await eventIntake.receive(request);
+            // The delivery and its firings are committed; send them now rather
+            // than at the next tick. The scheduler decides hold or fire, and does
+            // nothing while it is stopped or not yet started.
+            if (answer.body.status === 'matched') {
+                scheduler.kickEvents();
+            }
+            return answer;
+        },
+        eventSummary() {
+            const since = new Date(Date.now() - 86_400_000).toISOString();
+            if (!eventStore || !eventIntake) {
+                return { since, sources: {}, unknownSource: 0 };
+            }
+            return summarizeEvents({
+                sourceIds: eventSourceIds(),
+                plugins: Object.fromEntries(pluginEventSources),
+                since,
+                activity: eventStore.activity(since),
+                counters: eventIntake.counters(),
+            });
+        },
+        eventDeliveries(options = {}) {
+            return eventStore?.deliveries(options) ?? [];
+        },
         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