@spinabot/brigade 0.1.2 → 1.0.0

package/dist/agents/tools/send-message-tool.d.ts

@@ -0,0 +1,84 @@
+/**
+ * `send_message` — agent-callable channel outbound.
+ *
+ * Lets the agent send a text message via any started channel adapter mid-
+ * turn. Before this tool existed, the only way for the agent to "send
+ * a contact a WhatsApp" was to schedule a cron — which is the wrong
+ * primitive for "do it right now". This tool covers the immediate path;
+ * `cron` covers the scheduled path.
+ *
+ * Ownership: per-call gate, NOT a blanket refusal.
+ *   - Workspace owner (TUI / `connect` / CLI) keeps full access including
+ *     cross-channel and cross-conversation sends.
+ *   - Channel-routed peer (e.g. an approved WhatsApp DM): may send only to
+ *     their own chat. Explicit `channel`/`to` that match the inbound are
+ *     allowed; anything pointing elsewhere is refused. Omitting both
+ *     auto-routes back to the same chat. Mirrors the `send_media`
+ *     posture.
+ *
+ * Defaults:
+ *   - When `channel`/`to` aren't passed AND the calling turn came from a
+ *     channel-routed inbound (the channel manager wired up
+ *     `channelContext`), this tool auto-fills both fields with the
+ *     originating chat. That means in a WhatsApp DM the agent can call
+ *     `send_message({text: "..."})` to reply IN-PLACE without needing to
+ *     remember the peer id. This matches the cron tool's same auto-fill
+ *     behaviour.
+ *   - When EITHER `channel` or `to` is explicitly set, BOTH must be set;
+ *     mismatched auto-fill (e.g. channel from context + operator-supplied
+ *     to) would silently cross wires.
+ *
+ * Validation:
+ *   - `channel` must match a STARTED adapter (typo refusal via the channel
+ *     manager's `adapter(id)` lookup — `whatapp` returns undefined and the
+ *     tool refuses with a clear message including the started-channel
+ *     list).
+ *   - Sub-agents do not currently get this tool — they reply via the
+ *     parent's spawn_agent return path. (If we ever expose `send_message`
+ *     to sub-agents, the same per-call gate above applies.)
+ *
+ * Pattern note: the reference has a single polymorphic `message` tool with many
+ * actions (send/react/poll/sendAttachment/...). Brigade ships with just
+ * `send` today; future actions (react, edit, poll) get added as separate
+ * tools (`react_to_message`, `edit_message`, etc.) rather than inflating
+ * one tool's schema with action-mode branches — simpler for the model
+ * to reason about, and lets us add ownerOnly granularity per action.
+ */
+import { Type } from "typebox";
+import type { ChannelApprovalRoute } from "../channels/approval-router.js";
+import type { BrigadeTool } from "./types.js";
+declare const SendMessageParams: Type.TObject<{
+    text: Type.TString;
+    channel: Type.TOptional<Type.TString>;
+    to: Type.TOptional<Type.TString>;
+    threadId: Type.TOptional<Type.TString>;
+    accountId: Type.TOptional<Type.TString>;
+}>;
+type SendMessageDetails = {
+    channel: string;
+    to: string;
+    textPreview: string;
+    threadId?: string;
+};
+export interface MakeSendMessageToolOptions {
+    /** Active channel context for this turn — used for auto-fill defaults. */
+    channelContext?: ChannelApprovalRoute;
+    /**
+     * Whether the calling turn is the workspace owner. When `false`, the
+     * turn was routed in from an approved channel peer — they can still
+     * `send_message` BUT only with target = their own chat (same shape as
+     * `send_media`). Cross-conversation / cross-channel sends require
+     * workspace-owner privilege. Defaults to `true` when omitted so legacy
+     * paths (TUI, tests) keep full access without opting in.
+     */
+    senderIsOwner?: boolean;
+}
+/**
+ * Build the `send_message` tool. Caller is the registry — it only registers
+ * the tool when the gateway's channel manager is mounted; otherwise the
+ * tool stays out of the surface (no point offering a send tool when there
+ * are no channels to send through).
+ */
+export declare function makeSendMessageTool(opts?: MakeSendMessageToolOptions): BrigadeTool<typeof SendMessageParams, SendMessageDetails>;
+export {};
+//# sourceMappingURL=send-message-tool.d.ts.map

