@spinabot/brigade 0.1.2 → 1.0.1

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

@@ -0,0 +1,145 @@
+/**
+ * Shared helpers for the sessions tool surface (Step 19).
+ *
+ * Brand-scrubbed lift of upstream's `src/agents/tools/sessions-*` helpers.
+ * One file because the cross-tool surface is small (~400 LOC); splitting
+ * would just move declarations between files without saving any reads.
+ *
+ * The four sessions tools (`sessions_send`, `sessions_spawn`,
+ * `sessions_list`, `sessions_history`) all reach for the same primitives:
+ *
+ *   - History text sanitizer + 4 KB-per-block / 80 KB-total caps
+ *   - Tool-message stripper (drop tool-call rows from history)
+ *   - JSON-byte-cap enforcement for the per-call result envelope
+ *   - Sender-redactor (strip credentials/API keys before exposing history)
+ *   - Visibility resolution + agent-to-agent allowlist matcher
+ *   - Common error classes that map to tool-result error shapes
+ *
+ * Nothing here issues gateway calls — the tools receive a `GatewayCaller`
+ * (from Step 18 — `agents/gateway-call.ts`) and call out from their own
+ * execute bodies. Keeps the helper layer testable + tool-agnostic.
+ */
+export declare const SESSIONS_HISTORY_MAX_BYTES: number;
+export declare const SESSIONS_HISTORY_TEXT_MAX_CHARS = 4000;
+/**
+ * Sessions-tool-specific input / authorization errors. Prefixed with
+ * `Sessions*` to avoid colliding with Brigade's existing
+ * `BrigadeToolInputError` / `BrigadeToolAuthorizationError` in
+ * `src/agents/tools/common.ts` — the two surfaces serve different layers
+ * (sessions tools' execute bodies catch these and return error envelopes
+ * via `jsonToolResult`, while Brigade's existing tools wrap their errors
+ * inline via `wrapOwnerOnlyToolExecution`).
+ */
+export declare class SessionsToolInputError extends Error {
+    readonly status: number;
+    constructor(message: string);
+}
+export declare class SessionsToolAuthorizationError extends SessionsToolInputError {
+    readonly status = 403;
+    constructor(message: string);
+}
+/** @deprecated retained for backwards compatibility; use `SessionsToolInputError`. */
+export declare const ToolInputError: typeof SessionsToolInputError;
+/** @deprecated retained for backwards compatibility; use `SessionsToolAuthorizationError`. */
+export declare const ToolAuthorizationError: typeof SessionsToolAuthorizationError;
+/**
+ * UTF-16-safe truncation. Preserves surrogate-pair boundaries so the
+ * returned string is always valid UTF-16 (no orphan lead/trail
+ * surrogates), even at the cut point.
+ */
+export declare function truncateUtf16Safe(value: string, maxChars: number): string;
+/** Best-effort credential redaction for history text. NOT a security boundary. */
+export declare function redactSensitiveText(input: string): string;
+export declare function truncateHistoryText(text: string): {
+    text: string;
+    truncated: boolean;
+    redacted: boolean;
+};
+/** Sanitize ONE content block (text, image, thinking, tool-use payload, etc.). */
+export declare function sanitizeHistoryContentBlock(block: unknown): {
+    block: unknown;
+    truncated: boolean;
+    redacted: boolean;
+};
+/** Sanitize ONE message — strips heavy fields + sanitizes each content block. */
+export declare function sanitizeHistoryMessage(message: unknown): {
+    message: unknown;
+    truncated: boolean;
+    redacted: boolean;
+};
+/** Drop tool-call + tool-result messages (default for `includeTools: false`). */
+export declare function stripToolMessages(messages: readonly unknown[]): unknown[];
+/** Byte-aware JSON size estimate (UTF-8). */
+export declare function jsonUtf8Bytes(value: unknown): number;
+/**
+ * Hard byte cap for the per-call envelope. If the message list still
+ * exceeds the cap, fall back to the most recent message — and if even
+ * THAT is too big, swap in a placeholder so the tool never returns a
+ * response that overflows the wire budget.
+ */
+export declare function enforceSessionsHistoryHardCap(params: {
+    items: unknown[];
+    bytes: number;
+    maxBytes: number;
+}): {
+    items: unknown[];
+    bytes: number;
+    hardCapped: boolean;
+};
+export type SessionToolsVisibility = "self" | "tree" | "agent" | "all";
+export type SessionToolAccessAction = "history" | "send" | "list" | "status";
+export type SessionToolAccessResult = {
+    allowed: true;
+} | {
+    allowed: false;
+    error: string;
+    status: "forbidden";
+};
+export type AgentToAgentPolicy = {
+    enabled: boolean;
+    matchesAllow: (agentId: string) => boolean;
+    isAllowed: (requesterAgentId: string, targetAgentId: string) => boolean;
+};
+export interface AgentToAgentPolicyInput {
+    enabled: boolean;
+    allow: readonly string[];
+}
+/**
+ * Build the A2A policy from a config snapshot. The Brigade gateway
+ * passes `{ enabled, allow }` resolved from `cfg.tools.agentToAgent`;
+ * tests can inject a stub directly without going through config.
+ */
+export declare function createAgentToAgentPolicy(input: AgentToAgentPolicyInput): AgentToAgentPolicy;
+/**
+ * Decide whether a requester session may take the given action on a
+ * target session. The check folds visibility + A2A policy + parent-child
+ * spawned-tree containment in one place.
+ *
+ * `spawnedKeys` is the set of session keys spawned by the requester
+ * (transitively) — the caller is expected to compute it once and reuse
+ * across multiple `checkSessionToolAccess` calls during one tool
+ * invocation.
+ */
+export declare function checkSessionToolAccess(params: {
+    action: SessionToolAccessAction;
+    requesterSessionKey: string;
+    targetSessionKey: string;
+    visibility: SessionToolsVisibility;
+    a2aPolicy: AgentToAgentPolicy;
+    spawnedKeys?: ReadonlySet<string>;
+}): SessionToolAccessResult;
+export interface ToolResultEnvelope {
+    content: string;
+    details?: Record<string, unknown>;
+}
+/** Build the standard Pi AgentTool result for JSON payloads. */
+export declare function jsonToolResult(payload: unknown): ToolResultEnvelope;
+export declare const SESSIONS_LIST_TOOL_DISPLAY_SUMMARY = "List visible sessions and optional recent messages.";
+export declare const SESSIONS_HISTORY_TOOL_DISPLAY_SUMMARY = "Read sanitized message history for a visible session.";
+export declare const SESSIONS_SEND_TOOL_DISPLAY_SUMMARY = "Send a message to another visible session.";
+export declare const SESSIONS_SPAWN_TOOL_DISPLAY_SUMMARY = "Spawn a sub-agent session.";
+export declare function describeSessionsListTool(): string;
+export declare function describeSessionsHistoryTool(): string;
+export declare function describeSessionsSendTool(): string;
+export declare function describeSessionsSpawnTool(): string;
+//# sourceMappingURL=shared.d.ts.map

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

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

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

