mixdog 1.2.6 → 1.3.0

package/src/runtime/agent/orchestrator/runtime-core/context-status-shape.mjs

@@ -46,6 +46,7 @@ export function sessionTokenCounters(session) {
     totalOutputTokens: Number(session?.totalOutputTokens || 0),
     totalCachedReadTokens: Number(session?.totalCachedReadTokens || 0),
     totalCacheWriteTokens: Number(session?.totalCacheWriteTokens || 0),
+    usageReadout: session?.usageReadout || null,
     compactBoundaryTokens: Number(session?.compactBoundaryTokens || 0),
   };
 }
@@ -64,6 +65,9 @@ function sessionUsageCounters(session, lastContextTokens) {
     totalOutputTokens: Number(session?.totalOutputTokens || 0),
     totalCachedReadTokens: Number(session?.totalCachedReadTokens || 0),
     totalCacheWriteTokens: Number(session?.totalCacheWriteTokens || 0),
+    // Session-cumulative cache/speed totals behind the composer readout; null
+    // until the session has a call recorded.
+    usageReadout: session?.usageReadout || null,
   };
 }
 

package/src/runtime/agent/orchestrator/runtime-core/extension-scopes.mjs

@@ -48,12 +48,14 @@ export function filterMcpToolsForCwd(tools, scopes, cwd) {
   });
 }
 
-/** The MCP tools a session at `cwd` may see. No scopes configured → input
- *  returned as-is, so the global-only fast path costs one config read. */
+/** The MCP tools a session at `cwd` may see. No scopes configured → the input
+ *  as-is, so the global-only fast path costs one config read. An agent's
+ *  connectors never narrow this list: the schema and the BP2 manifest stay
+ *  identical across agents (one shared cache prefix), and the connector policy
+ *  is enforced at dispatch (pre-dispatch-deny / connector approval). */
 export function filterMcpToolsForSession(tools, cwd, config = null) {
   const list = Array.isArray(tools) ? tools : [];
   if (!list.length) return list;
   const scopes = extensionScopesFromConfig(config || loadConfig({ secrets: false }));
-  if (!hasExtensionScopes(scopes)) return list;
-  return filterMcpToolsForCwd(list, scopes, cwd);
+  return hasExtensionScopes(scopes) ? filterMcpToolsForCwd(list, scopes, cwd) : list;
 }

package/src/runtime/agent/orchestrator/runtime-core/orchestration.mjs

@@ -19,6 +19,18 @@ Lead executes all work directly and never delegates on its own judgment.
 Only when the user explicitly asks for delegation, load the deferred \`agent\`
 tool and brief each agent as the Lead rules describe.`;
 