package/dist/agents/tools/send-message-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-message-tool.d.ts","sourceRoot":"","sources":["../../../src/agents/tools/send-message-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAK/B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAG3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAI9C,QAAA,MAAM,iBAAiB;;;;;;EAsCrB,CAAC;AAEH,KAAK,kBAAkB,GAAG;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,WAAW,0BAA0B;IAC1C,0EAA0E;IAC1E,cAAc,CAAC,EAAE,oBAAoB,CAAC;IACtC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,GAAE,0BAA+B,GACnC,WAAW,CAAC,OAAO,iBAAiB,EAAE,kBAAkB,CAAC,CAmK3D"}

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

@@ -0,0 +1,226 @@
+/**
+ * `send_message` — agent-callable channel outbound.
+ *
+ * Lets the agent send a text message via any started channel adapter mid-
+ * turn. Before this tool existed, the only way for the agent to "send
+ * a contact a WhatsApp" was to schedule a cron — which is the wrong
+ * primitive for "do it right now". This tool covers the immediate path;
+ * `cron` covers the scheduled path.
+ *
+ * Ownership: per-call gate, NOT a blanket refusal.
+ *   - Workspace owner (TUI / `connect` / CLI) keeps full access including
+ *     cross-channel and cross-conversation sends.
+ *   - Channel-routed peer (e.g. an approved WhatsApp DM): may send only to
+ *     their own chat. Explicit `channel`/`to` that match the inbound are
+ *     allowed; anything pointing elsewhere is refused. Omitting both
+ *     auto-routes back to the same chat. Mirrors the `send_media`
+ *     posture.
+ *
+ * Defaults:
+ *   - When `channel`/`to` aren't passed AND the calling turn came from a
+ *     channel-routed inbound (the channel manager wired up
+ *     `channelContext`), this tool auto-fills both fields with the
+ *     originating chat. That means in a WhatsApp DM the agent can call
+ *     `send_message({text: "..."})` to reply IN-PLACE without needing to
+ *     remember the peer id. This matches the cron tool's same auto-fill
+ *     behaviour.
+ *   - When EITHER `channel` or `to` is explicitly set, BOTH must be set;
+ *     mismatched auto-fill (e.g. channel from context + operator-supplied
+ *     to) would silently cross wires.
+ *
+ * Validation:
+ *   - `channel` must match a STARTED adapter (typo refusal via the channel
+ *     manager's `adapter(id)` lookup — `whatapp` returns undefined and the
+ *     tool refuses with a clear message including the started-channel
+ *     list).
+ *   - Sub-agents do not currently get this tool — they reply via the
+ *     parent's spawn_agent return path. (If we ever expose `send_message`
+ *     to sub-agents, the same per-call gate above applies.)
+ *
+ * Pattern note: the reference has a single polymorphic `message` tool with many
+ * actions (send/react/poll/sendAttachment/...). Brigade ships with just
+ * `send` today; future actions (react, edit, poll) get added as separate
+ * tools (`react_to_message`, `edit_message`, etc.) rather than inflating
+ * one tool's schema with action-mode branches — simpler for the model
+ * to reason about, and lets us add ownerOnly granularity per action.
+ */
+import { Type } from "typebox";
+import { getActiveChannelManager } from "../channels/active-manager.js";
+import { createSubsystemLogger } from "../../logging/subsystem-logger.js";
+import { failedTextResult, payloadTextResult, readStringParam } from "./common.js";
+const log = createSubsystemLogger("brigade/send-message");
+const SendMessageParams = Type.Object({
+    text: Type.String({
+        description: "Message body. Plaintext or markdown — channel adapters render their " +
+            "native syntax (WhatsApp uses *bold*/_italic_/~strike~ etc.).",
+    }),
+    channel: Type.Optional(Type.String({
+        description: "Channel id to send through (e.g. `whatsapp`, `slack`, `telegram`). " +
+            "Must match a STARTED adapter. Auto-filled from the current turn's " +
+            "originating channel when omitted (so replying in-place doesn't " +
+            "require restating the channel).",
+    })),
+    to: Type.Optional(Type.String({
+        description: "Destination conversation id — phone number (WhatsApp), chat id " +
+            "(Telegram), channel id (Slack), etc. Auto-filled from the current " +
+            "turn's originating conversation when omitted.",
+    })),
+    threadId: Type.Optional(Type.String({
+        description: "Optional thread/topic id (Slack thread_ts, Telegram topic, Discord " +
+            "thread). Channels without threading ignore it.",
+    })),
+    accountId: Type.Optional(Type.String({
+        description: "Multi-account channels (Slack with 2 workspaces, WhatsApp with 2 " +
+            "linked numbers) use this to pick which account sends. Leave " +
+            "unset for the default account.",
+    })),
+});
+/**
+ * Build the `send_message` tool. Caller is the registry — it only registers
+ * the tool when the gateway's channel manager is mounted; otherwise the
+ * tool stays out of the surface (no point offering a send tool when there
+ * are no channels to send through).
+ */
+export function makeSendMessageTool(opts = {}) {
+    const channelContext = opts.channelContext;
+    const senderIsOwner = opts.senderIsOwner !== false;
+    return {
+        name: "send_message",
+        label: "send_message",
+        displaySummary: "sending a message",
+        description: "Send a text message through a connected channel (WhatsApp / Slack / " +
+            "Telegram / Discord / etc.) RIGHT NOW. Use this when the operator " +
+            "asks you to message someone immediately — for scheduled / delayed " +
+            "sends use the `cron` tool with a future `at` schedule instead.\n\n" +
+            "Auto-routing: when called from a channel-routed turn (operator is " +
+            "chatting from a channel), `channel` and `to` default to the " +
+            "originating conversation — so a 'reply with hi' becomes " +
+            "`{text: 'hi'}` without needing channel/to. Override by passing " +
+            "explicit `channel` + `to` to target a DIFFERENT chat (e.g. 'tell " +
+            "Alex on WhatsApp I'm in a meeting' from a TUI turn).\n\n" +
+            "Validation: `channel` MUST match a started channel adapter. The " +
+            "`## Channels` section of your system prompt lists what's available.",
+        parameters: SendMessageParams,
+        // NOTE: no blanket `ownerOnly: true`. Same shape as `send_media` —
+        // a non-owner-routed turn (approved channel peer) may still call
+        // this tool but the per-call gate below pins their target to their
+        // own chat. Cross-channel / cross-conversation sends require the
+        // workspace-owner privilege.
+        async execute(_toolCallId, params) {
+            const manager = getActiveChannelManager();
+            if (!manager) {
+                return failedTextResult("send_message: the gateway has no channel manager mounted (no channels are configured). " +
+                    "Configure a channel in brigade.json first, then restart the gateway.", { channel: "", to: "", textPreview: "" });
+            }
+            const text = readStringParam(params, "text", { required: true });
+            const channelRaw = readStringParam(params, "channel");
+            const toRaw = readStringParam(params, "to");
+            const threadIdParam = readStringParam(params, "threadId");
+            const accountId = readStringParam(params, "accountId");
+            // Per-call non-owner gate. A channel-routed peer may only
+            // reply-to-their-own-chat: BOTH `channel` and `to` either
+            // (a) unset (auto-fill from channelContext below), OR
+            // (b) set explicitly but EQUAL to channelContext's channelId +
+            //     conversationId (so the LLM can request the same chat
+            //     explicitly without it being a refusal).
+            // Anything else — cross-channel, cross-conversation, or any
+            // non-owner call with NO channelContext — is refused. Owners
+            // (TUI / connect / CLI) bypass this gate entirely.
+            if (!senderIsOwner) {
+                if (!channelContext) {
+                    return failedTextResult("send_message: as a non-owner-routed turn you must be reached through an approved channel.", { channel: channelRaw ?? "", to: toRaw ?? "", textPreview: text.slice(0, 80) });
+                }
+                const channelMatchesCtx = channelRaw === undefined || channelRaw === channelContext.channelId;
+                const toMatchesCtx = toRaw === undefined || toRaw === channelContext.conversationId;
+                if (!channelMatchesCtx || !toMatchesCtx) {
+                    return failedTextResult("send_message: as a non-owner-routed turn you may only send to your own chat. " +
+                        "Cross-conversation sends require workspace-owner privilege. " +
+                        "Omit `channel`/`to` to auto-route back to the inbound's own chat.", { channel: channelRaw ?? "", to: toRaw ?? "", textPreview: text.slice(0, 80) });
+                }
+            }
+            // Auto-fill from the active channel context when EITHER target field
+            // is missing AND we have one. Strict pairing: if the caller set
+            // `channel` but not `to`, we DON'T auto-fill just `to` from context
+            // — that would silently mix a caller-supplied channel with a
+            // context-derived peer, which is almost always wrong. The auto-fill
+            // path only kicks in when BOTH are missing.
+            let channel = channelRaw;
+            let to = toRaw;
+            let threadId = threadIdParam;
+            let resolvedAccountId = accountId;
+            if (!channel && !to && channelContext) {
+                channel = channelContext.channelId;
+                to = channelContext.conversationId;
+                threadId ??= channelContext.threadId;
+                // Inherit the routed inbound's accountId so a multi-account
+                // install's reply lands on the SAME socket the request arrived
+                // on. Caller-supplied `accountId` wins (operator may target a
+                // specific account explicitly).
+                resolvedAccountId ??= channelContext.accountId;
+            }
+            if (!channel || !to) {
+                const started = manager.started;
+                const targetHint = started.length > 0
+                    ? `available channels: ${started.join(", ")}.`
+                    : "no channels are started; configure one in brigade.json + restart the gateway.";
+                return failedTextResult(`send_message: \`channel\` and \`to\` are both required (no channel-routed turn context to auto-fill from). ${targetHint}`, { channel: channel ?? "", to: to ?? "", textPreview: text.slice(0, 80) });
+            }
+            const adapter = manager.adapter(channel, resolvedAccountId);
+            if (!adapter) {
+                const started = manager.started.join(", ") || "(none)";
+                const accountHint = resolvedAccountId
+                    ? ` (account "${resolvedAccountId}" not started for "${channel}")`
+                    : "";
+                return failedTextResult(`send_message: channel "${channel}" is not a started adapter${accountHint} — typo? available channels: ${started}.`, { channel, to, textPreview: text.slice(0, 80) });
+            }
+            // Pre-flight health check. The adapter may have STARTED successfully
+            // hours ago but its underlying socket has since gone away — most
+            // commonly because the operator unlinked WhatsApp from their phone,
+            // or a Slack token expired, etc. Calling sendText() against a dead
+            // socket either silently drops the message or fails with an opaque
+            // error far from the operator's mental model. Refusing here gives
+            // the model a clear, actionable error it can pass back: "the
+            // channel is logged out, here's the CLI to re-pair."
+            if (typeof adapter.health === "function") {
+                const status = adapter.health();
+                if (!status.ok) {
+                    const remediation = status.remediation
+                        ? ` Remediation: ${status.remediation}`
+                        : "";
+                    return failedTextResult(`send_message: channel "${channel}" is currently unavailable (${status.kind}). ${status.reason}${remediation}`, { channel, to, textPreview: text.slice(0, 80) });
+                }
+            }
+            const opts2 = {};
+            if (threadId)
+                opts2.threadId = threadId;
+            if (resolvedAccountId)
+                opts2.accountId = resolvedAccountId;
+            try {
+                await adapter.sendText(to, text, Object.keys(opts2).length > 0 ? opts2 : undefined);
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                log.warn("send_message dispatch threw", {
+                    channel,
+                    to,
+                    error: errMsg,
+                });
+                return failedTextResult(`send_message: dispatch failed via ${channel} adapter — ${errMsg}. The recipient may not have received the message; consider trying again or telling the operator.`, { channel, to, textPreview: text.slice(0, 80) });
+            }
+            log.info("send_message dispatched", {
+                channel,
+                to,
+                threadId,
+                accountId,
+                textPreview: text.slice(0, 80),
+            });
+            return payloadTextResult({
+                channel,
+                to,
+                textPreview: text.slice(0, 120),
+                ...(threadId !== undefined ? { threadId } : {}),
+            });
+        },
+    };
+}
+//# sourceMappingURL=send-message-tool.js.map

