@myagentroam/node 0.11.38 → 0.11.40

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');
+}