@@ -0,0 +1,352 @@
+/**
+ * Shared helpers for the sessions tool surface (Step 19).
+ *
+ * Brand-scrubbed lift of upstream's `src/agents/tools/sessions-*` helpers.
+ * One file because the cross-tool surface is small (~400 LOC); splitting
+ * would just move declarations between files without saving any reads.
+ *
+ * The four sessions tools (`sessions_send`, `sessions_spawn`,
+ * `sessions_list`, `sessions_history`) all reach for the same primitives:
+ *
+ *   - History text sanitizer + 4 KB-per-block / 80 KB-total caps
+ *   - Tool-message stripper (drop tool-call rows from history)
+ *   - JSON-byte-cap enforcement for the per-call result envelope
+ *   - Sender-redactor (strip credentials/API keys before exposing history)
+ *   - Visibility resolution + agent-to-agent allowlist matcher
+ *   - Common error classes that map to tool-result error shapes
+ *
+ * Nothing here issues gateway calls — the tools receive a `GatewayCaller`
+ * (from Step 18 — `agents/gateway-call.ts`) and call out from their own
+ * execute bodies. Keeps the helper layer testable + tool-agnostic.
+ */
+import { resolveAgentIdFromSessionKey } from "../../routing/session-key.js";
+export const SESSIONS_HISTORY_MAX_BYTES = 80 * 1024;
+export const SESSIONS_HISTORY_TEXT_MAX_CHARS = 4_000;
+/* ─── Error classes ─────────────────────────────────────────────── */
+/**
+ * Sessions-tool-specific input / authorization errors. Prefixed with
+ * `Sessions*` to avoid colliding with Brigade's existing
+ * `BrigadeToolInputError` / `BrigadeToolAuthorizationError` in
+ * `src/agents/tools/common.ts` — the two surfaces serve different layers
+ * (sessions tools' execute bodies catch these and return error envelopes
+ * via `jsonToolResult`, while Brigade's existing tools wrap their errors
+ * inline via `wrapOwnerOnlyToolExecution`).
+ */
+export class SessionsToolInputError extends Error {
+    status = 400;
+    constructor(message) {
+        super(message);
+        this.name = "SessionsToolInputError";
+    }
+}
+export class SessionsToolAuthorizationError extends SessionsToolInputError {
+    status = 403;
+    constructor(message) {
+        super(message);
+        this.name = "SessionsToolAuthorizationError";
+    }
+}
+/** @deprecated retained for backwards compatibility; use `SessionsToolInputError`. */
+export const ToolInputError = SessionsToolInputError;
+/** @deprecated retained for backwards compatibility; use `SessionsToolAuthorizationError`. */
+export const ToolAuthorizationError = SessionsToolAuthorizationError;
+/* ─── Text utility ──────────────────────────────────────────────── */
+/**
+ * UTF-16-safe truncation. Preserves surrogate-pair boundaries so the
+ * returned string is always valid UTF-16 (no orphan lead/trail
+ * surrogates), even at the cut point.
+ */
+export function truncateUtf16Safe(value, maxChars) {
+    if (value.length <= maxChars)
+        return value;
+    let end = maxChars;
+    // Don't split a surrogate pair.
+    if (end > 0) {
+        const code = value.charCodeAt(end - 1);
+        if (code >= 0xd800 && code <= 0xdbff)
+            end -= 1;
+    }
+    return value.slice(0, end);
+}
+const SENSITIVE_PATTERNS = [
+    // API keys / bearer tokens (long alphanumeric runs with prefixes)
+    /\b(?:sk|pk|api[_-]?key|bearer|token)[-_=:\s]+[A-Za-z0-9_\-]{16,}\b/gi,
+    // Standalone long base64-ish runs
+    /\b[A-Za-z0-9+/]{40,}={0,2}\b/g,
+    // Generic password-y assignments
+    /\bpassword[\s:=]+\S+/gi,
+    // Github / Slack / common service tokens by prefix
+    /\bghp_[A-Za-z0-9]{20,}\b/g,
+    /\bxoxb-[A-Za-z0-9-]{10,}\b/g,
+    /\bxoxp-[A-Za-z0-9-]{10,}\b/g,
+];
+/** Best-effort credential redaction for history text. NOT a security boundary. */
+export function redactSensitiveText(input) {
+    let out = input;
+    for (const re of SENSITIVE_PATTERNS) {
+        out = out.replace(re, "[redacted]");
+    }
+    return out;
+}
+/* ─── History sanitizers ────────────────────────────────────────── */
+export function truncateHistoryText(text) {
+    const sanitized = redactSensitiveText(text);
+    const redacted = sanitized !== text;
+    if (sanitized.length <= SESSIONS_HISTORY_TEXT_MAX_CHARS) {
+        return { text: sanitized, truncated: false, redacted };
+    }
+    const cut = truncateUtf16Safe(sanitized, SESSIONS_HISTORY_TEXT_MAX_CHARS);
+    return { text: `${cut}\n…(truncated)…`, truncated: true, redacted };
+}
+function readStringValue(value) {
+    return typeof value === "string" ? value : undefined;
+}
+/** Sanitize ONE content block (text, image, thinking, tool-use payload, etc.). */
+export function sanitizeHistoryContentBlock(block) {
+    if (!block || typeof block !== "object") {
+        return { block, truncated: false, redacted: false };
+    }
+    const entry = { ...block };
+    let truncated = false;
+    let redacted = false;
+    const type = typeof entry.type === "string" ? entry.type : "";
+    if (typeof entry.text === "string") {
+        const res = truncateHistoryText(entry.text);
+        entry.text = res.text;
+        truncated ||= res.truncated;
+        redacted ||= res.redacted;
+    }
+    if (type === "thinking") {
+        if (typeof entry.thinking === "string") {
+            const res = truncateHistoryText(entry.thinking);
+            entry.thinking = res.text;
+            truncated ||= res.truncated;
+            redacted ||= res.redacted;
+        }
+        if ("thinkingSignature" in entry) {
+            delete entry.thinkingSignature;
+            truncated = true;
+        }
+    }
+    if (typeof entry.partialJson === "string") {
+        const res = truncateHistoryText(entry.partialJson);
+        entry.partialJson = res.text;
+        truncated ||= res.truncated;
+        redacted ||= res.redacted;
+    }
+    if (type === "image") {
+        const data = readStringValue(entry.data);
+        const bytes = data ? data.length : undefined;
+        if ("data" in entry) {
+            delete entry.data;
+            truncated = true;
+        }
+        entry.omitted = true;
+        if (bytes !== undefined)
+            entry.bytes = bytes;
+    }
+    return { block: entry, truncated, redacted };
+}
+/** Sanitize ONE message — strips heavy fields + sanitizes each content block. */
+export function sanitizeHistoryMessage(message) {
+    if (!message || typeof message !== "object") {
+        return { message, truncated: false, redacted: false };
+    }
+    const entry = { ...message };
+    let truncated = false;
+    let redacted = false;
+    for (const heavy of ["details", "usage", "cost"]) {
+        if (heavy in entry) {
+            delete entry[heavy];
+            truncated = true;
+        }
+    }
+    if (typeof entry.content === "string") {
+        const res = truncateHistoryText(entry.content);
+        entry.content = res.text;
+        truncated ||= res.truncated;
+        redacted ||= res.redacted;
+    }
+    else if (Array.isArray(entry.content)) {
+        const updated = entry.content.map((block) => sanitizeHistoryContentBlock(block));
+        entry.content = updated.map((item) => item.block);
+        truncated ||= updated.some((item) => item.truncated);
+        redacted ||= updated.some((item) => item.redacted);
+    }
+    if (typeof entry.text === "string") {
+        const res = truncateHistoryText(entry.text);
+        entry.text = res.text;
+        truncated ||= res.truncated;
+        redacted ||= res.redacted;
+    }
+    return { message: entry, truncated, redacted };
+}
+/** Drop tool-call + tool-result messages (default for `includeTools: false`). */
+export function stripToolMessages(messages) {
+    return messages.filter((msg) => {
+        if (!msg || typeof msg !== "object")
+            return true;
+        const role = msg.role;
+        return role !== "toolResult" && role !== "tool";
+    });
+}
+/** Byte-aware JSON size estimate (UTF-8). */
+export function jsonUtf8Bytes(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), "utf8");
+    }
+    catch {
+        return Number.MAX_SAFE_INTEGER;
+    }
+}
+/**
+ * Hard byte cap for the per-call envelope. If the message list still
+ * exceeds the cap, fall back to the most recent message — and if even
+ * THAT is too big, swap in a placeholder so the tool never returns a
+ * response that overflows the wire budget.
+ */
+export function enforceSessionsHistoryHardCap(params) {
+    if (params.bytes <= params.maxBytes) {
+        return { items: params.items, bytes: params.bytes, hardCapped: false };
+    }
+    const last = params.items.at(-1);
+    const lastOnly = last ? [last] : [];
+    const lastBytes = jsonUtf8Bytes(lastOnly);
+    if (lastBytes <= params.maxBytes) {
+        return { items: lastOnly, bytes: lastBytes, hardCapped: true };
+    }
+    const placeholder = [
+        { role: "assistant", content: "[sessions_history omitted: message too large]" },
+    ];
+    return { items: placeholder, bytes: jsonUtf8Bytes(placeholder), hardCapped: true };
+}
+/**
+ * Build the A2A policy from a config snapshot. The Brigade gateway
+ * passes `{ enabled, allow }` resolved from `cfg.tools.agentToAgent`;
+ * tests can inject a stub directly without going through config.
+ */
+export function createAgentToAgentPolicy(input) {
+    const { enabled, allow } = input;
+    const matchesAllow = (agentId) => {
+        if (!allow || allow.length === 0)
+            return true;
+        return allow.some((pattern) => {
+            const raw = 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 isAllowed = (requesterAgentId, targetAgentId) => {
+        if (requesterAgentId === targetAgentId)
+            return true;
+        if (!enabled)
+            return false;
+        return matchesAllow(requesterAgentId) && matchesAllow(targetAgentId);
+    };
+    return { enabled, matchesAllow, isAllowed };
+}
+/**
+ * Decide whether a requester session may take the given action on a
+ * target session. The check folds visibility + A2A policy + parent-child
+ * spawned-tree containment in one place.
+ *
+ * `spawnedKeys` is the set of session keys spawned by the requester
+ * (transitively) — the caller is expected to compute it once and reuse
+ * across multiple `checkSessionToolAccess` calls during one tool
+ * invocation.
+ */
+export function checkSessionToolAccess(params) {
+    const { action, requesterSessionKey, targetSessionKey, visibility, a2aPolicy } = params;
+    if (requesterSessionKey === targetSessionKey)
+        return { allowed: true };
+    const requesterAgentId = resolveAgentIdFromSessionKey(requesterSessionKey);
+    const targetAgentId = resolveAgentIdFromSessionKey(targetSessionKey);
+    const crossAgent = targetAgentId !== requesterAgentId;
+    if (crossAgent) {
+        // Self-documenting refusals: each carries the EXACT operator remedy.
+        // Production 2026-06-11 — without this the model guessed wrong causes
+        // ("hot-reload issue") instead of naming the real knob. The remedy is
+        // addressed to the OPERATOR by design: enabling cross-agent reach is
+        // a security decision the agent must surface, not silently apply.
+        if (visibility !== "all") {
+            return forbidden(action, 'cross-agent visibility not enabled (session.sessionTools.visibility is not "all"). When the operator asks you to enable cross-agent messaging, call manage_access set {visibility: "all"} then RETRY this sessions_send in the same turn — it re-checks against the new setting and goes through. The change is live in-memory; NEVER tell the operator to restart the gateway. Do NOT change it unasked.');
+        }
+        if (!a2aPolicy.enabled) {
+            return forbidden(action, "agent-to-agent messaging disabled (session.agentToAgent.enabled is false). When the operator asks, call manage_access set {a2aEnabled: true} (it seeds a wide-open allow list if none exists) then RETRY this sessions_send in the same turn. The change is live — NEVER suggest a gateway restart. Do NOT change it unasked.");
+        }
+        if (!a2aPolicy.isAllowed(requesterAgentId, targetAgentId)) {
+            return forbidden(action, `agent ${targetAgentId} not reachable from ${requesterAgentId} under the current policy. With an org configured, edges follow the org graph (escalate up, assign down, same-department lateral, top↔all; cross-department lateral is closed) — route via the shared manager. A non-org agent like main reaches org members only under explicit/open mode: when the operator asks, call manage_access set {a2aMode: "explicit"}. Do NOT change it unasked.`);
+        }
+        return { allowed: true };
+    }
+    if (visibility === "self") {
+        return forbidden(action, "sessions tool visibility is self-only");
+    }
+    if (visibility === "tree") {
+        if (!params.spawnedKeys?.has(targetSessionKey)) {
+            return forbidden(action, "target session is not in the spawned tree");
+        }
+    }
+    return { allowed: true };
+}
+function forbidden(action, reason) {
+    return {
+        allowed: false,
+        status: "forbidden",
+        error: `sessions_${action} forbidden: ${reason}`,
+    };
+}
+/** Build the standard Pi AgentTool result for JSON payloads. */
+export function jsonToolResult(payload) {
+    return { content: JSON.stringify(payload, null, 2), details: { payload } };
+}
+/* ─── Tool-description presets ──────────────────────────────────── */
+export const SESSIONS_LIST_TOOL_DISPLAY_SUMMARY = "List visible sessions and optional recent messages.";
+export const SESSIONS_HISTORY_TOOL_DISPLAY_SUMMARY = "Read sanitized message history for a visible session.";
+export const SESSIONS_SEND_TOOL_DISPLAY_SUMMARY = "Send a message to another visible session.";
+export const SESSIONS_SPAWN_TOOL_DISPLAY_SUMMARY = "Spawn a sub-agent session.";
+export function describeSessionsListTool() {
+    return [
+        "List visible sessions with optional filters for kind, recent activity, and last messages.",
+        "Use this to discover a target session before calling sessions_history or sessions_send.",
+    ].join(" ");
+}
+export function describeSessionsHistoryTool() {
+    return [
+        "Fetch sanitized message history for a visible session.",
+        "Supports limits and optional tool messages; use this to inspect another session before replying, debugging, or resuming work.",
+    ].join(" ");
+}
+export function describeSessionsSendTool() {
+    return [
+        "Delegate a question to another agent in the crew. The peer agent runs the message in ITS own session (its persona, skills, memory) and returns its reply to you — you can then relay to the user.",
+        "OUTCOMES — exactly two, read them carefully:",
+        '  status "ok": the peer\'s run FINISHED and `reply` is its complete, final answer. Relay it. If the reply is a bare acknowledgement with no deliverable, the peer violated its contract — send a follow-up demanding the deliverable.',
+        '  status "accepted": the peer is STILL WORKING past your wait window. Its finished reply will be DELIVERED to your session automatically — you will see "A2A reply from <peer>: …" on a later turn; relay it to the user THEN. Meanwhile tell the user the work is in progress. Do NOT fabricate results, do NOT poll sessions_history, do NOT promise a time.',
+        "For long tasks you can raise timeoutSeconds (default 90) to wait inline instead of taking the async path.",
+        "Two shorthand shapes:",
+        '  sessions_send({ agentId: "<peer-id>", message: "..." })  — auto-targets the peer\'s main session (the common case)',
+        '  sessions_send({ sessionKey: "agent:<peer-id>:main", message: "..." })  — when you need an explicit session',
+        "This is the canonical delegation pattern when the user asks YOU (the main/orchestrator agent) for something a specialist peer handles better.",
+        "Do NOT use sessions_spawn for delegation — that creates a sub-agent under YOUR session, not a peer hand-off.",
+        "Do NOT tell the user to type /agent <id> when they ask you to handle a delegation request — use this tool to fetch the peer's answer and relay it.",
+        "Tell the user to type /agent <id> ONLY when they explicitly say 'let me talk to <agent>' / 'switch me to <agent>' — that's user-driven, not delegation.",
+    ].join(" ");
+}
+export function describeSessionsSpawnTool() {
+    return [
+        'ASYNC fire-and-forget. Returns IMMEDIATELY with {status:"accepted", childSessionKey, runId}. The child runs in its own session lane.',
+        "WHEN the child finishes, its final assistant reply is DELIVERED into YOUR session transcript as a system message (you will see it on your next turn).",
+        "Do NOT call sessions_history immediately - the result has not landed yet. Use sessions_spawn for parallel fan-out where you do not need the result THIS turn.",
+        "For a blocking call that returns the child's reply as the tool result this turn, use spawn_agent instead.",
+        'mode="run" is one-shot; mode="session" keeps the child available for thread follow-up via sessions_send. Sub-agents inherit the parent workspace directory automatically.',
+    ].join(" ");
+}
+//# sourceMappingURL=shared.js.map

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

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

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

@@ -0,0 +1,71 @@
+/**
+ * `sessions_spawn` agent tool (Step 20).
+ *
+ * Thin factory around `spawnSubagentDirect` (the spawn engine). The tool
+ * declares its TypeBox-shaped schema, parses + validates args, then
+ * delegates to the engine and returns a structured `jsonToolResult`.
+ *
+ * Pi AgentTool shape (best-effort match — Brigade pins to the version in
+ * `node_modules/@mariozechner/pi-coding-agent`):
+ *
+ *   {
+ *     name: "sessions_spawn",
+ *     description: "...",
+ *     parameters: TypeBox schema,
+ *     execute: async (args, ctx) => ToolResultEnvelope,
+ *   }
+ *
+ * The tool factory accepts the **per-turn opts** the gateway dispatcher
+ * fills in (caller's session key, channel, agent id override, etc.) and
+ * returns a Pi-compatible tool descriptor.
+ */
+import type { SpawnSubagentMode, SpawnSubagentSandboxMode } from "../../subagent-registry.types.js";
+import { type AgentToAgentPolicy, type SessionToolsVisibility, type ToolResultEnvelope } from "./shared.js";
+export interface SessionsSpawnToolArgs {
+    task: string;
+    label?: string;
+    agentId?: string;
+    model?: string;
+    thinking?: string;
+    runTimeoutSeconds?: number;
+    thread?: boolean;
+    mode?: SpawnSubagentMode;
+    cleanup?: "delete" | "keep";
+    sandbox?: SpawnSubagentSandboxMode;
+    lightContext?: boolean;
+    expectsCompletionMessage?: boolean;
+}
+export interface SessionsSpawnToolOptions {
+    agentSessionKey?: string;
+    agentChannel?: string;
+    agentAccountId?: string;
+    agentTo?: string;
+    agentThreadId?: string | number;
+    requesterAgentIdOverride?: string;
+    workspaceDir?: string;
+    /** Caller's spawn depth — usually read from the session store. */
+    callerDepth?: number;
+    maxSpawnDepth?: number;
+    maxChildrenPerAgent?: number;
+    /** 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.
+     * Untrusted callers leave this unset so unwired bundles refuse spawn
+     * requests by default.
+     */
+    bypassAccessGuard?: boolean;
+}
+export interface SessionsSpawnToolDescriptor {
+    name: "sessions_spawn";
+    displaySummary: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (args: SessionsSpawnToolArgs) => Promise<ToolResultEnvelope>;
+}
+export declare function createSessionsSpawnTool(opts?: SessionsSpawnToolOptions): SessionsSpawnToolDescriptor;
+//# sourceMappingURL=spawn.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../../../../src/agents/tools/sessions/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EACX,iBAAiB,EACjB,wBAAwB,EACxB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAMN,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACvB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,OAAO,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACnC;AAED,MAAM,WAAW,wBAAwB;IACxC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,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,2BAA2B;IAC3C,IAAI,EAAE,gBAAgB,CAAC;IACvB,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,qBAAqB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACtE;AAyDD,wBAAgB,uBAAuB,CACtC,IAAI,GAAE,wBAA6B,GACjC,2BAA2B,CA0D7B"}