mixdog 1.4.1 → 1.4.3

package/src/session-runtime/resource-mcp-api.mjs

@@ -14,9 +14,11 @@ import { migrateMergedConnectorServers } from './connector-merge-migration.mjs';
 import {
   connectorAccountServers,
   connectorAccountsOf,
+  connectorAppPasswordOnly,
   connectorById,
-  connectorMultiAccount,
+  connectorServerInput,
   gmailAppPasswordAccount,
+  gmailAppPasswordServerInput,
   mergeConnectorAccountServers,
 } from '../runtime/shared/connector-catalog.mjs';
 import { saveMcpOAuthClientSecret } from '../runtime/agent/orchestrator/mcp/oauth-client.mjs';
@@ -75,14 +77,24 @@ export function createMcpResourceApi({ deps, sync, decorate }) {
     resolveMcpCatalog,
     pluginMcpServer,
   });
-  const { storeOAuthClientSecret, storeGmailAppPassword, releaseOAuth, forgetUnusedGmailAppPassword, releaseAccount } =
-    createMcpServerSecrets({
-      gmailAppPassword,
-      saveOAuthClientSecret,
-      clearMcpServerOAuth,
-      resolveConfiguredMcpCatalog,
-    });
-  const { addConnectorAccount, saveConnectorAccount, setConnectorAccountEnabled } = createConnectorAccountEdits({
+  const {
+    storeOAuthClientSecret,
+    storeGmailAppPassword,
+    releaseOAuth,
+    forgetUnusedGmailAppPassword,
+    forgetStoredSecrets,
+    releaseAccount,
+  } = createMcpServerSecrets({
+    gmailAppPassword,
+    saveOAuthClientSecret,
+    clearMcpServerOAuth,
+    resolveConfiguredMcpCatalog,
+  });
+  const {
+    addConnectorAccount: joinConnectorAccount,
+    saveConnectorAccount,
+    setConnectorAccountEnabled,
+  } = createConnectorAccountEdits({
     normalizeMcpServerInput,
     pluginMcpServer,
     sync,
@@ -91,16 +103,65 @@ export function createMcpResourceApi({ deps, sync, decorate }) {
     storeOAuthClientSecret,
     storeGmailAppPassword,
     forgetUnusedGmailAppPassword,
+    forgetStoredSecrets,
     releaseOAuth,
   });
   // Peers reload config from disk on receipt: land the write before publishing.
   const persisted = async () => {
     await flushSkillsSave?.();
   };
+  // One account addition of a connector at a time, each reading the servers
+  // the one before it saved: two at once never take the same name, nor does
+  // one's save drop the other's account.
+  const connectorAdds = new Map();
+  const oneAddAtATime = (connector, run) => {
+    const next = (connectorAdds.get(connector) || Promise.resolve()).then(run, run);
+    const settled = next.then(
+      () => {},
+      () => {}
+    );
+    connectorAdds.set(connector, settled);
+    void settled.then(() => {
+      if (connectorAdds.get(connector) === settled) connectorAdds.delete(connector);
+    });
+    return next;
+  };
+
+  async function addMcpServer(input = {}) {
+    // A catalog connector's account (as its own server config) joins that
+    // connector's one server.
+    const connector = clean(input.connector);
+    if (connector && !Array.isArray(input.accounts)) return oneAddAtATime(connector, () => addServerNow(input));
+    return addServerNow(input);
+  }
+
+  async function addServerNow(input) {
+    const { name, config: serverConfig } = normalizeMcpServerInput(input);
+    // A catalog connector's server keeps its catalog id (connector-catalog.mjs).
+    const connector = clean(input.connector);
+    if (connector) {
+      if (!connectorById(connector)) throw new Error(`Unknown connector: ${connector}`);
+      serverConfig.connector = connector;
+    }
+    const servers = userServers();
+    if (connector && !Array.isArray(input.accounts)) {
+      return joinConnectorAccount(servers, connector, name, serverConfig, input);
+    }
+    if (Object.hasOwn(servers, name) || accountTarget(servers, name)) {
+      throw nameTakenError(servers, name);
+    }
+    const owned = pluginMcpServer(name);
+    if (owned) throw new Error(`MCP server already exists: ${name} (provided by plugin "${owned.owner.id}")`);
+    await storeOAuthClientSecret(input, serverConfig);
+    await storeGmailAppPassword(input, serverConfig, true);
+    saveServers({ ...servers, [name]: serverConfig });
+    const status = await sync.reconnectMcpAndAnnounce({ only: name, enabled: serverConfig.enabled !== false });
+    return { name, status };
+  }
 
   return {
-    /** One-time, idempotent: merge the one-account servers of a multi-account
-     *  connector (`gmail`, `gmail-2`…) into one server holding the accounts
+    /** One-time, idempotent: merge the one-account servers of a catalog
+     *  connector (`notion`, `notion-2`…) into one server holding the accounts
      *  (connector-catalog.mjs mergeConnectorAccountServers). Every account
      *  keeps its address, so its stored sign-in and app password stay as
      *  they are. Settings keyed by a merged-away server name go with it:
@@ -155,30 +216,32 @@ export function createMcpResourceApi({ deps, sync, decorate }) {
     },
     // Sign-in / sign-out (resource-mcp-oauth-api.mjs), in this key position.
     ...oauthApi,
-    async addMcpServer(input = {}) {
-      const { name, config: serverConfig } = normalizeMcpServerInput(input);
-      // A catalog connector's server keeps its catalog id (connector-catalog.mjs).
-      const connector = clean(input.connector);
-      if (connector) {
-        if (!connectorById(connector)) throw new Error(`Unknown connector: ${connector}`);
-        serverConfig.connector = connector;
-      }
-      const servers = userServers();
-      // A multi-account connector's account (as its own server config) joins
-      // that connector's one server.
-      if (connector && connectorMultiAccount(connectorById(connector)) && !Array.isArray(input.accounts)) {
-        return addConnectorAccount(servers, connector, name, serverConfig, input);
-      }
-      if (Object.hasOwn(servers, name) || accountTarget(servers, name)) {
-        throw nameTakenError(servers, name);
-      }
-      const owned = pluginMcpServer(name);
-      if (owned) throw new Error(`MCP server already exists: ${name} (provided by plugin "${owned.owner.id}")`);
-      await storeOAuthClientSecret(input, serverConfig);
-      await storeGmailAppPassword(input, serverConfig, true);
-      saveServers({ ...servers, [name]: serverConfig });
-      const status = await sync.reconnectMcpAndAnnounce({ only: name, enabled: serverConfig.enabled !== false });
-      return { name, status };
+    addMcpServer,
+    /** One more account of catalog connector `input.connector`, connected as
+     *  its catalog entry says: `key` for an API-key service (Hugging Face,
+     *  Stripe; Postgres takes its connection string), `email` and
+     *  `appPassword` for Gmail, nothing more for a sign-in service (the
+     *  account then signs in with beginMcpOAuthLogin(account)); the user's own
+     *  OAuth client rides on `oauthClientId` / `oauthClientSecret`. The account
+     *  gets a free name (`notion`, `notion-2`…) and joins the connector's one
+     *  server, which is made when there is none. Resolves `{ name, account,
+     *  status }`: the server's name and the new account's (for a Gmail
+     *  address already connected, that account, which took the new password). */
+    async addConnectorAccount(input = {}) {
+      const entry = connectorById(clean(input.connector));
+      if (!entry) throw new Error(`Unknown connector: ${clean(input.connector)}`);
+      // Its name is picked from the servers the additions before it saved.
+      return oneAddAtATime(entry.id, () => {
+        const name = freeName(userServers(), entry.id);
+        const account = connectorAppPasswordOnly(entry)
+          ? gmailAppPasswordServerInput(name, input.email, input.appPassword)
+          : connectorServerInput(entry, name, input.key);
+        const ownClient = clean(input.oauthClientId);
+        return addServerNow({
+          ...account,
+          ...(ownClient ? { oauthClientId: ownClient, oauthClientSecret: input.oauthClientSecret } : {}),
+        });
+      });
     },
     async saveMcpServer(input = {}) {
       const servers = userServers();

package/src/session-runtime/resource-mcp-connector-accounts.mjs

@@ -1,6 +1,7 @@
-// The accounts of a multi-account connector server as the MCP server API
-// edits them: adding one more account (into its server, or a new server
-// holding it) and editing one account's transport, app password or client.
+// The accounts of a connector server as the MCP server API edits them: adding
+// one more account (into its server, or a new server holding it) and editing
+// one account's transport, app password or client.
+import { randomUUID } from 'node:crypto';
 import { clean } from '../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 import {
   mergeMcpServerConfig,
@@ -13,15 +14,16 @@ import {
   connectorAccountServers,
   connectorAccountsOf,
   connectorAccountsUrl,
-  connectorById,
   connectorOfServer,
+  connectorServerSettings,
   gmailAppPasswordAccount,
   withConnectorAccountEnabled,
 } from '../runtime/shared/connector-catalog.mjs';
 import { forgetConnectorAccountHealth } from '../runtime/connectors/connector-accounts-mcp.mjs';
-import { accountTarget, mergedServerInput, nameTakenError, oauthUrlOf } from './resource-mcp-servers.mjs';
+import { hasConfiguredMcpAuth } from '../runtime/agent/orchestrator/mcp/client-transport.mjs';
+import { accountTarget, mergedServerInput, nameTakenError, oauthCredentialOf } from './resource-mcp-servers.mjs';
 
-/** The server of multi-account connector `connector` in `servers`, or ''. */
+/** The server of connector `connector` in `servers`, or ''. */
 function connectorServerName(servers, connector) {
   return (
     Object.keys(servers).find(
@@ -36,7 +38,7 @@ function connectorServerName(servers, connector) {
 export const editsServerItself = (target, input) => {
   if (target.serverName !== target.account.name || !clean(input.url)) return false;
   try {
-    return oauthUrlOf({ type: input.type || 'http', url: input.url }) === oauthUrlOf(target.cfg);
+    return oauthCredentialOf({ type: input.type || 'http', url: input.url }) === oauthCredentialOf(target.cfg);
   } catch {
     return false;
   }
@@ -51,12 +53,14 @@ export function createConnectorAccountEdits({
   storeOAuthClientSecret,
   storeGmailAppPassword,
   forgetUnusedGmailAppPassword,
+  forgetStoredSecrets,
   releaseOAuth,
 }) {
-  /** One more account of multi-account connector `connector` (one-account
-   *  config `accountCfg` as normalized from `input`): into its server, or a
-   *  new server named `name` holding it. The same Gmail address again takes
-   *  the new app password. Resolves `{ name, account, status }`. */
+  /** One more account of connector `connector` (one-account config
+   *  `accountCfg` as normalized from `input`): into its server, or a new
+   *  server named `name` holding it. The same Gmail address again takes the
+   *  new app password. `servers` is read under the caller's per-connector
+   *  serialization (resource-mcp-api.mjs). Resolves `{ name, account, status }`. */
   async function addConnectorAccount(servers, connector, name, accountCfg, input) {
     const serverName = connectorServerName(servers, connector);
     const address = gmailAppPasswordAccount(accountCfg);
@@ -76,30 +80,41 @@ export function createConnectorAccountEdits({
       throw nameTakenError(servers, name);
     }
     const accountName = serverName ? freeName(servers, name) : name;
-    const account = connectorAccountEntry(accountName, accountCfg);
-    // Sign-in tokens are stored per exact URL: another account needs its own.
-    const backendUrl = connectorById(connector)?.backend?.url;
-    if (
-      !address &&
-      cfg &&
-      connectorAccountServers(cfg).some((other) => oauthUrlOf(other) === oauthUrlOf({ type: 'http', url: account.url }))
-    ) {
-      account.url = `${backendUrl}?account=${encodeURIComponent(accountName)}`;
+    // A fresh identity: a conversation that used a removed account of this
+    // name never takes this one for it (connector-accounts-mcp.mjs).
+    const account = { ...connectorAccountEntry(accountName, accountCfg), id: randomUUID() };
+    // A sign-in is stored per exact URL: another account signing in at the
+    // same URL gets its own key, so the two never share tokens.
+    const asServer = connectorAccountServer({ connector }, account);
+    const signIn = hasConfiguredMcpAuth(asServer) ? null : oauthCredentialOf(asServer);
+    if (signIn && cfg && connectorAccountServers(cfg).some((other) => oauthCredentialOf(other) === signIn)) {
+      account.oauthKey = randomUUID();
     }
     const storedCfg = connectorAccountServer({ connector }, account);
-    await storeOAuthClientSecret(input, storedCfg);
-    await storeGmailAppPassword(input, storedCfg, true);
-    forgetConnectorAccountHealth(accountName);
     let target = serverName;
-    if (cfg) {
-      servers[serverName] = { ...cfg, accounts: [...connectorAccountsOf(cfg), account] };
-    } else {
-      // The server's own settings (timeouts, enabled) ride on the input.
-      const { type: _type, url: _url, headers: _headers, oauthClientId: _client, ...rest } = accountCfg;
-      target = name;
-      servers[name] = { ...rest, type: 'http', url: connectorAccountsUrl(connector), connector, accounts: [account] };
+    // Its secrets and its config land together: a failed step takes back the secrets.
+    try {
+      await storeOAuthClientSecret(input, storedCfg);
+      await storeGmailAppPassword(input, storedCfg, true);
+      if (cfg) {
+        servers[serverName] = { ...cfg, accounts: [...connectorAccountsOf(cfg), account] };
+      } else {
+        // The server's own settings (timeouts, enabled) ride on the input.
+        target = name;
+        servers[name] = {
+          ...connectorServerSettings(accountCfg),
+          type: 'http',
+          url: connectorAccountsUrl(connector),
+          connector,
+          accounts: [account],
+        };
+      }
+      saveServers(servers);
+    } catch (error) {
+      await forgetStoredSecrets(storedCfg);
+      throw error;
     }
-    saveServers(servers);
+    forgetConnectorAccountHealth(accountName);
     const status = await sync.reconnectMcpAndAnnounce({ only: target, enabled: servers[target].enabled !== false });
     return { name: target, account: accountName, status };
   }
@@ -116,7 +131,7 @@ export function createConnectorAccountEdits({
     await storeOAuthClientSecret(input, next, accountCfg);
     await storeGmailAppPassword(input, next, false);
     // Settings that are not the account's transport (timeouts) are the server's.
-    const { type: _type, url: _url, headers: _headers, oauthClientId: _client, ...serverFields } = config;
+    const serverFields = connectorServerSettings(config);
     const server = { ...cfg };
     for (const group of MCP_TIMEOUT_FIELD_GROUPS) {
       if (group.some((field) => Object.hasOwn(serverFields, field))) for (const field of group) delete server[field];
@@ -128,6 +143,8 @@ export function createConnectorAccountEdits({
         entry.name === account.name
           ? {
               ...connectorAccountEntry(account.name, next),
+              // An edit keeps the account's identity.
+              ...(entry.id ? { id: entry.id } : {}),
               ...(connectorAccountEnabled(entry) ? {} : { enabled: false }),
             }
           : entry

package/src/session-runtime/resource-mcp-secrets.mjs

@@ -7,7 +7,7 @@ import {
   connectorAccountServers,
 } from '../runtime/shared/connector-catalog.mjs';
 import { forgetConnectorAccountHealth } from '../runtime/connectors/connector-accounts-mcp.mjs';
-import { oauthUrlOf } from './resource-mcp-servers.mjs';
+import { oauthCredentialOf } from './resource-mcp-servers.mjs';
 
 /** Every config `servers` connects with, a multi-account server's accounts
  *  as the one-account configs they are. */
@@ -44,15 +44,16 @@ export function createMcpServerSecrets({
     }
   };
   // A server's OAuth tokens and client registration go with it, unless another
-  // configured server (plugin or disabled ones included, even with MCP
-  // disabled for this runtime) still uses them through the same exact URL.
-  // `signIn` tells the caller what happened to the sign-in: `removed` (local
-  // secrets deleted, `revoked` when the provider confirmed the revocation
-  // too), `shared` (another server still uses it), or none (null).
+  // configured server or account (plugin or disabled ones included, even with
+  // MCP disabled for this runtime) still uses them through the same exact URL
+  // (or the same account key). `signIn` tells the caller what happened to the
+  // sign-in: `removed` (local secrets deleted, `revoked` when the provider
+  // confirmed the revocation too), `shared` (another server still uses it),
+  // or none (null).
   const releaseOAuth = async (cfg) => {
-    const url = oauthUrlOf(cfg);
-    if (!url) return null;
-    if (expandedConfigs(resolveConfiguredMcpCatalog().servers).some((other) => oauthUrlOf(other) === url)) {
+    const key = oauthCredentialOf(cfg);
+    if (!key) return null;
+    if (expandedConfigs(resolveConfiguredMcpCatalog().servers).some((other) => oauthCredentialOf(other) === key)) {
       return { signIn: 'shared', revoked: false };
     }
     const { revoked = false } = (await clearMcpServerOAuth(cfg, { revoke: true })) || {};
@@ -66,6 +67,15 @@ export function createMcpServerSecrets({
     await gmailAppPassword.forget(account);
     return true;
   };
+  // What storeOAuthClientSecret / storeGmailAppPassword stored for `cfg`, gone
+  // again unless a configured server uses it (an add that was not saved).
+  const forgetStoredSecrets = async (cfg) => {
+    await forgetUnusedGmailAppPassword(gmailAppPasswordAccount(cfg));
+    if (!cfg?.url || !cfg.oauthClientId) return;
+    const servers = expandedConfigs(resolveConfiguredMcpCatalog().servers);
+    if (!servers.some((other) => other.url === cfg.url && other.oauthClientId))
+      await saveOAuthClientSecret(cfg.url, '');
+  };
   // A removed account keeps no sign-in another configured server or account
   // does not share: `{ signIn, revoked }` as removeMcpServer reports it.
   const releaseAccount = async (accountCfg) => {
@@ -78,5 +88,12 @@ export function createMcpServerSecrets({
     return releaseOAuth(accountCfg);
   };
 
-  return { storeOAuthClientSecret, storeGmailAppPassword, releaseOAuth, forgetUnusedGmailAppPassword, releaseAccount };
+  return {
+    storeOAuthClientSecret,
+    storeGmailAppPassword,
+    releaseOAuth,
+    forgetUnusedGmailAppPassword,
+    forgetStoredSecrets,
+    releaseAccount,
+  };
 }

package/src/session-runtime/resource-mcp-servers.mjs

@@ -3,7 +3,7 @@
 // name refusals and the merge of a partial server edit.
 import { clean } from '../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 import { MCP_TIMEOUT_FIELD_GROUPS } from '../runtime/agent/orchestrator/runtime-core/plugin-mcp.mjs';
-import { resolveMcpOAuthUrl } from '../runtime/agent/orchestrator/mcp/client-config.mjs';
+import { resolveMcpOAuthCredentialKey } from '../runtime/agent/orchestrator/mcp/client-config.mjs';
 import {
   connectorAccountServer,
   connectorAccountsOf,
@@ -11,10 +11,11 @@ import {
   connectorOfServer,
 } from '../runtime/shared/connector-catalog.mjs';
 
-/** The URL a server's OAuth credentials are stored under, or null. */
-export function oauthUrlOf(cfg) {
+/** What a server's OAuth credentials are stored under (its URL, or a
+ *  connector account's own key), or null. */
+export function oauthCredentialOf(cfg) {
   try {
-    return resolveMcpOAuthUrl(cfg);
+    return resolveMcpOAuthCredentialKey(cfg);
   } catch {
     // No valid remote URL: such a server never logged in.
     return null;

package/src/session-runtime/resource-plugins-api.mjs

@@ -29,6 +29,7 @@ export function createPluginsResourceApi({ deps, sync, decorate }) {
     pluginsStatus,
     resolveMcpCatalog = () => ({ adoption: null }),
     flushSkillsSave,
+    invalidateSkills,
   } = deps;
   const pluginData = () => cfgMod.getPluginData?.();
 
@@ -59,6 +60,9 @@ export function createPluginsResourceApi({ deps, sync, decorate }) {
       return { plugin, status: pluginsStatus() };
     },
     async updatePlugin(plugin = {}) {
+      // Windows refuses to rename a directory holding an open recursive
+      // skill watch, so drop the watchers before the root is swapped.
+      invalidateSkills?.();
       const updated = registryUpdatePlugin(pluginKey(plugin), { dataDir: pluginData() });
       await adoptPluginServerCopies();
       await sync.reconcilePluginsAndAnnounce();

package/src/session-runtime/routine-executor.mjs

@@ -0,0 +1,152 @@
+/**
+ * A routine (schedule or webhook) may name an executor: a workflow sub-agent
+ * (Worker, …) on its own configured route. Each fire is then carried out by
+ * that sub-agent first, headless and to its end, and only its final report
+ * goes to the owner bot's home thread, which relays it (routine-home-turn.mjs).
+ * No executor = the bot does the work itself, as before.
+ *
+ * The executor is a delegatable workflow agent: never a bot (contact agent) or
+ * Mixy, never one that is unknown or turned off — refused when the routine is
+ * saved (assertRoutineExecutor) and again when it fires (a sub-agent that
+ * disappeared or was turned off since fails the fire; nothing falls back).
+ *
+ * The run is unattended like the bot's own routine turn: it is created under a
+ * session id marked as that routine's run (held-requests.mjs markUnattendedRun)
+ * so the sub-agent's record carries the run stamp (human-gate/delegation.mjs):
+ * it never asks, payments and permanent deletes are refused
+ * (human-gate/run-policy.mjs). A sub-agent session has no `agent`, `session`
+ * or `ask_user` tool (AGENT_WORKER_DENIED_TOOLS), so it can start no task
+ * session and ask nobody.
+ */
+import { randomUUID } from 'node:crypto';
+import { MIXY_AGENT_ID } from '../runtime/agent/orchestrator/session/agent-home.mjs';
+import {
+  BUILTIN_SLOT_AGENT_IDS,
+  normalizeWorkflowId,
+} from '../runtime/agent/orchestrator/runtime-core/workflow-ids.mjs';
+import { storeInlineDocumentPart, storeInlineImagePart } from '../runtime/attachments/store.mjs';
+import { MIXY_BOT_ID } from '../runtime/shared/agent-store.mjs';
+import { automationPromptContent } from '../runtime/shared/automation-attachments.mjs';
+import { routineExecutorHeader } from '../runtime/shared/routine-trigger.mjs';
+import { scheduleOwnerAgentId } from './agent-home-delivery.mjs';
+import { markUnattendedRun } from './held-requests.mjs';
+
+/** `routineExecutorProblem` codes and the error each one raises. */
+export const ROUTINE_EXECUTOR_PROBLEMS = Object.freeze({
+  unknown: (id) => `executor agent "${id}" is not an available sub-agent: pick one from the workflow agents`,
+  'not-agent': (id) =>
+    `executor agent "${id}" is a bot, not a workflow sub-agent: pick a sub-agent such as Worker, or leave it unset`,
+  disabled: (id) => `executor agent "${id}" is turned off: turn it on in the workflow agents or pick another`,
+});
+
+/** The stored form of an executor id: lower-cased with dashes; null for none. */
+export function normalizeExecutorAgentId(value) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  return text ? normalizeWorkflowId(text, text.toLowerCase()) : null;
+}
+
+async function defaultProbe(id) {
+  const [{ workflowHelpers }, { getPluginData, loadConfig }, { isAgentDisabled, isContactAgentId }] = await Promise.all(
+    [
+      import('./boot/shared.mjs'),
+      import('../runtime/agent/orchestrator/config.mjs'),
+      import('../runtime/shared/agent-route-config.mjs'),
+    ]
+  );
+  const dataDir = getPluginData();
+  // The fresh scan: an agent made a moment ago counts.
+  const listed = workflowHelpers.listCustomAgentIds(dataDir).includes(id) && !BUILTIN_SLOT_AGENT_IDS.has(id);
+  const definition = listed ? workflowHelpers.loadAgentDefinition(dataDir, id) : null;
+  return {
+    listed: Boolean(definition),
+    contact: Boolean(definition) && isContactAgentId(id, definition.kind),
+    disabled: isAgentDisabled(loadConfig({ secrets: false }), id),
+  };
+}
+
+/** Why `id` (normalized) cannot execute a routine: a ROUTINE_EXECUTOR_PROBLEMS
+ *  code, '' when it can. `probe(id)` → `{ listed, contact, disabled }`. */
+export async function routineExecutorProblem(id, probe = defaultProbe) {
+  if (id === MIXY_AGENT_ID || id === MIXY_BOT_ID) return 'not-agent';
+  const facts = await probe(id);
+  if (!facts.listed) return 'unknown';
+  if (facts.contact) return 'not-agent';
+  return facts.disabled ? 'disabled' : '';
+}
+
+/** The executor id to store for a save's `executorAgentId` (null/empty = none),
+ *  or the error naming why it cannot be one. */
+export async function assertRoutineExecutor(value, probe = defaultProbe) {
+  if (value == null) return null;
+  if (typeof value !== 'string') throw new Error('executorAgentId must be a sub-agent id (a string) or null');
+  const id = normalizeExecutorAgentId(value);
+  if (!id) return null;
+  const problem = await routineExecutorProblem(id, probe);
+  if (problem) throw new Error(ROUTINE_EXECUTOR_PROBLEMS[problem](id));
+  return id;
+}
+
+/** An inline image/PDF/Office part as the stored reference part a sub-agent's
+ *  prompt may carry (handoff-attachments.mjs admits references only). */
+const referencePart = (part) => (part.type === 'image' ? storeInlineImagePart(part) : storeInlineDocumentPart(part));
+
+/**
+ * Carry out one fire of routine `name` with sub-agent `agentId` and resolve its
+ * final report (trimmed text). `prompt` is the routine's instructions (plus a
+ * webhook's fenced payload); `ownerAgentId` the bot whose run it is. Rejects
+ * when the executor is no longer valid, fails, is cancelled, or `signal` aborts.
+ */
+export async function runRoutineExecutor(
+  {
+    agentId,
+    kind,
+    name,
+    ownerAgentId = null,
+    prompt,
+    // The trusted part of `prompt` (the routine's instructions): the only text
+    // the executor's skills are selected from, never a webhook payload.
+    skillSelection = '',
+    attachments = null,
+    cwd = null,
+    signal = null,
+  },
+  { surface, probe = defaultProbe } = {}
+) {
+  const problem = await routineExecutorProblem(agentId, probe);
+  if (problem) throw new Error(`${kind} "${name}" cannot run: ${ROUTINE_EXECUTOR_PROBLEMS[problem](agentId)}`);
+  if (typeof surface?.runAgent !== 'function') throw new Error('routine run: the agent service is not running');
+  const header = routineExecutorHeader({ kind, name, project: cwd ? String(cwd) : '' });
+  const content = automationPromptContent(`${header}\n\n${prompt}`, attachments);
+  const parts = Array.isArray(content) ? content : [{ type: 'text', text: content }];
+  const attachmentParts = parts.slice(1).map(referencePart).filter(Boolean);
+  // The id the executor is created under: marked as this routine's unattended
+  // run for as long as it works (its record keeps the run stamp afterwards).
+  const parentSessionId = `routine_exec_${randomUUID()}`;
+  const unmark = markUnattendedRun(parentSessionId, {
+    kind,
+    agentId: scheduleOwnerAgentId({ ownerAgentId }),
+    name,
+  });
+  try {
+    const result = await surface.runAgent(
+      {
+        agent: agentId,
+        prompt: parts[0].text,
+        skillSelection: String(skillSelection ?? ''),
+        ...(cwd ? { cwd: String(cwd) } : {}),
+        ...(attachmentParts.length ? { attachmentParts } : {}),
+      },
+      { callerSessionId: parentSessionId },
+      { signal }
+    );
+    return String(result?.content ?? '').trim();
+  } catch (error) {
+    // The caller's own cancellation stays as it is.
+    if (signal?.aborted) throw error;
+    throw new Error(`${kind} "${name}": executor agent "${agentId}" failed: ${error?.message || error}`, {
+      cause: error,
+    });
+  } finally {
+    unmark();
+  }
+}