package/dist/agents/tools/send-message-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"send-message-tool.js","sourceRoot":"","sources":["../../../src/agents/tools/send-message-tool.ts"],"names":[],"mappings":"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"}

package/dist/agents/tools/sessions/history.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `sessions_history` agent tool (Step 23).
+ *
+ * Fetches the sanitised message history of another session. The agent
+ * uses this to inspect a sub-agent's progress, debug a sibling's
+ * decision, or resume a thread.
+ *
+ * Sanitisation pipeline:
+ *
+ *   1. Fetch raw messages via `callGateway("chat.history", ...)`.
+ *   2. If `includeTools !== true`, drop tool-call + tool-result rows
+ *      via `stripToolMessages` (Step 19).
+ *   3. Sanitise each remaining message via `sanitizeHistoryMessage`:
+ *      - Drop `details`, `usage`, `cost` (heavy fields).
+ *      - Truncate text > 4 KB → `…(truncated)…`.
+ *      - Strip image `data` payloads (keep only byte count).
+ *      - Apply credential redaction (`redactSensitiveText`).
+ *      - Strip `thinkingSignature` from thinking blocks.
+ *   4. Enforce the 80 KB JSON envelope cap via
+ *      `enforceSessionsHistoryHardCap` — if still over budget, swap in
+ *      a placeholder so the tool never blows the wire budget.
+ */
+import { type AgentToAgentPolicy, type SessionToolsVisibility, type ToolResultEnvelope } from "./shared.js";
+export interface SessionsHistoryToolArgs {
+    sessionKey: string;
+    limit?: number;
+    includeTools?: boolean;
+}
+export interface SessionsHistoryToolOptions {
+    agentSessionKey?: string;
+    /** Visibility scope for the caller's session: self/tree/agent/all. */
+    visibility?: SessionToolsVisibility;
+    /** A2A policy resolved from `cfg.session.agentToAgent`. */
+    a2aPolicy?: AgentToAgentPolicy;
+    /** Session keys the caller (transitively) spawned — used for tree-scope. */
+    spawnedKeys?: ReadonlySet<string>;
+    /**
+     * Fail-closed opt-out — set to true ONLY for trusted internal pathways
+     * (boot wiring, cron lane, heartbeat). Channel adapters and the model
+     * surface MUST leave this unset so unwired bundles refuse traffic by
+     * default.
+     */
+    bypassAccessGuard?: boolean;
+}
+export interface SessionsHistoryToolDescriptor {
+    name: "sessions_history";
+    displaySummary: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: SessionsHistoryToolArgs) => Promise<ToolResultEnvelope>;
+}
+export declare function createSessionsHistoryTool(opts?: SessionsHistoryToolOptions): SessionsHistoryToolDescriptor;
+//# sourceMappingURL=history.d.ts.map

