@myagentroam/node 0.11.39 → 0.11.41

package/dist/service/agent-network-service.js

@@ -0,0 +1,315 @@
+import { randomUUID } from 'node:crypto';
+import { isPlainRecord } from '../util/records.js';
+import { safeErrorCode } from '../util/safe-error.js';
+import { parseAgentGoal } from './agent-network-goal.js';
+import { validateAgentWaitOptions, waitForAgentTargets } from './agent-network-wait.js';
+/** Product collaboration delegates execution and Goal ownership to existing Node services. */
+export class AgentNetworkService {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    list(actor, input = {}) {
+        return this.options.list(actor, input);
+    }
+    view(actor, input) {
+        return this.options.view(actor, input);
+    }
+    async start(actor, input, signal) {
+        signal?.throwIfAborted();
+        const goal = parseAgentGoal(input.goal);
+        const content = input.content ?? '';
+        if (typeof content !== 'string' ||
+            (!content.trim() && !input.attachments?.length && !input.attachmentIds?.length) ||
+            (input.attachments !== undefined && !Array.isArray(input.attachments)) ||
+            (input.attachmentIds !== undefined &&
+                (!Array.isArray(input.attachmentIds) ||
+                    input.attachmentIds.some((id) => typeof id !== 'string' || !id))) ||
+            (!!input.attachments?.length && !!input.attachmentIds?.length) ||
+            !validOptionalString(input.runner) ||
+            !validOptionalString(input.model) ||
+            !validOptionalString(input.effort) ||
+            !validOptionalString(input.title) ||
+            !validOptionalString(input.parentSessionId) ||
+            !validOptionalString(input.clientMessageId))
+            throw new Error('AGENT_START_INVALID');
+        const { goal: _goal, ...start } = input;
+        const created = await this.options.start(actor, {
+            ...start,
+            content,
+            clientMessageId: input.clientMessageId ?? randomUUID(),
+            goal
+        }, signal);
+        try {
+            this.options.observe(actor, created.session);
+            return { agentId: created.session.id, start: created.result };
+        }
+        catch (error) {
+            return {
+                agentId: created.session.id,
+                start: created.result,
+                observation: { status: 'failed', code: safeErrorCode(error, 'AGENT_OBSERVATION_FAILED') }
+            };
+        }
+    }
+    async send(actor, input, signal) {
+        signal?.throwIfAborted();
+        const goal = parseAgentGoal(input.goal);
+        const content = input.content ?? '';
+        if (typeof input.agentId !== 'string' ||
+            !input.agentId ||
+            typeof content !== 'string' ||
+            (!content.trim() &&
+                !input.attachments?.length &&
+                !input.attachmentIds?.length &&
+                goal.kind === 'unchanged' &&
+                input.approval === undefined) ||
+            (input.attachments !== undefined && !Array.isArray(input.attachments)) ||
+            (input.attachmentIds !== undefined &&
+                (!Array.isArray(input.attachmentIds) ||
+                    input.attachmentIds.some((id) => typeof id !== 'string' || !id))) ||
+            (!!input.attachments?.length && !!input.attachmentIds?.length) ||
+            !validOptionalString(input.clientMessageId) ||
+            (input.approval !== undefined &&
+                (!isPlainRecord(input.approval) ||
+                    Object.keys(input.approval).some((key) => key !== 'approvalId' && key !== 'decision') ||
+                    typeof input.approval.approvalId !== 'string' ||
+                    !input.approval.approvalId ||
+                    !['approve', 'reject'].includes(input.approval.decision))))
+            throw new Error('AGENT_SEND_INVALID');
+        if (input.deliveryIntent !== undefined &&
+            !['SEND', 'QUEUE', 'REPLACE_CURRENT'].includes(input.deliveryIntent))
+            throw new Error('AGENT_SEND_INVALID');
+        const hasMessage = !!content.trim() || !!input.attachments?.length || !!input.attachmentIds?.length;
+        const session = await this.options.target(actor, input.agentId);
+        signal?.throwIfAborted();
+        if (hasMessage)
+            await this.options.authorize(actor, session, 'send');
+        if (goal.kind !== 'unchanged')
+            await this.options.authorize(actor, session, 'goal');
+        if (input.approval !== undefined)
+            await this.options.validateApproval(actor, session, input.approval);
+        signal?.throwIfAborted();
+        if (hasMessage && (await this.options.isUpward(actor, session))) {
+            signal?.throwIfAborted();
+            if (goal.kind !== 'unchanged' ||
+                input.approval !== undefined ||
+                input.deliveryIntent === 'REPLACE_CURRENT' ||
+                input.deliveryIntent === 'QUEUE' ||
+                input.attachments?.length ||
+                input.attachmentIds?.length)
+                throw new Error('AGENT_UPWARD_REPORT_INVALID');
+            const result = await this.options.reportUpward(actor, session, {
+                clientMessageId: input.clientMessageId ?? randomUUID(),
+                content
+            }, signal);
+            return { agentId: session.id, message: { status: 'accepted', result } };
+        }
+        signal?.throwIfAborted();
+        this.options.observe(actor, session);
+        const approvalResult = input.approval === undefined
+            ? undefined
+            : await this.options.approval(actor, session, input.approval, signal);
+        const approvalReceipt = input.approval === undefined ? {} : { approval: approvalResult };
+        if (approvalResult?.status === 'partial')
+            return {
+                agentId: session.id,
+                ...approvalReceipt,
+                ...(goal.kind === 'unchanged' ? {} : { goal: { status: 'not_attempted' } }),
+                message: { status: 'not_attempted' }
+            };
+        if (signal?.aborted && approvalResult !== undefined)
+            return {
+                agentId: session.id,
+                ...approvalReceipt,
+                ...(goal.kind === 'unchanged' ? {} : { goal: { status: 'not_attempted' } }),
+                message: { status: 'not_attempted' }
+            };
+        signal?.throwIfAborted();
+        const captured = this.options.observations.get(actor.sessionId)?.captureBeforeSend(session.id);
+        const message = hasMessage
+            ? {
+                clientMessageId: input.clientMessageId ?? randomUUID(),
+                content,
+                deliveryIntent: input.deliveryIntent ?? 'SEND',
+                ...(input.attachments === undefined ? {} : { attachments: input.attachments }),
+                ...(input.attachmentIds === undefined ? {} : { attachmentIds: input.attachmentIds })
+            }
+            : undefined;
+        let goalResult;
+        if (goal.kind !== 'unchanged') {
+            const previous = this.options.goal(session.id);
+            try {
+                goalResult = await this.options.setGoal(actor, session, goal, goal.kind === 'set' ? message : undefined, signal);
+                if (goal.kind === 'set' && message)
+                    captured?.acknowledge();
+            }
+            catch (error) {
+                const current = this.options.goal(session.id);
+                if (sameGoal(current, previous) && input.approval === undefined)
+                    throw error;
+                return {
+                    agentId: session.id,
+                    ...approvalReceipt,
+                    goal: {
+                        status: 'failed',
+                        code: safeErrorCode(error, 'AGENT_GOAL_FAILED'),
+                        current: current ?? null
+                    },
+                    message: { status: goal.kind === 'set' && message ? 'unknown' : 'not_attempted' }
+                };
+            }
+        }
+        if (!message || goal.kind === 'set')
+            return {
+                agentId: session.id,
+                ...approvalReceipt,
+                ...(goal.kind === 'unchanged' ? {} : { goal: { status: 'applied', result: goalResult } }),
+                message: message ? { status: 'accepted', result: goalResult } : null
+            };
+        if (signal?.aborted && (goal.kind !== 'unchanged' || approvalResult !== undefined))
+            return {
+                agentId: session.id,
+                ...approvalReceipt,
+                ...(goal.kind === 'unchanged' ? {} : { goal: { status: 'applied', result: goalResult } }),
+                message: { status: 'not_attempted' }
+            };
+        signal?.throwIfAborted();
+        try {
+            const result = await this.options.message(actor, session, message, signal);
+            captured?.acknowledge();
+            return {
+                agentId: session.id,
+                ...approvalReceipt,
+                ...(goal.kind === 'unchanged' ? {} : { goal: { status: 'applied', result: goalResult } }),
+                message: { status: 'accepted', result }
+            };
+        }
+        catch (error) {
+            if (signal?.aborted && error === signal.reason) {
+                if (goal.kind === 'unchanged' && approvalResult === undefined)
+                    throw error;
+                return {
+                    agentId: session.id,
+                    ...approvalReceipt,
+                    ...(goal.kind === 'unchanged' ? {} : { goal: { status: 'applied', result: goalResult } }),
+                    message: { status: 'not_attempted' }
+                };
+            }
+            return {
+                agentId: session.id,
+                ...approvalReceipt,
+                ...(goal.kind === 'unchanged' ? {} : { goal: { status: 'applied', result: goalResult } }),
+                message: { status: 'unknown', code: safeErrorCode(error, 'AGENT_SEND_FAILED') }
+            };
+        }
+    }
+    async stop(actor, input) {
+        if (typeof input.agentId !== 'string' ||
+            !input.agentId ||
+            typeof input.executionId !== 'string' ||
+            !input.executionId)
+            throw new Error('AGENT_STOP_INVALID');
+        const session = await this.options.target(actor, input.agentId);
+        await this.options.authorize(actor, session, 'stop');
+        const goalBefore = this.options.goal(session.id);
+        try {
+            const result = this.options.stop(actor, session, input.executionId);
+            return {
+                agentId: session.id,
+                executionId: input.executionId,
+                cancel: { status: 'accepted', result },
+                goal: {
+                    status: goalBefore != null && this.options.goal(session.id) == null ? 'cleared' : 'unchanged'
+                }
+            };
+        }
+        catch (error) {
+            const code = safeErrorCode(error, 'AGENT_STOP_FAILED');
+            if (code === 'RUN_EXECUTION_STALE' || code === 'RUN_OWNED_BY_ANOTHER_USER')
+                throw error;
+            const current = this.options.goal(session.id);
+            return {
+                agentId: session.id,
+                executionId: input.executionId,
+                cancel: { status: 'unknown', code },
+                goal: { status: goalBefore != null && current == null ? 'cleared' : 'unchanged' }
+            };
+        }
+    }
+    async wait(actor, input) {
+        validateAgentWaitOptions(input);
+        if ((input.mode !== undefined && input.agentIds === undefined) ||
+            (input.agentId !== undefined && input.agentIds !== undefined) ||
+            (input.agentId !== undefined && (typeof input.agentId !== 'string' || !input.agentId)) ||
+            (input.agentIds !== undefined &&
+                (!Array.isArray(input.agentIds) ||
+                    input.agentIds.length === 0 ||
+                    input.agentIds.length > 8 ||
+                    input.agentIds.some((id) => typeof id !== 'string' || !id) ||
+                    new Set(input.agentIds).size !== input.agentIds.length)))
+            throw new Error('AGENT_WAIT_INVALID');
+        input.signal?.throwIfAborted();
+        const ids = input.agentId === undefined ? input.agentIds : [input.agentId];
+        let sessions;
+        if (ids)
+            sessions = await Promise.all(ids.map((id) => this.options.target(actor, id)));
+        else
+            sessions = await this.options.children(actor);
+        await Promise.all(sessions.map((session) => this.options.authorize(actor, session, 'wait')));
+        input.signal?.throwIfAborted();
+        let targets = sessions.flatMap((session) => {
+            const target = this.options.freezeExecution(session);
+            return target === undefined ? [] : [target];
+        });
+        if (ids && targets.length !== sessions.length)
+            throw new Error('AGENT_EXECUTION_NOT_FOUND');
+        if (!ids) {
+            const active = targets.filter((target) => !['SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED'].includes(target.read().status));
+            if (active.length) {
+                const creation = new Map(sessions.map((session) => [session.id, session.createdAt]));
+                targets = active.sort((a, b) => (creation.get(b.agentId) ?? 0) - (creation.get(a.agentId) ?? 0));
+            }
+            else {
+                const withExecution = new Set(targets.map((target) => target.agentId));
+                const latest = [...sessions]
+                    .filter((session) => withExecution.has(session.id))
+                    .sort((a, b) => b.createdAt - a.createdAt)[0];
+                targets = targets.filter((target) => target.agentId === latest?.id);
+            }
+        }
+        if (!targets.length)
+            throw new Error('AGENT_EXECUTION_NOT_FOUND');
+        const selected = new Set(targets.map((target) => target.agentId));
+        for (const session of sessions)
+            if (selected.has(session.id))
+                this.options.observe(actor, session);
+        const observations = this.options.observations.get(actor.observationId ?? actor.sessionId);
+        if (!observations)
+            throw new Error('AGENT_OBSERVATION_UNAVAILABLE');
+        return waitForAgentTargets({
+            targets,
+            observations,
+            single: input.agentIds === undefined,
+            waitMs: input.waitMs ?? 30_000,
+            ...(input.mode === undefined ? {} : { mode: input.mode }),
+            ...(input.waitFor === undefined ? {} : { waitFor: input.waitFor }),
+            ...(input.signal === undefined ? {} : { signal: input.signal }),
+            ...(input.interrupt === undefined ? {} : { interrupt: input.interrupt })
+        });
+    }
+}
+function sameGoal(left, right) {
+    if (left === right)
+        return true;
+    return (isPlainRecord(left) &&
+        isPlainRecord(right) &&
+        typeof left.id === 'string' &&
+        left.id === right.id &&
+        typeof left.revision === 'number' &&
+        left.revision === right.revision &&
+        left.status === right.status);
+}
+function validOptionalString(value) {
+    return value === undefined || (typeof value === 'string' && value.trim().length > 0);
+}

