@myagentroam/node 0.11.39 → 0.11.41

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

@@ -122,6 +122,7 @@ export class MarAgentRunner extends AbstractRunner {
                 id: model.id,
                 label: model.name,
                 supportedEfforts: [...model.reasoningEfforts],
+                subagentModel: model.subagentModel === true,
                 defaultEffort: resolveMarAgentDefaultReasoningEffort(model.defaultReasoningEffort, model.reasoningEfforts),
                 ...(index === 0 ? { isDefault: true } : {})
             })),
@@ -195,6 +196,16 @@ export class MarAgentRunner extends AbstractRunner {
             ]
         };
     }
+    childModels() {
+        const eligible = new Set(this.#models
+            .filter((model) => model.enabled && model.conversationModel !== false && model.subagentModel === true)
+            .map((model) => model.id));
+        return this.profileForValidation().models.filter((model) => eligible.has(model.id));
+    }
+    assertChildModel(modelId) {
+        if (!this.childModels().some((model) => model.id === modelId))
+            throw new Error('MAR_AGENT_SUBAGENT_MODEL_UNAVAILABLE');
+    }
     supportsConfiguration(configuration) {
         if (configuration.runner !== this.name)
             return false;
@@ -289,6 +300,9 @@ export class MarAgentRunner extends AbstractRunner {
                                 runner: this.name,
                                 externalSessionId: session.id,
                                 cwd: session.workspace,
+                                ...(session.source?.parentSessionId === undefined
+                                    ? {}
+                                    : { parentSessionId: session.source.parentSessionId }),
                                 lastActivityAt: Date.parse(session.lastActivityAt)
                             })
                         ]
@@ -311,6 +325,9 @@ export class MarAgentRunner extends AbstractRunner {
                             runner: this.name,
                             externalSessionId: session.id,
                             cwd: session.workspace,
+                            ...(session.source?.parentSessionId === undefined
+                                ? {}
+                                : { parentSessionId: session.source.parentSessionId }),
                             ...title,
                             lastActivityAt: Date.parse(session.lastActivityAt)
                         }),
@@ -406,6 +423,25 @@ export class MarAgentRunner extends AbstractRunner {
             await catalog.close().catch(() => undefined);
         }
     }