+/** Agent mode's fixed delegation block, in place of the orchestration mode. */
+export const AGENT_MODE_DELEGATION = `# Delegation
+
+Handle conversation yourself. Delegate specialised work to sub-agents. Hand
+substantial coding to a new coding-mode task session (\`session create\`) with
+a self-contained brief: start it when already requested, otherwise suggest it. Then relay the
+result in your own words.`;
+
+/** Mixy only: it also routes requests to the user's contact agents. */
+export const MIXY_CONTACTS_INTRO = `You also coordinate the user's contact agents: route a request to the
+contact best suited for it with the same kind of brief.`;
+
 export function orchestrationInstructions(value) {
   const mode = normalizeOrchestrationMode(value);
   if (mode === 'none') return SOLO;

package/src/runtime/agent/orchestrator/runtime-core/plugin-mcp.mjs

@@ -23,6 +23,7 @@ const MCP_TRANSPORT_FIELDS = new Set([
   'env_http_headers',
   'env_vars',
   'autoDetect',
+  'oauthClientId',
 ]);
 
 // Every spelling resolveMcpStartupTimeoutMs / resolveMcpCallTimeoutMs reads.

package/src/runtime/agent/orchestrator/runtime-core/tool-bridge.mjs

@@ -14,6 +14,7 @@ import {
   deferredCatalogUnion,
   filterSessionToolPolicy,
   isReadonlySelectable,
+  mcpServerSelection,
   toolSearchMatches,
 } from './tool-catalog.mjs';
 import { parseToolSelection, sortedCatalogByMeasuredUsage } from './tool-catalog-schema.mjs';
@@ -249,8 +250,9 @@ function describeNames(raw) {
   return names;
 }
 
-// Requested names → available tools; an alias that names no tool expands to
-// its members (existing load_tool alias compatibility).
+// Requested names → available tools; an alias or `mcp__<server>` that names no
+// tool expands to its members (existing load_tool alias compatibility).
+// Definitions past the continuation target cap are listed as omitted.
 function resolveDescribeTargets(session, names, mode, available) {
   const eagerNames = eagerToolNames(session);
   const targets = [];
@@ -271,13 +273,15 @@ function resolveDescribeTargets(session, names, mode, available) {
       add(tool);
       continue;
     }
-    const members = (DEFERRED_SELECT_ALIASES[requested.toLowerCase()] || [])
+    const aliased = (DEFERRED_SELECT_ALIASES[requested.toLowerCase()] || [])
       .map((member) => lookupByName(available, member))
       .filter(Boolean);
+    const members = aliased.length ? aliased : mcpServerSelection(available, requested);
     if (members.length) members.forEach(add);
     else missing.push(requested);
   }
-  return { targets, missing, blocked };
+  const omitted = targets.splice(BRIDGE_LIMITS.continuationMaxTargets).map((tool) => clean(tool?.name));
+  return { targets, missing, blocked, omitted };
 }
 
 const SEARCH_MAX_MATCHES = 20;
@@ -367,6 +371,7 @@ export function describeBridgeTools(session, args = {}, { mode } = {}) {
   let missing = [];
   let blocked = [];
   let matches = [];
+  let omitted = [];
   if (continuation) {
     targets = continuationTargets(session, continuation.indexes, available, mode);
     if (!targets) return catalogChanged();
@@ -378,10 +383,11 @@ export function describeBridgeTools(session, args = {}, { mode } = {}) {
         `names must be 1-${BRIDGE_LIMITS.describeMaxNames} exact tool names of at most ${BRIDGE_LIMITS.nameMaxChars} characters.${syntaxHint}`
       );
     }
-    ({ targets, missing, blocked } = resolveDescribeTargets(session, names, mode, available));
+    ({ targets, missing, blocked, omitted } = resolveDescribeTargets(session, names, mode, available));
     ({ matches, missing } = searchKeywords(session, missing, mode, available));
   }
