@myagentroam/node 0.11.39 → 0.11.41

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

@@ -0,0 +1,179 @@
+import { actorForApprovedAgentCall, actorForAuthenticatedTerminal } from './agent-network-bindings.js';
+import { isPlainRecord } from '../util/records.js';
+import { randomUUID } from 'node:crypto';
+import { modelUsageGrantSchema } from '@myagentroam/protocol';
+/** Bind each native invocation to the actual live Node Execution and its captured resources. */
+export function agentNetworkInvoke(input) {
+    return async (executionId, action, payload, context) => {
+        const actor = executionAgentActor({ ...input, executionId });
+        return invokeAgentNetwork(input.service, actor, action, payload, context);
+    };
+}
+/** Read actor resources from the current Node-owned Execution, not caller arguments. */
+export function executionAgentActor(input) {
+    const { sessionId, executionId } = input;
+    const execution = input.runtime.executionSnapshot(executionId);
+    const prepared = input.coordinator.pending(executionId);
+    const run = execution && input.runtime.getRun(execution.runId);
+    if (!execution ||
+        !prepared ||
+        !run ||
+        execution.sessionId !== sessionId ||
+        prepared.sessionId !== sessionId ||
+        input.runtime.activeSessionRun(sessionId)?.id !== run.id ||
+        input.runtime.currentExecutionId(run.id) !== executionId ||
+        !['STARTING', 'RUNNING'].includes(execution.status) ||
+        !Number.isSafeInteger(run.initiatedByUserId))
+        throw new Error('AGENT_ACTOR_NOT_ACTIVE');
+    const captured = prepared.executionContext.runner === 'mar-agent' &&
+        isPlainRecord(prepared.executionContext.runnerInput)
+        ? prepared.executionContext.runnerInput
+        : {};
+    return {
+        sessionId,
+        runId: run.id,
+        executionId,
+        ...(run.initiatedByUserId === undefined ? {} : { requestUserId: run.initiatedByUserId }),
+        secretEnvironment: prepared.secretEnvironment,
+        ...(prepared.usageGrant === undefined ? {} : { usageGrant: prepared.usageGrant }),
+        ...(prepared.personalInstructions === undefined
+            ? {}
+            : { personalInstructions: prepared.personalInstructions }),
+        runnerConfiguration: {
+            marAgentModel: captured.model,
+            marAgentModels: captured.models,
+            marAgentCompact: captured.compact,
+            marAgentRuntimeScopeId: captured.runtimeScopeId
+        }
+    };
+}
+/** Shared command dispatch; callers must bind actor authority at their trusted boundary. */
+export async function invokeAgentNetwork(service, actor, action, payload, context, requestSignal) {
+    const targets = typeof payload.agentId === 'string'
+        ? [payload.agentId]
+        : Array.isArray(payload.agentIds)
+            ? payload.agentIds.filter((id) => typeof id === 'string')
+            : [];
+    const operations = action === 'send'
+        ? ['send', 'goal']
+        : action === 'stop'
+            ? ['stop']
+            : action === 'wait'
+                ? ['wait']
+                : [];
+    const authorized = context
+        ? actorForApprovedAgentCall(actor, context, targets, operations)
+        : actor;
+    const signal = context?.signal ?? requestSignal;
+    switch (action) {
+        case 'start':
+            if ((context || actor.executionId) &&
+                (typeof payload.title !== 'string' || !payload.title.trim()))
+                throw new Error('AGENT_START_INVALID');
+            if (!context &&
+                !actor.executionId &&
+                typeof payload.title === 'string' &&
+                !payload.title.trim()) {
+                const { title: _title, ...withoutTitle } = payload;
+                return service.start(actor, withoutTitle, signal);
+            }
+            return service.start(actor, {
+                ...payload,
+                ...(typeof payload.title === 'string' ? { title: payload.title.trim() } : {})
+            }, signal);
+        case 'send':
+            return service.send(authorized, payload, signal);
+        case 'stop':
+            return service.stop(authorized, payload);
+        case 'wait':
+            return service.wait(authorized, {
+                ...payload,
+                ...(context
+                    ? { signal: context.signal, interrupt: context.waitInterrupt }
+                    : requestSignal
+                        ? { signal: requestSignal }
+                        : {})
+            });
+        case 'list':
+            return service.list(actor, payload);
+        case 'view':
+            return service.view(actor, payload);
+    }
+}
+/** Node broker injects the caller only after validating the Server-issued Execution credential. */
+export function agentNetworkExecutionCommand(input) {
+    return async (data) => {
+        if (!isPlainRecord(data) ||
+            !isPlainRecord(data.__marctlCaller) ||
+            typeof data.__requestUserId !== 'number' ||
+            typeof data.workspaceId !== 'string' ||
+            !['start', 'send', 'wait', 'stop', 'list', 'view'].includes(String(data.action)) ||
+            !isPlainRecord(data.input))
+            throw new Error('MARCTL_EXECUTION_CREDENTIAL_INVALID');
+        if (data.__marctlCaller.type === 'terminal') {
+            if (!input.observations ||
+                !Number.isSafeInteger(data.__requestUserId) ||
+                data.__requestUserId <= 0)
+                throw new Error('MARCTL_EXECUTION_CREDENTIAL_INVALID');
+            const observationId = `terminal:${randomUUID()}`;
+            const observer = input.observations.attach(observationId);
+            const environment = isPlainRecord(data.secretEnvironment) &&
+                Object.values(data.secretEnvironment).every((value) => typeof value === 'string')
+                ? data.secretEnvironment
+                : {};
+            const usageGrant = modelUsageGrantSchema.safeParse(data.__usageGrant);
+            const actor = actorForAuthenticatedTerminal({
+                sessionId: '',
+                observationId,
+                requestUserId: data.__requestUserId,
+                secretEnvironment: environment,
+                runnerConfiguration: {
+                    marAgentModel: data.marAgentModel,
+                    marAgentModels: data.marAgentModels,
+                    marAgentCompact: data.marAgentCompact,
+                    marAgentRuntimeScopeId: data.marAgentRuntimeScopeId
+                },
+                ...(usageGrant.success ? { usageGrant: usageGrant.data } : {}),
+                ...(typeof data.personalInstructions === 'string'
+                    ? { personalInstructions: data.personalInstructions }
+                    : {})
+            }, data.workspaceId);
+            try {
+                return await invokeAgentNetwork(input.service, actor, data.action, data.input, undefined, data.__requestAbortSignal instanceof AbortSignal ? data.__requestAbortSignal : undefined);
+            }
+            finally {
+                observer.close();
+            }
+        }
+        if (data.__marctlCaller.type !== 'execution' ||
+            typeof data.__marctlCaller.sessionId !== 'string' ||
+            typeof data.__marctlCaller.executionId !== 'string')
+            throw new Error('MARCTL_EXECUTION_CREDENTIAL_INVALID');
+        const actor = executionAgentActor({
+            ...input,
+            sessionId: data.__marctlCaller.sessionId,
+            executionId: data.__marctlCaller.executionId
+        });
+        const session = input.runtime.getAgentSession(actor.sessionId);
+        if (actor.requestUserId !== data.__requestUserId || session?.workspaceId !== data.workspaceId)
+            throw new Error('MARCTL_EXECUTION_CREDENTIAL_INVALID');
+        const profileQuery = data.action === 'list' && data.input.scope === 'profile' && data.input.runner === 'mar-agent';
+        const resources = (['start', 'send'].includes(String(data.action)) || profileQuery) &&
+            isPlainRecord(data.__marctlExecutionResources)
+            ? data.__marctlExecutionResources
+            : undefined;
+        const boundActor = resources === undefined
+            ? actor
+            : {
+                ...actor,
+                runnerConfiguration: {
+                    ...actor.runnerConfiguration,
+                    marAgentModel: resources.marAgentModel,
+                    marAgentModels: resources.marAgentModels,
+                    marAgentCompact: resources.marAgentCompact,
+                    marAgentRuntimeScopeId: resources.marAgentRuntimeScopeId
+                }
+            };
+        return invokeAgentNetwork(input.service, boundActor, data.action, data.input, undefined, data.__requestAbortSignal instanceof AbortSignal ? data.__requestAbortSignal : undefined);
+    };
+}

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

