@intent-systems/nexus 2026.1.5-3

package/dist/agents/tools/sessions-send-tool.js

@@ -0,0 +1,371 @@
+import crypto from "node:crypto";
+import { Type } from "@sinclair/typebox";
+import { loadConfig } from "../../config/config.js";
+import { callGateway } from "../../gateway/call.js";
+import { isSubagentSessionKey, normalizeAgentId, parseAgentSessionKey, } from "../../routing/session-key.js";
+import { readLatestAssistantReply, runAgentStep } from "./agent-step.js";
+import { jsonResult, readStringParam } from "./common.js";
+import { resolveAnnounceTarget } from "./sessions-announce-target.js";
+import { extractAssistantText, resolveDisplaySessionKey, resolveInternalSessionKey, resolveMainSessionAlias, stripToolMessages, } from "./sessions-helpers.js";
+import { buildAgentToAgentAnnounceContext, buildAgentToAgentMessageContext, buildAgentToAgentReplyContext, isAnnounceSkip, isReplySkip, resolvePingPongTurns, } from "./sessions-send-helpers.js";
+const SessionsSendToolSchema = Type.Object({
+    sessionKey: Type.String(),
+    message: Type.String(),
+    timeoutSeconds: Type.Optional(Type.Integer({ minimum: 0 })),
+});
+export function createSessionsSendTool(opts) {
+    return {
+        label: "Session Send",
+        name: "sessions_send",
+        description: "Send a message into another session.",
+        parameters: SessionsSendToolSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const sessionKey = readStringParam(params, "sessionKey", {
+                required: true,
+            });
+            const message = readStringParam(params, "message", { required: true });
+            const cfg = loadConfig();
+            const { mainKey, alias } = resolveMainSessionAlias(cfg);
+            const visibility = cfg.agent?.sandbox?.sessionToolsVisibility ?? "spawned";
+            const requesterInternalKey = typeof opts?.agentSessionKey === "string" && opts.agentSessionKey.trim()
+                ? resolveInternalSessionKey({
+                    key: opts.agentSessionKey,
+                    alias,
+                    mainKey,
+                })
+                : undefined;
+            const resolvedKey = resolveInternalSessionKey({
+                key: sessionKey,
+                alias,
+                mainKey,
+            });
+            const restrictToSpawned = opts?.sandboxed === true &&
+                visibility === "spawned" &&
+                requesterInternalKey &&
+                !isSubagentSessionKey(requesterInternalKey);
+            if (restrictToSpawned) {
+                try {
+                    const list = (await callGateway({
+                        method: "sessions.list",
+                        params: {
+                            includeGlobal: false,
+                            includeUnknown: false,
+                            limit: 500,
+                            spawnedBy: requesterInternalKey,
+                        },
+                    }));
+                    const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
+                    const ok = sessions.some((entry) => entry?.key === resolvedKey);
+                    if (!ok) {
+                        return jsonResult({
+                            runId: crypto.randomUUID(),
+                            status: "forbidden",
+                            error: `Session not visible from this sandboxed agent session: ${sessionKey}`,
+                            sessionKey: resolveDisplaySessionKey({
+                                key: sessionKey,
+                                alias,
+                                mainKey,
+                            }),
+                        });
+                    }
+                }
+                catch {
+                    return jsonResult({
+                        runId: crypto.randomUUID(),
+                        status: "forbidden",
+                        error: `Session not visible from this sandboxed agent session: ${sessionKey}`,
+                        sessionKey: resolveDisplaySessionKey({
+                            key: sessionKey,
+                            alias,
+                            mainKey,
+                        }),
+                    });
+                }
+            }
+            const timeoutSeconds = typeof params.timeoutSeconds === "number" &&
+                Number.isFinite(params.timeoutSeconds)
+                ? Math.max(0, Math.floor(params.timeoutSeconds))
+                : 30;
+            const timeoutMs = timeoutSeconds * 1000;
+            const announceTimeoutMs = timeoutSeconds === 0 ? 30_000 : timeoutMs;
+            const idempotencyKey = crypto.randomUUID();
+            let runId = idempotencyKey;
+            const displayKey = resolveDisplaySessionKey({
+                key: sessionKey,
+                alias,
+                mainKey,
+            });
+            const routingA2A = cfg.routing?.agentToAgent;
+            const a2aEnabled = routingA2A?.enabled === true;
+            const allowPatterns = Array.isArray(routingA2A?.allow)
+                ? routingA2A.allow
+                : [];
+            const matchesAllow = (agentId) => {
+                if (allowPatterns.length === 0)
+                    return true;
+                return allowPatterns.some((pattern) => {
+                    const raw = String(pattern ?? "").trim();
+                    if (!raw)
+                        return false;
+                    if (raw === "*")
+                        return true;
+                    if (!raw.includes("*"))
+                        return raw === agentId;
+                    const escaped = raw.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+                    const re = new RegExp(`^${escaped.replaceAll("\\*", ".*")}$`, "i");
+                    return re.test(agentId);
+                });
+            };
+            const requesterAgentId = normalizeAgentId(parseAgentSessionKey(requesterInternalKey)?.agentId);
+            const targetAgentId = normalizeAgentId(parseAgentSessionKey(resolvedKey)?.agentId);
+            const isCrossAgent = requesterAgentId !== targetAgentId;
+            if (isCrossAgent) {
+                if (!a2aEnabled) {
+                    return jsonResult({
+                        runId: crypto.randomUUID(),
+                        status: "forbidden",
+                        error: "Agent-to-agent messaging is disabled. Set routing.agentToAgent.enabled=true to allow cross-agent sends.",
+                        sessionKey: displayKey,
+                    });
+                }
+                if (!matchesAllow(requesterAgentId) || !matchesAllow(targetAgentId)) {
+                    return jsonResult({
+                        runId: crypto.randomUUID(),
+                        status: "forbidden",
+                        error: "Agent-to-agent messaging denied by routing.agentToAgent.allow.",
+                        sessionKey: displayKey,
+                    });
+                }
+            }
+            const agentMessageContext = buildAgentToAgentMessageContext({
+                requesterSessionKey: opts?.agentSessionKey,
+                requesterProvider: opts?.agentProvider,
+                targetSessionKey: displayKey,
+            });
+            const sendParams = {
+                message,
+                sessionKey: resolvedKey,
+                idempotencyKey,
+                deliver: false,
+                lane: "nested",
+                extraSystemPrompt: agentMessageContext,
+            };
+            const requesterSessionKey = opts?.agentSessionKey;
+            const requesterProvider = opts?.agentProvider;
+            const maxPingPongTurns = resolvePingPongTurns(cfg);
+            const runAgentToAgentFlow = async (roundOneReply, runInfo) => {
+                try {
+                    let primaryReply = roundOneReply;
+                    let latestReply = roundOneReply;
+                    if (!primaryReply && runInfo?.runId) {
+                        const waitMs = Math.min(announceTimeoutMs, 60_000);
+                        const wait = (await callGateway({
+                            method: "agent.wait",
+                            params: {
+                                runId: runInfo.runId,
+                                timeoutMs: waitMs,
+                            },
+                            timeoutMs: waitMs + 2000,
+                        }));
+                        if (wait?.status === "ok") {
+                            primaryReply = await readLatestAssistantReply({
+                                sessionKey: resolvedKey,
+                            });
+                            latestReply = primaryReply;
+                        }
+                    }
+                    if (!latestReply)
+                        return;
+                    const announceTarget = await resolveAnnounceTarget({
+                        sessionKey: resolvedKey,
+                        displayKey,
+                    });
+                    const targetProvider = announceTarget?.provider ?? "unknown";
+                    if (maxPingPongTurns > 0 &&
+                        requesterSessionKey &&
+                        requesterSessionKey !== resolvedKey) {
+                        let currentSessionKey = requesterSessionKey;
+                        let nextSessionKey = resolvedKey;
+                        let incomingMessage = latestReply;
+                        for (let turn = 1; turn <= maxPingPongTurns; turn += 1) {
+                            const currentRole = currentSessionKey === requesterSessionKey
+                                ? "requester"
+                                : "target";
+                            const replyPrompt = buildAgentToAgentReplyContext({
+                                requesterSessionKey,
+                                requesterProvider,
+                                targetSessionKey: displayKey,
+                                targetProvider,
+                                currentRole,
+                                turn,
+                                maxTurns: maxPingPongTurns,
+                            });
+                            const replyText = await runAgentStep({
+                                sessionKey: currentSessionKey,
+                                message: incomingMessage,
+                                extraSystemPrompt: replyPrompt,
+                                timeoutMs: announceTimeoutMs,
+                                lane: "nested",
+                            });
+                            if (!replyText || isReplySkip(replyText)) {
+                                break;
+                            }
+                            latestReply = replyText;
+                            incomingMessage = replyText;
+                            const swap = currentSessionKey;
+                            currentSessionKey = nextSessionKey;
+                            nextSessionKey = swap;
+                        }
+                    }
+                    const announcePrompt = buildAgentToAgentAnnounceContext({
+                        requesterSessionKey,
+                        requesterProvider,
+                        targetSessionKey: displayKey,
+                        targetProvider,
+                        originalMessage: message,
+                        roundOneReply: primaryReply,
+                        latestReply,
+                    });
+                    const announceReply = await runAgentStep({
+                        sessionKey: resolvedKey,
+                        message: "Agent-to-agent announce step.",
+                        extraSystemPrompt: announcePrompt,
+                        timeoutMs: announceTimeoutMs,
+                        lane: "nested",
+                    });
+                    if (announceTarget &&
+                        announceReply &&
+                        announceReply.trim() &&
+                        !isAnnounceSkip(announceReply)) {
+                        await callGateway({
+                            method: "send",
+                            params: {
+                                to: announceTarget.to,
+                                message: announceReply.trim(),
+                                provider: announceTarget.provider,
+                                accountId: announceTarget.accountId,
+                                idempotencyKey: crypto.randomUUID(),
+                            },
+                            timeoutMs: 10_000,
+                        });
+                    }
+                }
+                catch {
+                    // Best-effort follow-ups; ignore failures to avoid breaking the caller response.
+                }
+            };
+            if (timeoutSeconds === 0) {
+                try {
+                    const response = (await callGateway({
+                        method: "agent",
+                        params: sendParams,
+                        timeoutMs: 10_000,
+                    }));
+                    if (typeof response?.runId === "string" && response.runId) {
+                        runId = response.runId;
+                    }
+                    void runAgentToAgentFlow(undefined, { runId });
+                    return jsonResult({
+                        runId,
+                        status: "accepted",
+                        sessionKey: displayKey,
+                    });
+                }
+                catch (err) {
+                    const messageText = err instanceof Error
+                        ? err.message
+                        : typeof err === "string"
+                            ? err
+                            : "error";
+                    return jsonResult({
+                        runId,
+                        status: "error",
+                        error: messageText,
+                        sessionKey: displayKey,
+                    });
+                }
+            }
+            try {
+                const response = (await callGateway({
+                    method: "agent",
+                    params: sendParams,
+                    timeoutMs: 10_000,
+                }));
+                if (typeof response?.runId === "string" && response.runId) {
+                    runId = response.runId;
+                }
+            }
+            catch (err) {
+                const messageText = err instanceof Error
+                    ? err.message
+                    : typeof err === "string"
+                        ? err
+                        : "error";
+                return jsonResult({
+                    runId,
+                    status: "error",
+                    error: messageText,
+                    sessionKey: displayKey,
+                });
+            }
+            let waitStatus;
+            let waitError;
+            try {
+                const wait = (await callGateway({
+                    method: "agent.wait",
+                    params: {
+                        runId,
+                        timeoutMs,
+                    },
+                    timeoutMs: timeoutMs + 2000,
+                }));
+                waitStatus = typeof wait?.status === "string" ? wait.status : undefined;
+                waitError = typeof wait?.error === "string" ? wait.error : undefined;
+            }
+            catch (err) {
+                const messageText = err instanceof Error
+                    ? err.message
+                    : typeof err === "string"
+                        ? err
+                        : "error";
+                return jsonResult({
+                    runId,
+                    status: messageText.includes("gateway timeout") ? "timeout" : "error",
+                    error: messageText,
+                    sessionKey: displayKey,
+                });
+            }
+            if (waitStatus === "timeout") {
+                return jsonResult({
+                    runId,
+                    status: "timeout",
+                    error: waitError,
+                    sessionKey: displayKey,
+                });
+            }
+            if (waitStatus === "error") {
+                return jsonResult({
+                    runId,
+                    status: "error",
+                    error: waitError ?? "agent error",
+                    sessionKey: displayKey,
+                });
+            }
+            const history = (await callGateway({
+                method: "chat.history",
+                params: { sessionKey: resolvedKey, limit: 50 },
+            }));
+            const filtered = stripToolMessages(Array.isArray(history?.messages) ? history.messages : []);
+            const last = filtered.length > 0 ? filtered[filtered.length - 1] : undefined;
+            const reply = last ? extractAssistantText(last) : undefined;
+            void runAgentToAgentFlow(reply ?? undefined);
+            return jsonResult({
+                runId,
+                status: "ok",
+                reply,
+                sessionKey: displayKey,
+            });
+        },
+    };
+}

