@myagentroam/node 0.11.51 → 0.11.52

package/dist/connector.js

@@ -194,10 +194,9 @@ export class NodeConnector {
             await this.sessionMessageService.drain();
         },
         closeResume: () => this.externalSessionResumeService.close(),
-        capture: async () => {
+        capture: () => {
             if (!this.config?.nodeId)
                 return;
-            await this.marAgentRuntimeModels.waitForPendingCredentials();
             return this.restartHandoff.capture();
         },
         dispose: () => this.disposeRuntime(),
@@ -1102,7 +1101,6 @@ export class NodeConnector {
             goals: this.goalRuntime,
             runs: this.runWorkbenchService,
             observations: this.agentNetworkObservations,
-            history: async (input) => this.sessionQueryService.operations()['session.turns.list'](input),
             ensureObservations: (actor) => {
                 const existing = this.agentNetworkObservations.get(actor.observationId ?? actor.sessionId);
                 if (existing)
@@ -1133,7 +1131,36 @@ export class NodeConnector {
             messages: this.sessionMessageService,
             resolve: (id) => this.externalSessionResumeService.resolveForMessage(id),
             inputState,
-            withGrant: (context, work) => this.modelUsage.withGrant(context.usageGrant, work),
+            withExecution: async (session, checkpoint, work) => {
+                if (checkpoint.initiatedByUserId === undefined)
+                    throw new Error('RESTART_EXECUTION_USER_UNAVAILABLE');
+                const context = await this.scheduledRunAuthorization.prepare({
+                    userId: checkpoint.initiatedByUserId,
+                    sessionId: session.id,
+                    workspaceId: session.workspaceId,
+                    runner: session.runner,
+                    modelId: checkpoint.configuration === undefined
+                        ? session.modelId
+                        : checkpoint.configuration.modelId
+                });
+                return this.gitOperationService.execute('session.message', {
+                    sessionId: session.id,
+                    workspaceId: session.workspaceId,
+                    __requestUserId: checkpoint.initiatedByUserId,
+                    ...context
+                }, async (data) => this.modelUsage.withGrant(context.usageGrant, () => work({
+                    ...checkpoint,
+                    secretEnvironment: data
+                        .secretEnvironment,
+                    executionContext: this.runners
+                        .require(session.runner)
+                        .prepareExecutionContext(context),
+                    ...(typeof context.personalInstructions === 'string'
+                        ? { personalInstructions: context.personalInstructions }
+                        : {}),
+                    ...(context.usageGrant === undefined ? {} : { usageGrant: context.usageGrant })
+                })));
+            },
             publishGoal: (session, goal) => this.goalCoordinator.publishGoalState(session, goal),
             goalReference: (sessionId) => this.goalCoordinator.reference(sessionId),
             publishQueue: (session) => this.continuousRunCoordinator.publish(session.id)
@@ -1146,7 +1173,6 @@ export class NodeConnector {
             coordinator: this.continuousRunCoordinator,
             goals: this.goalRuntime,
             goalExecution: (id) => this.goalCoordinator.restartExecution(id),
-            executionContext: (id, context, modelId) => this.marAgentRunController.restartExecutionContext(id, context, modelId === undefined ? this.runtime.getAgentSession(id)?.modelId : modelId),
             commandActive: (id, command) => this.commandStates.get(id, command)?.active === true,
             inputState,
             restore: (entry, id) => restorer.restore(entry, id),
@@ -1486,6 +1512,9 @@ export class NodeConnector {
                     modelId: configuredSession.modelId
                 });
                 return {
+                    ...(context.gitConfiguration === undefined
+                        ? {}
+                        : { gitConfiguration: context.gitConfiguration }),
                     secretEnvironment: context.secretEnvironment,
                     personalInstructions: context.personalInstructions,
                     usageGrant: context.usageGrant,
@@ -1493,16 +1522,25 @@ export class NodeConnector {
                 };
             },
             submit: async (task, occurrenceId, context) => {
-                const result = (await this.sessionMessageService.submitScheduled({
+                const result = (await this.gitOperationService.execute('session.message', {
+                    sessionId: task.sessionId,
+                    workspaceId: task.workspaceId,
+                    __requestUserId: task.ownerUserId,
+                    secretEnvironment: context.secretEnvironment,
+                    ...(context.gitConfiguration === undefined
+                        ? {}
+                        : { gitConfiguration: context.gitConfiguration })
+                }, async (data) => this.sessionMessageService.submitScheduled({
                     sessionId: task.sessionId,
                     occurrenceId,
                     objective: task.objective,
                     initiatedByUserId: task.ownerUserId,
-                    secretEnvironment: context.secretEnvironment,
+                    secretEnvironment: data
+                        .secretEnvironment,
                     personalInstructions: context.personalInstructions,
                     ...(context.usageGrant === undefined ? {} : { usageGrant: context.usageGrant }),
                     executionContext: context.executionContext
-                }));
+                })));
                 return { runId: result.run.id };
             },
             sessionTitle: (sessionId) => {

package/dist/marctl-guidance.js

@@ -5,11 +5,13 @@ export function hasMarctlContext(environment) {
         !!environment['MAR_CTL_NODE_ID'] &&
         !!environment['MAR_CTL_WORKSPACE_ID']);
 }
-export const marctlManagementDescription = 'Use marctl to manage MAR Agent session settings (model, effort, title, persistent prompts, and schedules), discover authorized MAR Nodes, and execute commands or transfer files on those Nodes. Use native agent_* tools for other Agent lifecycle and collaboration operations.';
+export const marctlManagementDescription = 'Use marctl to manage MAR Agent session settings (model, effort, title, persistent prompts, and schedules), read paginated public history, discover authorized MAR Nodes, and execute commands or transfer files on those Nodes. Use native agent_* tools for other Agent lifecycle and collaboration operations.';
+const marctlHistory = 'Use marctl agents history <id> [--cursor <cursor>] [--limit <1..100>] --json to read public history on demand; agents view returns state, Goal and recent activity only.';
 const marctlSafety = 'If a request result is unknown, inspect history before retrying. Session IDs and parent relationships do not grant authorization.';
 export const marctlManagementInstructions = [
     '## MAR Workspace management',
     'Use native agent_* tools for Agent discovery, creation, communication, observation, waiting and stopping. Do not switch to marctl when a native operation fails.',
+    marctlHistory,
     'Use marctl agents config <id> --model-id <id> --effort <effort> to change future model settings; agents rename <id> --title <title> changes a title.',
     'Use agents prompt get/set/clear for persistent instructions; set accepts -m or --message-file. Use agents schedule list/get/create/update for scheduled tasks; update requires --expected-revision.',
     'marctl nodes lists authorized Nodes; marctl ssh executes remote commands and marctl scp transfers files. Use marctl help agents, nodes, ssh or scp for options.',
@@ -20,12 +22,13 @@ export const marctlInstructions = [
     '## MAR Workspace CLI',
     'Run marctl from the shell. Commands use the authenticated Node and Workspace; marctl help agents, nodes, ssh or scp shows options.',
     'Use agents start --title <title> -m <text> [--runner <runner>] [--model-id <id>] [--effort <effort>] [--goal <objective>]. An Agent must supply a nonblank title; a manual terminal may omit it. The default Runner is the current Session Runner; a terminal without a current Session must specify --runner or an explicit --parent. Start returns without waiting for completion.',
-    'Use agents send <id> -m <text> [--steer|--queue], agents wait [<id>] [--wait-for message|completion] [--timeout <duration>], agents stop <id> --execution <execution-id>, agents list [--scope tree|active], and agents view <id> [--history]. --timeout 0ms takes a snapshot. Stop clears the target Session Goal.',
+    'Use agents send <id> -m <text> [--steer|--queue], agents wait [<id>] [--wait-for message|completion] [--timeout <duration>], agents stop <id>, agents list [--scope tree|active], and agents view <id>. --timeout 0ms takes a snapshot; positive durations are used as requested. Stop targets the current Session execution and clears its Goal.',
+    marctlHistory,
     'While children run, prefer advancing meaningful, non-overlapping task work rather than duplicating delegated work. Waiting is generally useful once no meaningful local task work remains and a required result is needed to unblock or finish the task.',
     'Prefer agents send <id> --steer -m <text> for timely communication or course correction. --queue is best reserved for deferred input explicitly requested by the user or recipient: it is consumed after current work and earlier queued inputs finish, and with an active Goal it is not consumed until that Goal exits. Acceptance is not a guarantee of immediate processing.',
     'An accepted message normally needs no separate acknowledgment. Requests for receipt-only replies and immediate agents view checks solely to confirm receipt are usually unnecessary.',
     'Send can update a Goal alone with --goal <objective> or --clear-goal; omitted Goal leaves it unchanged. Decide an authorized Agent approval with send <id> --approval <approval-id> --decision approve|reject.',
-    'List accepts only --scope tree|active, optional --query <title-fragment> and --limit <1..100> (default 100). With a current Session it defaults to the containing collaboration tree, including idle Sessions; without one it defaults to active Workspace Sessions (running or sleeping), and explicit tree is rejected. Returns currentAgentId (null without a Session), flat sessions with id, parentSessionId, title, runner and status, and truncated; no cursor or pagination. Reuse known IDs directly.',
+    'List accepts only --scope tree|active, optional --query <title-fragment> and --limit <1..100> (default 10). With a current Session it defaults to the containing collaboration tree, including idle Sessions; without one it defaults to active Workspace Sessions (running or sleeping), and explicit tree is rejected. Active Sessions come first, then recent activity descending. Returns currentAgentId (null without a Session), flat sessions with id, parentSessionId, title and status, and truncated; no cursor or pagination. Reuse known IDs directly.',
     'Only direct-child updates are collected automatically. Sending to a non-child never subscribes; an explicit wait observes it only for that call.',
     'Use agents config, rename, prompt and schedule for management. marctl nodes, ssh and scp use authorized Nodes.',
     marctlSafety

package/dist/runner/mar-agent/agent-network-extension.js

@@ -77,9 +77,9 @@ const tools = [
     },
     {
         action: 'stop',
-        description: 'Stop the specified Agent Execution and clear its Goal.',
-        properties: { agentId: text, executionId: text },
-        required: ['agentId', 'executionId']
+        description: 'Stop the Agent’s current execution and clear its Goal.',
+        properties: { agentId: text },
+        required: ['agentId']
     },
     {
         action: 'list',
@@ -95,17 +95,14 @@ const tools = [
                 maxLength: 160,
                 description: 'Optional case-insensitive title fragment within the scope.'
             },
-            limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Defaults to 100.' }
+            limit: { type: 'integer', minimum: 1, maximum: 100, description: 'Defaults to 10.' }
         }
     },
     {
         action: 'view',
-        description: "View an Agent's state, Goal and public history.",
+        description: "View an Agent's state, Goal and recent activity.",
         properties: {
-            agentId: text,
-            includeHistory: { type: 'boolean' },
-            limit: { type: 'integer', minimum: 1, maximum: 100 },
-            cursor: text
+            agentId: text
         },
         required: ['agentId']
     }

package/dist/runner/mar-agent/managed-run-controller.js

@@ -15,7 +15,6 @@ import { MarAgentConversationNormalizer, normalizeMarAgentUsage } from './conver
 import { parseRunnerImageAttachments } from '../../session/attachments.js';
 import { runnerErrorProjection } from '../runner-error.js';
 import { MarAgentRuntimeModelFactory, sdkModelConfigurations, closeImageCredentialProviders } from './runtime-model-factory.js';
-import { snapshotRuntimeModel } from './runtime-model-factory.js';
 import { createImageGenerationExtensions } from './image-generation-extensions.js';
 import { createWebToolsExtensions } from './web-tools-extensions.js';
 import { combineExecutionExtensions } from './execution-extensions.js';
@@ -95,43 +94,6 @@ export class MarAgentManagedRunController {
     releaseSession(sessionId) {
         return this.#runtimes.releaseSession(sessionId);
     }
-    restartExecutionContext(sessionId, context, selectedModelId) {
-        const runtime = this.#runtimes.findRuntime(sessionId);
-        const input = marAgentEnvelopeInput(context);
-        if (runtime === undefined || typeof input?.runtimeScopeId !== 'string')
-            return context;
-        const scope = input.runtimeScopeId;
-        const snapshots = new Map(runtime.models.flatMap((model) => {
-            const snapshot = snapshotRuntimeModel(model, scope);
-            return snapshot === undefined ? [] : [[model.id, snapshot]];
-        }));
-        if (snapshots.size === 0)
-            return context;
-        const refresh = (value) => {
-            if (value === null || typeof value !== 'object' || !('id' in value))
-                return value;
-            return typeof value.id === 'string' ? (snapshots.get(value.id) ?? value) : value;
-        };
-        const models = Array.isArray(input.models) ? input.models.map(refresh) : input.models;
-        const selected = Array.isArray(models)
-            ? models.find((model) => model !== null &&
-                typeof model === 'object' &&
-                'id' in model &&
-                model.id === selectedModelId)
-            : undefined;
-        const compact = input.compact;
-        return {
-            runner: 'mar-agent',
-            runnerInput: {
-                ...input,
-                model: selected ?? refresh(input.model),
-                models,
-                compact: compact !== null && typeof compact === 'object' && 'model' in compact
-                    ? { ...compact, model: refresh(compact.model) }
-                    : compact
-            }
-        };
-    }
     async executeCommand(session, command, input, context) {
         if (command.id === 'plan') {
             const current = this.host.commandState(session.id, 'plan');

package/dist/runner/mar-agent/runtime-model-factory.js

@@ -21,42 +21,14 @@ class PendingCredentialResolution {
         this.initialReason = initialReason;
     }
 }
-const restartConfigurations = new WeakMap();
-export function snapshotRuntimeModel(model, scope) {
-    const state = restartConfigurations.get(model);
-    if (state === undefined || state.scope !== scope)
-        return;
-    const configuration = structuredClone(state.configuration);
-    for (const credential of [configuration.credential, configuration.imageGeneration?.credential]) {
-        if (credential?.type !== 'RUNTIME_TICKET')
-            continue;
-        const key = `${credential.credentialId}\0${credential.ticket.runtimeScopeId}\0${credential.ticket.purpose ?? 'MODEL'}`;
-        const current = state.tickets.get(key);
-        if (current === undefined || current.released)
-            return;
-        credential.ticket = structuredClone(current.ticket);
-    }
-    return configuration;
-}
 const CREDENTIAL_REFRESH_WINDOW_MS = 60_000;
 const CREDENTIAL_REFRESH_RETRY_MS = 30_000;
 export class MarAgentRuntimeModelFactory {
-    now;
     control;
-    pendingCredentials = new Set();
+    now;
     constructor(control, now = Date.now) {
+        this.control = control;
         this.now = now;
-        this.control = {
-            resolve: (...args) => {
-                const pending = control.resolve(...args);
-                this.pendingCredentials.add(pending);
-                void pending.then(() => this.pendingCredentials.delete(pending), () => this.pendingCredentials.delete(pending));
-                return pending;
-            }
-        };
-    }
-    async waitForPendingCredentials() {
-        await Promise.allSettled([...this.pendingCredentials]);
     }
     create(configurations, context) {
         const tickets = new Map();
@@ -64,14 +36,6 @@ export class MarAgentRuntimeModelFactory {
         try {
             return configurations.map((raw) => {
                 const configuration = marAgentRuntimeModelConfigurationSchema.parse(raw);
-                const remember = (model) => {
-                    restartConfigurations.set(model, {
-                        configuration,
-                        scope: context.runtimeScopeId,
-                        tickets
-                    });
-                    return model;
-                };
                 const imageGeneration = configuration.imageGeneration === undefined ||
                     configuration.imageGeneration.credential === undefined
                     ? undefined
@@ -125,10 +89,10 @@ export class MarAgentRuntimeModelFactory {
                 };
                 const { credential } = configuration;
                 if (credential.type === 'INLINE_API_KEY')
-                    return remember({
+                    return {
                         ...model,
                         apiKey: new SecretValue(credential.value)
-                    });
+                    };
                 if (credential?.type !== 'RUNTIME_TICKET')
                     throw new AgentError('MAR_AGENT_RUNTIME_MODEL_CREDENTIAL_INVALID', 'The runtime model credential is invalid.');
                 if (context.runtimeScopeId === undefined ||
@@ -136,7 +100,7 @@ export class MarAgentRuntimeModelFactory {
                     !credential.ticket.allowedModelIds.includes(configuration.id))
                     throw new AgentError('MAR_AGENT_RUNTIME_CREDENTIAL_SCOPE_INVALID', 'The runtime credential does not authorize this execution or model.');
                 const provider = runtimeProvider(credential, configuration.id, context, tickets, providers, this.control, this.now);
-                return remember({
+                return {
                     ...model,
                     ...(configuration.imageGeneration !== undefined &&
                         configuration.imageGeneration.credential === undefined
@@ -153,7 +117,7 @@ export class MarAgentRuntimeModelFactory {
                         }
                         : {}),
                     credentialProvider: provider
-                });
+                };
             });
         }
         catch (error) {

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

@@ -1,4 +1,5 @@
 import { auditConversationReceiptSchema, marAgentRuntimeModelConfigurationSchema } from '@myagentroam/protocol';
+import { AgentError } from '@myagentroam/agent';
 import { resolvedPersonalInstructions } from '../runner/personal-instructions.js';
 import { AgentNetworkService } from './agent-network-service.js';
 import { isPlainRecord } from '../util/records.js';
@@ -12,17 +13,17 @@ export function actorForAuthenticatedTerminal(actor, workspaceId) {
     terminalCalls.set(authenticated, { workspaceId });
     return authenticated;
 }
-import { marctlSessionDetail } from './session-recent-activity.js';
+import { agentNetworkSessionView } from './session-recent-activity.js';
 import { listAgentNetworkSessions } from './agent-network-list.js';
 /** Bind the collaboration use case to the existing Session, Run and Goal owners. */
 export function createNodeAgentNetwork(options) {
     async function actorSession(actor) {
         if (!Number.isSafeInteger(actor.requestUserId) || (actor.requestUserId ?? 0) <= 0)
-            throw new Error('USER_AUTHORIZATION_REQUIRED');
+            throw new AgentError('USER_AUTHORIZATION_REQUIRED', 'An authenticated user is required for agent operations.');
         const parent = options.runtime.getAgentSession(actor.sessionId) ??
             (await options.projection.resolve(actor.sessionId, true));
         if (!parent)
-            throw new Error('SESSION_NOT_FOUND');
+            throw new AgentError('SESSION_NOT_FOUND', 'The calling agent session was not found.');
         if (actor.runId !== undefined) {
             const run = options.runtime.getRun(actor.runId);
             if (!run ||
@@ -31,7 +32,7 @@ export function createNodeAgentNetwork(options) {
                 (actor.executionId !== undefined &&
                     options.runtime.currentExecutionId(run.id) !== actor.executionId) ||
                 run.initiatedByUserId !== actor.requestUserId)
-                throw new Error('AGENT_ACTOR_INVALID');
+                throw new AgentError('AGENT_ACTOR_INVALID', 'The calling agent execution identity is invalid.');
         }
         return parent;
     }
@@ -41,7 +42,7 @@ export function createNodeAgentNetwork(options) {
         const workspaceId = terminal?.workspaceId ?? parent?.workspaceId;
         const session = options.runtime.getAgentSession(id) ?? (await options.projection.resolve(id, true));
         if (!session || session.workspaceId !== workspaceId)
-            throw new Error('SESSION_NOT_FOUND');
+            throw new AgentError('SESSION_NOT_FOUND', 'The target agent session was not found in this Workspace.');
         return session;
     }
     function ancestorDistance(source, targetId) {
@@ -138,7 +139,7 @@ export function createNodeAgentNetwork(options) {
         },
         children: async (actor) => {
             if (terminalCalls.has(actor))
-                throw new Error('AGENT_TARGET_REQUIRED');
+                throw new AgentError('AGENT_TARGET_REQUIRED', 'A terminal caller must specify an agent to wait for.');
             const parent = await actorSession(actor);
             const records = options.database()?.listChildSessionRecords(parent.workspaceId, parent.id) ?? [];
             const resolved = await Promise.all(records.map((record) => options.runtime.getAgentSession(record.id) ??
@@ -179,9 +180,18 @@ export function createNodeAgentNetwork(options) {
                 },
                 read: () => {
                     const id = currentId();
-                    return id === undefined
-                        ? (options.runtime.getRun(runId) ?? { status: 'UNKNOWN' })
-                        : (options.runtime.executionSnapshot(id) ?? { status: 'UNKNOWN' });
+                    const state = id === undefined
+                        ? options.runtime.getRun(runId)
+                        : options.runtime.executionSnapshot(id);
+                    if (!state)
+                        throw new AgentError('AGENT_EXECUTION_NOT_FOUND', 'The execution selected for this wait is no longer available.', {
+                            details: {
+                                agentId: session.id,
+                                runId,
+                                ...(id === undefined ? {} : { executionId: id })
+                            }
+                        });
+                    return state;
                 }
             };
         },
@@ -329,11 +339,16 @@ export function createNodeAgentNetwork(options) {
                 throw error;
             }
         },
-        stop: (actor, session, executionId) => publicReceipt(options.runs.stopAgentExecution({
-            sessionId: session.id,
-            executionId,
-            ...(actor.requestUserId === undefined ? {} : { requestUserId: actor.requestUserId })
-        })),
+        stop: (actor, session) => {
+            const result = options.runs.stopAgentSession({
+                sessionId: session.id,
+                ...(actor.requestUserId === undefined ? {} : { requestUserId: actor.requestUserId })
+            });
+            return {
+                ...publicReceipt(result),
+                ...(isPlainRecord(result) && result.status === 'IDLE' ? { status: 'IDLE' } : {})
+            };
+        },
         goal: (sessionId) => publicGoal(options.goals.get(sessionId)),
         list: async (actor, input) => {
             const terminal = terminalCalls.get(actor);
@@ -354,19 +369,8 @@ export function createNodeAgentNetwork(options) {
             assertSessionControlOwner(options.runtime, session.id, actor.requestUserId);
             await onResolved?.([session]);
             return {
-                session: marctlSessionDetail(options.runtime, session, options.runtime.sessionQueue(session.id).itemIds.length),
-                goal: publicGoal(options.goals.get(session.id)) ?? null,
-                ...(input.includeHistory
-                    ? {
-                        history: await options.history({
-                            sessionId: session.id,
-                            workspaceId: session.workspaceId,
-                            registeredOnly: true,
-                            limit: input.limit,
-                            cursor: input.cursor
-                        })
-                    }
-                    : {})
+                session: agentNetworkSessionView(options.runtime, session, options.runtime.sessionQueue(session.id).itemIds.length),
+                goal: publicGoal(options.goals.get(session.id)) ?? null
             };
         }
     });

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

@@ -1,3 +1,4 @@
+import { AgentError } from '@myagentroam/agent';
 import { actorForAuthenticatedTerminal } from './agent-network-bindings.js';
 import { isPlainRecord } from '../util/records.js';
 import { randomUUID } from 'node:crypto';
@@ -27,7 +28,7 @@ export function executionAgentActor(input) {
         input.runtime.currentExecutionId(run.id) !== executionId ||
         !['STARTING', 'RUNNING'].includes(execution.status) ||
         !Number.isSafeInteger(run.initiatedByUserId))
-        throw new Error('AGENT_ACTOR_NOT_ACTIVE');
+        throw new AgentError('AGENT_ACTOR_NOT_ACTIVE', 'The calling agent execution is no longer active.');
     const captured = prepared.executionContext.runner === 'mar-agent' &&
         isPlainRecord(prepared.executionContext.runnerInput)
         ? prepared.executionContext.runnerInput
@@ -57,7 +58,7 @@ export async function invokeAgentNetwork(service, actor, action, payload, contex
         case 'start':
             if ((context || actor.executionId) &&
                 (typeof payload.title !== 'string' || !payload.title.trim()))
-                throw new Error('AGENT_START_INVALID');
+                throw new AgentError('AGENT_START_INVALID', 'A nonblank title is required to start an agent.');
             if (!context &&
                 !actor.executionId &&
                 typeof payload.title === 'string' &&

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

@@ -52,20 +52,31 @@ export async function listAgentNetworkSessions(source, input, options) {
         sessions = (await Promise.all(ids.map((id) => known.get(id) ?? options.projection.resolve(id, true)))).filter((session) => session !== undefined && session.workspaceId === options.workspaceId);
     }
     else {
-        sessions = [...known.values()].sort((left, right) => right.lastActivityAt - left.lastActivityAt || left.id.localeCompare(right.id));
+        sessions = [...known.values()];
     }
     const query = input.query?.trim().normalize('NFKC').toLocaleLowerCase() ?? '';
     const matches = sessions
         .map((session) => {
-        const { id, title, runner, status } = marctlSessionSummary(options.runtime, session);
-        return { id, parentSessionId: session.parentSessionId ?? null, title, runner, status };
+        const { id, title, status } = marctlSessionSummary(options.runtime, session);
+        return {
+            id,
+            parentSessionId: session.parentSessionId ?? null,
+            title,
+            status,
+            lastActivityAt: session.lastActivityAt
+        };
     })
         .filter((session) => (scope !== 'active' || session.status !== 'IDLE') &&
-        (!query || session.title.normalize('NFKC').toLocaleLowerCase().includes(query)));
-    const limit = input.limit ?? 100;
+        (!query || session.title.normalize('NFKC').toLocaleLowerCase().includes(query)))
+        .sort((left, right) => Number(right.status !== 'IDLE') - Number(left.status !== 'IDLE') ||
+        right.lastActivityAt - left.lastActivityAt ||
+        left.id.localeCompare(right.id));
+    const limit = input.limit ?? 10;
     return {
         currentAgentId: source?.id ?? null,
-        sessions: matches.slice(0, limit),
+        sessions: matches
+            .slice(0, limit)
+            .map(({ lastActivityAt: _lastActivityAt, ...session }) => session),
         truncated: matches.length > limit
     };
 }

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

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { AgentError } from '@myagentroam/agent';
 import { isPlainRecord } from '../util/records.js';
 import { safeErrorCode } from '../util/safe-error.js';
 import { parseAgentGoal } from './agent-network-goal.js';
@@ -12,7 +13,11 @@ export class AgentNetworkService {
     list(actor, input = {}) {
         return this.options.list(actor, input);
     }
-    view(actor, input, onResolved) {
+    async view(actor, input, onResolved) {
+        if (typeof input.agentId !== 'string' ||
+            !input.agentId.trim() ||
+            Object.keys(input).some((key) => key !== 'agentId'))
+            throw new AgentError('AGENT_VIEW_INVALID', 'Agent view accepts only a target agent ID.');
         return this.options.view(actor, input, onResolved);
     }
     async start(actor, input, signal, onResolved) {
@@ -30,7 +35,7 @@ export class AgentNetworkService {
             !validOptionalString(input.title) ||
             !validOptionalString(input.parentSessionId) ||
             !validOptionalString(input.clientMessageId))
-            throw new Error('AGENT_START_INVALID');
+            throw new AgentError('AGENT_START_INVALID', 'The agent start input is invalid.');
         const { goal: _goal, ...start } = input;
         const created = await this.options.start(actor, {
             ...start,
@@ -69,10 +74,10 @@ export class AgentNetworkService {
                     typeof input.approval.approvalId !== 'string' ||
                     !input.approval.approvalId ||
                     !['approve', 'reject'].includes(input.approval.decision))))
-            throw new Error('AGENT_SEND_INVALID');
+            throw new AgentError('AGENT_SEND_INVALID', 'The agent send input is invalid.');
         if (input.deliveryIntent !== undefined &&
             !['SEND', 'QUEUE', 'REPLACE_CURRENT'].includes(input.deliveryIntent))
-            throw new Error('AGENT_SEND_INVALID');
+            throw new AgentError('AGENT_SEND_INVALID', 'The message delivery intent is invalid.');
         const hasMessage = !!content.trim();
         const session = await this.options.target(actor, input.agentId);
         signal?.throwIfAborted();
@@ -185,20 +190,21 @@ export class AgentNetworkService {
     }
     async stop(actor, input, onResolved) {
         if (typeof input.agentId !== 'string' ||
-            !input.agentId ||
-            typeof input.executionId !== 'string' ||
-            !input.executionId)
-            throw new Error('AGENT_STOP_INVALID');
+            !input.agentId.trim() ||
+            Object.keys(input).some((key) => key !== 'agentId'))
+            throw new AgentError('AGENT_STOP_INVALID', 'Agent stop accepts only a target agent ID.');
         const session = await this.options.target(actor, input.agentId);
         await this.options.authorize(actor, session, 'stop');
         await onResolved?.([session]);
         const goalBefore = this.options.goal(session.id);
         try {
-            const result = this.options.stop(actor, session, input.executionId);
+            const result = this.options.stop(actor, session);
             return {
                 agentId: session.id,
-                executionId: input.executionId,
-                cancel: { status: 'accepted', result },
+                cancel: {
+                    status: isPlainRecord(result) && result.status === 'IDLE' ? 'idle' : 'accepted',
+                    result
+                },
                 goal: {
                     status: goalBefore != null && this.options.goal(session.id) == null ? 'cleared' : 'unchanged'
                 }
@@ -206,12 +212,11 @@ export class AgentNetworkService {
         }
         catch (error) {
             const code = safeErrorCode(error, 'AGENT_STOP_FAILED');
-            if (code === 'RUN_EXECUTION_STALE' || code === 'RUN_OWNED_BY_ANOTHER_USER')
+            if (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' }
             };
@@ -228,7 +233,7 @@ export class AgentNetworkService {
                     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');
+            throw new AgentError('AGENT_WAIT_INVALID', 'The agent wait target selection is invalid.');
         input.signal?.throwIfAborted();
         const ids = input.agentId === undefined ? input.agentIds : [input.agentId];
         let sessions;
@@ -242,8 +247,18 @@ export class AgentNetworkService {
             const target = this.options.freezeExecution(session);
             return target === undefined ? [] : [target];
         });
-        if (ids && targets.length !== sessions.length)
-            throw new Error('AGENT_EXECUTION_NOT_FOUND');
+        if (!targets.length || (ids && targets.length !== sessions.length)) {
+            if (!sessions.length)
+                throw new AgentError('AGENT_WAIT_NO_TARGETS', 'There are no child agents to wait for.');
+            const idle = ids
+                ? sessions.filter((session) => !targets.some((target) => target.agentId === session.id))
+                : [...sessions].sort((a, b) => b.createdAt - a.createdAt).slice(0, 1);
+            const agentIds = idle.map((session) => session.id);
+            const message = 'Agent is idle; there is no execution to wait for.';
+            throw new AgentError('AGENT_IDLE', input.agentId === undefined
+                ? `${message} Idle agent IDs: ${agentIds.join(', ')}.`
+                : message, { details: { agentIds, status: 'IDLE' } });
+        }
         if (!ids) {
             const active = targets.filter((target) => !['SUCCEEDED', 'FAILED', 'CANCELLED', 'INTERRUPTED'].includes(target.read().status));
             if (active.length) {
@@ -258,8 +273,6 @@ export class AgentNetworkService {
                 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));
         await onResolved?.(targets.map((target) => sessions.find((session) => session.id === target.agentId)));
         const directChildren = new Set();
@@ -270,7 +283,7 @@ export class AgentNetworkService {
             }
         const parent = this.options.observations.get(actor.observationId ?? actor.sessionId);
         if (directChildren.size && !parent)
-            throw new Error('AGENT_OBSERVATION_UNAVAILABLE');
+            throw new AgentError('AGENT_OBSERVATION_UNAVAILABLE', 'The agent observation channel is unavailable.');
         const otherTargets = targets.filter((target) => !directChildren.has(target.agentId));
         const temporary = otherTargets.length && input.waitMs !== 0
             ? this.options.observations.watchExecutions(otherTargets)

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

@@ -1,3 +1,4 @@
+import { AgentError } from '@myagentroam/agent';
 import { waitForToolCondition } from '@myagentroam/agent/extensions';
 export function validateAgentWaitOptions(input) {
     if ((input.mode !== undefined && input.mode !== 'any' && input.mode !== 'all') ||
@@ -6,7 +7,7 @@ export function validateAgentWaitOptions(input) {
             input.waitFor !== 'completion') ||
         (input.waitMs !== undefined &&
             (!Number.isInteger(input.waitMs) || input.waitMs < 0 || input.waitMs > 300_000)))
-        throw new Error('AGENT_WAIT_INVALID');
+        throw new AgentError('AGENT_WAIT_INVALID', 'The agent wait mode, condition or duration is invalid.');
 }
 /** One deadline and one notification subscription, with Session-scoped consumption. */
 export async function waitForAgentTargets(input) {
@@ -15,7 +16,7 @@ export async function waitForAgentTargets(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');
+        throw new AgentError('AGENT_WAIT_INVALID', 'The agent wait target selection is invalid.');
     input.signal?.throwIfAborted();
     const waitMs = input.waitMs ?? 30_000;
     const snapshot = waitMs === 0;
@@ -55,7 +56,7 @@ export async function waitForAgentTargets(input) {
                     terminalSnapshots.set(JSON.stringify([terminal.childId, terminal.runId, terminal.executionId]), terminal);
                 listener();
             }),
-            waitMs: Math.max(waitMs, 10_000),
+            waitMs,
             signal: input.signal,
             interrupt: input.interrupt
         });

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

@@ -120,6 +120,9 @@ export class GoalContinuationCoordinator {
                 void this.enqueueGoalContinuation({
                     sessionId: retry.sessionId,
                     goal: pending.goal,
+                    ...(retry.initiatedByUserId === undefined
+                        ? {}
+                        : { initiatedByUserId: retry.initiatedByUserId }),
                     ...(pending.usageGrant === undefined ? {} : { usageGrant: pending.usageGrant }),
                     secretEnvironment: pending.secretEnvironment,
                     ...(pending.personalInstructions === undefined

package/dist/service/planned-restart-handoff.js

@@ -70,7 +70,7 @@ const sessionSchema = z
     .strict();
 export const plannedRestartSchema = z
     .object({
-    schemaVersion: z.literal(3),
+    schemaVersion: z.literal(4),
     id: identifier,
     nodeId: identifier,
     serverUrl: z.string().min(1),
@@ -198,8 +198,6 @@ export class PlannedRestartHandoff {
                         effort: session.effort,
                         access: session.access
                     };
-                if (execution !== undefined && this.options.executionContext !== undefined)
-                    execution.executionContext = this.options.executionContext(session.id, execution.executionContext, execution.configuration?.modelId);
                 return execution;
             };
             const toMessage = (id, clientMessageId, content, attachments, originatingUser, suppressNotifications, activeInput = false) => ({
@@ -262,7 +260,7 @@ export class PlannedRestartHandoff {
             });
         }
         return parseCapture(plannedRestartSchema, {
-            schemaVersion: 3,
+            schemaVersion: 4,
             id: randomUUID(),
             ...this.options.identity(),
             createdAt: Date.now(),

package/dist/service/restart-execution-state.js

@@ -1,5 +1,4 @@
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
-import { modelUsageGrantSchema } from '@myagentroam/protocol';
 import { z } from 'zod';
 export const restartExecutionSchema = z
     .object({
@@ -11,14 +10,6 @@ export const restartExecutionSchema = z
     })
         .strict()
         .optional(),
-    executionContext: z
-        .object({ runner: z.literal('mar-agent'), runnerInput: z.unknown().optional() })
-        .strict(),
-    secretEnvironment: z.record(z.string(), z.string()),
-    personalInstructions: z.string().optional(),
-    usageGrant: z
-        .custom((value) => modelUsageGrantSchema.safeParse(value).success)
-        .optional(),
     initiatedByUserId: z.number().int().positive().optional()
 })
     .strict();
@@ -29,12 +20,6 @@ export function captureRestartExecution(input, initiatedByUserId) {
         ...(input.modelId === undefined || input.effort === undefined || input.access === undefined
             ? {}
             : { configuration: { modelId: input.modelId, effort: input.effort, access: input.access } }),
-        executionContext: structuredClone(input.executionContext),
-        secretEnvironment: { ...input.secretEnvironment },
-        ...(input.personalInstructions === undefined
-            ? {}
-            : { personalInstructions: input.personalInstructions }),
-        ...(input.usageGrant === undefined ? {} : { usageGrant: { ...input.usageGrant } }),
         ...(initiatedByUserId === undefined ? {} : { initiatedByUserId })
     });
 }

package/dist/service/restart-session-restorer.js

@@ -67,8 +67,7 @@ export class RestartSessionRestorer {
                 closeInput: '/goal --clear'
             });
         const submit = async (input, content = input.content) => {
-            const context = execution(input.execution);
-            await this.options.withGrant(context, () => this.options.messages.restoreQueued({
+            await this.options.withExecution(session, execution(input.execution), (context) => this.options.messages.restoreQueued({
                 sessionId: session.id,
                 content,
                 clientMessageId: input.clientMessageId,
@@ -110,8 +109,7 @@ export class RestartSessionRestorer {
             for (const input of entry.queue)
                 await submit(input);
             if (entry.goal?.goal.status === 'active') {
-                const context = execution(entry.execution);
-                await this.options.withGrant(context, () => this.options.messages.submitGoal({
+                await this.options.withExecution(session, execution(entry.execution), (context) => this.options.messages.submitGoal({
                     sessionId: session.id,
                     kind: 'continue',
                     deliveryIntent: 'QUEUE',

package/dist/service/run-authorization-control.js

@@ -1,4 +1,4 @@
-import { createEnvelope, scheduledRunAuthorizeRequestSchema, scheduledRunAuthorizeResponseSchema } from '@myagentroam/protocol';
+import { createEnvelope, scheduledRunAuthorizeRequestSchema, executionPrepareResponseSchema, executionPrepareRequestSchema } from '@myagentroam/protocol';
 export class RunAuthorizationControl {
     send;
     #pending = new Map();
@@ -8,9 +8,6 @@ export class RunAuthorizationControl {
     constructor(send) {
         this.send = send;
     }
-    code(suffix) {
-        return `SCHEDULE_${suffix}`;
-    }
     connected() {
         this.disconnected();
         this.#connected = true;
@@ -19,29 +16,38 @@ export class RunAuthorizationControl {
         this.#connected = false;
         this.#generation++;
         for (const pending of [...this.#pending.values()])
-            pending.reject(new Error(this.code('SERVER_UNAVAILABLE')));
+            pending.reject(new Error(`${pending.prefix}_SERVER_UNAVAILABLE`));
     }
     close() {
         this.#closed = true;
         this.disconnected();
     }
     handle(envelope) {
-        if (envelope.type !== 'schedule.authorize.response')
+        if (envelope.type !== 'schedule.authorize.response' &&
+            envelope.type !== 'execution.prepare.response')
             return false;
         const pending = envelope.replyTo === undefined ? undefined : this.#pending.get(envelope.replyTo);
-        if (pending === undefined || pending.generation !== this.#generation)
+        if (pending === undefined ||
+            pending.generation !== this.#generation ||
+            pending.responseType !== envelope.type)
             return true;
-        const parsed = scheduledRunAuthorizeResponseSchema.safeParse(envelope.payload);
+        const parsed = executionPrepareResponseSchema.safeParse(envelope.payload);
         if (!parsed.success)
-            pending.reject(new Error(this.code('AUTH_RESPONSE_INVALID')));
+            pending.reject(new Error(`${pending.prefix}_AUTH_RESPONSE_INVALID`));
         else
             pending.resolve(parsed.data);
         return true;
     }
     authorize(request) {
+        return this.request('schedule.authorize', scheduledRunAuthorizeRequestSchema.parse({ ...request, executionResources: 1 }), 'SCHEDULE');
+    }
+    prepare(request) {
+        return this.request('execution.prepare', executionPrepareRequestSchema.parse(request), 'EXECUTION');
+    }
+    request(type, request, prefix) {
         if (!this.#connected || this.#closed)
-            return Promise.reject(new Error(this.code('SERVER_UNAVAILABLE')));
-        const envelope = createEnvelope('schedule.authorize', scheduledRunAuthorizeRequestSchema.parse(request));
+            return Promise.reject(new Error(`${prefix}_SERVER_UNAVAILABLE`));
+        const envelope = createEnvelope(type, request);
         return new Promise((resolve, reject) => {
             const settle = (action) => {
                 const pending = this.#pending.get(envelope.id);
@@ -51,10 +57,12 @@ export class RunAuthorizationControl {
                 clearTimeout(pending.timer);
                 action();
             };
-            const timer = setTimeout(() => settle(() => reject(new Error(this.code('AUTH_TIMEOUT')))), 15_000);
+            const timer = setTimeout(() => settle(() => reject(new Error(`${prefix}_AUTH_TIMEOUT`))), 15_000);
             timer.unref();
             this.#pending.set(envelope.id, {
                 generation: this.#generation,
+                responseType: `${type}.response`,
+                prefix,
                 timer,
                 resolve: (response) => settle(() => {
                     if ('error' in response)
@@ -68,7 +76,7 @@ export class RunAuthorizationControl {
                 this.send(envelope);
             }
             catch {
-                settle(() => reject(new Error(this.code('SERVER_UNAVAILABLE'))));
+                settle(() => reject(new Error(`${prefix}_SERVER_UNAVAILABLE`)));
             }
         });
     }

package/dist/service/run-ownership-policy.js

@@ -1,10 +1,11 @@
+import { AgentError } from '@myagentroam/agent';
 export function assertRunOwner(run, requestUserId) {
     if (Number.isSafeInteger(requestUserId) && run.initiatedByUserId !== requestUserId)
-        throw new Error('RUN_OWNED_BY_ANOTHER_USER');
+        throw new AgentError('RUN_OWNED_BY_ANOTHER_USER', 'The run belongs to another user.');
 }
 export function assertQueueItemOwner(item, requestUserId) {
     if (Number.isSafeInteger(requestUserId) && item.initiatedByUserId !== requestUserId)
-        throw new Error('RUN_OWNED_BY_ANOTHER_USER');
+        throw new AgentError('RUN_OWNED_BY_ANOTHER_USER', 'The queued input belongs to another user.');
 }
 export function assertSessionControlOwner(runtime, sessionId, requestUserId) {
     if (!Number.isSafeInteger(requestUserId))

package/dist/service/run-workbench-service.js

@@ -3,7 +3,7 @@ import { nodeOperationData } from '../connection/node-operation-data.js';
 import { isTerminalRunStatus } from '../session/runtime/type-guards.js';
 import { isPlainRecord } from '../util/records.js';
 import { isHostedConversationImageRunId } from '../runner/mar-agent/generated-images.js';
-import { assertRunOwner } from './run-ownership-policy.js';
+import { assertRunOwner, assertSessionControlOwner } from './run-ownership-policy.js';
 import { imagePreviews } from './image-preview-service.js';
 export class RunWorkbenchService {
     options;
@@ -22,16 +22,25 @@ export class RunWorkbenchService {
             'run.approval.decide': (data) => this.decideApproval(record(data))
         };
     }
-    /** Atomically validate the target Execution before invoking the existing stop path. */
-    stopAgentExecution(input) {
+    /** Resolve and stop the current Session execution inside its existing control owner. */
+    stopAgentSession(input) {
         const run = this.options.runtime.activeSessionRun(input.sessionId);
-        if (run === undefined ||
-            (this.options.runtime.currentExecutionId(run.id) ?? run.id) !== input.executionId)
-            throw new Error('RUN_EXECUTION_STALE');
-        return this.cancelOrInterrupt('run.cancel', {
-            runId: run.id,
-            ...(input.requestUserId === undefined ? {} : { __requestUserId: input.requestUserId })
-        });
+        if (run !== undefined)
+            return this.cancelOrInterrupt('run.cancel', {
+                runId: run.id,
+                ...(input.requestUserId === undefined ? {} : { __requestUserId: input.requestUserId })
+            });
+        if (!this.options.runtime.getAgentSession(input.sessionId))
+            throw new Error('SESSION_NOT_FOUND');
+        assertSessionControlOwner(this.options.runtime, input.sessionId, input.requestUserId);
+        let result;
+        try {
+            this.options.pauseQueue(input.sessionId);
+        }
+        finally {
+            result = this.options.runInterrupted(input.sessionId);
+        }
+        return { status: 'IDLE', ...result };
     }
     async modelResource(input) {
         const parsed = modelResourceReadInputSchema.safeParse(nodeOperationData(input));

package/dist/service/session-recent-activity.js

@@ -138,6 +138,23 @@ export function marctlSessionDetail(runtime, session, queuedCount) {
         ...pendingApprovals(runtime, session.id)
     };
 }
+/** Agent state views omit execution identities; low-level CLI queries keep their own contract. */
+export function agentNetworkSessionView(runtime, session, queuedCount) {
+    const { runId: _runId, latestMessage, recentTools, pendingApprovals: approvals, ...state } = marctlSessionDetail(runtime, session, queuedCount);
+    return {
+        ...state,
+        latestMessage: latestMessage === null
+            ? null
+            : {
+                text: latestMessage.text,
+                state: latestMessage.state,
+                at: latestMessage.at,
+                truncated: latestMessage.truncated
+            },
+        recentTools: recentTools.map(({ runId: _runId, ...tool }) => tool),
+        pendingApprovals: approvals.map(({ runId: _runId, ...approval }) => approval)
+    };
+}
 function time(item) {
     return item.updatedAt ?? item.completedAt ?? item.startedAt;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@myagentroam/node",
-  "version": "0.11.51",
+  "version": "0.11.52",
   "description": "MyAgentRoam Node runtime CLI.",
   "license": "Apache-2.0 AND GPL-2.0-or-later",
   "type": "module",
@@ -38,10 +38,10 @@
     "sharp": "0.35.5",
     "ws": "^8.21.3",
     "zod": "4.4.3",
-    "@myagentroam/agent": "0.11.51",
+    "@myagentroam/agent": "0.11.52",
     "@myagentroam/code-navigation": "0.11.1",
-    "@myagentroam/protocol": "0.11.51",
-    "@myagentroam/marctl": "0.11.10"
+    "@myagentroam/marctl": "0.11.11",
+    "@myagentroam/protocol": "0.11.52"
   },
   "devDependencies": {
     "@types/ws": "^8.18.1"