+    supportsNativeBatchRemoval() {
+        return true;
+    }
+    async removeNativeMembers(sessions) {
+        const ids = sessions.map((session) => {
+            if (session.runner !== this.name || session.externalSessionId === null)
+                throw new Error('NATIVE_TRANSCRIPT_UNAVAILABLE');
+            return session.externalSessionId;
+        });
+        for (const id of ids)
+            await this.#releaseSessionResources?.(id);
+        const catalog = await openAgentSessionCatalog({ homeDirectory: this.homeDirectory });
+        try {
+            await catalog.deleteMembers(ids);
+        }
+        finally {
+            await catalog.close().catch(() => undefined);
+        }
+    }
     async readManagedRunnerTitle(session, nativeSessionId) {
         if (session.runner !== this.name || session.externalSessionId !== nativeSessionId)
             return undefined;

package/dist/runner/opencode/tool-normalizer.js

@@ -1,4 +1,5 @@
 import { compactRunnerText, compactRunnerValue } from '../normalization.js';
+import { publicOutputSnapshot, shellExecution } from '../execution-presentation.js';
 export function normalizeOpenCodeTool(toolName, state) {
     const status = state?.status === 'completed'
         ? 'COMPLETED'
@@ -23,7 +24,11 @@ export function normalizeOpenCodeTool(toolName, state) {
                 outputRef: null,
                 exitCode: typeof state?.exitCode === 'number' ? state.exitCode : null,
                 durationMs: null,
-                truncated: false
+                truncated: typeof state?.output === 'string' && state.output.length > 10_000,
+                ...(typeof state?.output === 'string'
+                    ? { output: publicOutputSnapshot(state.output) }
+                    : {}),
+                toolPresentation: shellExecution(typeof state?.output === 'string' ? state.output : undefined)
             }
         };
     return {

package/dist/runtime-state.js

@@ -872,6 +872,63 @@ export class NodeRuntimeState {
                 return executionId;
         return undefined;
     }
+    /** Read the identity and status of one Execution without following a later turn. */
+    executionSnapshot(executionId) {
+        const execution = this.executions.get(executionId);
+        if (execution !== undefined) {
+            const run = this.getRun(execution.runId);
+            return run === undefined
+                ? undefined
+                : {
+                    executionId,
+                    runId: run.id,
+                    sessionId: run.sessionId,
+                    status: execution.status
+                };
+        }
+        const retained = this.retainedExecutionTurns.get(executionId);
+        if (retained === undefined)
+            return undefined;
+        const turn = this.turns.get(retained.sessionId)?.find((value) => value.id === retained.turnId);
+        return turn?.runId == null
+            ? undefined
+            : {
+                executionId,
+                runId: turn.runId,
+                sessionId: retained.sessionId,
+                status: turn.status
+            };
+    }
+    latestRunExecution(runId) {
+        const turn = this.conversationTurnForRun(runId);
+        if (turn === undefined)
+            return undefined;
+        for (const execution of this.executions.values())
+            if (execution.runId === runId && execution.turnId === turn.id)
+                return this.executionSnapshot(execution.id);
+        for (const [executionId, retained] of this.retainedExecutionTurns)
+            if (retained.sessionId === turn.sessionId && retained.turnId === turn.id)
+                return this.executionSnapshot(executionId);
+        return undefined;
+    }
+    /** Resolve the current or most recent retained Execution of a Session. */
+    latestSessionExecution(sessionId) {
+        const active = this.activeSessionRun(sessionId);
+        if (active !== undefined)
+            return this.latestRunExecution(active.id);
+        const turns = this.turns.get(sessionId) ?? [];
+        for (let index = turns.length - 1; index >= 0; index -= 1) {
+            const turn = turns[index];
+            const live = [...this.executions.values()].find((value) => value.turnId === turn.id);
+            if (live !== undefined)
+                return this.executionSnapshot(live.id);
+            for (const [executionId, retained] of this.retainedExecutionTurns) {
+                if (retained.sessionId === sessionId && retained.turnId === turn.id)
+                    return this.executionSnapshot(executionId);
+            }
+        }
+        return undefined;
+    }
     createExecution(runId) {
         const canonicalRunId = this.canonicalRunId(runId);
         const turn = this.currentTurnForRun(canonicalRunId);

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

@@ -0,0 +1,483 @@
+import { auditConversationReceiptSchema, marAgentRuntimeModelConfigurationSchema } from '@myagentroam/protocol';
+import { AgentNetworkService } from './agent-network-service.js';
+import { isPlainRecord } from '../util/records.js';
+import { safeErrorCode } from '../util/safe-error.js';
+import { withSessionMessageOrigin } from './composer-message-input.js';
+import { SESSION_ADMISSION_SIGNAL } from '../session/operation-admission.js';
+import { assertSessionControlOwner } from './run-ownership-policy.js';
+const approvedCalls = new WeakMap();
+const terminalCalls = new WeakMap();
+/** Bind a terminal actor only after the Node request boundary has authenticated its caller. */
+export function actorForAuthenticatedTerminal(actor, workspaceId) {
+    const authenticated = Object.freeze({ ...actor });
+    terminalCalls.set(authenticated, { workspaceId });
+    return authenticated;
+}
+/** Bind a Host-approved invocation to its exact target and domain operations. */
+export function actorForApprovedAgentCall(actor, context, agentIds, operations) {
+    if (context.permission?.decision !== 'approved')
+        return actor;
+    const approved = Object.freeze({ ...actor });
+    approvedCalls.set(approved, { agentIds: [...agentIds], operations: [...operations] });
+    return approved;
+}
+import { sessionPage } from '../session/pagination.js';
+import { marctlSessionSummary, marctlSessionDetail } from './session-recent-activity.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');
+        const parent = options.runtime.getAgentSession(actor.sessionId) ??
+            (await options.projection.resolve(actor.sessionId, true));
+        if (!parent)
+            throw new Error('SESSION_NOT_FOUND');
+        if (actor.runId !== undefined) {
+            const run = options.runtime.getRun(actor.runId);
+            if (!run ||
+                run.sessionId !== parent.id ||
+                options.runtime.activeSessionRun(parent.id)?.id !== run.id ||
+                (actor.executionId !== undefined &&
+                    options.runtime.currentExecutionId(run.id) !== actor.executionId) ||
+                run.initiatedByUserId !== actor.requestUserId)
+                throw new Error('AGENT_ACTOR_INVALID');
+        }
+        return parent;
+    }
+    async function target(actor, id) {
+        const terminal = terminalCalls.get(actor);
+        const parent = terminal ? undefined : await actorSession(actor);
+        const workspaceId = terminal?.workspaceId ?? parent?.workspaceId;
+        const session = options.runtime.getAgentSession(id) ?? (await options.projection.resolve(id, true));
+        if (!session || session.workspaceId !== workspaceId || session.id === parent?.id)
+            throw new Error('SESSION_NOT_FOUND');
+        return session;
+    }
+    function origin(parent) {
+        return {
+            sessionId: parent.id,
+            name: parent.customTitle?.trim() || parent.runnerTitle?.trim() || parent.id
+        };
+    }
+    function childEnvironment(actor) {
+        // Retained only inside Node; dispatch exchanges its delegation before creating the child process.
+        return actor.secretEnvironment ?? {};
+    }
+    function executionInput(actor, runner, model, requireSubagent = true) {
+        const result = {
+            ...actor.runnerConfiguration,
+            secretEnvironment: childEnvironment(actor),
+            ...(actor.personalInstructions === undefined
+                ? {}
+                : { personalInstructions: actor.personalInstructions }),
+            ...(actor.requestUserId === undefined ? {} : { __requestUserId: actor.requestUserId }),
+            ...(actor.usageGrant === undefined ? {} : { __usageGrant: actor.usageGrant })
+        };
+        if (runner === 'mar-agent') {
+            const candidates = [
+                result.marAgentModel,
+                ...(Array.isArray(result.marAgentModels) ? result.marAgentModels : [])
+            ];
+            const selected = candidates.flatMap((value) => {
+                const parsed = marAgentRuntimeModelConfigurationSchema.safeParse(value);
+                return parsed.success && parsed.data.id === model ? [parsed.data] : [];
+            })[0];
+            if (!selected ||
+                !selected.enabled ||
+                !selected.conversationModel ||
+                (requireSubagent && !selected.subagentModel))
+                throw new Error('MAR_AGENT_SUBAGENT_MODEL_UNAVAILABLE');
+            result.marAgentModel = selected;
+        }
+        return result;
+    }
+    async function validateApproval(actor, session, input) {
+        if (!terminalCalls.has(actor)) {
+            const parent = await actorSession(actor);
+            if (session.parentSessionId !== parent.id)
+                throw new Error('AGENT_TARGET_NOT_AUTHORIZED');
+        }
+        assertSessionControlOwner(options.runtime, session.id, actor.requestUserId);
+        const approval = options.runtime.getApproval(input.approvalId);
+        if (!approval)
+            throw new Error('APPROVAL_NOT_FOUND');
+        const runId = options.runtime.canonicalRunId(approval.runId);
+        const run = options.runtime.getRun(runId);
+        const active = options.runtime.activeSessionRun(session.id);
+        if (!run ||
+            run.sessionId !== session.id ||
+            active?.id !== runId ||
+            (approval.runId !== runId && approval.runId !== options.runtime.currentExecutionId(runId)))
+            throw new Error('APPROVAL_NOT_FOUND');
+        if (approval.status === 'EXPIRED')
+            throw new Error('APPROVAL_EXPIRED');
+        if (approval.status !== 'PENDING')
+            throw new Error('APPROVAL_ALREADY_DECIDED');
+    }
+    return new AgentNetworkService({
+        observations: options.observations,
+        target,
+        authorize: async (actor, session, operation) => {
+            assertSessionControlOwner(options.runtime, session.id, actor.requestUserId);
+            if (terminalCalls.has(actor))
+                return;
+            const source = await actorSession(actor);
+            if (session.parentSessionId === source.id)
+                return;
+            if (source.parentSessionId === session.id && operation === 'send')
+                return;
+            const approved = approvedCalls.get(actor);
+            if (approved?.agentIds.includes(session.id) && approved.operations.includes(operation))
+                return;
+            throw new Error('AGENT_TARGET_NOT_AUTHORIZED');
+        },
+        children: async (actor) => {
+            if (terminalCalls.has(actor))
+                throw new Error('AGENT_TARGET_REQUIRED');
+            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) ??
+                options.projection.resolve(record.id, true)));
+            return resolved.filter((session) => session !== undefined);
+        },
+        observe: (actor, session) => options.ensureObservations(actor).observe(session.id),
+        isUpward: async (actor, session) => !terminalCalls.has(actor) && (await actorSession(actor)).parentSessionId === session.id,
+        reportUpward: async (actor, session, input, signal) => {
+            const child = await actorSession(actor);
+            const runId = actor.runId;
+            const executionId = actor.executionId;
+            if (!runId ||
+                !executionId ||
+                options.runtime.currentExecutionId(runId) !== executionId ||
+                child.parentSessionId !== session.id)
+                throw new Error('AGENT_ACTOR_NOT_ACTIVE');
+            signal?.throwIfAborted();
+            const parent = options.observations.get(session.id);
+            if (!parent?.report({
+                childId: child.id,
+                runId,
+                executionId,
+                value: withSessionMessageOrigin(input.content, origin(child), session.parentSessionId)
+            }))
+                throw new Error('AGENT_PARENT_NOT_WARM');
+            return { delivery: 'reported', clientMessageId: input.clientMessageId };
+        },
+        freezeExecution: (session) => {
+            const snapshot = options.runtime.latestSessionExecution(session.id);
+            const run = options.runtime.activeSessionRun(session.id);
+            const runId = snapshot?.runId ?? run?.id;
+            if (!runId)
+                return undefined;
+            let executionId = snapshot?.executionId;
+            const currentId = () => {
+                executionId ??= options.runtime.latestRunExecution(runId)?.executionId;
+                return executionId;
+            };
+            return {
+                agentId: session.id,
+                runId,
+                get executionId() {
+                    return currentId();
+                },
+                read: () => {
+                    const id = currentId();
+                    return id === undefined
+                        ? (options.runtime.getRun(runId) ?? { status: 'UNKNOWN' })
+                        : (options.runtime.executionSnapshot(id) ?? { status: 'UNKNOWN' });
+                }
+            };
+        },
+        start: async (actor, input, signal) => {
+            const terminal = terminalCalls.get(actor);
+            const parent = terminal
+                ? input.parentSessionId === undefined
+                    ? undefined
+                    : await target(actor, input.parentSessionId)
+                : await actorSession(actor);
+            if (!terminal && input.parentSessionId !== undefined && input.parentSessionId !== parent?.id)
+                throw new Error('AGENT_TARGET_NOT_AUTHORIZED');
+            signal?.throwIfAborted();
+            options.ensureObservations(actor);
+            const runner = input.runner ?? parent?.runner;
+            if (!runner)
+                throw new Error('RUNNER_REQUIRED');
+            const runnerAdapter = options.runners.product(runner);
+            const database = options.database();
+            const workspaceId = terminal?.workspaceId ?? parent?.workspaceId;
+            const workspace = workspaceId === undefined ? undefined : database?.getWorkspace(workspaceId);
+            if (!runnerAdapter || !database || !workspace)
+                throw new Error('SESSION_INVALID');
+            const model = input.model ??
+                database.getRunnerDefaults().find((entry) => entry.runner === runner)?.model ??
+                runnerAdapter.defaultConfiguration(workspace, actor.secretEnvironment ?? {}).model;
+            const request = {
+                ...executionInput(actor, runner, model, parent !== undefined),
+                workspaceId: workspace.id,
+                ...(signal ? { [SESSION_ADMISSION_SIGNAL]: signal } : {}),
+                ...(parent ? { parentSessionId: parent.id } : {}),
+                runner,
+                cwd: parent?.cwd ?? workspace.path,
+                content: input.content,
+                clientMessageId: input.clientMessageId,
+                ...(!terminal && parent ? { __marctlOrigin: origin(parent) } : {}),
+                ...(input.title === undefined ? {} : { title: input.title }),
+                ...(model ? { model } : {}),
+                ...(input.effort === undefined ? {} : { effort: input.effort }),
+                ...(input.attachments === undefined ? {} : { attachments: input.attachments }),
+                ...(input.attachmentIds === undefined ? {} : { attachmentIds: input.attachmentIds })
+            };
+            signal?.throwIfAborted();
+            const result = await options.withGrant(actor, () => input.goal.kind === 'set'
+                ? options.lifecycle.startAgentWithGoal(request, (session, executionContext) => options.coordinator.start({
+                    session,
+                    executionContext,
+                    objective: input.goal.kind === 'set' ? input.goal.objective : '',
+                    secretEnvironment: childEnvironment(actor),
+                    messageContent: input.content,
+                    ...(!terminal && parent ? { messageOrigin: origin(parent) } : {}),
+                    clientMessageId: input.clientMessageId,
+                    ...(input.attachments === undefined ? {} : { attachments: input.attachments }),
+                    ...(input.attachmentIds === undefined
+                        ? {}
+                        : { attachmentIds: input.attachmentIds }),
+                    ...(actor.requestUserId === undefined
+                        ? {}
+                        : { initiatedByUserId: actor.requestUserId }),
+                    ...(actor.usageGrant === undefined ? {} : { usageGrant: actor.usageGrant }),
+                    ...(actor.personalInstructions === undefined
+                        ? {}
+                        : { personalInstructions: actor.personalInstructions })
+                }))
+                : options.lifecycle.operations()['session.start'](request));
+            if (!isPlainRecord(result) ||
+                !isPlainRecord(result.session) ||
+                typeof result.session.id !== 'string')
+                throw new Error('SESSION_START_INVALID_RESULT');
+            const session = await target(actor, result.session.id);
+            return {
+                session,
+                result: { ...publicReceipt(result), clientMessageId: input.clientMessageId }
+            };
+        },
+        setGoal: async (actor, session, change, message, signal) => {
+            const parent = terminalCalls.has(actor) ? undefined : await actorSession(actor);
+            signal?.throwIfAborted();
+            if (change.kind === 'clear')
+                return publicReceipt(options.coordinator.clear(session));
+            const current = await options.resume.resolveForMessage(session.id);
+            const executionContext = options.runners
+                .require(current.runner)
+                .prepareExecutionContext(executionInput(actor, current.runner, current.model, current.parentSessionId != null));
+            signal?.throwIfAborted();
+            const result = await options.withGrant(actor, () => options.coordinator.start({
+                session: current,
+                objective: change.objective,
+                executionContext,
+                secretEnvironment: childEnvironment(actor),
+                ...(actor.requestUserId === undefined ? {} : { initiatedByUserId: actor.requestUserId }),
+                ...(actor.personalInstructions === undefined
+                    ? {}
+                    : { personalInstructions: actor.personalInstructions }),
+                ...(actor.usageGrant === undefined ? {} : { usageGrant: actor.usageGrant }),
+                preserveActiveRun: true,
+                ...(parent ? { messageOrigin: origin(parent) } : {}),
+                ...(message === undefined
+                    ? {}
+                    : {
+                        messageContent: message.content,
+                        clientMessageId: message.clientMessageId,
+                        messageIntent: message.deliveryIntent,
+                        ...(message.attachments === undefined ? {} : { attachments: message.attachments }),
+                        ...(message.attachmentIds === undefined
+                            ? {}
+                            : { attachmentIds: message.attachmentIds })
+                    })
+            }));
+            return publicReceipt(result);
+        },
+        message: async (actor, session, input, signal) => {
+            const parent = terminalCalls.has(actor) ? undefined : await actorSession(actor);
+            signal?.throwIfAborted();
+            const result = await options.withGrant(actor, () => options.messages.operations()['session.message']({
+                ...executionInput(actor, session.runner, session.model, session.parentSessionId != null),
+                ...input,
+                ...(signal ? { [SESSION_ADMISSION_SIGNAL]: signal } : {}),
+                sessionId: session.id,
+                ...(parent ? { __marctlOrigin: origin(parent) } : {})
+            }));
+            return publicReceipt(result);
+        },
+        validateApproval,
+        approval: async (actor, session, input, signal) => {
+            await validateApproval(actor, session, input);
+            signal?.throwIfAborted();
+            const approval = options.runtime.getApproval(input.approvalId);
+            const runId = options.runtime.canonicalRunId(approval.runId);
+            const decision = input.decision === 'approve' ? 'APPROVED' : 'REJECTED';
+            try {
+                options.runs.operations()['run.approval.decide']({
+                    runId,
+                    approvalId: input.approvalId,
+                    decision,
+                    __requestUserId: actor.requestUserId
+                });
+                return {
+                    status: 'applied',
+                    result: { approvalId: input.approvalId, decision: input.decision }
+                };
+            }
+            catch (error) {
+                if (approval.status === 'PENDING' &&
+                    options.runtime.getApproval(input.approvalId)?.status === decision)
+                    return {
+                        status: 'partial',
+                        code: safeErrorCode(error, 'APPROVAL_DECISION_FAILED'),
+                        result: { approvalId: input.approvalId, decision: input.decision }
+                    };
+                throw error;
+            }
+        },
+        stop: (actor, session, executionId) => publicReceipt(options.runs.stopAgentExecution({
+            sessionId: session.id,
+            executionId,
+            ...(actor.requestUserId === undefined ? {} : { requestUserId: actor.requestUserId })
+        })),
+        goal: (sessionId) => publicGoal(options.goals.get(sessionId)),
+        list: async (actor, input) => {
+            const terminal = terminalCalls.get(actor);
+            const source = terminal ? undefined : await actorSession(actor);
+            const workspaceId = terminal?.workspaceId ?? source?.workspaceId;
+            if (!workspaceId)
+                throw new Error('SESSION_INVALID');
+            const current = source ? marctlSessionSummary(options.runtime, source) : null;
+            const scope = input.scope ?? (terminal ? 'workspace' : 'children');
+            if (scope === 'profile') {
+                const runner = input.runner ?? source?.runner;
+                if (!runner)
+                    throw new Error('RUNNER_REQUIRED');
+                const profiles = await options.profiles(actor.secretEnvironment ?? {}, actor.runnerConfiguration?.marAgentModels);
+                const profile = profiles.find((item) => item.runner === runner);
+                if (!profile)
+                    throw new Error('RUNNER_PROFILE_NOT_FOUND');
+                const models = profile.runner !== 'mar-agent'
+                    ? profile.models
+                    : profile.models.filter((model) => {
+                        const configurations = [
+                            actor.runnerConfiguration?.marAgentModel,
+                            ...(Array.isArray(actor.runnerConfiguration?.marAgentModels)
+                                ? actor.runnerConfiguration.marAgentModels
+                                : [])
+                        ];
+                        return configurations.some((value) => isPlainRecord(value) &&
+                            value.id === model.id &&
+                            value.enabled === true &&
+                            value.conversationModel === true &&
+                            value.subagentModel === true);
+                    });
+                return { current, runner: profile.runner, models, capabilities: profile.capabilities };
+            }
+            if (scope === 'workspace') {
+                const result = await options.listSessions({
+                    workspaceId,
+                    view: 'marctl',
+                    registeredOnly: true,
+                    ...(input.query === undefined ? {} : { query: input.query }),
+                    ...(input.parent === undefined ? {} : { parentSessionId: input.parent }),
+                    ...(input.limit === undefined ? {} : { limit: input.limit }),
+                    ...(input.cursor === undefined ? {} : { cursor: input.cursor })
+                });
+                if (!isPlainRecord(result))
+                    throw new Error('SESSION_LIST_INVALID_RESULT');
+                return { ...result, current };
+            }
+            if (scope !== 'children' && scope !== 'descendants')
+                throw new Error('AGENT_LIST_INVALID');
+            const root = input.agentId === undefined || input.agentId === source?.id
+                ? source
+                : await target(actor, input.agentId);
+            if (!root)
+                throw new Error('AGENT_TARGET_REQUIRED');
+            const database = options.database();
+            if (!database)
+                throw new Error('DATABASE_UNAVAILABLE');
+            const records = scope === 'children'
+                ? database.listChildSessionRecords(root.workspaceId, root.id)
+                : database.sessionTreeRecords(root.workspaceId, root.id).slice(1);
+            const sessions = (await Promise.all(records.map((record) => options.runtime.getAgentSession(record.id) ??
+                options.projection.resolve(record.id, true))))
+                .filter((session) => session !== undefined)
+                .filter((session) => !input.query ||
+                (session.customTitle ?? session.runnerTitle ?? '')
+                    .normalize('NFKC')
+                    .toLocaleLowerCase()
+                    .includes(input.query.normalize('NFKC').toLocaleLowerCase()));
+            const page = sessionPage(sessions, { limit: input.limit, cursor: input.cursor });
+            return {
+                current,
+                sessions: page.sessions.map((session) => marctlSessionSummary(options.runtime, session)),
+                nextCursor: page.nextCursor,
+                truncated: page.nextCursor !== null
+            };
+        },
+        view: async (actor, input) => {
+            const source = terminalCalls.has(actor) ? undefined : await actorSession(actor);
+            const session = input.agentId === source?.id ? source : await target(actor, input.agentId);
+            assertSessionControlOwner(options.runtime, session.id, actor.requestUserId);
+            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
+                        })
+                    }
+                    : {})
+            };
+        }
+    });
+}
+function publicGoal(goal) {
+    return goal === undefined
+        ? undefined
+        : {
+            id: goal.id,
+            objective: goal.objective,
+            status: goal.status,
+            revision: goal.revision,
+            startedAt: goal.startedAt,
+            turns: goal.turns
+        };
+}
+/** Project receipts without leaking Session internals or execution credentials. */
+function publicReceipt(value) {
+    if (!isPlainRecord(value))
+        return {};
+    const result = {};
+    const audit = auditConversationReceiptSchema.safeParse(value.auditReceipt);
+    if (audit.success)
+        result.auditReceipt = audit.data;
+    for (const key of ['delivery', 'queueItemId', 'idempotent', 'cleared', 'goalAccessChanged'])
+        if (typeof value[key] === 'string' || typeof value[key] === 'boolean')
+            result[key] = value[key];
+    if (isPlainRecord(value.run) && typeof value.run.id === 'string')
+        result.run = { id: value.run.id, status: value.run.status };
+    if (isPlainRecord(value.turn) && typeof value.turn.id === 'string')
+        result.turn = { id: value.turn.id, status: value.turn.status };
+    if (isPlainRecord(value.goal)) {
+        const goal = value.goal;
+        result.goal = {
+            id: goal.id,
+            objective: goal.objective,
+            status: goal.status,
+            revision: goal.revision
+        };
+    }
+    if (isPlainRecord(value.goalExit))
+        result.goalExit = value.goalExit;
+    return result;
+}

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

@@ -0,0 +1,19 @@
+import { isPlainRecord } from '../util/records.js';
+/** Shared Goal input contract for native tools and CLI. */
+export function parseAgentGoal(input) {
+    if (input === undefined || input === null)
+        return { kind: 'unchanged' };
+    if (!isPlainRecord(input))
+        throw new Error('AGENT_GOAL_INVALID');
+    const keys = Object.keys(input);
+    if (keys.length !== 1)
+        throw new Error('AGENT_GOAL_INVALID');
+    if (keys[0] === 'clear' && input.clear === true)
+        return { kind: 'clear' };
+    if (keys[0] === 'objective' && typeof input.objective === 'string') {
+        const objective = input.objective.trim();
+        if (objective.length > 0 && objective.length <= 20_000)
+            return { kind: 'set', objective };
+    }
+    throw new Error('AGENT_GOAL_INVALID');
+}