@myagentroam/node 0.11.44 → 0.11.46

package/dist/runner/codex-runner.js

@@ -202,7 +202,7 @@ export class CodexRunner extends AbstractRunner {
                     ? emptyCodexConfiguration()
                     : {
                         runner: this.name,
-                        model: selected.model,
+                        modelId: selected.model,
                         effort: selected.defaultEffort,
                         access: 'on-request'
                     }
@@ -361,7 +361,8 @@ export class CodexRunner extends AbstractRunner {
             return false;
         const profile = this.profileCacheForEnvironment(environment)?.profile;
         return (profile !== undefined &&
-            profile.models.some((model) => model.id === configuration.model && model.supportedEfforts.includes(configuration.effort)) &&
+            profile.models.some((model) => model.id === configuration.modelId &&
+                model.supportedEfforts.includes(configuration.effort)) &&
             profile.accessOptions.some((option) => option.id === configuration.access));
     }
     profileCacheForEnvironment(_environment) {
@@ -695,7 +696,11 @@ export class CodexRunner extends AbstractRunner {
         const threadId = session.externalSessionId;
         if (threadId === null)
             throw new Error('SESSION_REWIND_UNAVAILABLE');
-        const configuration = { model: session.model, effort: session.effort, access: session.access };
+        const configuration = {
+            model: session.modelId,
+            effort: session.effort,
+            access: session.access
+        };
         return this.withTemporaryClient(async (client) => {
             const result = boundary === null
                 ? await client.startThread(session.cwd, configuration)
@@ -719,7 +724,7 @@ export class CodexRunner extends AbstractRunner {
         const threadId = session.externalSessionId;
         return this.withTemporaryClient(async (client) => {
             const resumed = await client.resumeThread(threadId, session.cwd, {
-                model: session.model,
+                model: session.modelId,
                 effort: session.effort,
                 access: session.access
             });
@@ -753,7 +758,7 @@ export class CodexRunner extends AbstractRunner {
     }
 }
 function emptyCodexConfiguration() {
-    return { runner: 'codex', model: '', effort: '', access: 'on-request' };
+    return { runner: 'codex', modelId: '', effort: '', access: 'on-request' };
 }
 function codexModelPage(value) {
     if (!isPlainRecord(value) || !Array.isArray(value.data))

package/dist/runner/execution-presentation.js

@@ -1,53 +1,10 @@
-const MAX_BYTES = 128 * 1024;
-function tail(text, limit) {
-    if (limit === 0)
-        return '';
-    const result = text.slice(-limit);
-    const first = result.charCodeAt(0);
-    return first >= 0xdc00 && first <= 0xdfff ? result.slice(1) : result;
-}
-/** Keep public execution output bounded without copying an unbounded source. */
-export function boundExecutionPresentation(execution) {
-    let truncated = (execution.output?.length ?? 0) > 4;
-    const output = execution.output?.slice(0, 4).map((block) => {
-        if (block.text.length > 10_000)
-            truncated = true;
-        return { ...block, text: tail(block.text, 10_000) };
-    });
-    const detail = {
-        ...execution,
-        ...(output === undefined ? {} : { output }),
-        ...(execution.truncation === undefined ? {} : { truncation: { ...execution.truncation } })
-    };
-    if (truncated)
-        detail.truncation = { ...detail.truncation, output: detail.truncation?.output ?? 'HEAD' };
-    const presentation = { kind: 'EXECUTION', execution: detail };
-    const size = () => Buffer.byteLength(JSON.stringify(presentation));
-    for (const block of [...(detail.output ?? [])].reverse()) {
-        if (size() <= MAX_BYTES)
-            break;
-        const source = block.text;
-        detail.truncation = { ...detail.truncation, output: detail.truncation?.output ?? 'HEAD' };
-        truncated = true;
-        let low = 0;
-        let high = source.length;
-        while (low < high) {
-            const middle = Math.ceil((low + high) / 2);
-            block.text = tail(source, middle);
-            if (size() <= MAX_BYTES)
-                low = middle;
-            else
-                high = middle - 1;
+/** Execution metadata is independent of the public output body and its budget. */
+export function shellExecution(inputTruncated = false) {
+    return {
+        kind: 'EXECUTION',
+        execution: {
+            kind: 'SHELL',
+            ...(inputTruncated ? { truncation: { input: true } } : {})
         }
-        block.text = tail(source, low);
-    }
-    return { presentation, truncated };
-}
-/** Project only the stream facts actually supplied by the runner. */
-export function shellExecution(output, sourceTruncated = false) {
-    return boundExecutionPresentation({
-        kind: 'SHELL',
-        ...(output === undefined ? {} : { output: [{ channel: 'COMBINED', text: output }] }),
-        ...(sourceTruncated ? { truncation: { output: 'SOURCE' } } : {})
-    }).presentation;
+    };
 }

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

@@ -1,5 +1,10 @@
 import { agentNetworkWaitModelOutput } from './agent-network-wait-output.js';
+import { agentOperationEvent } from './agent-operation-presentation.js';
 const text = { type: 'string', minLength: 1 };
+const runner = {
+    ...text,
+    description: 'Runner type (for example mar-agent), not a model name; defaults to the current Runner.'
+};
 const attachmentIds = {
     type: 'array',
     items: text,
@@ -41,8 +46,11 @@ const tools = [
             content: { type: 'string' },
             attachments,
             attachmentIds,
-            runner: text,
-            model: text,
+            runner,
+            modelId: {
+                ...text,
+                description: 'Model ID from the target Runner Profile models[].id, not a display name. For MAR Agent this is an internal configuration ID, not an upstream model ID; omit to use the Runner default.'
+            },
             effort: text,
             title: text,
             goal,
@@ -52,7 +60,7 @@ const tools = [
     },
     {
         action: 'send',
-        description: 'Send input, decide an approval or update a Goal; goal:null leaves it unchanged, goal:{clear:true} clears it. Prefer REPLACE_CURRENT for timely communication or course correction. QUEUE is consumed only after current work and earlier queued inputs finish; an active Goal must exit first. Sending to a non-child does not subscribe to its updates.',
+        description: 'Send input, decide an approval or update a Goal; goal:null leaves it unchanged, goal:{clear:true} clears it. Messages default to REPLACE_CURRENT (steer); use QUEUE only when deferred delivery is explicitly requested. QUEUE is consumed only after current work and earlier queued inputs finish; an active Goal must exit first.',
         properties: {
             agentId: text,
             content: { type: 'string' },
@@ -65,14 +73,18 @@ const tools = [
                 required: ['approvalId', 'decision'],
                 properties: { approvalId: text, decision: { type: 'string', enum: ['approve', 'reject'] } }
             },
-            deliveryIntent: { type: 'string', enum: ['SEND', 'QUEUE', 'REPLACE_CURRENT'] },
+            deliveryIntent: {
+                type: 'string',
+                enum: ['SEND', 'QUEUE', 'REPLACE_CURRENT'],
+                description: 'Message delivery defaults to REPLACE_CURRENT (steer); explicit SEND remains supported.'
+            },
             clientMessageId: text
         },
         required: ['agentId']
     },
     {
         action: 'wait',
-        description: 'Wait for completion or messages; defaults to direct children, completion and 30 seconds. Use waitMs 0 for a snapshot. Non-child targets are observed only during this call.',
+        description: 'Wait for completion or messages; defaults to direct children, completion and 30 seconds. Use waitMs 0 for a snapshot.',
         properties: {
             agentId: text,
             agentIds: { type: 'array', items: text, minItems: 1, maxItems: 8 },
@@ -89,13 +101,18 @@ const tools = [
     },
     {
         action: 'list',
-        description: 'List Sessions, descendants or a Runner profile.',
+        description: 'List direct children by default, discover Workspace Sessions, inspect descendants or query a Runner profile.',
         properties: {
             scope: { type: 'string', enum: ['workspace', 'children', 'descendants', 'profile'] },
-            agentId: text,
-            parent: text,
-            runner: text,
-            query: { type: 'string' },
+            agentId: {
+                ...text,
+                description: 'Root for children or descendants; defaults to the current Session.'
+            },
+            runner: {
+                ...runner,
+                description: 'Runner for profile scope; defaults to the current Runner, not a model name.'
+            },
+            query: { type: 'string', description: 'Search Sessions; not a model selector.' },
             limit: { type: 'integer', minimum: 1, maximum: 100 },
             cursor: text
         }
@@ -112,11 +129,52 @@ const tools = [
         required: ['agentId']
     }
 ];
+const delegationPrompt = [
+    '# Delegation and coordination',
+    'Delegate bounded, self-contained tasks when independent progress or context savings materially helps. Keep simple or tightly coupled work local.',
+    'Give each child an objective, necessary context, expected output, and a read-only boundary or non-overlapping write scope.',
+    'Follow up through the direct delegate by default; inspect deeper Sessions only when a concrete issue needs independent verification.',
+    'While children run, continue meaningful non-overlapping work. Do not redo delegated work. Wait only when the next step needs the result.',
+    'Verify consequential findings and changes. Join or stop task-required child work before final delivery, and retain responsibility for the final result.'
+].join('\n\n');
+const collaborationPrompt = [
+    '# Workspace collaboration',
+    "Use native agent_* tools to collaborate within the Agent Network when another Session's context or ongoing work materially helps. Keep requests focused and avoid unnecessary cross-Session coordination. Peer Sessions retain their own work and lifecycle; do not treat them as task-owned children or stop them merely for task cleanup. Explicitly wait when you need progress or completion.",
+    "Reuse known Session IDs rather than rediscovering them. Send updates for meaningful progress, blockers, or changes that affect the recipient's work; combine related updates and avoid acknowledgment-only exchanges."
+].join('\n\n');
+const managementPrompt = [
+    '# Workspace management',
+    "Load marctl when needed to manage existing Session settings, titles, persistent prompts or schedules, or to discover authorized Nodes, execute remote commands or transfer files. Ordinary Agent collaboration and selecting a child's model or effort at creation use native agent_* tools. Do not switch to marctl when a native operation fails."
+].join('\n\n');
 export function agentNetworkExtension(invoke, currentExecution) {
     return {
         id: 'mar.node.agent-network',
         apiVersion: '1.0',
         attachSession(context) {
+            context.hooks.intercept('prompt.sections', (input, _call, next) => {
+                const available = new Set(input.facts?.tools);
+                const enabled = input.facts?.mode !== 'compact';
+                return next({
+                    ...input,
+                    sections: [
+                        ...input.sections,
+                        {
+                            id: 'mar.node.agent-network:delegation',
+                            text: enabled && available.has('agent_start') ? delegationPrompt : null
+                        },
+                        {
+                            id: 'mar.node.agent-network:collaboration',
+                            text: enabled && available.has('agent_send') ? collaborationPrompt : null
+                        },
+                        {
+                            id: 'mar.node.agent-network:management',
+                            text: enabled && tools.some((tool) => available.has(`agent_${tool.action}`))
+                                ? managementPrompt
+                                : null
+                        }
+                    ]
+                });
+            });
             for (const tool of tools)
                 context.tools.register({
                     name: `agent_${tool.action}`,
@@ -124,10 +182,11 @@ export function agentNetworkExtension(invoke, currentExecution) {
                     allowedCallers: ['direct', 'programmatic'],
                     eventInputFields: [
                         'agentId',
+                        'agentIds',
                         'title',
                         'executionId',
                         'runner',
-                        'model',
+                        'modelId',
                         'effort',
                         'waitFor',
                         'waitMs',
@@ -143,23 +202,20 @@ export function agentNetworkExtension(invoke, currentExecution) {
                         const executionId = currentExecution();
                         if (!executionId)
                             throw new Error('AGENT_ACTOR_NOT_ACTIVE');
-                        const result = await invoke(executionId, tool.action, input, call);
-                        const value = result !== null && typeof result === 'object' && !Array.isArray(result)
-                            ? result
-                            : undefined;
-                        const id = value?.agentId;
-                        const eventData = ['start', 'send', 'stop', 'wait'].includes(tool.action) &&
-                            typeof id === 'string' &&
-                            id.length > 0 &&
-                            id.length <= 128
-                            ? { agentId: id, productSessionId: id }
-                            : undefined;
+                        const args = input;
+                        const operationInput = tool.action === 'send' &&
+                            args.deliveryIntent === undefined &&
+                            ((typeof args.content === 'string' && !!args.content.trim()) ||
+                                (Array.isArray(args.attachments) && args.attachments.length > 0) ||
+                                (Array.isArray(args.attachmentIds) && args.attachmentIds.length > 0))
+                            ? { ...args, deliveryIntent: 'REPLACE_CURRENT' }
+                            : args;
+                        const result = await invoke(executionId, tool.action, operationInput, call);
                         const modelResult = tool.action === 'wait' ? agentNetworkWaitModelOutput(result) : result;
                         return {
                             data: result,
                             content: JSON.stringify(modelResult),
-                            eventSummary: JSON.stringify(eventData ?? {}),
-                            eventData: eventData ?? {}
+                            ...agentOperationEvent(tool.action, operationInput, result)
                         };
                     }
                 });

package/dist/runner/mar-agent/agent-operation-presentation.js

@@ -0,0 +1,167 @@
+import { agentOperationPresentationSchema } from '@myagentroam/protocol';
+import { isPlainRecord } from '../../util/records.js';
+const actions = {
+    agent_start: 'START',
+    agent_send: 'SEND',
+    agent_wait: 'WAIT',
+    agent_stop: 'STOP',
+    agent_list: 'LIST',
+    agent_view: 'VIEW'
+};
+export function agentOperationAction(toolName) {
+    return Object.hasOwn(actions, toolName) ? actions[toolName] : undefined;
+}
+function text(value, max = 128) {
+    return typeof value === 'string' && value.trim()
+        ? value.slice(0, max).replace(/[\uD800-\uDBFF]$/u, '')
+        : undefined;
+}
+function latestWaitMessage(updates) {
+    if (!Array.isArray(updates))
+        return undefined;
+    const message = updates.findLast((entry) => isPlainRecord(entry) && entry.kind === 'message' && typeof entry.value === 'string');
+    if (!isPlainRecord(message))
+        return undefined;
+    const value = text(message.value, 800);
+    if (!value)
+        return undefined;
+    return {
+        value,
+        ...(message.final === true ? { final: true } : {}),
+        ...(message.truncated === true || message.value.length > 800
+            ? { truncated: true }
+            : {})
+    };
+}
+/** Input identities are display-only; only successful Node results establish navigation. */
+export function agentOperationPresentation(toolName, input, data) {
+    const action = agentOperationAction(toolName);
+    if (!action)
+        return undefined;
+    const parsed = agentOperationPresentationSchema.safeParse(isPlainRecord(data) ? data.agentOperation : undefined);
+    if (parsed.success && parsed.data.action === action)
+        return parsed.data;
+    const value = isPlainRecord(input) ? input : {};
+    const ids = typeof value.agentId === 'string'
+        ? [value.agentId]
+        : Array.isArray(value.agentIds)
+            ? value.agentIds
+            : [];
+    return {
+        action,
+        targets: ids
+            .filter((id) => typeof id === 'string' && id.length > 0 && id.length <= 128)
+            .slice(0, 8)
+            .map((agentId) => ({ agentId })),
+        ...(text(value.scope, 32) ? { scope: text(value.scope, 32) } : {})
+    };
+}
+/** Whitelist public receipts; never serialize configuration, credentials or full history. */
+export function agentOperationEvent(action, input, result) {
+    const operation = agentOperationPresentation(`agent_${action}`, input);
+    const value = isPlainRecord(result) ? result : {};
+    const args = isPlainRecord(input) ? input : {};
+    const rows = action === 'list' ? value.sessions : action === 'wait' ? value.agents : undefined;
+    const records = Array.isArray(rows)
+        ? rows
+        : action === 'list'
+            ? []
+            : action === 'view'
+                ? isPlainRecord(value.session)
+                    ? [value.session]
+                    : []
+                : typeof value.agentId === 'string'
+                    ? [value]
+                    : [];
+    const returnedTargets = records
+        .flatMap((entry) => {
+        if (!isPlainRecord(entry))
+            return [];
+        const rawId = entry.agentId ?? entry.id;
+        const agentId = typeof rawId === 'string' && rawId.length <= 128 ? text(rawId) : undefined;
+        if (!agentId)
+            return [];
+        const title = text(entry.title ?? (action === 'start' ? args.title : undefined), 500);
+        return [{ agentId, sessionId: agentId, ...(title ? { title } : {}) }];
+    })
+        .slice(0, 100);
+    // An any-wait may return one result for several requested targets; keep the call multi-target.
+    const targets = action === 'wait' && operation.targets.length > 0
+        ? operation.targets.map((target) => returnedTargets.find((result) => result.agentId === target.agentId) ?? target)
+        : returnedTargets;
+    const presentation = { ...operation, targets };
+    if (records.length > returnedTargets.length)
+        presentation.targetsTruncated = true;
+    // Core accepts at most 8 KiB of explicit extension event data.
+    while (Buffer.byteLength(JSON.stringify({ agentOperation: presentation }), 'utf8') > 7000) {
+        targets.pop();
+        presentation.targetsTruncated = true;
+    }
+    const receipt = {};
+    if (action === 'list' && Array.isArray(value.models)) {
+        receipt.runner = text(value.runner);
+        receipt.modelCount = value.models.length;
+    }
+    if (action === 'view' && isPlainRecord(value.session)) {
+        for (const key of ['status', 'model', 'effort']) {
+            const field = text(value.session[key]);
+            if (field)
+                receipt[key] = field;
+        }
+        const message = isPlainRecord(value.session.latestMessage)
+            ? value.session.latestMessage
+            : undefined;
+        const messageText = text(message?.text, 800);
+        if (messageText)
+            receipt.latestMessage = {
+                text: messageText,
+                truncated: message?.truncated === true || messageText !== message?.text
+            };
+    }
+    for (const key of ['status', 'waitOutcome', 'waitFor', 'mode', 'reason', 'executionId']) {
+        const field = text(value[key]);
+        if (field)
+            receipt[key] = field;
+    }
+    for (const key of ['message', 'cancel', 'goal', 'approval', 'observation']) {
+        const item = value[key];
+        if (!isPlainRecord(item))
+            continue;
+        receipt[key] = {
+            ...(text(item.status) ? { status: text(item.status) } : {}),
+            ...(text(item.code) ? { code: text(item.code) } : {}),
+            ...(isPlainRecord(item.result) && text(item.result.delivery)
+                ? { delivery: text(item.result.delivery) }
+                : {})
+        };
+    }
+    if (Array.isArray(rows))
+        receipt.count = rows.length;
+    if (action === 'wait' && Array.isArray(rows))
+        receipt.agents = rows.slice(0, 8).map((entry) => {
+            const agent = isPlainRecord(entry) ? entry : {};
+            return {
+                agentId: text(agent.agentId),
+                status: text(agent.status),
+                waitOutcome: text(agent.waitOutcome),
+                summary: text(agent.summary, 800),
+                latestMessage: latestWaitMessage(agent.updates),
+                ...(agent.summaryTruncated === true ||
+                    (typeof agent.summary === 'string' && agent.summary.length > 800)
+                    ? { summaryTruncated: true }
+                    : {})
+            };
+        });
+    if (action === 'wait' && !Array.isArray(rows))
+        receipt.latestMessage = latestWaitMessage(value.updates);
+    const summary = text(value.summary, 4000);
+    if (summary)
+        receipt.summary = summary;
+    if (value.summaryTruncated === true ||
+        (typeof value.summary === 'string' && value.summary.length > 4000))
+        receipt.summaryTruncated = true;
+    return {
+        eventData: { agentOperation: presentation },
+        eventSummary: JSON.stringify(receipt)
+    };
+}