package/dist/agents/tools/sessions-spawn-tool.js

@@ -0,0 +1,319 @@
+import crypto from "node:crypto";
+import { Type } from "@sinclair/typebox";
+import { loadConfig } from "../../config/config.js";
+import { callGateway } from "../../gateway/call.js";
+import { isSubagentSessionKey, normalizeAgentId, parseAgentSessionKey, } from "../../routing/session-key.js";
+import { readLatestAssistantReply, runAgentStep } from "./agent-step.js";
+import { jsonResult, readStringParam } from "./common.js";
+import { resolveAnnounceTarget } from "./sessions-announce-target.js";
+import { resolveDisplaySessionKey, resolveInternalSessionKey, resolveMainSessionAlias, } from "./sessions-helpers.js";
+import { isAnnounceSkip } from "./sessions-send-helpers.js";
+const SessionsSpawnToolSchema = Type.Object({
+    task: Type.String(),
+    label: Type.Optional(Type.String()),
+    timeoutSeconds: Type.Optional(Type.Integer({ minimum: 0 })),
+    cleanup: Type.Optional(Type.Union([Type.Literal("delete"), Type.Literal("keep")])),
+});
+function buildSubagentSystemPrompt(params) {
+    const lines = [
+        "Sub-agent context:",
+        params.label ? `Label: ${params.label}` : undefined,
+        params.requesterSessionKey
+            ? `Requester session: ${params.requesterSessionKey}.`
+            : undefined,
+        params.requesterProvider
+            ? `Requester provider: ${params.requesterProvider}.`
+            : undefined,
+        `Your session: ${params.childSessionKey}.`,
+        "Run the task. Provide a clear final answer (plain text).",
+        'After you finish, you may be asked to produce an "announce" message to post back to the requester chat.',
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+function buildSubagentAnnouncePrompt(params) {
+    const lines = [
+        "Sub-agent announce step:",
+        params.requesterSessionKey
+            ? `Requester session: ${params.requesterSessionKey}.`
+            : undefined,
+        params.requesterProvider
+            ? `Requester provider: ${params.requesterProvider}.`
+            : undefined,
+        `Post target provider: ${params.announceChannel}.`,
+        `Original task: ${params.task}`,
+        params.subagentReply
+            ? `Sub-agent result: ${params.subagentReply}`
+            : "Sub-agent result: (not available).",
+        'Reply exactly "ANNOUNCE_SKIP" to stay silent.',
+        "Any other reply will be posted to the requester chat provider.",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+async function runSubagentAnnounceFlow(params) {
+    try {
+        let reply = params.roundOneReply;
+        if (!reply) {
+            const waitMs = Math.min(params.timeoutMs, 60_000);
+            const wait = (await callGateway({
+                method: "agent.wait",
+                params: {
+                    runId: params.childRunId,
+                    timeoutMs: waitMs,
+                },
+                timeoutMs: waitMs + 2000,
+            }));
+            if (wait?.status !== "ok")
+                return;
+            reply = await readLatestAssistantReply({
+                sessionKey: params.childSessionKey,
+            });
+        }
+        const announceTarget = await resolveAnnounceTarget({
+            sessionKey: params.requesterSessionKey,
+            displayKey: params.requesterDisplayKey,
+        });
+        if (!announceTarget)
+            return;
+        const announcePrompt = buildSubagentAnnouncePrompt({
+            requesterSessionKey: params.requesterSessionKey,
+            requesterProvider: params.requesterProvider,
+            announceChannel: announceTarget.provider,
+            task: params.task,
+            subagentReply: reply,
+        });
+        const announceReply = await runAgentStep({
+            sessionKey: params.childSessionKey,
+            message: "Sub-agent announce step.",
+            extraSystemPrompt: announcePrompt,
+            timeoutMs: params.timeoutMs,
+            lane: "nested",
+        });
+        if (!announceReply ||
+            !announceReply.trim() ||
+            isAnnounceSkip(announceReply))
+            return;
+        await callGateway({
+            method: "send",
+            params: {
+                to: announceTarget.to,
+                message: announceReply.trim(),
+                provider: announceTarget.provider,
+                accountId: announceTarget.accountId,
+                idempotencyKey: crypto.randomUUID(),
+            },
+            timeoutMs: 10_000,
+        });
+    }
+    catch {
+        // Best-effort follow-ups; ignore failures to avoid breaking the caller response.
+    }
+    finally {
+        if (params.cleanup === "delete") {
+            try {
+                await callGateway({
+                    method: "sessions.delete",
+                    params: { key: params.childSessionKey, deleteTranscript: true },
+                    timeoutMs: 10_000,
+                });
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+export function createSessionsSpawnTool(opts) {
+    return {
+        label: "Sessions",
+        name: "sessions_spawn",
+        description: "Spawn a background sub-agent run in an isolated session and announce the result back to the requester chat.",
+        parameters: SessionsSpawnToolSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const task = readStringParam(params, "task", { required: true });
+            const label = typeof params.label === "string" ? params.label.trim() : "";
+            const cleanup = params.cleanup === "keep" || params.cleanup === "delete"
+                ? params.cleanup
+                : "delete";
+            const timeoutSeconds = typeof params.timeoutSeconds === "number" &&
+                Number.isFinite(params.timeoutSeconds)
+                ? Math.max(0, Math.floor(params.timeoutSeconds))
+                : 0;
+            const timeoutMs = timeoutSeconds * 1000;
+            const cfg = loadConfig();
+            const { mainKey, alias } = resolveMainSessionAlias(cfg);
+            const requesterSessionKey = opts?.agentSessionKey;
+            if (typeof requesterSessionKey === "string" &&
+                isSubagentSessionKey(requesterSessionKey)) {
+                return jsonResult({
+                    status: "forbidden",
+                    error: "sessions_spawn is not allowed from sub-agent sessions",
+                });
+            }
+            const requesterInternalKey = requesterSessionKey
+                ? resolveInternalSessionKey({
+                    key: requesterSessionKey,
+                    alias,
+                    mainKey,
+                })
+                : alias;
+            const requesterDisplayKey = resolveDisplaySessionKey({
+                key: requesterInternalKey,
+                alias,
+                mainKey,
+            });
+            const requesterAgentId = normalizeAgentId(parseAgentSessionKey(requesterInternalKey)?.agentId);
+            const childSessionKey = `agent:${requesterAgentId}:subagent:${crypto.randomUUID()}`;
+            if (opts?.sandboxed === true) {
+                try {
+                    await callGateway({
+                        method: "sessions.patch",
+                        params: { key: childSessionKey, spawnedBy: requesterInternalKey },
+                        timeoutMs: 10_000,
+                    });
+                }
+                catch {
+                    // best-effort; scoping relies on this metadata but spawning still works without it
+                }
+            }
+            const childSystemPrompt = buildSubagentSystemPrompt({
+                requesterSessionKey,
+                requesterProvider: opts?.agentProvider,
+                childSessionKey,
+                label: label || undefined,
+            });
+            const childIdem = crypto.randomUUID();
+            let childRunId = childIdem;
+            try {
+                const response = (await callGateway({
+                    method: "agent",
+                    params: {
+                        message: task,
+                        sessionKey: childSessionKey,
+                        idempotencyKey: childIdem,
+                        deliver: false,
+                        lane: "subagent",
+                        extraSystemPrompt: childSystemPrompt,
+                    },
+                    timeoutMs: 10_000,
+                }));
+                if (typeof response?.runId === "string" && response.runId) {
+                    childRunId = response.runId;
+                }
+            }
+            catch (err) {
+                const messageText = err instanceof Error
+                    ? err.message
+                    : typeof err === "string"
+                        ? err
+                        : "error";
+                return jsonResult({
+                    status: "error",
+                    error: messageText,
+                    childSessionKey,
+                    runId: childRunId,
+                });
+            }
+            if (timeoutSeconds === 0) {
+                void runSubagentAnnounceFlow({
+                    childSessionKey,
+                    childRunId,
+                    requesterSessionKey: requesterInternalKey,
+                    requesterProvider: opts?.agentProvider,
+                    requesterDisplayKey,
+                    task,
+                    timeoutMs: 30_000,
+                    cleanup,
+                });
+                return jsonResult({
+                    status: "accepted",
+                    childSessionKey,
+                    runId: childRunId,
+                });
+            }
+            let waitStatus;
+            let waitError;
+            try {
+                const wait = (await callGateway({
+                    method: "agent.wait",
+                    params: {
+                        runId: childRunId,
+                        timeoutMs,
+                    },
+                    timeoutMs: timeoutMs + 2000,
+                }));
+                waitStatus = typeof wait?.status === "string" ? wait.status : undefined;
+                waitError = typeof wait?.error === "string" ? wait.error : undefined;
+            }
+            catch (err) {
+                const messageText = err instanceof Error
+                    ? err.message
+                    : typeof err === "string"
+                        ? err
+                        : "error";
+                return jsonResult({
+                    status: messageText.includes("gateway timeout") ? "timeout" : "error",
+                    error: messageText,
+                    childSessionKey,
+                    runId: childRunId,
+                });
+            }
+            if (waitStatus === "timeout") {
+                void runSubagentAnnounceFlow({
+                    childSessionKey,
+                    childRunId,
+                    requesterSessionKey: requesterInternalKey,
+                    requesterProvider: opts?.agentProvider,
+                    requesterDisplayKey,
+                    task,
+                    timeoutMs: 30_000,
+                    cleanup,
+                });
+                return jsonResult({
+                    status: "timeout",
+                    error: waitError,
+                    childSessionKey,
+                    runId: childRunId,
+                });
+            }
+            if (waitStatus === "error") {
+                void runSubagentAnnounceFlow({
+                    childSessionKey,
+                    childRunId,
+                    requesterSessionKey: requesterInternalKey,
+                    requesterProvider: opts?.agentProvider,
+                    requesterDisplayKey,
+                    task,
+                    timeoutMs: 30_000,
+                    cleanup,
+                });
+                return jsonResult({
+                    status: "error",
+                    error: waitError ?? "agent error",
+                    childSessionKey,
+                    runId: childRunId,
+                });
+            }
+            const replyText = await readLatestAssistantReply({
+                sessionKey: childSessionKey,
+            });
+            void runSubagentAnnounceFlow({
+                childSessionKey,
+                childRunId,
+                requesterSessionKey: requesterInternalKey,
+                requesterProvider: opts?.agentProvider,
+                requesterDisplayKey,
+                task,
+                timeoutMs: 30_000,
+                cleanup,
+                roundOneReply: replyText,
+            });
+            return jsonResult({
+                status: "ok",
+                childSessionKey,
+                runId: childRunId,
+                reply: replyText,
+            });
+        },
+    };
+}