package/dist/agents/tools/sessions/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAWN,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uBAAuB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,0BAA0B;IAC1C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,UAAU,CAAC,EAAE,sBAAsB,CAAC;IACpC,2DAA2D;IAC3D,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,6BAA6B;IAC7C,IAAI,EAAE,kBAAkB,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,EAAE,CAAC,IAAI,EAAE,uBAAuB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACxE;AA2BD,wBAAgB,yBAAyB,CACxC,IAAI,GAAE,0BAA+B,GACnC,6BAA6B,CAuF/B"}

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

@@ -0,0 +1,138 @@
+/**
+ * `sessions_history` agent tool (Step 23).
+ *
+ * Fetches the sanitised message history of another session. The agent
+ * uses this to inspect a sub-agent's progress, debug a sibling's
+ * decision, or resume a thread.
+ *
+ * Sanitisation pipeline:
+ *
+ *   1. Fetch raw messages via `callGateway("chat.history", ...)`.
+ *   2. If `includeTools !== true`, drop tool-call + tool-result rows
+ *      via `stripToolMessages` (Step 19).
+ *   3. Sanitise each remaining message via `sanitizeHistoryMessage`:
+ *      - Drop `details`, `usage`, `cost` (heavy fields).
+ *      - Truncate text > 4 KB → `…(truncated)…`.
+ *      - Strip image `data` payloads (keep only byte count).
+ *      - Apply credential redaction (`redactSensitiveText`).
+ *      - Strip `thinkingSignature` from thinking blocks.
+ *   4. Enforce the 80 KB JSON envelope cap via
+ *      `enforceSessionsHistoryHardCap` — if still over budget, swap in
+ *      a placeholder so the tool never blows the wire budget.
+ */
+import { callGateway } from "../../gateway-call.js";
+import { checkSessionToolAccess, describeSessionsHistoryTool, enforceSessionsHistoryHardCap, jsonToolResult, jsonUtf8Bytes, sanitizeHistoryMessage, SESSIONS_HISTORY_MAX_BYTES, SESSIONS_HISTORY_TOOL_DISPLAY_SUMMARY, stripToolMessages, ToolInputError, } from "./shared.js";
+const SESSIONS_HISTORY_SCHEMA = {
+    type: "object",
+    required: ["sessionKey"],
+    properties: {
+        sessionKey: { type: "string", minLength: 1 },
+        limit: { type: "number", minimum: 1, maximum: 500 },
+        includeTools: { type: "boolean" },
+    },
+    additionalProperties: false,
+};
+function coerceArgs(args) {
+    if (!args || typeof args !== "object") {
+        throw new ToolInputError("sessions_history requires an object argument");
+    }
+    const obj = args;
+    const sessionKey = typeof obj.sessionKey === "string" ? obj.sessionKey.trim() : "";
+    if (!sessionKey)
+        throw new ToolInputError("sessions_history requires `sessionKey`");
+    return {
+        sessionKey,
+        limit: typeof obj.limit === "number" ? obj.limit : undefined,
+        includeTools: typeof obj.includeTools === "boolean" ? obj.includeTools : false,
+    };
+}
+export function createSessionsHistoryTool(opts = {}) {
+    return {
+        name: "sessions_history",
+        displaySummary: SESSIONS_HISTORY_TOOL_DISPLAY_SUMMARY,
+        description: describeSessionsHistoryTool(),
+        parameters: SESSIONS_HISTORY_SCHEMA,
+        execute: async (args) => {
+            const parsed = coerceArgs(args);
+            // Access guard — fail-closed. An unwired bundle (missing caller
+            // key OR visibility OR A2A policy) refuses every call; trusted
+            // internal pathways opt out via `bypassAccessGuard: true`.
+            if (opts.bypassAccessGuard !== true) {
+                if (!opts.agentSessionKey || !opts.visibility || !opts.a2aPolicy) {
+                    return jsonToolResult({
+                        status: "forbidden",
+                        sessionKey: parsed.sessionKey,
+                        error: "sessions_history forbidden: session access policy not configured",
+                    });
+                }
+                const access = checkSessionToolAccess({
+                    action: "history",
+                    requesterSessionKey: opts.agentSessionKey,
+                    targetSessionKey: parsed.sessionKey,
+                    visibility: opts.visibility,
+                    a2aPolicy: opts.a2aPolicy,
+                    ...(opts.spawnedKeys ? { spawnedKeys: opts.spawnedKeys } : {}),
+                });
+                if (!access.allowed) {
+                    return jsonToolResult({
+                        status: "forbidden",
+                        sessionKey: parsed.sessionKey,
+                        error: access.error,
+                    });
+                }
+            }
+            let raw;
+            try {
+                raw = await callGateway({
+                    method: "sessions.history",
+                    params: {
+                        sessionKey: parsed.sessionKey,
+                        limit: parsed.limit,
+                    },
+                    timeoutMs: 10_000,
+                });
+            }
+            catch (err) {
+                return jsonToolResult({
+                    status: "error",
+                    sessionKey: parsed.sessionKey,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            const rawMessages = Array.isArray(raw?.messages) ? raw.messages : [];
+            const selected = parsed.includeTools ? rawMessages : stripToolMessages(rawMessages);
+            const sanitized = selected.map((message) => sanitizeHistoryMessage(message));
+            let contentTruncated = false;
+            let contentRedacted = false;
+            let droppedMessages = false;
+            for (const item of sanitized) {
+                if (item.truncated)
+                    contentTruncated = true;
+                if (item.redacted)
+                    contentRedacted = true;
+            }
+            let items = sanitized.map((item) => item.message);
+            let bytes = jsonUtf8Bytes(items);
+            const capped = enforceSessionsHistoryHardCap({
+                items,
+                bytes,
+                maxBytes: SESSIONS_HISTORY_MAX_BYTES,
+            });
+            if (capped.hardCapped) {
+                droppedMessages = true;
+                items = capped.items;
+                bytes = capped.bytes;
+            }
+            return jsonToolResult({
+                sessionKey: parsed.sessionKey,
+                messages: items,
+                truncated: contentTruncated || droppedMessages,
+                droppedMessages,
+                contentTruncated,
+                contentRedacted,
+                bytes,
+            });
+        },
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/agents/tools/sessions/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/history.ts"],"names":[],"mappings":"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"}

package/dist/agents/tools/sessions/index.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Sessions tools bundle — public entry point (Step 26).
+ *
+ * Wires Steps 19-23's tool factories with Step 11's `SessionContext` so
+ * the per-turn dispatcher (Step 25) can construct the right tool surface
+ * for the caller. Replaces the alternative of every dispatcher hand-
+ * threading agentSessionKey/agentChannel/etc. through four factory calls.
+ *
+ * Usage from the dispatcher:
+ *
+ *   ```ts
+ *   import { createSessionsToolsBundle } from "./tools/sessions/index.js";
+ *   const tools = createSessionsToolsBundle({
+ *     sessionContext: buildSessionContext({ sessionKey }),
+ *     callerDepth: resolveCallerDepth({ sessionKey }),
+ *   });
+ *   // tools is `{ send, spawn, list, history }` — each factory output
+ *   // is already wired with the caller's context.
+ *   ```
+ *
+ * The bundle is plain factory output — caller is expected to spread it
+ * into Pi's `customTools` array (or whatever the host runtime accepts).
+ *
+ * Naming note: this file is the SOLE re-export surface for the four
+ * sessions tools — `import { createSessionsSendTool } from "..."` etc.
+ * still works, but new code should prefer the bundle factory.
+ */
+import type { AnyBrigadeTool } from "../types.js";
+import type { SessionContext } from "../../session-context.js";
+import { createSessionsHistoryTool } from "./history.js";
+import { createSessionsListTool } from "./list.js";
+import { createSessionsSendTool } from "./send.js";
+import { createSessionsSpawnTool } from "./spawn.js";
+import type { AgentToAgentPolicy, SessionToolsVisibility } from "./shared.js";
+export { createSessionsHistoryTool, createSessionsListTool, createSessionsSendTool, createSessionsSpawnTool, };
+export type { SessionsHistoryToolArgs, SessionsHistoryToolDescriptor } from "./history.js";
+export type { SessionsListToolArgs, SessionsListToolDescriptor } from "./list.js";
+export type { SessionsSendToolArgs, SessionsSendToolDescriptor } from "./send.js";
+export type { SessionsSpawnToolArgs, SessionsSpawnToolDescriptor } from "./spawn.js";
+export { jsonToolResult, SESSIONS_HISTORY_MAX_BYTES, SESSIONS_HISTORY_TEXT_MAX_CHARS, ToolAuthorizationError, ToolInputError, } from "./shared.js";
+export interface CreateSessionsToolsBundleParams {
+    /** Per-turn context produced by Step 11's `buildSessionContext`. */
+    sessionContext?: SessionContext;
+    /** Caller's resolved spawn depth (from session store). Defaults to 0. */
+    callerDepth?: number;
+    /** Optional cap overrides; defaults to 3 / 5 from Step 20. */
+    maxSpawnDepth?: number;
+    maxChildrenPerAgent?: number;
+    /** Caller's workspace dir (sub-agents inherit it). */
+    workspaceDir?: string;
+    /** Sandbox flag — tightens `sessions_list` visibility to spawned-only. */
+    sandboxed?: boolean;
+    /** Visibility scope for the caller's session: self/tree/agent/all. */
+    visibility?: SessionToolsVisibility;
+    /** A2A policy resolved from `cfg.session.agentToAgent`. */
+    a2aPolicy?: AgentToAgentPolicy;
+    /** Session keys the caller (transitively) spawned — used for tree-scope. */
+    spawnedKeys?: ReadonlySet<string>;
+    /**
+     * Fail-closed opt-out — set to true ONLY when the caller is a trusted
+     * internal pathway (boot wiring, cron lane, heartbeat). Channel-routed
+     * and model-side bundles must leave this unset so the four sessions
+     * tools refuse traffic when policy is missing.
+     */
+    bypassAccessGuard?: boolean;
+}
+export interface SessionsToolsBundle {
+    send: ReturnType<typeof createSessionsSendTool>;
+    spawn: ReturnType<typeof createSessionsSpawnTool>;
+    list: ReturnType<typeof createSessionsListTool>;
+    history: ReturnType<typeof createSessionsHistoryTool>;
+}
+/**
+ * Build the four-tool bundle the gateway dispatcher (Step 25) installs
+ * for one agent turn. Every tool in the bundle is pre-wired with the
+ * caller's session context — no further hand-threading needed.
+ *
+ * The bundle returns descriptor objects (NOT Pi `AgentTool`s yet). The
+ * dispatcher wraps each descriptor in Brigade's `BrigadeTool` shape at
+ * the seam where Pi's runtime is set up. Keeping the bundle in
+ * descriptor form means tests can exercise the `execute` body directly
+ * without depending on Pi's tool-loop.
+ */
+export declare function createSessionsToolsBundle(params?: CreateSessionsToolsBundleParams): SessionsToolsBundle;
+/**
+ * Build the sessions-tools bundle and adapt every descriptor into a
+ * Brigade `AnyBrigadeTool` for `createBrigadeTools`'s `customTools` slot.
+ * Returned in registry order so `assembleBrigadeToolset` can spread it
+ * directly into the tool array.
+ */
+export declare function createSessionsBrigadeTools(params?: CreateSessionsToolsBundleParams): AnyBrigadeTool[];
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/tools/sessions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,yBAAyB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,KAAK,EACX,kBAAkB,EAClB,sBAAsB,EAEtB,MAAM,aAAa,CAAC;AAErB,OAAO,EACN,yBAAyB,EACzB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,GACvB,CAAC;AACF,YAAY,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,cAAc,CAAC;AAC3F,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAClF,YAAY,EAAE,oBAAoB,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAClF,YAAY,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EACN,cAAc,EACd,0BAA0B,EAC1B,+BAA+B,EAC/B,sBAAsB,EACtB,cAAc,GACd,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,+BAA+B;IAC/C,oEAAoE;IACpE,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,sBAAsB,CAAC;IACpC,2DAA2D;IAC3D,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,4EAA4E;IAC5E,WAAW,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAClC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IACnC,IAAI,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAChD,KAAK,EAAE,UAAU,CAAC,OAAO,uBAAuB,CAAC,CAAC;IAClD,IAAI,EAAE,UAAU,CAAC,OAAO,sBAAsB,CAAC,CAAC;IAChD,OAAO,EAAE,UAAU,CAAC,OAAO,yBAAyB,CAAC,CAAC;CACtD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACxC,MAAM,GAAE,+BAAoC,GAC1C,mBAAmB,CA6CrB;AAyCD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,GAAE,+BAAoC,GAC1C,cAAc,EAAE,CAQlB"}