@intent-systems/nexus 2026.1.5-3

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

@@ -0,0 +1,137 @@
+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 { jsonResult, readStringParam } from "./common.js";
+import { resolveDisplaySessionKey, resolveInternalSessionKey, resolveMainSessionAlias, stripToolMessages, } from "./sessions-helpers.js";
+const SessionsHistoryToolSchema = Type.Object({
+    sessionKey: Type.String(),
+    limit: Type.Optional(Type.Integer({ minimum: 1 })),
+    includeTools: Type.Optional(Type.Boolean()),
+});
+function resolveSandboxSessionToolsVisibility(cfg) {
+    return cfg.agent?.sandbox?.sessionToolsVisibility ?? "spawned";
+}
+async function isSpawnedSessionAllowed(params) {
+    try {
+        const list = (await callGateway({
+            method: "sessions.list",
+            params: {
+                includeGlobal: false,
+                includeUnknown: false,
+                limit: 500,
+                spawnedBy: params.requesterSessionKey,
+            },
+        }));
+        const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
+        return sessions.some((entry) => entry?.key === params.targetSessionKey);
+    }
+    catch {
+        return false;
+    }
+}
+export function createSessionsHistoryTool(opts) {
+    return {
+        label: "Session History",
+        name: "sessions_history",
+        description: "Fetch message history for a session.",
+        parameters: SessionsHistoryToolSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const sessionKey = readStringParam(params, "sessionKey", {
+                required: true,
+            });
+            const cfg = loadConfig();
+            const { mainKey, alias } = resolveMainSessionAlias(cfg);
+            const visibility = resolveSandboxSessionToolsVisibility(cfg);
+            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) {
+                const ok = await isSpawnedSessionAllowed({
+                    requesterSessionKey: requesterInternalKey,
+                    targetSessionKey: resolvedKey,
+                });
+                if (!ok) {
+                    return jsonResult({
+                        status: "forbidden",
+                        error: `Session not visible from this sandboxed agent session: ${sessionKey}`,
+                    });
+                }
+            }
+            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({
+                        status: "forbidden",
+                        error: "Agent-to-agent history is disabled. Set routing.agentToAgent.enabled=true to allow cross-agent access.",
+                    });
+                }
+                if (!matchesAllow(requesterAgentId) || !matchesAllow(targetAgentId)) {
+                    return jsonResult({
+                        status: "forbidden",
+                        error: "Agent-to-agent history denied by routing.agentToAgent.allow.",
+                    });
+                }
+            }
+            const limit = typeof params.limit === "number" && Number.isFinite(params.limit)
+                ? Math.max(1, Math.floor(params.limit))
+                : undefined;
+            const includeTools = Boolean(params.includeTools);
+            const result = (await callGateway({
+                method: "chat.history",
+                params: { sessionKey: resolvedKey, limit },
+            }));
+            const rawMessages = Array.isArray(result?.messages)
+                ? result.messages
+                : [];
+            const messages = includeTools
+                ? rawMessages
+                : stripToolMessages(rawMessages);
+            return jsonResult({
+                sessionKey: resolveDisplaySessionKey({
+                    key: sessionKey,
+                    alias,
+                    mainKey,
+                }),
+                messages,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,196 @@
+import path from "node:path";
+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 { jsonResult, readStringArrayParam } from "./common.js";
+import { classifySessionKind, deriveProvider, resolveDisplaySessionKey, resolveInternalSessionKey, resolveMainSessionAlias, stripToolMessages, } from "./sessions-helpers.js";
+const SessionsListToolSchema = Type.Object({
+    kinds: Type.Optional(Type.Array(Type.String())),
+    limit: Type.Optional(Type.Integer({ minimum: 1 })),
+    activeMinutes: Type.Optional(Type.Integer({ minimum: 1 })),
+    messageLimit: Type.Optional(Type.Integer({ minimum: 0 })),
+});
+function resolveSandboxSessionToolsVisibility(cfg) {
+    return cfg.agent?.sandbox?.sessionToolsVisibility ?? "spawned";
+}
+export function createSessionsListTool(opts) {
+    return {
+        label: "Sessions",
+        name: "sessions_list",
+        description: "List sessions with optional filters and last messages.",
+        parameters: SessionsListToolSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const cfg = loadConfig();
+            const { mainKey, alias } = resolveMainSessionAlias(cfg);
+            const visibility = resolveSandboxSessionToolsVisibility(cfg);
+            const requesterInternalKey = typeof opts?.agentSessionKey === "string" && opts.agentSessionKey.trim()
+                ? resolveInternalSessionKey({
+                    key: opts.agentSessionKey,
+                    alias,
+                    mainKey,
+                })
+                : undefined;
+            const restrictToSpawned = opts?.sandboxed === true &&
+                visibility === "spawned" &&
+                requesterInternalKey &&
+                !isSubagentSessionKey(requesterInternalKey);
+            const kindsRaw = readStringArrayParam(params, "kinds")?.map((value) => value.trim().toLowerCase());
+            const allowedKindsList = (kindsRaw ?? []).filter((value) => ["main", "group", "cron", "hook", "node", "other"].includes(value));
+            const allowedKinds = allowedKindsList.length
+                ? new Set(allowedKindsList)
+                : undefined;
+            const limit = typeof params.limit === "number" && Number.isFinite(params.limit)
+                ? Math.max(1, Math.floor(params.limit))
+                : undefined;
+            const activeMinutes = typeof params.activeMinutes === "number" &&
+                Number.isFinite(params.activeMinutes)
+                ? Math.max(1, Math.floor(params.activeMinutes))
+                : undefined;
+            const messageLimitRaw = typeof params.messageLimit === "number" &&
+                Number.isFinite(params.messageLimit)
+                ? Math.max(0, Math.floor(params.messageLimit))
+                : 0;
+            const messageLimit = Math.min(messageLimitRaw, 20);
+            const list = (await callGateway({
+                method: "sessions.list",
+                params: {
+                    limit,
+                    activeMinutes,
+                    includeGlobal: !restrictToSpawned,
+                    includeUnknown: !restrictToSpawned,
+                    spawnedBy: restrictToSpawned ? requesterInternalKey : undefined,
+                },
+            }));
+            const sessions = Array.isArray(list?.sessions) ? list.sessions : [];
+            const storePath = typeof list?.path === "string" ? list.path : undefined;
+            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 rows = [];
+            for (const entry of sessions) {
+                if (!entry || typeof entry !== "object")
+                    continue;
+                const key = typeof entry.key === "string" ? entry.key : "";
+                if (!key)
+                    continue;
+                const entryAgentId = normalizeAgentId(parseAgentSessionKey(key)?.agentId);
+                const crossAgent = entryAgentId !== requesterAgentId;
+                if (crossAgent) {
+                    if (!a2aEnabled)
+                        continue;
+                    if (!matchesAllow(requesterAgentId) || !matchesAllow(entryAgentId))
+                        continue;
+                }
+                if (key === "unknown")
+                    continue;
+                if (key === "global" && alias !== "global")
+                    continue;
+                const gatewayKind = typeof entry.kind === "string" ? entry.kind : undefined;
+                const kind = classifySessionKind({ key, gatewayKind, alias, mainKey });
+                if (allowedKinds && !allowedKinds.has(kind))
+                    continue;
+                const displayKey = resolveDisplaySessionKey({
+                    key,
+                    alias,
+                    mainKey,
+                });
+                const entryProvider = typeof entry.provider === "string" ? entry.provider : undefined;
+                const lastProvider = typeof entry.lastProvider === "string"
+                    ? entry.lastProvider
+                    : undefined;
+                const lastAccountId = typeof entry.lastAccountId === "string"
+                    ? entry.lastAccountId
+                    : undefined;
+                const derivedProvider = deriveProvider({
+                    key,
+                    kind,
+                    provider: entryProvider,
+                    lastProvider,
+                });
+                const sessionId = typeof entry.sessionId === "string" ? entry.sessionId : undefined;
+                const transcriptPath = sessionId && storePath
+                    ? path.join(path.dirname(storePath), `${sessionId}.jsonl`)
+                    : undefined;
+                const row = {
+                    key: displayKey,
+                    kind,
+                    provider: derivedProvider,
+                    displayName: typeof entry.displayName === "string"
+                        ? entry.displayName
+                        : undefined,
+                    updatedAt: typeof entry.updatedAt === "number" ? entry.updatedAt : undefined,
+                    sessionId,
+                    model: typeof entry.model === "string" ? entry.model : undefined,
+                    contextTokens: typeof entry.contextTokens === "number"
+                        ? entry.contextTokens
+                        : undefined,
+                    totalTokens: typeof entry.totalTokens === "number"
+                        ? entry.totalTokens
+                        : undefined,
+                    thinkingLevel: typeof entry.thinkingLevel === "string"
+                        ? entry.thinkingLevel
+                        : undefined,
+                    verboseLevel: typeof entry.verboseLevel === "string"
+                        ? entry.verboseLevel
+                        : undefined,
+                    systemSent: typeof entry.systemSent === "boolean"
+                        ? entry.systemSent
+                        : undefined,
+                    abortedLastRun: typeof entry.abortedLastRun === "boolean"
+                        ? entry.abortedLastRun
+                        : undefined,
+                    sendPolicy: typeof entry.sendPolicy === "string" ? entry.sendPolicy : undefined,
+                    lastProvider,
+                    lastTo: typeof entry.lastTo === "string" ? entry.lastTo : undefined,
+                    lastAccountId,
+                    transcriptPath,
+                };
+                if (messageLimit > 0) {
+                    const resolvedKey = resolveInternalSessionKey({
+                        key: displayKey,
+                        alias,
+                        mainKey,
+                    });
+                    const history = (await callGateway({
+                        method: "chat.history",
+                        params: { sessionKey: resolvedKey, limit: messageLimit },
+                    }));
+                    const rawMessages = Array.isArray(history?.messages)
+                        ? history.messages
+                        : [];
+                    const filtered = stripToolMessages(rawMessages);
+                    row.messages =
+                        filtered.length > messageLimit
+                            ? filtered.slice(-messageLimit)
+                            : filtered;
+                }
+                rows.push(row);
+            }
+            return jsonResult({
+                count: rows.length,
+                sessions: rows,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,103 @@
+const ANNOUNCE_SKIP_TOKEN = "ANNOUNCE_SKIP";
+const REPLY_SKIP_TOKEN = "REPLY_SKIP";
+const DEFAULT_PING_PONG_TURNS = 5;
+const MAX_PING_PONG_TURNS = 5;
+export function resolveAnnounceTargetFromKey(sessionKey) {
+    const rawParts = sessionKey.split(":").filter(Boolean);
+    const parts = rawParts.length >= 3 && rawParts[0] === "agent"
+        ? rawParts.slice(2)
+        : rawParts;
+    if (parts.length < 3)
+        return null;
+    const [providerRaw, kind, ...rest] = parts;
+    if (kind !== "group" && kind !== "channel")
+        return null;
+    const id = rest.join(":").trim();
+    if (!id)
+        return null;
+    if (!providerRaw)
+        return null;
+    const provider = providerRaw.toLowerCase();
+    if (provider === "discord") {
+        return { provider, to: `channel:${id}` };
+    }
+    if (provider === "signal") {
+        return { provider, to: `group:${id}` };
+    }
+    return { provider, to: id };
+}
+export function buildAgentToAgentMessageContext(params) {
+    const lines = [
+        "Agent-to-agent message context:",
+        params.requesterSessionKey
+            ? `Agent 1 (requester) session: ${params.requesterSessionKey}.`
+            : undefined,
+        params.requesterProvider
+            ? `Agent 1 (requester) provider: ${params.requesterProvider}.`
+            : undefined,
+        `Agent 2 (target) session: ${params.targetSessionKey}.`,
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+export function buildAgentToAgentReplyContext(params) {
+    const currentLabel = params.currentRole === "requester"
+        ? "Agent 1 (requester)"
+        : "Agent 2 (target)";
+    const lines = [
+        "Agent-to-agent reply step:",
+        `Current agent: ${currentLabel}.`,
+        `Turn ${params.turn} of ${params.maxTurns}.`,
+        params.requesterSessionKey
+            ? `Agent 1 (requester) session: ${params.requesterSessionKey}.`
+            : undefined,
+        params.requesterProvider
+            ? `Agent 1 (requester) provider: ${params.requesterProvider}.`
+            : undefined,
+        `Agent 2 (target) session: ${params.targetSessionKey}.`,
+        params.targetProvider
+            ? `Agent 2 (target) provider: ${params.targetProvider}.`
+            : undefined,
+        `If you want to stop the ping-pong, reply exactly "${REPLY_SKIP_TOKEN}".`,
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+export function buildAgentToAgentAnnounceContext(params) {
+    const lines = [
+        "Agent-to-agent announce step:",
+        params.requesterSessionKey
+            ? `Agent 1 (requester) session: ${params.requesterSessionKey}.`
+            : undefined,
+        params.requesterProvider
+            ? `Agent 1 (requester) provider: ${params.requesterProvider}.`
+            : undefined,
+        `Agent 2 (target) session: ${params.targetSessionKey}.`,
+        params.targetProvider
+            ? `Agent 2 (target) provider: ${params.targetProvider}.`
+            : undefined,
+        `Original request: ${params.originalMessage}`,
+        params.roundOneReply
+            ? `Round 1 reply: ${params.roundOneReply}`
+            : "Round 1 reply: (not available).",
+        params.latestReply
+            ? `Latest reply: ${params.latestReply}`
+            : "Latest reply: (not available).",
+        `If you want to remain silent, reply exactly "${ANNOUNCE_SKIP_TOKEN}".`,
+        "Any other reply will be posted to the target provider.",
+        "After this reply, the agent-to-agent conversation is over.",
+    ].filter(Boolean);
+    return lines.join("\n");
+}
+export function isAnnounceSkip(text) {
+    return (text ?? "").trim() === ANNOUNCE_SKIP_TOKEN;
+}
+export function isReplySkip(text) {
+    return (text ?? "").trim() === REPLY_SKIP_TOKEN;
+}
+export function resolvePingPongTurns(cfg) {
+    const raw = cfg?.session?.agentToAgent?.maxPingPongTurns;
+    const fallback = DEFAULT_PING_PONG_TURNS;
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return fallback;
+    const rounded = Math.floor(raw);
+    return Math.max(0, Math.min(MAX_PING_PONG_TURNS, rounded));
+}