package/dist/service/agent-network-wait.js

@@ -0,0 +1,130 @@
+import { waitForToolCondition } from '@myagentroam/agent/extensions';
+export function validateAgentWaitOptions(input) {
+    if ((input.mode !== undefined && input.mode !== 'any' && input.mode !== 'all') ||
+        (input.waitFor !== undefined &&
+            input.waitFor !== 'message' &&
+            input.waitFor !== 'completion') ||
+        (input.waitMs !== undefined &&
+            (!Number.isInteger(input.waitMs) || input.waitMs < 0 || input.waitMs > 300_000)))
+        throw new Error('AGENT_WAIT_INVALID');
+}
+/** One deadline and one notification subscription, with Session-scoped consumption. */
+export async function waitForAgentTargets(input) {
+    const { targets, observations } = input;
+    validateAgentWaitOptions(input);
+    if (!targets.length ||
+        (!input.single && targets.length > 8) ||
+        new Set(targets.map((target) => target.agentId)).size !== targets.length)
+        throw new Error('AGENT_WAIT_INVALID');
+    input.signal?.throwIfAborted();
+    const waitMs = input.waitMs ?? 30_000;
+    const snapshot = waitMs === 0;
+    const terminalSnapshots = new Map();
+    const read = (target) => {
+        const state = target.read();
+        const executionId = target.executionId;
+        const observation = executionId === undefined
+            ? undefined
+            : (observations.capture(target.agentId, executionId) ??
+                terminalSnapshots.get(JSON.stringify([target.agentId, target.runId, executionId])));
+        const terminal = ['SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED'].includes(state.status);
+        const message = observation?.updates.some((update) => update.kind === 'message') === true;
+        return {
+            state,
+            executionId,
+            observation,
+            terminal,
+            ready: terminal || (input.waitFor === 'message' && message)
+        };
+    };
+    const satisfied = () => {
+        const values = targets.map(read);
+        return input.mode === 'all'
+            ? values.every((value) => value.ready)
+            : values.some((value) => value.ready);
+    };
+    let outcome = 'snapshot';
+    if (!snapshot) {
+        outcome = await waitForToolCondition({
+            ready: satisfied,
+            subscribe: (listener) => observations.subscribe((terminal) => {
+                if (terminal &&
+                    targets.some((target) => target.agentId === terminal.childId &&
+                        target.runId === terminal.runId &&
+                        target.executionId === terminal.executionId))
+                    terminalSnapshots.set(JSON.stringify([terminal.childId, terminal.runId, terminal.executionId]), terminal);
+                listener();
+            }),
+            waitMs: Math.max(waitMs, 10_000),
+            signal: input.signal,
+            interrupt: input.interrupt
+        });
+        input.signal?.throwIfAborted();
+    }
+    const values = targets.map((target) => ({ target, ...read(target) }));
+    const pendingAgentIds = values
+        .filter((value) => !value.ready)
+        .map((value) => value.target.agentId);
+    const ordered = input.single
+        ? [...values].sort((a, b) => (a.observation?.firstRevision ?? Infinity) - (b.observation?.firstRevision ?? Infinity))
+        : values;
+    const selected = input.single
+        ? [
+            ordered.find((value) => value.ready) ??
+                ordered.find((value) => (value.observation?.updates.length ?? 0) > 0) ??
+                values[0]
+        ]
+        : values;
+    const agents = selected.map(({ target, executionId, state, observation, terminal, ready }) => {
+        const waitOutcome = snapshot
+            ? 'snapshot'
+            : terminal
+                ? 'completion'
+                : ready
+                    ? 'message'
+                    : outcome === 'timeout'
+                        ? 'timeout'
+                        : outcome === 'interrupted'
+                            ? 'interrupted'
+                            : 'snapshot';
+        const include = !snapshot && (ready || outcome === 'timeout' || outcome === 'interrupted');
+        const projection = include && terminal ? observation?.result : undefined;
+        const updates = include && projection?.summary && !projection.summaryTruncated
+            ? observation?.updates.filter((update) => !update.final)
+            : include
+                ? observation?.updates
+                : undefined;
+        if (include)
+            observation?.acknowledge();
+        return {
+            agentId: target.agentId,
+            runId: target.runId,
+            ...(executionId === undefined ? {} : { executionId }),
+            status: state.status,
+            waitOutcome,
+            ...projection,
+            ...(updates?.length ? { updates } : {})
+        };
+    });
+    const ready = values.filter((value) => value.ready);
+    const groupOutcome = outcome === 'ready'
+        ? ready.every((value) => value.terminal)
+            ? 'completion'
+            : 'message'
+        : outcome;
+    if (input.single)
+        return {
+            ...agents[0],
+            waitFor: input.waitFor ?? 'completion',
+            ...(groupOutcome === 'interrupted' ? { waitOutcome: 'interrupted' } : {}),
+            ...(groupOutcome === 'interrupted' ? { reason: 'steer' } : {})
+        };
+    return {
+        mode: input.mode ?? 'any',
+        waitFor: input.waitFor ?? 'completion',
+        waitOutcome: snapshot ? 'snapshot' : groupOutcome,
+        ...(groupOutcome === 'interrupted' ? { reason: 'steer' } : {}),
+        agents,
+        pendingAgentIds
+    };
+}