-  const found = matches.length ? { matches } : {};
+  // Omitted names are described by a later request naming them.
+  const found = { ...(matches.length ? { matches } : {}), ...(omitted.length ? { omitted } : {}) };
   const docs = targets.map((tool) => {
     const document = toolDocument(tool);
     return {

package/src/runtime/agent/orchestrator/runtime-core/tool-catalog.mjs

@@ -4,6 +4,8 @@
 import { clean } from './session-text.mjs';
 import { mergePendingDeferredToolDelta } from './deferred-tool-delta.mjs';
 import { applyInitialDeferredToolManifestToBp2 } from '../context/collect.mjs';
+import { listedDeferredToolNames } from '../context/deferred-tools.mjs';
+import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
 import { getMcpServerInstructionsMap, getMcpTools, getMcpToolGeneration } from '../mcp/client.mjs';
 import { filterMcpToolsForSession } from './extension-scopes.mjs';
 import { isDeferredToolAvailable, isToolPermittedBySessionPolicy } from './deferred-tool-availability.mjs';
@@ -259,6 +261,17 @@ function expandSelectionNames(names) {
   return [...new Set(out)];
 }
 
+/**
+ * The tools of `tools` that `mcp__<server>` stands for (the deferred manifest
+ * lists MCP servers, not their tools); [] for any other name. Callers try an
+ * exact tool name first.
+ */
+export function mcpServerSelection(tools, requested) {
+  const server = /^mcp__(.+)$/i.exec(clean(requested))?.[1]?.toLowerCase();
+  if (!server) return [];
+  return (tools || []).filter((tool) => String(parseMcpToolName(tool)?.server || '').toLowerCase() === server);
+}
+
 function storedDeferredToolNames(session) {
   for (const source of [session?.deferredDiscoveredTools, session?.deferredSelectedTools]) {
     const names = parseToolSelection(source);
@@ -430,8 +443,11 @@ export function applyDeferredToolSurface(session, mode, extraTools = [], options
     // manifest, or the bridge roster + guidance. History stays as is.
     session.mcpServerInstructions = getMcpServerInstructionsMap(session.mcpScopeId);
     applyInitialDeferredToolManifestToBp2(session, deferredPoolToolNames(session), { rebuild: true });
-    const rendered = renderedDeferredManifest(session);
-    session.deferredAnnouncedTools = deferredPoolToolNames(session).filter((name) => rendered.includes(name));
+    session.deferredAnnouncedTools = listedDeferredToolNames(
+      session,
+      deferredPoolToolNames(session),
+      renderedDeferredManifest(session)
+    );
   }
   if (!session.deferredToolBp2Applied && session.messages?.some((m) => m?.role === 'system')) {
     if (!session.mcpServerInstructions || typeof session.mcpServerInstructions !== 'object') {
@@ -519,8 +535,11 @@ export function refreshInitialDeferredMcpSurface(session, liveMcpTools) {
   // Pre-mark ONLY the names that ACTUALLY landed in the rebuilt BP2 manifest as
   // announced; anything the manifest could not advertise stays un-announced so
   // the turn-boundary late reminder can still surface it.
-  const rendered = renderedDeferredManifest(session);
-  session.deferredAnnouncedTools = deferredPoolToolNames(session).filter((name) => rendered.includes(name));
+  session.deferredAnnouncedTools = listedDeferredToolNames(
+    session,
+    deferredPoolToolNames(session),
+    renderedDeferredManifest(session)
+  );
   session.updatedAt = Date.now();
   return true;
 }
@@ -726,7 +745,15 @@ export function selectDeferredTools(session, names, mode, { exact = false } = {}
   const already = [];
   const blocked = [];
   const missing = [];
-  for (const rawName of exact ? [...new Set(names)] : expandSelectionNames(names)) {
+  const requested = exact
+    ? names
+    : expandSelectionNames(names).flatMap((raw) => {
+        const key = clean(raw);
+        if (byName.has(key) || byName.has(key.toLowerCase())) return [key];
+        const members = mcpServerSelection(catalog, key).map((tool) => clean(tool?.name));
+        return members.length ? members : [key];
+      });
+  for (const rawName of new Set(requested)) {
     const requestedName = clean(rawName);
     const tool = byName.get(requestedName) || byName.get(requestedName.toLowerCase());
     const name = clean(tool?.name);

package/src/runtime/agent/orchestrator/runtime-core/tool-defs.mjs

@@ -17,7 +17,8 @@ export const TOOL_SEARCH_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  description: 'Load full schemas for missing deferred tool names/aliases; batch needed names in one call.',
+  description:
+    'Load full schemas for missing deferred tool names/aliases; a connector name loads all its tools; batch needed names in one call.',
   inputSchema: {
     type: 'object',
     properties: {
@@ -72,7 +73,7 @@ export const SESSION_TOOL = {
     openWorldHint: false,
     agentHidden: true,
   },
-  trigger: 'Session lookup/control, title, compact, fork, Project and worktrees.',
+  trigger: 'Session lookup/control, coding task sessions, title, compact, fork, Project and worktrees.',
   description:
     'Inspect sessions or control another by exact ID, never a guessed one. send acknowledges queue intake, not completion. Cancel/delete and worktree actions require the user’s request. Other actions affect only the current session.',
   inputSchema: {
@@ -87,6 +88,7 @@ export const SESSION_TOOL = {
           'send',
           'cancel',
           'delete',
+          'create',
           'rename',
           'compact',
           'fork',
@@ -100,9 +102,9 @@ export const SESSION_TOOL = {
           'prune-worktrees',
         ],
         description:
-          'status defaults to current; list pages sessions; read returns latest items; send queues prompt; cancel stops the turn; delete removes the session. compact runs after this turn; fork copies it without switching. merge-worktree merges into the Project’s checked-out branch; remove-worktree returns to the Project (repeat on WORKTREE_REMOVAL_INCOMPLETE); list-worktrees includes retaining sessions; prune-worktrees removes only clean, merged, unretained worktrees.',
+          'status defaults to current; list pages sessions; read returns latest items; send queues prompt; cancel stops the turn; delete removes the session. create (agent conversations) starts a visible coding task session from brief and reports its turns back; unknown Project: list-projects first, still ambiguous: ask the user. compact runs after this turn; fork copies it without switching. merge-worktree merges into the Project’s checked-out branch; remove-worktree returns to the Project (repeat on WORKTREE_REMOVAL_INCOMPLETE); list-worktrees includes retaining sessions; prune-worktrees removes only clean, merged, unretained worktrees.',
       },
-      title: { type: 'string', description: 'rename: new current-session title.' },
+      title: { type: 'string', description: 'rename: new current-session title; create: task title.' },
       session_id: {
         type: 'string',
         description:
@@ -143,6 +145,10 @@ export const SESSION_TOOL = {
         description: 'remove-worktree: allow uncommitted/unmerged work only when explicitly requested.',
       },
       value: { type: 'boolean', description: 'favorite/archive: on or off.' },
+      brief: { type: 'string', description: 'create: self-contained instruction, the first message.' },
+      project: { type: 'string', description: 'create: registered Project name or existing directory.' },
+      model: { type: 'string', description: 'create: provider/model or preset; default route otherwise.' },
+      notify: { type: 'boolean', description: 'create: report results back, default true.' },
     },
     additionalProperties: false,
   },

package/src/runtime/agent/orchestrator/runtime-core/workflow/agents.mjs

@@ -29,7 +29,8 @@ function* scanCustomAgentIds(userRoot, shippedRoot) {
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       const id = normalizeWorkflowId(entry.name);
-      if (!id || AGENT_ROLE_IDS.has(id) || isHiddenAgent(id)) continue;
+      // `lead` is Mixy's own folder (PERSONA.md, AGENT.md), never an agent.
+      if (!id || id === 'lead' || AGENT_ROLE_IDS.has(id) || isHiddenAgent(id)) continue;
       if (root !== userRoot && (yield { op: 'exists', path: join(userRoot, id, AGENT_DELETED_MARKER) })) continue;
       if (!(yield { op: 'exists', path: join(root, entry.name, 'AGENT.md') })) continue;
       ids.add(id);
@@ -101,6 +102,8 @@ export function createWorkflowAgents({ rootDir, dataDir, readMarkdownDocument, n
         permission: normalizeAgentPermissionOrNone(doc.frontmatter.permission),
         frontmatter: doc.frontmatter,
         body,
+        // Optional PERSONA.md beside AGENT.md (same dir, same cache entry).
+        persona: (readTextSafe(join(d, 'PERSONA.md')) || '').trim(),
       };
       setAgentDefinitionCache(cacheKey, definition);
       return definition;

package/src/runtime/agent/orchestrator/runtime-core/workflow/context.mjs

@@ -2,8 +2,8 @@
 // (active pack + orchestration instructions + delegatable agent catalog).
 import { clean } from '../session-text.mjs';
 import { configuredOrchestrationMode } from '../../../../shared/orchestration.mjs';
-import { orchestrationInstructions } from '../orchestration.mjs';
-import { DEFAULT_WORKFLOW_ID, normalizeWorkflowId } from '../workflow-ids.mjs';
+import { AGENT_MODE_DELEGATION, MIXY_CONTACTS_INTRO, orchestrationInstructions } from '../orchestration.mjs';
+import { DEFAULT_WORKFLOW_ID, isContactAgentId, normalizeWorkflowId } from '../workflow-ids.mjs';
 
 export function createWorkflowContext({ packs, agents }) {
   function workflowSummary(pack, { hasAgents = true } = {}) {
@@ -43,26 +43,53 @@ export function createWorkflowContext({ packs, agents }) {
     return lines.join('\n\n');
   }
 
-  function orchestrationContextBlock(config, dir) {
+  // Name + description only: the AGENT.md body is the worker's own system
+  // prompt and rides in the worker session at spawn time — repeating it in
+  // the Lead prompt only bloats context. Lead picks agents by description
+  // (a when-to-use signal); orchestration carries the delegation rules.
+  function agentCatalog(dir, ids) {
+    return ids
+      .map((id) => agents.loadAgentDefinition(dir, id))
+      .filter(Boolean)
+      .map((agent) => `- ${agent.name} (${agent.id})${agent.description ? `: ${agent.description}` : ''}`)
+      .join('\n');
+  }
+
+  // A Lead's workflow slices for BP3 (composeSystemPrompt orders them):
+  // - coding: the orchestration mode block and the full agent catalog;
+  // - agent mode: the fixed delegation block (no per-agent setting) and the
+  //   sub-agent catalog — identical for every agent, so their prompts share
+  //   it — plus, for Mixy only, the contact-agent catalog.
+  function leadPromptParts(config, dir, { agentMode = false, mixy = false } = {}) {
     const mode = configuredOrchestrationMode(config);
-    const agentIds = agents.delegatableAgentIds(config, dir);
-    // Solo without agents has nothing to delegate to on request either.
-    if (mode === 'none' && !agentIds.length) return '';
-    const lines = [orchestrationInstructions(mode)];
-    const agentBlocks = agentIds.map((id) => agents.loadAgentDefinition(dir, id)).filter(Boolean);
-    if (agentBlocks.length) {
-      lines.push('# Available Agents');
-      // Name + description only: the AGENT.md body is the worker's own system
-      // prompt and rides in the worker session at spawn time — repeating it in
-      // the Lead prompt only bloats context. Lead picks agents by description
-      // (a when-to-use signal); orchestration carries the delegation rules.
-      lines.push(
-        agentBlocks
-          .map((agent) => `- ${agent.name} (${agent.id})${agent.description ? `: ${agent.description}` : ''}`)
-          .join('\n')
-      );
+    const ids = agents.delegatableAgentIds(config, dir);
+    if (!agentMode) {
+      const catalog = agentCatalog(dir, ids);
+      return {
+        // Solo without agents has nothing to delegate to on request either.
+        orchestrationContext: mode === 'none' && !ids.length ? '' : orchestrationInstructions(mode),
+        agentCatalogContext: catalog ? `# Available Agents\n\n${catalog}` : '',
+        contactCatalogContext: '',
+      };
     }
-    return lines.join('\n\n');
+    const isContact = (id) => isContactAgentId(id, agents.loadAgentDefinition(dir, id)?.frontmatter?.kind);
+    const subAgents = agentCatalog(
+      dir,
+      ids.filter((id) => !isContact(id))
+    );
+    const contacts = mixy ? agentCatalog(dir, ids.filter(isContact)) : '';
+    return {
+      // An agent-mode Lead without agents has no one to delegate to at all.
+      orchestrationContext: subAgents || contacts ? AGENT_MODE_DELEGATION : '',
+      agentCatalogContext: subAgents ? `# Available Agents\n\n${subAgents}` : '',
+      contactCatalogContext: contacts ? `# Contact Agents\n\n${MIXY_CONTACTS_INTRO}\n\n${contacts}` : '',
+    };
+  }
+
+  // The coding Lead's combined block (orchestration + catalog), as before.
+  function orchestrationContextBlock(config, dir) {
+    const { orchestrationContext, agentCatalogContext } = leadPromptParts(config, dir);
+    return [orchestrationContext, agentCatalogContext].filter(Boolean).join('\n\n');
   }
 
   // Single-pass variant: loads the active WORKFLOW.md pack once and derives both
@@ -81,6 +108,9 @@ export function createWorkflowContext({ packs, agents }) {
       // orchestration instructions / agent catalog.
       packContext,
       context: [packContext, orchestrationContextBlock(config, dir)].filter(Boolean).join('\n\n'),
+      // A Lead's BP3 slices beside the pack: `{ agentMode, mixy }` picks the
+      // coding, agent or Mixy variant (session/agent-mode.mjs).
+      leadPromptParts: (options) => leadPromptParts(config, dir, options),
     };
   }
 

package/src/runtime/agent/orchestrator/runtime-core/workflow-ids.mjs

@@ -15,6 +15,8 @@ export const BUILTIN_SLOT_AGENT_IDS = new Set(
   FIXED_AGENT_SLOTS.filter((agent) => agent.workflowSlot).map((agent) => agent.id)
 );
 export const STARTER_AGENT_ORDER = new Map(DEFAULT_DISABLED_AGENT_IDS.map((id, index) => [id, index]));
+// Only Mixy delegates to contacts (agent-route-config.mjs isContactAgentId).
+export { isContactAgentId } from '../../../shared/agent-route-config.mjs';
 export const DEFAULT_WORKFLOW_ID = 'default';
 
 // Loaded AGENT.md definitions, keyed `${dir}\n${agentId}`.

package/src/runtime/agent/orchestrator/session/agent-home.d.mts

@@ -0,0 +1,4 @@
+export const MIXY_AGENT_ID: 'lead';
+export function agentHomeSessionId(agentId: unknown): string;
+export function agentIdOfHomeSession(sessionId: unknown): string;
+export function isAgentHomeSessionId(sessionId: unknown): boolean;

package/src/runtime/agent/orchestrator/session/agent-home.mjs

@@ -0,0 +1,33 @@
+// session/agent-home.mjs
+// An agent's home thread: the ONE user conversation each agent contact owns.
+// Its session id is a fixed key derived from the agent id, never a stored
+// pointer, so every surface (PC, phone, a restarted host) resolves the same
+// session, and two concurrent first opens can only ever name the same id.
+
+/** The primary assistant's contact: the Lead configuration itself. */
+export const MIXY_AGENT_ID = 'lead';
+
+const HOME_PREFIX = 'sess_home_';
+// A normalized agent id (workflow-ids normalizeWorkflowId): underscores are
+// already folded to dashes, so mapping '.' to '_' stays reversible.
+const AGENT_ID = /^[a-z0-9][a-z0-9.-]*$/;
+const MAX_AGENT_ID_LENGTH = 200;
+
+/** The home session id of `agentId`, or '' when it is not a normalized id. */
+export function agentHomeSessionId(agentId) {
+  const id = typeof agentId === 'string' ? agentId : '';
+  if (id.length > MAX_AGENT_ID_LENGTH || !AGENT_ID.test(id)) return '';
+  return `${HOME_PREFIX}${id.replaceAll('.', '_')}`;
+}
+
+/** The agent id a home session belongs to, or '' for any other session. */
+export function agentIdOfHomeSession(sessionId) {
+  const value = typeof sessionId === 'string' ? sessionId : '';
+  if (!value.startsWith(HOME_PREFIX)) return '';
+  const id = value.slice(HOME_PREFIX.length).replaceAll('_', '.');
+  return agentHomeSessionId(id) === value ? id : '';
+}
+
+export function isAgentHomeSessionId(sessionId) {
+  return agentIdOfHomeSession(sessionId) !== '';
+}

package/src/runtime/agent/orchestrator/session/agent-mode.mjs

@@ -0,0 +1,62 @@
+// session/agent-mode.mjs
+// Which mode a Lead session runs in, and the agent it acts as. ONE resolver,
+// used at creation, resume and every refresh:
+// - agent mode: a Lead created as an agent — Mixy's home (`sess_home_lead`),
+//   a contact agent's home (`sess_home_<id>`), a group-room member session
+//   (`sess_rmem_<room>_<id>`), and an agent's schedule/webhook run (stamped
+//   `ownerAgentId`);
+// - coding mode: every other Lead (task sessions, new-task tabs) and every
+//   delegated worker. `owner:'agent'` marks a delegated worker, never an
+//   agent-mode Lead.
+import { isAgentOwner } from '../agent-owner.mjs';
+import { MIXY_AGENT_ID, agentHomeSessionId, agentIdOfHomeSession } from './agent-home.mjs';
+import { roomMemberOfSession } from './agent-room.mjs';
+
+export const AGENT_MODE = 'agent';
+export const CODING_MODE = 'coding';
+
+const validAgentId = (value) => {
+  const id = typeof value === 'string' ? value.trim() : '';
+  return id && agentHomeSessionId(id) ? id : '';
+};
+
+/**
+ * `{ mode, agentId }` of a session record (or create options), its reserved id
+ * and creation profile. `agentId` is the agent the session acts as: '' for a
+ * delegated worker, Mixy for a coding Lead.
+ */
+export function resolveSessionMode({ session = null, sessionId = '', profile = null } = {}) {
+  if (
+    isAgentOwner(session) ||
+    session?.visibility === 'agent-only' ||
+    profile?.owner === 'agent' ||
+    profile?.visibility === 'agent-only'
+  ) {
+    return { mode: CODING_MODE, agentId: '' };
+  }
+  const id = String(session?.id || sessionId || '');
+  const agentId =
+    roomMemberOfSession(id)?.agentId ||
+    agentIdOfHomeSession(id) ||
+    validAgentId(session?.ownerAgentId) ||
+    validAgentId(profile?.ownerAgentId) ||
+    validAgentId(profile?.homeAgent);
+  return agentId ? { mode: AGENT_MODE, agentId } : { mode: CODING_MODE, agentId: MIXY_AGENT_ID };
+}
+
+/** The persisted mode of a session record; older records resolve it. */
+export function sessionModeOf(session) {
+  const stored = session?.sessionMode;
+  if (stored === AGENT_MODE || stored === CODING_MODE) return stored;
+  return resolveSessionMode({ session }).mode;
+}
+
+/** A schedule or webhook run (a routine): no user is present in it. */
+export function isRoutineSource(sourceType) {
+  const kind = String(sourceType || '').toLowerCase();
+  return kind === 'schedule' || kind === 'webhook';
+}
+
+export function isAgentModeSession(session) {
+  return sessionModeOf(session) === AGENT_MODE;
+}

package/src/runtime/agent/orchestrator/session/agent-room-supervisor.d.mts

@@ -0,0 +1,31 @@
+import type { RoomRow, RoomScene, RoomTurnResult } from './agent-room.mjs';
+
+export interface RoomSupervisorMember {
+  id: string;
+  name: string;
+  /** One line about the member, when it has one. */
+  description?: string;
+}
+/** One supervisor step's decision, with its reading of the talk. */
+export type RoomDecision =
+  | { action: 'speak'; agentId: string; scene: RoomScene; instruction?: string }
+  | { action: 'finish'; scene: RoomScene };
+/** What a supervisor step reads (all of it data, never instructions). */
+export interface RoomSupervisorInput {
+  roomName: string;
+  members: RoomSupervisorMember[];
+  rows: RoomRow[];
+  /** This exchange's turns so far, in order. */
+  turns: Array<{ id: string; result: RoomTurnResult }>;
+  /** Nobody has spoken yet: the step must pick a member. */
+  mustPick: boolean;
+  /** The member that took the last turn ('' for none). */
+  last: string;
+  remaining: { messages: number; steps: number };
+}
+export function roomSupervisorRows(rows: unknown): RoomRow[];
+export function roomSupervisorPrompt(input?: Partial<RoomSupervisorInput>): { system: string; user: string };
+export function parseRoomDecision(
+  reply: unknown,
+  members?: readonly { id: string; name?: string }[]
+): RoomDecision | null;