@spinabot/brigade 0.1.2 → 1.0.0

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

@@ -0,0 +1,125 @@
+/**
+ * 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 { createSessionsHistoryTool } from "./history.js";
+import { createSessionsListTool } from "./list.js";
+import { createSessionsSendTool } from "./send.js";
+import { createSessionsSpawnTool } from "./spawn.js";
+export { createSessionsHistoryTool, createSessionsListTool, createSessionsSendTool, createSessionsSpawnTool, };
+export { jsonToolResult, SESSIONS_HISTORY_MAX_BYTES, SESSIONS_HISTORY_TEXT_MAX_CHARS, ToolAuthorizationError, ToolInputError, } from "./shared.js";
+/**
+ * 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 function createSessionsToolsBundle(params = {}) {
+    const ctx = params.sessionContext;
+    const sharedOpts = {
+        agentSessionKey: ctx?.key,
+        agentChannel: undefined,
+        agentAccountId: ctx?.requesterAccountId,
+        agentTo: ctx?.requesterSenderId,
+        sandboxed: params.sandboxed,
+    };
+    // Shared access-guard context — threaded into every tool so each
+    // execute body can fail-closed BEFORE dispatching. The bypass flag is
+    // forwarded only when the factory caller explicitly opts in.
+    const accessGuard = {
+        ...(params.visibility ? { visibility: params.visibility } : {}),
+        ...(params.a2aPolicy ? { a2aPolicy: params.a2aPolicy } : {}),
+        ...(params.spawnedKeys ? { spawnedKeys: params.spawnedKeys } : {}),
+        ...(params.bypassAccessGuard === true ? { bypassAccessGuard: true } : {}),
+    };
+    const send = createSessionsSendTool({
+        agentSessionKey: sharedOpts.agentSessionKey,
+        agentChannel: sharedOpts.agentChannel,
+        ...accessGuard,
+    });
+    const spawn = createSessionsSpawnTool({
+        agentSessionKey: sharedOpts.agentSessionKey,
+        agentChannel: sharedOpts.agentChannel,
+        agentAccountId: sharedOpts.agentAccountId,
+        agentTo: sharedOpts.agentTo,
+        requesterAgentIdOverride: ctx?.agentId,
+        workspaceDir: params.workspaceDir,
+        callerDepth: params.callerDepth,
+        maxSpawnDepth: params.maxSpawnDepth,
+        maxChildrenPerAgent: params.maxChildrenPerAgent,
+        ...accessGuard,
+    });
+    const list = createSessionsListTool({
+        agentSessionKey: sharedOpts.agentSessionKey,
+        sandboxed: params.sandboxed,
+        ...accessGuard,
+    });
+    const history = createSessionsHistoryTool({
+        agentSessionKey: sharedOpts.agentSessionKey,
+        ...accessGuard,
+    });
+    return { send, spawn, list, history };
+}
+function toBrigadeTool(descriptor) {
+    return {
+        name: descriptor.name,
+        label: descriptor.displaySummary,
+        description: descriptor.description,
+        displaySummary: descriptor.displaySummary,
+        parameters: descriptor.parameters,
+        execute: async (_toolCallId, args) => {
+            const result = await descriptor.execute(args);
+            // Pi expects `content` as an array of content blocks (TextContent
+            // | ImageContent). The sessions tools return a single string; wrap
+            // it in one `{type: "text", text}` block.
+            return {
+                content: [{ type: "text", text: result.content }],
+                details: result.details ?? {},
+            };
+        },
+    };
+}
+/**
+ * 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 function createSessionsBrigadeTools(params = {}) {
+    const bundle = createSessionsToolsBundle(params);
+    return [
+        toBrigadeTool(bundle.send),
+        toBrigadeTool(bundle.spawn),
+        toBrigadeTool(bundle.list),
+        toBrigadeTool(bundle.history),
+    ];
+}
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,53 @@
+/**
+ * `sessions_list` agent tool (Step 22).
+ *
+ * Enumerates the sessions the caller can see — typically the caller's
+ * own session + the sessions it has spawned (transitively). The
+ * permission check + visibility resolution lives in Step 19's
+ * `checkSessionToolAccess`. The actual session list comes from the
+ * gateway via `callGateway("sessions.list", ...)` — Brigade has the
+ * registry in-process (Step 11) but the gateway is the canonical surface
+ * because cross-process clients (web UI, mobile) also use it.
+ *
+ * Output shape:
+ *
+ *   { count, sessions: SessionListRow[] }
+ *
+ * Each row is the gateway's snapshot — Brigade trims to the small set
+ * of fields the agent typically needs (sessionKey, kind, agentId,
+ * lastActivityAt, state, label?). The full row (channel, model,
+ * tokens, etc.) is available via `sessions_history` if needed.
+ */
+import { type AgentToAgentPolicy, type SessionToolsVisibility, type ToolResultEnvelope } from "./shared.js";
+export interface SessionsListToolArgs {
+    kinds?: string[];
+    limit?: number;
+    activeMinutes?: number;
+    messageLimit?: number;
+}
+export interface SessionsListToolOptions {
+    agentSessionKey?: string;
+    /** Sandbox flag — when true, the gateway clamps visibility to spawned. */
+    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 — true ONLY for trusted internal pathways (boot,
+     * cron, heartbeat). Untrusted callers leave this unset so an unwired
+     * bundle returns zero rows by default instead of surfacing the registry.
+     */
+    bypassAccessGuard?: boolean;
+}
+export interface SessionsListToolDescriptor {
+    name: "sessions_list";
+    displaySummary: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: SessionsListToolArgs) => Promise<ToolResultEnvelope>;
+}
+export declare function createSessionsListTool(opts?: SessionsListToolOptions): SessionsListToolDescriptor;
+//# sourceMappingURL=list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/list.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAMN,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,oBAAoB;IACpC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,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;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,eAAe,CAAC;IACtB,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,oBAAoB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACrE;AAmCD,wBAAgB,sBAAsB,CACrC,IAAI,GAAE,uBAA4B,GAChC,0BAA0B,CAkF5B"}

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