package/dist/service/composer-message-input.js

@@ -3,10 +3,17 @@ import { relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { SkillDirectoryService } from './skill-directory-service.js';
 /** Keep the admitted source snapshot beside message and Goal markup. */
-export function withSessionMessageOrigin(input, origin) {
+export function withSessionMessageOrigin(input, origin, parentSessionId) {
     if (origin === undefined)
         return input;
-    const tag = serializeComposerTag('mar_session_origin', sessionMessageOriginSchema.parse(origin));
+    const parsed = sessionMessageOriginSchema.parse(origin);
+    const snapshot = parsed.sessionId === undefined
+        ? parsed
+        : {
+            ...parsed,
+            relation: parsed.sessionId === parentSessionId ? 'parent' : 'other'
+        };
+    const tag = serializeComposerTag('mar_session_origin', snapshot);
     const parts = parseComposerTags(input);
     const first = parts[0];
     const goal = first?.kind === 'mar_goal_start' || first?.kind === 'mar_goal_continue' ? first : undefined;

package/dist/service/continuous-run-coordinator.js

@@ -672,8 +672,30 @@ export class ContinuousRunCoordinator {
             const goalMcp = pending.goal === undefined ? undefined : await this.options.goalMcp?.(executionInput);
             const scheduleMcp = await this.options.scheduleMcp?.(executionInput);
             const notificationMcp = await this.options.notificationMcp?.(executionInput);
+            const { MAR_CTL_USER_TOKEN: parentToken, ...runnerEnvironment } = pending.secretEnvironment;
+            let executionToken;
+            if (parentToken !== undefined) {
+                const execution = this.options.runtime.executionSnapshot(executionId);
+                if (!this.options.mintMarctlExecutionCredential ||
+                    !execution ||
+                    execution.sessionId !== pending.sessionId ||
+                    execution.runId !== active.id ||
+                    !Number.isSafeInteger(active.initiatedByUserId))
+                    throw new Error('MARCTL_EXECUTION_AUTHORIZATION_INVALID');
+                executionToken = await this.options.mintMarctlExecutionCredential({
+                    parentToken,
+                    workspaceId: pending.workspaceId,
+                    sessionId: pending.sessionId,
+                    executionId,
+                    userId: active.initiatedByUserId
+                });
+            }
             if (this.suspended || this.options.stopped() || !this.dispatchedExecutions.has(executionId))
                 return;
+            if (executionToken !== undefined &&
+                (this.options.runtime.activeSessionRun(pending.sessionId)?.id !== active.id ||
+                    this.options.runtime.currentExecutionId(active.id) !== executionId))
+                throw new Error('MARCTL_EXECUTION_AUTHORIZATION_INVALID');
             if (!this.goalCurrent(pending)) {
                 this.dispatchedExecutions.delete(executionId);
                 this.rejectStaleGoal(executionId);
@@ -701,7 +723,8 @@ export class ContinuousRunCoordinator {
                 collaborationMode: pending.collaborationMode,
                 ...(pending.serviceTier === undefined ? {} : { serviceTier: pending.serviceTier }),
                 secretEnvironment: {
-                    ...pending.secretEnvironment,
+                    ...runnerEnvironment,
+                    ...(executionToken === undefined ? {} : { MAR_CTL_USER_TOKEN: executionToken }),
                     MAR_CTL_NODE_ID: this.options.runtime.getAgentSession(pending.sessionId)?.nodeId ?? '',
                     MAR_CTL_WORKSPACE_ID: pending.workspaceId,
                     MAR_CTL_SESSION_ID: this.options.runtime.getAgentSession(pending.sessionId)?.id ?? pending.sessionId,

package/dist/service/goal-continuation-coordinator.js

@@ -179,7 +179,7 @@ export class GoalContinuationCoordinator {
             goalAccessChanged: prepared.changed
         };
     }
-    async start({ session, objective, initiatedByUserId, suppressNotifications, secretEnvironment, personalInstructions, executionContext, usageGrant }) {
+    async start({ session, objective, initiatedByUserId, suppressNotifications, secretEnvironment, personalInstructions, executionContext, usageGrant, preserveActiveRun, messageIntent, messageContent, clientMessageId, messageOrigin, attachments, attachmentIds }) {
         this.invalidateGoalContinuation(session.id);
         const prepared = this.prepareGoalSession(session);
         const goalSession = prepared.session;
@@ -198,8 +198,18 @@ export class GoalContinuationCoordinator {
                 kind: 'start',
                 content: this.options.goals.prompt(attempt.sessionId, 'start'),
                 objective: goal.objective,
-                deliveryIntent: replacing ? 'REPLACE_CURRENT' : 'SEND',
+                deliveryIntent: messageIntent ??
+                    (preserveActiveRun && activeRun !== undefined
+                        ? 'QUEUE'
+                        : replacing
+                            ? 'REPLACE_CURRENT'
+                            : 'SEND'),
                 goal: goalRef,
+                ...(messageContent === undefined ? {} : { messageContent }),
+                ...(clientMessageId === undefined ? {} : { clientMessageId }),
+                ...(messageOrigin === undefined ? {} : { messageOrigin }),
+                ...(attachments === undefined ? {} : { attachments }),
+                ...(attachmentIds === undefined ? {} : { attachmentIds }),
                 ...(suppressNotifications === true ? { suppressNotifications: true } : {}),
                 ...(usageGrant === undefined ? {} : { usageGrant }),
                 ...(initiatedByUserId === undefined ? {} : { initiatedByUserId }),

package/dist/service/marctl-caller.js

@@ -0,0 +1,80 @@
+import { isPlainRecord } from '../util/records.js';
+import { assertSessionControlOwner } from './run-ownership-policy.js';
+const executionReadOperations = new Set([
+    'agent.network',
+    'session.cli.context',
+    'session.get',
+    'session.list',
+    'session.graph',
+    'session.runs',
+    'session.goal.get',
+    'session.turns.list',
+    'workspace.queue.get',
+    'session.schedule.list',
+    'session.schedule.get',
+    'runner.profiles.list',
+    'session.watch',
+    'session.unwatch'
+]);
+const executionManagementOperations = new Set([
+    'session.metadata.update',
+    'session.config.update',
+    'session.schedule.agent.save'
+]);
+/** Prevent execution credentials from reaching legacy writes outside their Session tree. */
+export async function authorizeMarctlExecutionOperation(input) {
+    if (!isPlainRecord(input.caller))
+        throw new Error('MARCTL_EXECUTION_CREDENTIAL_INVALID');
+    if (input.caller.type === 'terminal')
+        return;
+    if (input.caller.type !== 'execution' || typeof input.caller.sessionId !== 'string')
+        throw new Error('MARCTL_EXECUTION_CREDENTIAL_INVALID');
+    if (executionReadOperations.has(input.operation))
+        return;
+    if (!executionManagementOperations.has(input.operation) ||
+        !isPlainRecord(input.data) ||
+        typeof input.data.sessionId !== 'string' ||
+        typeof input.data.workspaceId !== 'string')
+        throw new Error('MARCTL_AGENT_NETWORK_REQUIRED');
+    const source = input.runtime.getAgentSession(input.caller.sessionId);
+    const target = input.runtime.getAgentSession(input.data.sessionId) ??
+        (await input.resolveSession(input.data.sessionId));
+    if (!source ||
+        !target ||
+        source.workspaceId !== input.data.workspaceId ||
+        target.workspaceId !== source.workspaceId ||
+        (target.id !== source.id && target.parentSessionId !== source.id))
+        throw new Error('AGENT_TARGET_NOT_AUTHORIZED');
+    assertSessionControlOwner(input.runtime, target.id, input.userId);
+}
+/** Resolve only Server-verified credentials against the current Node Execution owner. */
+export function resolveMarctlCaller(input) {
+    if (!isPlainRecord(input.caller))
+        return undefined;
+    if (input.caller.type === 'terminal')
+        return { type: 'terminal' };
+    if (input.caller.type !== 'execution' ||
+        typeof input.caller.sessionId !== 'string' ||
+        typeof input.caller.executionId !== 'string' ||
+        !isPlainRecord(input.data) ||
+        typeof input.data.workspaceId !== 'string')
+        return undefined;
+    const session = input.runtime.getAgentSession(input.caller.sessionId);
+    const execution = input.runtime.executionSnapshot(input.caller.executionId);
+    const prepared = input.coordinator.pending(input.caller.executionId);
+    const run = execution && input.runtime.getRun(execution.runId);
+    if (!session ||
+        !execution ||
+        !prepared ||
+        !run ||
+        session.workspaceId !== input.data.workspaceId ||
+        execution.sessionId !== session.id ||
+        prepared.sessionId !== session.id ||
+        prepared.workspaceId !== session.workspaceId ||
+        run.initiatedByUserId !== input.userId ||
+        !['STARTING', 'RUNNING'].includes(execution.status) ||
+        input.runtime.activeSessionRun(session.id)?.id !== run.id ||
+        input.runtime.currentExecutionId(run.id) !== execution.executionId)
+        return undefined;
+    return { type: 'execution', sessionId: session.id, executionId: execution.executionId };
+}