@@ -0,0 +1,377 @@
+import { isPlainRecord } from '../util/records.js';
+export function agentObservationFromRunEvent(input) {
+    if (input.terminalStatus !== undefined)
+        return { kind: 'terminal', value: input.terminalStatus };
+    if (input.eventType === 'conversation.item' &&
+        isPlainRecord(input.payload) &&
+        input.payload.kind === 'assistant_message' &&
+        input.payload.status === 'COMPLETED' &&
+        isPlainRecord(input.payload.payload) &&
+        typeof input.payload.payload.text === 'string' &&
+        input.payload.payload.text.length > 0)
+        return {
+            kind: 'message',
+            value: input.payload.payload.text,
+            ...(input.payload.payload.phase === 'final_answer' ? { final: true } : {}),
+            ...(typeof input.payload.turnId === 'string' ? { turnId: input.payload.turnId } : {})
+        };
+    if (input.eventType === 'conversation.item' &&
+        isPlainRecord(input.payload) &&
+        input.payload.kind === 'file_change' &&
+        input.payload.status === 'COMPLETED' &&
+        isPlainRecord(input.payload.payload) &&
+        Array.isArray(input.payload.payload.changes)) {
+        const paths = input.payload.payload.changes.flatMap((change) => isPlainRecord(change) && typeof change.path === 'string' && change.path.length > 0
+            ? [change.path]
+            : []);
+        if (paths.length)
+            return { kind: 'files', paths };
+    }
+    return undefined;
+}
+/** Volatile, session-owned delivery of live direct-child observations. */
+export class AgentNetworkObservations {
+    #parents = new Map();
+    attach(parentId) {
+        if (this.#parents.has(parentId))
+            throw new Error('AGENT_NETWORK_PARENT_ALREADY_ATTACHED');
+        const parent = new ParentObservations(() => {
+            for (const [id, current] of this.#parents)
+                if (current === parent)
+                    this.#parents.delete(id);
+        });
+        this.#parents.set(parentId, parent);
+        return parent;
+    }
+    get(parentId) {
+        return this.#parents.get(parentId);
+    }
+    publish(input) {
+        this.#parents.get(input.parentId)?.publish(input);
+    }
+    /** Direct children are automatic; other Sessions are watched only when explicitly targeted. */
+    publishChild(input) {
+        for (const [parentId, parent] of this.#parents) {
+            if (parentId === input.parentId || parent.observes(input.childId))
+                parent.publish(input);
+        }
+    }
+    promote(previousId, nextId) {
+        if (previousId === nextId)
+            return;
+        const parent = this.#parents.get(previousId);
+        if (parent === undefined)
+            return;
+        if (this.#parents.has(nextId))
+            throw new Error('AGENT_NETWORK_PARENT_ALREADY_ATTACHED');
+        this.#parents.delete(previousId);
+        this.#parents.set(nextId, parent);
+    }
+}
+export class ParentObservations {
+    detach;
+    #items = new Map();
+    #results = new Map();
+    #listeners = new Set();
+    #wakeListeners = new Set();
+    #targets = new Set();
+    #revision = 0;
+    #closed = false;
+    constructor(detach) {
+        this.detach = detach;
+    }
+    observe(childId) {
+        if (!this.#closed)
+            this.#targets.add(childId);
+    }
+    observes(childId) {
+        return this.#targets.has(childId);
+    }
+    wake = {
+        pending: () => [...this.#items.values()].some((item) => item.kind === 'message' && item.wakes !== false),
+        subscribe: (listener) => {
+            if (!this.#closed)
+                this.#wakeListeners.add(listener);
+            return () => this.#wakeListeners.delete(listener);
+        }
+    };
+    /** Queue an upward report for natural collection without waking the parent. */
+    report(input) {
+        if (this.#closed)
+            return false;
+        const value = boundedUtf8(input.value, 2000);
+        this.#items.set(JSON.stringify([input.childId, input.runId, input.executionId, 'report']), {
+            revision: ++this.#revision,
+            childId: input.childId,
+            runId: input.runId,
+            executionId: input.executionId,
+            kind: 'message',
+            value: value.value,
+            truncated: value.truncated,
+            wakes: false
+        });
+        return true;
+    }
+    /** Waiters also need terminal notifications; sleeping model turns only wake for messages. */
+    subscribe(listener) {
+        if (!this.#closed)
+            this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    publish(input) {
+        if (this.#closed)
+            return;
+        const { childId, runId, executionId, kind } = input;
+        const resultKey = JSON.stringify([childId, runId, executionId]);
+        if (kind === 'terminal' && input.value !== 'SUCCEEDED') {
+            const result = this.#results.get(resultKey);
+            if (result) {
+                result.revision = ++this.#revision;
+                delete result.summary;
+                delete result.summaryTruncated;
+            }
+        }
+        if (kind === 'files' || (kind === 'message' && input.final)) {
+            const result = this.#results.get(resultKey) ?? { changedFiles: [], revision: 0 };
+            result.revision = ++this.#revision;
+            if (kind === 'files') {
+                for (const path of input.paths) {
+                    if (result.changedFiles.includes(path))
+                        continue;
+                    if (result.changedFiles.length >= 200) {
+                        result.changedFilesTruncated = true;
+                        break;
+                    }
+                    result.changedFiles.push(path);
+                }
+            }
+            else {
+                const summary = boundedUtf8(input.value, 16_384);
+                result.summary = summary.value;
+                if (summary.truncated)
+                    result.summaryTruncated = true;
+                else
+                    delete result.summaryTruncated;
+                if (input.turnId)
+                    result.turnId = input.turnId;
+                else
+                    delete result.turnId;
+            }
+            this.#results.set(resultKey, result);
+        }
+        if (kind === 'files')
+            return;
+        const { value } = input;
+        const bounded = boundedUtf8(value, 2_000);
+        const key = JSON.stringify([childId, runId, executionId, kind]);
+        this.#items.set(key, {
+            revision: ++this.#revision,
+            childId,
+            runId,
+            executionId,
+            kind,
+            value: bounded.value,
+            truncated: bounded.truncated,
+            ...(input.final ? { final: true } : {})
+        });
+        const terminalSnapshot = kind === 'terminal' ? this.capture(childId, executionId) : undefined;
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(terminalSnapshot);
+            }
+            catch {
+                // An observer must not interrupt authoritative Run publication or cleanup.
+            }
+        }
+        if (kind === 'message')
+            for (const listener of [...this.#wakeListeners]) {
+                try {
+                    listener();
+                }
+                catch {
+                    /* A wake observer cannot affect Run publication. */
+                }
+            }
+    }
+    collect(signal) {
+        signal.throwIfAborted();
+        const children = [...new Set([...this.#items.values()].map((item) => item.childId))].slice(0, 8);
+        return children.map((childId) => {
+            const snapshot = this.capture(childId);
+            const updates = snapshot.result?.summary && !snapshot.result.summaryTruncated
+                ? snapshot.updates.filter((item) => !item.final)
+                : snapshot.updates;
+            const content = boundedObservation({
+                agentId: snapshot.childId,
+                runId: snapshot.runId,
+                executionId: snapshot.executionId,
+                ...snapshot.result,
+                updates: updates.map((item) => ({
+                    kind: item.kind,
+                    value: item.value,
+                    ...(item.truncated ? { truncated: true } : {})
+                }))
+            });
+            return {
+                content,
+                acknowledge: snapshot.acknowledge
+            };
+        });
+    }
+    /** Capture the same versions used by automatic collection for wait/send consumption. */
+    capture(childId, executionId) {
+        const group = [];
+        for (const [key, item] of this.#items) {
+            if (item.childId !== childId ||
+                (executionId !== undefined && item.executionId !== executionId))
+                continue;
+            const first = group[0]?.[1];
+            if (first && (first.runId !== item.runId || first.executionId !== item.executionId))
+                continue;
+            group.push([key, item]);
+        }
+        const first = group[0]?.[1];
+        if (!first)
+            return undefined;
+        const resultKey = JSON.stringify([childId, first.runId, first.executionId]);
+        const stored = group.some(([, item]) => item.kind === 'terminal')
+            ? this.#results.get(resultKey)
+            : undefined;
+        const result = stored && {
+            ...(stored.summary === undefined ? {} : { summary: stored.summary }),
+            ...(stored.summaryTruncated ? { summaryTruncated: true } : {}),
+            ...(stored.turnId ? { turnId: stored.turnId } : {}),
+            changedFiles: [...stored.changedFiles],
+            ...(stored.changedFilesTruncated ? { changedFilesTruncated: true } : {})
+        };
+        const resultRevision = stored?.revision;
+        return {
+            childId,
+            runId: first.runId,
+            executionId: first.executionId,
+            firstRevision: Math.min(...group.map(([, item]) => item.revision)),
+            ...(result === undefined ? {} : { result }),
+            updates: group.map(([, item]) => ({
+                kind: item.kind,
+                value: item.value,
+                truncated: item.truncated,
+                ...(item.final ? { final: true } : {})
+            })),
+            acknowledge: () => {
+                let terminalAcknowledged = false;
+                for (const [key, item] of group) {
+                    if (this.#items.get(key)?.revision !== item.revision)
+                        continue;
+                    this.#items.delete(key);
+                    if (item.kind === 'terminal')
+                        terminalAcknowledged = true;
+                }
+                if (terminalAcknowledged && this.#results.get(resultKey)?.revision === resultRevision)
+                    this.#results.delete(resultKey);
+            }
+        };
+    }
+    captureBeforeSend(childId) {
+        const captured = [...this.#items].filter(([, item]) => item.childId === childId);
+        const results = new Map(captured
+            .filter(([, item]) => item.kind === 'terminal')
+            .map(([, item]) => {
+            const key = JSON.stringify([item.childId, item.runId, item.executionId]);
+            return [key, this.#results.get(key)?.revision];
+        }));
+        return {
+            acknowledge: () => {
+                for (const [key, item] of captured) {
+                    if (this.#items.get(key)?.revision !== item.revision)
+                        continue;
+                    this.#items.delete(key);
+                    if (item.kind === 'terminal') {
+                        const resultKey = JSON.stringify([item.childId, item.runId, item.executionId]);
+                        if (this.#results.get(resultKey)?.revision === results.get(resultKey))
+                            this.#results.delete(resultKey);
+                    }
+                }
+            }
+        };
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#items.clear();
+        this.#results.clear();
+        this.#listeners.clear();
+        this.#wakeListeners.clear();
+        this.#targets.clear();
+        this.detach();
+    }
+}
+function boundedUtf8(value, maximum) {
+    const bytes = Buffer.from(value, 'utf8');
+    if (bytes.length <= maximum)
+        return { value, truncated: false };
+    let end = maximum;
+    while (end > 0 && (bytes[end] & 0xc0) === 0x80)
+        end--;
+    return { value: bytes.subarray(0, end).toString('utf8'), truncated: true };
+}
+function boundedObservation(input) {
+    const data = {
+        ...input,
+        ...(input.changedFiles ? { changedFiles: [...input.changedFiles] } : {}),
+        updates: input.updates.map((update) => ({ ...update }))
+    };
+    let updatesTruncated = false;
+    const render = () => `<mar_subagent_update>\n${JSON.stringify({
+        ...data,
+        ...(updatesTruncated ? { updatesTruncated: true } : {})
+    }).replace(/[<>&]/g, (character) => character === '<' ? '\\u003c' : character === '>' ? '\\u003e' : '\\u0026')}\n</mar_subagent_update>`;
+    const tooLarge = () => Buffer.byteLength(render(), 'utf8') > 32768;
+    while (tooLarge() && data.changedFiles?.length) {
+        data.changedFiles.pop();
+        data.changedFilesTruncated = true;
+    }
+    const shorten = (value, set) => {
+        let low = 0;
+        let high = Buffer.byteLength(value, 'utf8');
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            set(boundedUtf8(value, middle).value);
+            if (tooLarge())
+                high = middle - 1;
+            else
+                low = middle;
+        }
+        set(boundedUtf8(value, low).value);
+    };
+    if (tooLarge() && data.summary !== undefined) {
+        const summary = data.summary;
+        data.summaryTruncated = true;
+        shorten(summary, (value) => {
+            data.summary = value;
+        });
+    }
+    for (const update of data.updates) {
+        if (!tooLarge())
+            break;
+        const value = update.value;
+        update.truncated = true;
+        shorten(value, (text) => {
+            update.value = text;
+        });
+    }
+    while (tooLarge() && data.updates.length) {
+        data.updates.pop();
+        updatesTruncated = true;
+    }
+    if (tooLarge()) {
+        const fallback = {
+            agentId: boundedUtf8(data.agentId, 512).value,
+            runId: boundedUtf8(data.runId, 512).value,
+            executionId: boundedUtf8(data.executionId, 512).value,
+            detailsTruncated: true
+        };
+        return `<mar_subagent_update>\n${JSON.stringify(fallback).replace(/[<>&]/g, (character) => character === '<' ? '\\u003c' : character === '>' ? '\\u003e' : '\\u0026')}\n</mar_subagent_update>`;
+    }
+    return render();
+}