@@ -0,0 +1,134 @@
+/**
+ * `sessions_list` agent tool (Step 22).
+ *
+ * Enumerates the sessions the caller can see — typically the caller's
+ * own session + the sessions it has spawned (transitively). The
+ * permission check + visibility resolution lives in Step 19's
+ * `checkSessionToolAccess`. The actual session list comes from the
+ * gateway via `callGateway("sessions.list", ...)` — Brigade has the
+ * registry in-process (Step 11) but the gateway is the canonical surface
+ * because cross-process clients (web UI, mobile) also use it.
+ *
+ * Output shape:
+ *
+ *   { count, sessions: SessionListRow[] }
+ *
+ * Each row is the gateway's snapshot — Brigade trims to the small set
+ * of fields the agent typically needs (sessionKey, kind, agentId,
+ * lastActivityAt, state, label?). The full row (channel, model,
+ * tokens, etc.) is available via `sessions_history` if needed.
+ */
+import { callGateway } from "../../gateway-call.js";
+import { checkSessionToolAccess, describeSessionsListTool, jsonToolResult, SESSIONS_LIST_TOOL_DISPLAY_SUMMARY, ToolInputError, } from "./shared.js";
+const SESSIONS_LIST_SCHEMA = {
+    type: "object",
+    properties: {
+        kinds: {
+            type: "array",
+            items: {
+                type: "string",
+                enum: ["main", "group", "subagent", "cron", "hook", "node", "other"],
+            },
+        },
+        limit: { type: "number", minimum: 1, maximum: 200 },
+        activeMinutes: { type: "number", minimum: 1 },
+        messageLimit: { type: "number", minimum: 0, maximum: 50 },
+    },
+    additionalProperties: false,
+};
+function coerceArgs(args) {
+    if (args == null)
+        return {};
+    if (typeof args !== "object") {
+        throw new ToolInputError("sessions_list args must be an object");
+    }
+    const obj = args;
+    return {
+        kinds: Array.isArray(obj.kinds)
+            ? obj.kinds.filter((value) => typeof value === "string")
+            : undefined,
+        limit: typeof obj.limit === "number" ? obj.limit : undefined,
+        activeMinutes: typeof obj.activeMinutes === "number" ? obj.activeMinutes : undefined,
+        messageLimit: typeof obj.messageLimit === "number" ? obj.messageLimit : undefined,
+    };
+}
+export function createSessionsListTool(opts = {}) {
+    return {
+        name: "sessions_list",
+        displaySummary: SESSIONS_LIST_TOOL_DISPLAY_SUMMARY,
+        description: describeSessionsListTool(),
+        parameters: SESSIONS_LIST_SCHEMA,
+        execute: async (args) => {
+            const parsed = coerceArgs(args);
+            // Wave O0.6 — fail-closed early-return. An unwired bundle
+            // (missing caller key OR visibility OR A2A policy) refuses
+            // every call. Internal trusted callers opt out via
+            // `bypassAccessGuard: true`. Previously the per-row filter
+            // fell through to the unfiltered `sessions` when any policy
+            // field was missing, leaking the full registry to unwired
+            // callers.
+            if (opts.bypassAccessGuard !== true &&
+                (!opts.agentSessionKey || !opts.visibility || !opts.a2aPolicy)) {
+                return jsonToolResult({
+                    status: "forbidden",
+                    error: "sessions_list forbidden: session access policy not configured",
+                    count: 0,
+                    sessions: [],
+                });
+            }
+            try {
+                const result = await callGateway({
+                    method: "sessions.list",
+                    params: {
+                        limit: parsed.limit,
+                        activeMinutes: parsed.activeMinutes,
+                        messageLimit: parsed.messageLimit,
+                        kinds: parsed.kinds,
+                        // When the caller is sandboxed, gateway filters to
+                        // `spawnedBy: <caller>` so the tool can't see siblings.
+                        ...(opts.sandboxed && opts.agentSessionKey
+                            ? { spawnedBy: opts.agentSessionKey }
+                            : {}),
+                    },
+                    timeoutMs: 10_000,
+                });
+                const sessions = Array.isArray(result?.sessions) ? result.sessions : [];
+                // Per-row access guard — drop rows the caller is not allowed
+                // to see. The gateway's sandbox flag clamps visibility on the
+                // server side; this is the tool-side enforcement that also
+                // applies to non-sandboxed paths (any caller's tool surface).
+                // Skipped only on the trusted-bypass branch (early-return
+                // above already refused the unwired-policy case).
+                const filtered = opts.bypassAccessGuard === true
+                    ? sessions
+                    : sessions.filter((row) => {
+                        const targetKey = typeof row.sessionKey === "string"
+                            ? (row.sessionKey)
+                            : "";
+                        if (!targetKey)
+                            return true;
+                        const access = checkSessionToolAccess({
+                            action: "list",
+                            requesterSessionKey: opts.agentSessionKey,
+                            targetSessionKey: targetKey,
+                            visibility: opts.visibility,
+                            a2aPolicy: opts.a2aPolicy,
+                            ...(opts.spawnedKeys ? { spawnedKeys: opts.spawnedKeys } : {}),
+                        });
+                        return access.allowed;
+                    });
+                return jsonToolResult({
+                    count: filtered.length,
+                    sessions: filtered,
+                });
+            }
+            catch (err) {
+                return jsonToolResult({
+                    status: "error",
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=list.js.map

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

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

package/dist/agents/tools/sessions/resolve-access.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Session-tool access policy resolution from a config snapshot.
+ *
+ * Extracted from `agent-loop.ts` (2026-06-11) so BOTH the per-turn toolset
+ * build AND the `sessions_send` LIVE re-check derive the policy identically.
+ *
+ * Why the live re-check exists: the agent loop captures the access policy
+ * ONCE at run start and freezes it into the sessions tools. When the model
+ * calls `manage_access` to enable cross-agent messaging and then immediately
+ * retries `sessions_send` IN THE SAME RUN, the frozen policy still says
+ * "denied" — the change only reached `brigade.json`, not the in-memory
+ * closure. The operator saw "still blocked, try a gateway restart" (the
+ * model's wrong inference). `sessions_send` now re-resolves from CURRENT
+ * config on a denial, so a mid-run enable takes effect on the next call
+ * without any restart. This module is the single source of that derivation.
+ */
+import { type AgentToAgentPolicy, type SessionToolsVisibility } from "./shared.js";
+export interface ResolvedSessionAccess {
+    visibility: SessionToolsVisibility;
+    a2aPolicy: AgentToAgentPolicy;
+}
+/**
+ * Resolve `{ visibility, a2aPolicy }` from a Brigade config snapshot.
+ *
+ * Mirrors the legacy agent-loop block exactly: visibility defaults to
+ * "self"; the flat `session.agentToAgent.allow` `{from,to}` pairs flatten to
+ * a union of ids for the matcher; and when `cfg.org` is present with a mode
+ * OTHER than "explicit", the org-graph policy supersedes the flat allow
+ * matrix (explicit / no-org keep the flat policy — same contract Stage C
+ * shipped). Uses `deriveOrgGraph` (POLICY derivation — explicit → undefined
+ * → flat fallback), NEVER `deriveOrgDisplayGraph`.
+ */
+export declare function resolveSessionAccessPolicy(cfg: unknown): ResolvedSessionAccess;
+//# sourceMappingURL=resolve-access.d.ts.map

package/dist/agents/tools/sessions/resolve-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-access.d.ts","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/resolve-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,EAEN,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,qBAAqB;IACrC,UAAU,EAAE,sBAAsB,CAAC;IACnC,SAAS,EAAE,kBAAkB,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,qBAAqB,CA0C9E"}

package/dist/agents/tools/sessions/resolve-access.js

@@ -0,0 +1,67 @@
+/**
+ * Session-tool access policy resolution from a config snapshot.
+ *
+ * Extracted from `agent-loop.ts` (2026-06-11) so BOTH the per-turn toolset
+ * build AND the `sessions_send` LIVE re-check derive the policy identically.
+ *
+ * Why the live re-check exists: the agent loop captures the access policy
+ * ONCE at run start and freezes it into the sessions tools. When the model
+ * calls `manage_access` to enable cross-agent messaging and then immediately
+ * retries `sessions_send` IN THE SAME RUN, the frozen policy still says
+ * "denied" — the change only reached `brigade.json`, not the in-memory
+ * closure. The operator saw "still blocked, try a gateway restart" (the
+ * model's wrong inference). `sessions_send` now re-resolves from CURRENT
+ * config on a denial, so a mid-run enable takes effect on the next call
+ * without any restart. This module is the single source of that derivation.
+ */
+import { resolveDefaultAgentId } from "../../agent-scope.js";
+import { deriveOrgGraph } from "../../org/derive-graph.js";
+import { orgGraphAsA2APolicy } from "../../org/a2a-adapter.js";
+import { createAgentToAgentPolicy, } from "./shared.js";
+/**
+ * Resolve `{ visibility, a2aPolicy }` from a Brigade config snapshot.
+ *
+ * Mirrors the legacy agent-loop block exactly: visibility defaults to
+ * "self"; the flat `session.agentToAgent.allow` `{from,to}` pairs flatten to
+ * a union of ids for the matcher; and when `cfg.org` is present with a mode
+ * OTHER than "explicit", the org-graph policy supersedes the flat allow
+ * matrix (explicit / no-org keep the flat policy — same contract Stage C
+ * shipped). Uses `deriveOrgGraph` (POLICY derivation — explicit → undefined
+ * → flat fallback), NEVER `deriveOrgDisplayGraph`.
+ */
+export function resolveSessionAccessPolicy(cfg) {
+    const c = cfg;
+    const visibility = c.session?.sessionTools?.visibility ?? "self";
+    const a2aRaw = c.session?.agentToAgent;
+    const a2aAllow = [];
+    if (Array.isArray(a2aRaw?.allow)) {
+        for (const pair of a2aRaw.allow) {
+            const from = typeof pair?.from === "string" ? pair.from.trim() : "";
+            const to = typeof pair?.to === "string" ? pair.to.trim() : "";
+            if (from)
+                a2aAllow.push(from);
+            if (to)
+                a2aAllow.push(to);
+        }
+    }
+    let a2aPolicy = createAgentToAgentPolicy({ enabled: !!a2aRaw?.enabled, allow: a2aAllow });
+    const orgCfg = c.org;
+    if (orgCfg && orgCfg.a2a?.mode !== "explicit") {
+        const graph = deriveOrgGraph(cfg);
+        if (graph) {
+            // Orchestrator bypass: the operator's DEFAULT agent is the
+            // operator's own voice, not a chart member — in derived mode the
+            // graph used to hard-refuse it as a non-member, so "ask eng-lead
+            // if they're up for work" from main was forbidden out of the box
+            // and the model offered to flip the whole org to explicit mode.
+            // Pairs touching the default agent bypass the chart; everyone
+            // else stays graph-governed. Lockdown installs opt out with
+            // `org.a2a.restrictDefaultAgent: true`.
+            const restrict = orgCfg.a2a
+                ?.restrictDefaultAgent === true;
+            a2aPolicy = orgGraphAsA2APolicy(graph, restrict ? {} : { orchestratorId: resolveDefaultAgentId(cfg) });
+        }
+    }
+    return { visibility, a2aPolicy };
+}
+//# sourceMappingURL=resolve-access.js.map

package/dist/agents/tools/sessions/resolve-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-access.js","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/resolve-access.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EACN,wBAAwB,GAGxB,MAAM,aAAa,CAAC;AAOrB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CAAC,GAAY;IACtD,MAAM,CAAC,GAAG,GAMT,CAAC;IACF,MAAM,UAAU,GAA2B,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,IAAI,MAAM,CAAC;IACzF,MAAM,MAAM,GAAG,CAAC,CAAC,OAAO,EAAE,YAAY,CAAC;IACvC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjC,MAAM,IAAI,GAAG,OAAO,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACpE,MAAM,EAAE,GAAG,OAAO,IAAI,EAAE,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,IAAI,IAAI;gBAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,EAAE;gBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;IACF,CAAC;IACD,IAAI,SAAS,GAAG,wBAAwB,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAC;IAC1F,MAAM,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC;IACrB,IAAI,MAAM,IAAI,MAAM,CAAC,GAAG,EAAE,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/C,MAAM,KAAK,GAAG,cAAc,CAAC,GAAY,CAAC,CAAC;QAC3C,IAAI,KAAK,EAAE,CAAC;YACX,2DAA2D;YAC3D,iEAAiE;YACjE,iEAAiE;YACjE,iEAAiE;YACjE,gEAAgE;YAChE,8DAA8D;YAC9D,4DAA4D;YAC5D,wCAAwC;YACxC,MAAM,QAAQ,GACZ,MAAM,CAAC,GAAsD;gBAC7D,EAAE,oBAAoB,KAAK,IAAI,CAAC;YAClC,SAAS,GAAG,mBAAmB,CAC9B,KAAK,EACL,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,qBAAqB,CAAC,GAAY,CAAC,EAAE,CACvE,CAAC;QACH,CAAC;IACF,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC;AAClC,CAAC"}

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

@@ -0,0 +1,68 @@
+/**
+ * `sessions_send` agent tool (Step 21).
+ *
+ * Sends a message into another session (child, sibling, or — when A2A
+ * is enabled in config — a session belonging to a different agent). The
+ * receiving session sees the inbound as a system event and drains it on
+ * the next turn (Step 12's prompt orchestrator handles the prefix).
+ *
+ * Brigade scope today:
+ *   - Validates target sessionKey + caller permissions (Step 19 helpers).
+ *   - Dispatches via `callGateway("agent", ...)` with `lane: Nested` so the
+ *     target turn runs without bumping the caller's main lane.
+ *   - Returns the run id; the announce-back flow is fired on the target
+ *     side via Step 12's drain + Step 14's heartbeat.
+ *
+ * What this tool DOES NOT do at this milestone:
+ *   - The full ping-pong A2A flow (upstream's `runSessionsSendA2AFlow`)
+ *     stays deferred; today the caller sends one message, and the target
+ *     session replies on its next turn. Multi-turn A2A lands when the
+ *     gateway dispatcher (Step 25) wires the cross-session announce
+ *     callback.
+ */
+import { type AgentToAgentPolicy, type SessionToolsVisibility, type ToolResultEnvelope } from "./shared.js";
+export interface SessionsSendToolArgs {
+    sessionKey: string;
+    message: string;
+    timeoutSeconds?: number;
+}
+/**
+ * Resolved per-turn access context for the session-tool guard. Threaded by
+ * the bundle factory so each tool's execute body can fail-closed BEFORE
+ * dispatching when the caller is not allowed to talk to the target session.
+ *
+ * Fail-closed contract: when the bundle was constructed without a complete
+ * access policy (any of `agentSessionKey` / `visibility` / `a2aPolicy`
+ * missing) the tool refuses every call. Callers that need to bypass the
+ * guard (internal boot/cron/heartbeat flows that prove the request is
+ * trusted) must opt in by setting `bypassAccessGuard: true`.
+ */
+export interface SessionToolAccessOptions {
+    /** 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>;
+    /**
+     * When true, skip the access guard entirely. Reserved for internal
+     * system pathways (boot wiring, cron lane, heartbeat) where the caller
+     * has independently proven trust. Channel adapters / model-side dispatch
+     * MUST NOT set this — leaving it unset means an unwired bundle fails
+     * closed instead of accidentally allowing traffic.
+     */
+    bypassAccessGuard?: boolean;
+}
+export interface SessionsSendToolOptions extends SessionToolAccessOptions {
+    agentSessionKey?: string;
+    agentChannel?: string;
+}
+export interface SessionsSendToolDescriptor {
+    name: "sessions_send";
+    displaySummary: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: SessionsSendToolArgs) => Promise<ToolResultEnvelope>;
+}
+export declare function createSessionsSendTool(opts?: SessionsSendToolOptions): SessionsSendToolDescriptor;
+//# sourceMappingURL=send.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/send.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,OAAO,EAMN,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,MAAM,aAAa,CAAC;AASrB,MAAM,WAAW,oBAAoB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAYD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,wBAAwB;IACxC,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;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACxE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,eAAe,CAAC;IACtB,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,oBAAoB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACrE;AA4FD,wBAAgB,sBAAsB,CACrC,IAAI,GAAE,uBAA4B,GAChC,0BAA0B,CA0W5B"}