mixdog 1.2.6 → 1.3.1

package/src/session-runtime/services/agent-tool/helpers.mjs

@@ -12,6 +12,8 @@ import {
 import { PRESET_ALIASES } from './tool-def.mjs';
 import { positiveInt } from '../../../runtime/shared/numbers.mjs';
 import { clean } from '../../../runtime/shared/clean.mjs';
+import { readAgentDefinitionKind } from '../../../runtime/shared/agent-kind.mjs';
+import { isStoreBot, userDefinitionDir } from '../../../runtime/shared/agent-store.mjs';
 import { normalizeContextTokens } from '../../../runtime/shared/llm/default-context-window.mjs';
 
 export { positiveInt };
@@ -300,13 +302,18 @@ const _frontmatterPermCache = new Map(); // key -> { value, atMs }
 const FRONTMATTER_PERM_CACHE_TTL_MS = envTimeoutMs('MIXDOG_AGENT_FRONTMATTER_TTL_MS', 5_000);
 
 function agentDeleted(cleanAgent, dataDir) {
-  return Boolean(dataDir) && existsSync(join(dataDir, 'agents', cleanAgent, '.deleted'));
+  return Boolean(dataDir) && existsSync(join(userDefinitionDir(dataDir, cleanAgent), '.deleted'));
 }
 
 /** Where an agent's definition may live, in precedence order: the data dir
  *  (user/custom agents) before the shipped source root. */
 function agentDefinitionFiles(cleanAgent, dataDir, standaloneSourceRoot) {
   const candidates = [];
+  if (dataDir && isStoreBot(dataDir, cleanAgent)) {
+    // A bot of the store: only its own folder (never the agents/ original).
+    candidates.push(join(userDefinitionDir(dataDir, cleanAgent), 'AGENT.md'));
+    return candidates;
+  }
   if (dataDir) {
     candidates.push(join(dataDir, 'agents', cleanAgent, 'AGENT.md'));
     candidates.push(join(dataDir, 'agents', `${cleanAgent}.md`));
@@ -352,6 +359,28 @@ export function readAgentFrontmatterPermission(agent, dataDir, standaloneSourceR
   );
 }
 
+const _frontmatterKindCache = new Map(); // key -> { value, atMs }
+const _frontmatterKindValueCache = new Map(); // key -> { value, atMs }
+
+/** The agent definition's kind (isContactAgentId reads it), by the one
+ *  read-only rule (agent-kind.mjs), cached per agent for the frontmatter TTL. */
+export function readAgentFrontmatterKind(agent, dataDir, standaloneSourceRoot) {
+  const id = clean(agent);
+  if (!id || agentDeleted(id, dataDir)) return null;
+  const cacheKey = `${dataDir}\u0000${id}`;
+  const cached = _frontmatterKindCache.get(cacheKey);
+  if (cached && Date.now() - cached.atMs < FRONTMATTER_PERM_CACHE_TTL_MS) return cached.value;
+  // An explicit kind in the definition in effect (any layout) wins; only an
+  // unmarked user copy goes to the evidence rule.
+  const explicit = cachedFrontmatterValue(_frontmatterKindValueCache, id, dataDir, standaloneSourceRoot, (fm) =>
+    typeof fm.kind === 'string' && fm.kind.trim() ? fm.kind.trim().toLowerCase() : null
+  );
+  const value =
+    explicit || (dataDir ? readAgentDefinitionKind({ dataDir, shippedRoot: standaloneSourceRoot, id }) : null);
+  _frontmatterKindCache.set(cacheKey, { value, atMs: Date.now() });
+  return value;
+}
+
 /** The agent definition's `firstResponseTimeoutMs` (a non-negative integer;
  *  0 disables the first-response deadline), or null when it sets none. */
 export function readAgentFirstResponseTimeoutMs(agent, dataDir, standaloneSourceRoot) {

package/src/session-runtime/services/agent-tool/send-flow.mjs

@@ -16,6 +16,7 @@ import {
   terminalResultHook,
 } from './job-task-reconcile.mjs';
 import { createTurnReviewCollector } from './turn-review.mjs';
+import { handoffContent } from '../../handoff-attachments.mjs';
 import { settledWorkerStatus } from './worker-index/row-liveness.mjs';
 
 // `send` to an existing worker: resolve the live session, run one follow-up
@@ -69,8 +70,10 @@ export function createSendFlow({ mgr, defaultCwd, sessionSurface, canUseSessionS
     return hooks;
   }
 
-  function runTurn({ session, sessionId, prompt, args }, turnHooks) {
+  function runTurn({ session, sessionId, prompt: text, args }, turnHooks) {
     const cwd = session.cwd || defaultCwd;
+    // The caller's forwarded files ride along as attachment parts.
+    const prompt = handoffContent(text, args.attachmentParts);
     if (canUseSessionSurface(session)) {
       return sessionSurface.runTurn({ session, prompt, context: args.context || null, cwd, ...turnHooks });
     }
@@ -194,7 +197,11 @@ export function createSendFlow({ mgr, defaultCwd, sessionSurface, canUseSessionS
     const { session, sessionId, prompt } = prepared;
     const tag = registry.tagForSession(sessionId);
     if (canUseSessionSurface(session) && views.isSessionBusy(sessionId)) {
-      const queued = await sessionSurface.enqueueTurn({ session, prompt, context: prepared.args.context || null });
+      const queued = await sessionSurface.enqueueTurn({
+        session,
+        prompt: handoffContent(prompt, prepared.args.attachmentParts),
+        context: prepared.args.context || null,
+      });
       if (queued) {
         return renderResult({ queued: true, ...extras, tag, sessionId, agent: session.agent || null, ...queued });
       }
@@ -204,7 +211,8 @@ export function createSendFlow({ mgr, defaultCwd, sessionSurface, canUseSessionS
       views.isSessionBusy(sessionId) &&
       typeof mgr.enqueuePendingMessage === 'function'
     ) {
-      const queueDepth = mgr.enqueuePendingMessage(sessionId, prompt);
+      // The queued follow-up keeps the forwarded files, as the canonical queue does.
+      const queueDepth = mgr.enqueuePendingMessage(sessionId, handoffContent(prompt, prepared.args.attachmentParts));
       return renderResult({ queued: true, ...extras, tag, sessionId, agent: session.agent || null, queueDepth });
     }
     const job = spawnFlow.startJob(

package/src/session-runtime/services/agent-tool/spawn-flow/spawn-plan.mjs

@@ -9,6 +9,7 @@ import {
   agentDefinitionExists,
   clean,
   normalizeAgentName,
+  readAgentFrontmatterKind,
   readAgentFrontmatterPermission,
   resolvePrompt,
   terminalPidForContext,
@@ -18,8 +19,13 @@ import { normalizeAgentPermission } from '../../../../runtime/shared/markdown-fr
 import { resolveAgentSpawnPreset } from '../spawn-preset.mjs';
 import { AGENT_OWNER } from '../../../../runtime/agent/orchestrator/agent-owner.mjs';
 import { workspaceCwdLock } from '../../../workspace/admission-gate.mjs';
+import { isContactAgentId } from '../../../../runtime/agent/orchestrator/runtime-core/workflow-ids.mjs';
+import { AGENT_MODE, resolveSessionMode } from '../../../../runtime/agent/orchestrator/session/agent-mode.mjs';
+import { MIXY_AGENT_ID } from '../../../../runtime/agent/orchestrator/session/agent-home.mjs';
+import { mixyDisplayName } from '../../../../runtime/agent/orchestrator/session/mixy-name.mjs';
 
 export function createSpawnPlanner({
+  mgr = null,
   cfgMod,
   dataDir,
   STANDALONE_SOURCE_ROOT,
@@ -44,6 +50,18 @@ export function createSpawnPlanner({
     if (isAgentDisabled(config, agent)) {
       throw new Error(`agent spawn: agent "${agent}" is turned off`);
     }
+    // Only Mixy hands work to a contact agent; any other agent-mode Lead
+    // delegates to sub-agents alone (its catalog lists no contact either).
+    if (isContactAgentId(agent, readAgentFrontmatterKind(agent, dataDir, STANDALONE_SOURCE_ROOT))) {
+      const callerId = clean(context?.callerSessionId || context?.sessionId);
+      const caller = (callerId && mgr?.getSession?.(callerId)) || null;
+      const { mode, agentId } = resolveSessionMode({ session: caller, sessionId: callerId });
+      if (mode === AGENT_MODE && agentId !== MIXY_AGENT_ID) {
+        throw new Error(
+          `agent spawn: only ${mixyDisplayName()} (the representative agent) can hand work to the contact agent "${agent}"; delegate to a sub-agent instead`
+        );
+      }
+    }
     const agentPermission = readAgentFrontmatterPermission(agent, dataDir, STANDALONE_SOURCE_ROOT);
     const agentPerm = normalizeAgentPermission(agentPermission) || null;
     const { presetName, preset } = resolveAgentSpawnPreset(config, args);
@@ -56,10 +74,7 @@ export function createSpawnPlanner({
     // Workers share their Lead's execution root. While the Lead runs in its
     // worktree, that root is locked: neither args.cwd nor an inherited
     // (pre-transition) cwd can send a worker elsewhere.
-    const lockedCwd = workspaceCwdLock([
-      context?.ownerSessionId,
-      context?.callerSessionId || context?.sessionId,
-    ]);
+    const lockedCwd = workspaceCwdLock([context?.ownerSessionId, context?.callerSessionId || context?.sessionId]);
     const baseCwd = resolve(lockedCwd || callerCwd || defaultCwd || process.cwd());
     const workerCwd = !lockedCwd && clean(args.cwd) ? resolve(baseCwd, args.cwd) : baseCwd;
     const prompt = await resolvePrompt(args, workerCwd);

package/src/session-runtime/services/agent-tool/spawn-flow/spawn-prep.mjs

@@ -58,8 +58,10 @@ export function createSpawnPreparer({
   ensureProvider,
   sessionSurface = null,
   refreshTagsFromSessions,
+  mgr = null,
 }) {
   const { resolveSpawnPlan, spawnSessionSpec } = createSpawnPlanner({
+    mgr,
     cfgMod,
     dataDir,
     STANDALONE_SOURCE_ROOT,

package/src/session-runtime/services/agent-tool/spawn-flow/spawn-run.mjs

@@ -25,6 +25,7 @@ import { settledWorkerStatus } from '../worker-index/row-liveness.mjs';
 import { saveSessionAsync } from '../../../../runtime/agent/orchestrator/session/store.mjs';
 import { presetDescriptor } from './spawn-prep.mjs';
 import { workerStageForStatus } from '../worker-rows.mjs';
+import { handoffContent } from '../../../handoff-attachments.mjs';
 
 // Mid-turn worker persistence cadence. The watchdog sweep runs every second;
 // a transcript save is far more expensive than a bookkeeping stamp, so the
@@ -117,7 +118,9 @@ export function createSpawnRunner({
   };
 
   async function runTurn(prepared, turnHooks) {
-    const { args, session, prompt, workerCwd } = prepared;
+    const { args, session, workerCwd } = prepared;
+    // The caller's forwarded files ride along as attachment parts.
+    const prompt = handoffContent(prepared.prompt, args.attachmentParts);
     if (typeof sessionSurface?.runTurn === 'function' && sessionSurface.canRun?.(session) !== false) {
       return sessionSurface.runTurn({ session, prompt, context: args.context || null, cwd: workerCwd, ...turnHooks });
     }

package/src/session-runtime/services/agent-tool/spawn-preset.mjs

@@ -27,11 +27,10 @@ export function resolveAgentSpawnPreset(config, args = {}) {
   }
 
   const agentName = normalizeAgentName(args.agent);
-  const agentRoute = !clean(args.preset)
-    ? configuredAgentRouteCandidates(config, agentName)
-        .map((candidate) => normalizeAgentRoute(candidate))
-        .find(Boolean) || null
-    : null;
+  // The agent's stored route: config.agents, or a store bot's own folder.
+  const candidates = !clean(args.preset) ? configuredAgentRouteCandidates(config, agentName) : [];
+  const agentRoute = candidates.map((candidate) => normalizeAgentRoute(candidate)).find(Boolean) || null;
+  const storedFallbacks = candidates.find((candidate) => normalizeAgentRoute(candidate))?.fallbacks;
   if (agentRoute) {
     return {
       presetName: agentPresetName(agentName),
@@ -41,9 +40,7 @@ export function resolveAgentSpawnPreset(config, args = {}) {
         type: 'agent',
         provider: agentRoute.provider,
         model: agentRoute.model,
-        ...(config.agents?.[agentName]?.fallbacks?.length
-          ? { fallbacks: config.agents[agentName].fallbacks.map(normalizeAgentRoute) }
-          : {}),
+        ...(storedFallbacks?.length ? { fallbacks: storedFallbacks.map(normalizeAgentRoute) } : {}),
         effort: agentRoute.effort,
         fast: agentRoute.fast === true,
         ...(agentRoute.autoEffort === false ? { autoEffort: false } : {}),

package/src/session-runtime/services/agent-tool/tool-def.mjs

@@ -53,6 +53,13 @@ export const AGENT_TOOL = {
       file: { type: 'string', description: 'Path to task text; alternative to prompt/message for spawn/send.' },
       cwd: { type: 'string', description: 'Project directory for a new or respawned agent.' },
       context: { type: 'string', description: 'Extra context for the spawn/send turn.' },
+      attachments: {
+        type: 'array',
+        items: { type: 'string' },
+        maxItems: 8,
+        description:
+          "spawn/send: files to attach (images, PDF/Office, text): a conversation attachment's file name or [attachment:id], or a path inside your folders. Produced files come back as paths; forward them by path.",
+      },
       model: {
         type: 'string',
         description:

package/src/session-runtime/services/channel-admin.mjs

@@ -23,13 +23,14 @@ import {
   setEndpointEnabled as dbSetEndpointEnabled,
 } from '../../runtime/channels/lib/webhooks-db.mjs';
 import { normalizeAutomationAttachments } from '../../runtime/shared/automation-attachments.mjs';
-import { migrateCodexModelRef } from '../../runtime/agent/orchestrator/providers/openai-oauth-catalog-store.mjs';
+import { assertRoutineOwner, routineOwnerProblem } from '../routine-owner.mjs';
 import { hasEnabledAutomation } from '../../runtime/shared/automation-presence.mjs';
 import { resolveScheduleTimezone, validateScheduleCron } from '../../runtime/shared/schedule-time.mjs';
 import { pgClusterExists } from '../../runtime/memory/lib/pg/adapter.mjs';
 import { resolvePluginData } from '../../runtime/shared/plugin-paths.mjs';
 import { readHookPublicBase } from '../../runtime/channels/lib/webhook/relay-tunnel.mjs';
 import { WEBHOOK_TEST_FIELD, WEBHOOK_TEST_HEADER } from '../../runtime/channels/lib/webhook/request-handler.mjs';
+import { MIXY_AGENT_ID, agentHomeSessionId } from '../../runtime/agent/orchestrator/session/agent-home.mjs';
 
 const NAME_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;
 
@@ -187,7 +188,7 @@ function parseAtDatetime(at) {
 // Map the store's def shape onto the flat display shape every schedule reader
 // (channelSetup, renderChannelStatus, TUI pickers) consumes: `.time` renders
 // the cron or the one-shot datetime, `.route` the channel/session target.
-function scheduleToDisplay(s) {
+function scheduleToDisplay(s, ownerProblem = '') {
   return {
     name: s.name,
     description: s.description || '',
@@ -195,26 +196,85 @@ function scheduleToDisplay(s) {
     whenAt: s.whenAt || undefined,
     whenCron: s.whenCron || undefined,
     timezone: s.timezone || undefined,
-    // Shown (and re-saved by the editor) on the catalog successor of a superseded model.
-    model: s.model ? migrateCodexModelRef(s.model) : undefined,
     cwd: s.cwd || undefined,
-    workflow: s.workflow || undefined,
     attachments: s.attachments || undefined,
     enabled: s.enabled !== false,
     instructions: s.prompt,
     route: 'session',
+    // The bot it belongs to: each run is a turn in that bot's chat.
+    owner: s.ownerAgentId || MIXY_AGENT_ID,
+    // Why it is paused for its owner (routine-owner.mjs); absent when it runs.
+    ...(ownerProblem ? { ownerProblem } : {}),
+    nextFireAt: isoOrUndefined(s.nextFireAt),
+    lastSuccessAt: isoOrUndefined(s.lastSuccessAt),
+    lastFailedAt: isoOrUndefined(s.lastFailedAt),
+    lastSkippedAt: isoOrUndefined(s.lastSkippedAt),
+    ...routineHealth(s),
+  };
+}
+
+// Failures in a row (the routine pauses itself at the limit) and the results
+// of finished runs still not queued for the owner: `{ count, failed, error }`,
+// `failed` when the queue refused one (the app offers a retry).
+function routineHealth(row) {
+  const entries = Object.values(row.resultDelivery || {}).filter(Boolean);
+  const refused = entries.filter((entry) => entry.state === 'failed').at(-1);
+  return {
+    consecutiveFailures: Number(row.consecutiveFailures) || 0,
+    ...(entries.length
+      ? {
+          undelivered: {
+            count: entries.length,
+            failed: Boolean(refused),
+            ...(refused?.error ? { error: String(refused.error) } : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+function isoOrUndefined(value) {
+  if (!value) return undefined;
+  const at = new Date(value);
+  return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+}
+
+// A schedule's or webhook's owner: an explicit agent id, else the saved owner
+// on an overwrite, else Mixy.
+function scheduleOwner(owner, existing) {
+  const value = String(owner ?? '').trim();
+  if (value) {
+    if (!agentHomeSessionId(value)) throw new Error(`schedule owner "${value}" is not a valid agent id`);
+    return value;
+  }
+  return existing?.ownerAgentId || MIXY_AGENT_ID;
+}
+
+/** Each owner's problem (routine-owner.mjs), probed once per owner. */
+function ownerProblems() {
+  const seen = new Map();
+  return (ownerAgentId) => {
+    const owner = ownerAgentId || MIXY_AGENT_ID;
+    if (!seen.has(owner))
+      seen.set(
+        owner,
+        routineOwnerProblem(owner).catch(() => '')
+      );
+    return seen.get(owner);
   };
 }
 
 export async function listSchedules() {
   const rows = await dbListSchedules();
-  return rows.map(scheduleToDisplay);
+  const problemOf = ownerProblems();
+  return Promise.all(rows.map(async (row) => scheduleToDisplay(row, await problemOf(row.ownerAgentId))));
 }
 
 // Register or update a schedule in the PG store. Recurring input maps `time`
 // (+ optional `days`) to a cron; one-shot input maps an `at` datetime; the two
 // are mutually exclusive (also enforced by the store's when_at/when_cron XOR).
-// Every schedule runs as a visible app session and requires a model.
+// Every schedule runs as a turn in its owner bot's chat; a bot that does not
+// exist (no representative bot yet, an archived bot) cannot own one.
 export async function saveSchedule({
   name,
   description = '',
@@ -222,26 +282,26 @@ export async function saveSchedule({
   at,
   timezone,
   days,
-  model,
   cwd,
-  workflow,
   attachments,
   enabled,
   instructions,
+  owner,
   overwrite = false,
 } = {}) {
   const id = assertScheduleName(name);
   const body = String(instructions || '').trim();
   if (!body) throw new Error('schedule instructions are required');
-  const scheduleModel = String(model || '').trim();
-  if (!scheduleModel) throw new Error('schedule model is required — choose a model before saving');
   const hasTime = time != null && String(time).trim() !== '';
   const hasAt = at != null && String(at).trim() !== '';
   if (hasTime && hasAt) throw new Error('provide either `time` (recurring) or `at` (one-shot), not both');
   if (!hasTime && !hasAt) throw new Error('either `time` (recurring cron) or `at` (one-shot datetime) is required');
-  if (overwrite !== true && (await dbGetSchedule(id))) {
+  const existing = await dbGetSchedule(id);
+  if (overwrite !== true && existing) {
     throw new Error(`schedule "${id}" already exists`);
   }
+  const ownerAgentId = scheduleOwner(owner, existing);
+  await assertRoutineOwner(ownerAgentId);
   const whenCron = hasTime ? validateScheduleCron(foldDaysIntoCron(normalizeCron(time), days)) : null;
   const whenAt = hasAt ? parseAtDatetime(at) : null;
   const scheduleTimezone = hasTime ? resolveScheduleTimezone(timezone) : null;
@@ -253,14 +313,13 @@ export async function saveSchedule({
     timezone: scheduleTimezone,
     target: 'session',
     channelId: null,
-    model: scheduleModel,
     cwd: cwd ? String(cwd).trim() : null,
-    workflow: workflow ? String(workflow).trim() : null,
     attachments: normalizeAutomationAttachments(attachments),
     delivery: 'app',
     prompt: body,
     enabled: enabled !== false,
     nextFireAt: whenAt,
+    ownerAgentId,
   });
   automationProbe.invalidate();
   return scheduleToDisplay(saved);
@@ -287,13 +346,13 @@ export async function setScheduleEnabled(name, enabled) {
 // store's migration hook.
 async function listWebhooks() {
   const endpoints = await dbListEndpoints();
-  return endpoints.map((ep) => ({
+  const problemOf = ownerProblems();
+  const problems = await Promise.all(endpoints.map((ep) => problemOf(ep.ownerAgentId)));
+  return endpoints.map((ep, index) => ({
     name: ep.name,
     description: ep.description || '',
     parser: ep.parser || 'github',
-    ...(ep.model ? { model: migrateCodexModelRef(ep.model) } : {}),
     ...(ep.cwd ? { cwd: ep.cwd } : {}),
-    ...(ep.workflow ? { workflow: ep.workflow } : {}),
     ...(ep.attachments ? { attachments: ep.attachments } : {}),
     enabled: ep.enabled,
     // The store never projects the plaintext secret through list paths; it
@@ -302,6 +361,16 @@ async function listWebhooks() {
     secret: undefined,
     instructions: ep.instructions,
     route: 'session',
+    // The bot it belongs to: each run is a turn in that bot's chat.
+    owner: ep.ownerAgentId || MIXY_AGENT_ID,
+    ...(problems[index] ? { ownerProblem: problems[index] } : {}),
+    lastEventAt: isoOrUndefined(ep.lastEventAt),
+    lastSuccessAt: isoOrUndefined(ep.lastSuccessAt),
+    lastFailedAt: isoOrUndefined(ep.lastFailedAt),
+    lastSkippedAt: isoOrUndefined(ep.lastSkippedAt),
+    // Whether "Run now" has a received payload to re-run (never the payload).
+    hasLastPayload: ep.hasLastPayload === true,
+    ...routineHealth(ep),
   }));
 }
 
@@ -310,12 +379,11 @@ export async function saveWebhook({
   description = '',
   parser = 'github',
   secret,
-  model,
   cwd,
-  workflow,
   attachments,
   enabled,
   instructions,
+  owner,
   overwrite = false,
 } = {}) {
   const id = assertName(name, 'webhook name');
@@ -327,9 +395,12 @@ export async function saveWebhook({
   }
   const body = String(instructions || '').trim();
   if (!body) throw new Error('webhook instructions are required');
-  if (overwrite !== true && (await dbLoadEndpoint(id))) {
+  const existing = await dbLoadEndpoint(id);
+  if (overwrite !== true && existing) {
     throw new Error(`webhook "${id}" already exists`);
   }
+  const ownerAgentId = scheduleOwner(owner, existing);
+  await assertRoutineOwner(ownerAgentId);
   // Secret semantics: an explicit value always wins; an EMPTY value on an
   // overwrite PRESERVES the stored secret (editing instructions must not
   // silently rotate the key the external service was configured with); only
@@ -343,23 +414,21 @@ export async function saveWebhook({
     description: String(description || '').trim(),
     parser: nextParser,
     channelId: null,
-    model: model ? String(model).trim() : null,
     cwd: cwd ? String(cwd).trim() : null,
-    workflow: workflow ? String(workflow).trim() : null,
     attachments: normalizeAutomationAttachments(attachments),
     delivery: 'app',
     secret: secretValue,
     instructions: body,
     enabled: enabled !== false,
+    ownerAgentId,
   });
   automationProbe.invalidate();
   return {
     name: id,
+    owner: saved.ownerAgentId || ownerAgentId,
     description: saved.description,
     parser: saved.parser,
-    ...(saved.model ? { model: saved.model } : {}),
     ...(saved.cwd ? { cwd: saved.cwd } : {}),
-    ...(saved.workflow ? { workflow: saved.workflow } : {}),
     ...(saved.attachments ? { attachments: saved.attachments } : {}),
     ...(enabled === false ? { enabled: false } : {}),
     secret: secretValue,

package/src/session-runtime/services/memory-access.mjs

@@ -0,0 +1,37 @@
+// Whose memory a session reads and writes (runtime/memory/lib/
+// core-memory-access.mjs enforces it). Mixy is the Lead configuration, so the
+// user's own sessions (an ordinary Lead session, Mixy's home) act as Mixy; an
+// agent's home thread and its room member sessions act as that agent; a
+// schedule or webhook run acts for its owning agent (`ownerAgentId`, stamped
+// at creation); a delegated agent as its own agent id.
+import { MIXY_AGENT_ID, agentHomeSessionId } from '../../runtime/agent/orchestrator/session/agent-home.mjs';
+import { resolveSessionMode } from '../../runtime/agent/orchestrator/session/agent-mode.mjs';
+import { isAgentOwner } from '../../runtime/agent/orchestrator/agent-owner.mjs';
+import { scheduleCallerScope } from './schedule-access.mjs';
+
+const validAgentId = (value) => {
+  const id = typeof value === 'string' ? value.trim() : '';
+  return id && agentHomeSessionId(id) ? id : '';
+};
+
+/** The `memory_caller` `{ kind, agentId }` of a calling session record:
+ *  'human' and 'agent' are conversations with the user, 'room-member' and
+ *  'headless' unattended runs. */
+export function memoryCallerScope(session) {
+  const scope = scheduleCallerScope(session);
+  if (scope.kind === 'human') return { kind: 'human', agentId: MIXY_AGENT_ID };
+  if (scope.kind !== 'headless') return scope;
+  const delegated = isAgentOwner(session) || Boolean(session?.parentSessionId);
+  return {
+    kind: 'headless',
+    agentId: validAgentId(session?.ownerAgentId) || (delegated ? validAgentId(session?.agent) : ''),
+  };
+}
+
+/** The agent whose own memory a session's prompt carries: its home thread's,
+ *  room member's or run owner's agent, Mixy for the user's Lead sessions, and
+ *  none for a delegated agent. `session` is the live record when there is
+ *  one, else the reserved id and creation profile. */
+export function injectedMemoryAgentId({ session = null, sessionId = '', profile = null } = {}) {
+  return resolveSessionMode({ session, sessionId, profile }).agentId;
+}