@spinabot/brigade 0.1.1 → 1.0.0

package/dist/agents/session-context.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Per-turn session-context metadata.
+ *
+ * Brand-scrubbed analogue of upstream's `src/infra/outbound/session-context.ts`
+ * (`OutboundSessionContext` + `buildOutboundSessionContext`).
+ *
+ * Holds the seven small fields every outbound + hook path needs to know
+ * which session a payload belongs to, which agent owns it, and where the
+ * inbound that triggered the turn came from. The factory is the canonical
+ * place to bind a session key to an agent id — every call site that
+ * threads context through downstream hooks routes through `buildSessionContext`
+ * so the resolution is consistent.
+ *
+ * What this is NOT:
+ *   - Not a state container (no mutation; immutable struct).
+ *   - Not the registry handle (see `./session-registry.ts`).
+ *   - Not the inbox handle (see `./session-inbox.ts`).
+ *   - Not the abort signal carrier (handlers receive `AbortSignal` as a
+ *     separate arg per upstream's split).
+ *
+ * What it IS: the short, JSON-friendly bundle that gets passed to media
+ * resolvers, hook handlers, delivery-queue persistence, and outbound
+ * routing so they can re-resolve policy decisions without re-parsing the
+ * session key or re-walking the bindings tree.
+ *
+ * Consumed (today + planned):
+ *   - Outbound media access resolver (channels): account-scoped policy match
+ *   - Delivery-queue storage (channels): crash-safe replay context
+ *   - Hook fan-out (Step 18): every hook sees `{ session }` arg
+ *   - Gateway dispatcher (Step 25): assembles per-turn context payload
+ *   - Cron failure-notification builder (later): re-routes failures to the
+ *     originating session
+ */
+/**
+ * Per-turn metadata pinned to one session.
+ *
+ * All fields are optional individually — the factory returns `undefined`
+ * if every field would be empty, so consumers can fail-open on a
+ * fully-anonymous context (the dispatcher won't build one for a bound
+ * inbound).
+ */
+export type SessionContext = {
+    /** Canonical session key used for internal hook dispatch. */
+    key?: string;
+    /** Active agent id used for workspace-scoped media roots. */
+    agentId?: string;
+    /** Originating account id used for requester-scoped group policy resolution. */
+    requesterAccountId?: string;
+    /** Originating sender id used for sender-scoped outbound media policy. */
+    requesterSenderId?: string;
+    /** Originating sender display name for name-keyed sender policy matching. */
+    requesterSenderName?: string;
+    /** Originating sender username for username-keyed sender policy matching. */
+    requesterSenderUsername?: string;
+    /** Originating sender E.164 phone number for e164-keyed sender policy matching. */
+    requesterSenderE164?: string;
+};
+export interface BuildSessionContextParams {
+    sessionKey?: string | null;
+    /** Pin a specific agent id. Overrides the agent id derived from `sessionKey`. */
+    agentId?: string | null;
+    requesterAccountId?: string | null;
+    requesterSenderId?: string | null;
+    requesterSenderName?: string | null;
+    requesterSenderUsername?: string | null;
+    requesterSenderE164?: string | null;
+}
+/**
+ * Assemble a `SessionContext` from the loose params the upstream caller
+ * has at hand. Returns `undefined` when every field would be empty —
+ * lets the caller skip the context-arg entirely for unbound flows.
+ *
+ * Agent id resolution:
+ *   1. `params.agentId` if explicit and non-empty
+ *   2. Otherwise, derive from `sessionKey` via `resolveAgentIdFromSessionKey`
+ *      (parses `agent:<id>:<rest>` or falls back to the default agent)
+ *   3. `undefined` if both are missing
+ */
+export declare function buildSessionContext(params: BuildSessionContextParams): SessionContext | undefined;
+//# sourceMappingURL=session-context.d.ts.map

package/dist/agents/session-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../src/agents/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG;IAC5B,6DAA6D;IAC7D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,0EAA0E;IAC1E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,mFAAmF;IACnF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,WAAW,yBAAyB;IACzC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,kBAAkB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,uBAAuB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAClC,MAAM,EAAE,yBAAyB,GAC/B,cAAc,GAAG,SAAS,CA8B5B"}

package/dist/agents/session-context.js

@@ -0,0 +1,76 @@
+/**
+ * Per-turn session-context metadata.
+ *
+ * Brand-scrubbed analogue of upstream's `src/infra/outbound/session-context.ts`
+ * (`OutboundSessionContext` + `buildOutboundSessionContext`).
+ *
+ * Holds the seven small fields every outbound + hook path needs to know
+ * which session a payload belongs to, which agent owns it, and where the
+ * inbound that triggered the turn came from. The factory is the canonical
+ * place to bind a session key to an agent id — every call site that
+ * threads context through downstream hooks routes through `buildSessionContext`
+ * so the resolution is consistent.
+ *
+ * What this is NOT:
+ *   - Not a state container (no mutation; immutable struct).
+ *   - Not the registry handle (see `./session-registry.ts`).
+ *   - Not the inbox handle (see `./session-inbox.ts`).
+ *   - Not the abort signal carrier (handlers receive `AbortSignal` as a
+ *     separate arg per upstream's split).
+ *
+ * What it IS: the short, JSON-friendly bundle that gets passed to media
+ * resolvers, hook handlers, delivery-queue persistence, and outbound
+ * routing so they can re-resolve policy decisions without re-parsing the
+ * session key or re-walking the bindings tree.
+ *
+ * Consumed (today + planned):
+ *   - Outbound media access resolver (channels): account-scoped policy match
+ *   - Delivery-queue storage (channels): crash-safe replay context
+ *   - Hook fan-out (Step 18): every hook sees `{ session }` arg
+ *   - Gateway dispatcher (Step 25): assembles per-turn context payload
+ *   - Cron failure-notification builder (later): re-routes failures to the
+ *     originating session
+ */
+import { resolveAgentIdFromSessionKey } from "./routing/session-key.js";
+import { normalizeOptionalString } from "../shared/string-coerce.js";
+/**
+ * Assemble a `SessionContext` from the loose params the upstream caller
+ * has at hand. Returns `undefined` when every field would be empty —
+ * lets the caller skip the context-arg entirely for unbound flows.
+ *
+ * Agent id resolution:
+ *   1. `params.agentId` if explicit and non-empty
+ *   2. Otherwise, derive from `sessionKey` via `resolveAgentIdFromSessionKey`
+ *      (parses `agent:<id>:<rest>` or falls back to the default agent)
+ *   3. `undefined` if both are missing
+ */
+export function buildSessionContext(params) {
+    const key = normalizeOptionalString(params.sessionKey);
+    const explicitAgentId = normalizeOptionalString(params.agentId);
+    const requesterAccountId = normalizeOptionalString(params.requesterAccountId);
+    const requesterSenderId = normalizeOptionalString(params.requesterSenderId);
+    const requesterSenderName = normalizeOptionalString(params.requesterSenderName);
+    const requesterSenderUsername = normalizeOptionalString(params.requesterSenderUsername);
+    const requesterSenderE164 = normalizeOptionalString(params.requesterSenderE164);
+    const derivedAgentId = key ? resolveAgentIdFromSessionKey(key) : undefined;
+    const agentId = explicitAgentId ?? derivedAgentId;
+    if (!key &&
+        !agentId &&
+        !requesterAccountId &&
+        !requesterSenderId &&
+        !requesterSenderName &&
+        !requesterSenderUsername &&
+        !requesterSenderE164) {
+        return undefined;
+    }
+    return {
+        ...(key ? { key } : {}),
+        ...(agentId ? { agentId } : {}),
+        ...(requesterAccountId ? { requesterAccountId } : {}),
+        ...(requesterSenderId ? { requesterSenderId } : {}),
+        ...(requesterSenderName ? { requesterSenderName } : {}),
+        ...(requesterSenderUsername ? { requesterSenderUsername } : {}),
+        ...(requesterSenderE164 ? { requesterSenderE164 } : {}),
+    };
+}
+//# sourceMappingURL=session-context.js.map

package/dist/agents/session-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.js","sourceRoot":"","sources":["../../src/agents/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAAE,4BAA4B,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AAsCrE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CAClC,MAAiC;IAEjC,MAAM,GAAG,GAAG,uBAAuB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IACvD,MAAM,eAAe,GAAG,uBAAuB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChE,MAAM,kBAAkB,GAAG,uBAAuB,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;IAC9E,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;IAC5E,MAAM,mBAAmB,GAAG,uBAAuB,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAChF,MAAM,uBAAuB,GAAG,uBAAuB,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC;IACxF,MAAM,mBAAmB,GAAG,uBAAuB,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;IAChF,MAAM,cAAc,GAAG,GAAG,CAAC,CAAC,CAAC,4BAA4B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3E,MAAM,OAAO,GAAG,eAAe,IAAI,cAAc,CAAC;IAClD,IACC,CAAC,GAAG;QACJ,CAAC,OAAO;QACR,CAAC,kBAAkB;QACnB,CAAC,iBAAiB;QAClB,CAAC,mBAAmB;QACpB,CAAC,uBAAuB;QACxB,CAAC,mBAAmB,EACnB,CAAC;QACF,OAAO,SAAS,CAAC;IAClB,CAAC;IACD,OAAO;QACN,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvB,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/B,GAAG,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvD,GAAG,CAAC,uBAAuB,CAAC,CAAC,CAAC,EAAE,uBAAuB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,mBAAmB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC;AACH,CAAC"}

package/dist/agents/session-event-prompt.d.ts

@@ -0,0 +1,124 @@
+/**
+ * SessionInbox → prompt-block orchestrator (Step 12).
+ *
+ * Sits one layer above `session-inbox.ts` (Step 11). Decides:
+ *
+ *   - WHEN to drain (turn-start; never mid-stream — events arriving while
+ *     the model is generating tokens queue and wait for the next turn
+ *     boundary).
+ *   - HOW to compose drained events into prompt text (`System: [ts] text`
+ *     per line, `System (untrusted): ...` for tainted events).
+ *   - WHICH events to filter (heartbeat scheduler noise, node-PII suffix
+ *     scrubbing) — at format time, NOT at enqueue time. Events stay in
+ *     the queue even if they'll be filtered, so consumers can audit what
+ *     was suppressed by `peek`-ing first.
+ *
+ * Brand-scrubbed analogue of upstream's `src/auto-reply/reply/session-system-events.ts`
+ * — the `drainFormattedSystemEvents` flow, scoped to the slice Brigade
+ * needs without the upstream's channel-summary prepend (no channel
+ * surface yet) or the upstream `Config`-driven timezone
+ * resolution (Brigade uses UTC ISO-8601 today; callers can override).
+ *
+ * Naming note: Brigade already has `agents/pending-system-events.ts`,
+ * which is the cron-only announce queue (Track 2 — see that file's
+ * doc-comment). The orchestrator here works against the broader
+ * SessionInbox queue from Step 11 and is reference-source-equivalent. The two
+ * queues serve different paths and are NOT consolidated until the
+ * Step 25 dispatcher arrives.
+ *
+ * Two entry points:
+ *
+ *   - `drainFormattedSessionEvents({ sessionKey, ... })` — drains + formats
+ *     in one call. Used by the turn-start path: when a real inbound
+ *     arrives, the prompt assembler calls this once and prepends the
+ *     returned block (if any) to the user message body.
+ *
+ *   - `peekFormattedSessionEvents({ sessionKey })` — read-only inspect
+ *     (no drain). Used by the heartbeat preflight: peek first, decide
+ *     whether to fire a heartbeat turn, only then `consume` the
+ *     inspected prefix so events stay queued for the next real turn if
+ *     the heartbeat is filtered out.
+ *
+ * Output format (one line per event sub-line):
+ *
+ *   `System: [2026-06-02T14:23:45Z] Build #42 complete`
+ *   `System (untrusted): [2026-06-02T14:23:50Z] alert: CPU > 90%`
+ *
+ * If every queued event is filtered, returns `undefined` so the caller
+ * can omit the block entirely (no empty "System: " line in the prompt).
+ *
+ * Filter rules (lifted verbatim from the upstream noise-suppression):
+ *
+ *   - drop lines containing `reason periodic`  (heartbeat-scheduler noise)
+ *   - drop lines starting with `read heartbeat.md`  (heartbeat prompt itself)
+ *   - drop lines containing `heartbeat poll` or `heartbeat wake`
+ *   - scrub the `Node: ... · last input X · Y` suffix (avoids PII echo)
+ *
+ * Filtering happens at compose time so an audit can `peek` to see what
+ * was queued including noise; the noise just doesn't make it to the
+ * prompt.
+ */
+import { type SystemEvent } from "./session-inbox.js";
+export interface FormatSessionEventsOptions {
+    /**
+     * Override the default ISO-8601 formatter. Receives ms-since-epoch,
+     * should return a short human-readable timestamp (or empty string to
+     * omit it).
+     */
+    formatTimestamp?: (ts: number) => string;
+}
+/**
+ * Format a `SystemEvent[]` list to a single prompt block (or `undefined`
+ * if every event was filtered out). Pure — does not touch the inbox.
+ */
+export declare function formatSessionEventBlock(events: readonly SystemEvent[], opts?: FormatSessionEventsOptions): string | undefined;
+export interface DrainFormattedSessionEventsParams extends FormatSessionEventsOptions {
+    sessionKey: string;
+    /** Reserved for future channel-summary prepend (no-op today). */
+    isMainSession?: boolean;
+    /** Reserved for future channel-summary prepend (no-op today). */
+    isNewSession?: boolean;
+}
+/**
+ * Drain every queued event for a session and return the formatted prompt
+ * block (or `undefined` if no event survived the filter). The session's
+ * inbox is empty after this call.
+ *
+ * `isMainSession` + `isNewSession` are accepted for upstream-parity but
+ * not yet used — when Brigade lands per-channel status summaries, those
+ * will prepend a "Channel status:" block on the first turn of a fresh
+ * main session.
+ */
+export declare function drainFormattedSessionEvents(params: DrainFormattedSessionEventsParams): string | undefined;
+export interface PeekFormattedSessionEventsParams extends FormatSessionEventsOptions {
+    sessionKey: string;
+}
+/**
+ * Peek (NO drain). Same composition as `drainFormattedSessionEvents`, but
+ * leaves the inbox intact. Used by the heartbeat preflight to decide
+ * whether to fire a turn; the actual drain only happens later (via
+ * `consumeSystemEventEntries`) if the heartbeat run is going to proceed.
+ *
+ * Returns `undefined` when every event would be filtered — the peek
+ * answer is "no surface-able events" even if the queue technically
+ * contains noise.
+ */
+export declare function peekFormattedSessionEvents(params: PeekFormattedSessionEventsParams): string | undefined;
+/**
+ * Inspect the pending events for a session without formatting.
+ *
+ * Returns the array of `SystemEvent` objects (cloned, safe to mutate)
+ * plus two derived flags:
+ *   - `hasSurfaceable` — `true` iff at least one event would survive the
+ *     filter pipeline; used by the heartbeat preflight to decide whether
+ *     to fire a turn at all.
+ *   - `hasUntrusted` — `true` iff any event carries `trusted: false`;
+ *     used to force `senderIsOwner: false` on the resulting turn so the
+ *     model treats the context as third-party.
+ */
+export declare function inspectPendingSessionEvents(sessionKey: string): {
+    events: SystemEvent[];
+    hasSurfaceable: boolean;
+    hasUntrusted: boolean;
+};
+//# sourceMappingURL=session-event-prompt.d.ts.map

package/dist/agents/session-event-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-event-prompt.d.ts","sourceRoot":"","sources":["../../src/agents/session-event-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAGH,OAAO,EAGN,KAAK,WAAW,EAChB,MAAM,oBAAoB,CAAC;AA4D5B,MAAM,WAAW,0BAA0B;IAC1C;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACzC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,IAAI,GAAE,0BAA+B,GACnC,MAAM,GAAG,SAAS,CAUpB;AAED,MAAM,WAAW,iCAAkC,SAAQ,0BAA0B;IACpF,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAC1C,MAAM,EAAE,iCAAiC,GACvC,MAAM,GAAG,SAAS,CAGpB;AAED,MAAM,WAAW,gCAAiC,SAAQ,0BAA0B;IACnF,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,gCAAgC,GACtC,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CAAC,UAAU,EAAE,MAAM,GAAG;IAChE,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;CACtB,CAKA"}

package/dist/agents/session-event-prompt.js

@@ -0,0 +1,179 @@
+/**
+ * SessionInbox → prompt-block orchestrator (Step 12).
+ *
+ * Sits one layer above `session-inbox.ts` (Step 11). Decides:
+ *
+ *   - WHEN to drain (turn-start; never mid-stream — events arriving while
+ *     the model is generating tokens queue and wait for the next turn
+ *     boundary).
+ *   - HOW to compose drained events into prompt text (`System: [ts] text`
+ *     per line, `System (untrusted): ...` for tainted events).
+ *   - WHICH events to filter (heartbeat scheduler noise, node-PII suffix
+ *     scrubbing) — at format time, NOT at enqueue time. Events stay in
+ *     the queue even if they'll be filtered, so consumers can audit what
+ *     was suppressed by `peek`-ing first.
+ *
+ * Brand-scrubbed analogue of upstream's `src/auto-reply/reply/session-system-events.ts`
+ * — the `drainFormattedSystemEvents` flow, scoped to the slice Brigade
+ * needs without the upstream's channel-summary prepend (no channel
+ * surface yet) or the upstream `Config`-driven timezone
+ * resolution (Brigade uses UTC ISO-8601 today; callers can override).
+ *
+ * Naming note: Brigade already has `agents/pending-system-events.ts`,
+ * which is the cron-only announce queue (Track 2 — see that file's
+ * doc-comment). The orchestrator here works against the broader
+ * SessionInbox queue from Step 11 and is reference-source-equivalent. The two
+ * queues serve different paths and are NOT consolidated until the
+ * Step 25 dispatcher arrives.
+ *
+ * Two entry points:
+ *
+ *   - `drainFormattedSessionEvents({ sessionKey, ... })` — drains + formats
+ *     in one call. Used by the turn-start path: when a real inbound
+ *     arrives, the prompt assembler calls this once and prepends the
+ *     returned block (if any) to the user message body.
+ *
+ *   - `peekFormattedSessionEvents({ sessionKey })` — read-only inspect
+ *     (no drain). Used by the heartbeat preflight: peek first, decide
+ *     whether to fire a heartbeat turn, only then `consume` the
+ *     inspected prefix so events stay queued for the next real turn if
+ *     the heartbeat is filtered out.
+ *
+ * Output format (one line per event sub-line):
+ *
+ *   `System: [2026-06-02T14:23:45Z] Build #42 complete`
+ *   `System (untrusted): [2026-06-02T14:23:50Z] alert: CPU > 90%`
+ *
+ * If every queued event is filtered, returns `undefined` so the caller
+ * can omit the block entirely (no empty "System: " line in the prompt).
+ *
+ * Filter rules (lifted verbatim from the upstream noise-suppression):
+ *
+ *   - drop lines containing `reason periodic`  (heartbeat-scheduler noise)
+ *   - drop lines starting with `read heartbeat.md`  (heartbeat prompt itself)
+ *   - drop lines containing `heartbeat poll` or `heartbeat wake`
+ *   - scrub the `Node: ... · last input X · Y` suffix (avoids PII echo)
+ *
+ * Filtering happens at compose time so an audit can `peek` to see what
+ * was queued including noise; the noise just doesn't make it to the
+ * prompt.
+ */
+import { normalizeLowercaseStringOrEmpty } from "../shared/string-coerce.js";
+import { drainSystemEventEntries, peekSystemEventEntries, } from "./session-inbox.js";
+const NODE_LAST_INPUT_SUFFIX_RE = / · last input [^·]+/i;
+/**
+ * Apply upstream's heartbeat-noise filter + node-PII scrub.
+ * Returns the compacted text or `null` if the line should be dropped.
+ */
+function compactSystemEventText(line) {
+    const trimmed = line.trim();
+    if (!trimmed)
+        return null;
+    const lower = normalizeLowercaseStringOrEmpty(trimmed);
+    // Heartbeat scheduler noise — never useful to the model.
+    if (lower.includes("reason periodic"))
+        return null;
+    // The heartbeat prompt itself. Cron payloads that *mention* heartbeat
+    // won't match this prefix.
+    if (lower.startsWith("read heartbeat.md"))
+        return null;
+    // Heartbeat poll/wake completion noise.
+    if (lower.includes("heartbeat poll") || lower.includes("heartbeat wake"))
+        return null;
+    // `Node:` status lines leak the last input path. Scrub the suffix.
+    if (trimmed.startsWith("Node:")) {
+        return trimmed.replace(NODE_LAST_INPUT_SUFFIX_RE, "").trim();
+    }
+    return trimmed;
+}
+/**
+ * Default timestamp formatter: ISO 8601 in UTC, second resolution.
+ * Consumers that need local-time formatting can pass their own `formatTimestamp`.
+ */
+function defaultFormatTimestamp(ts) {
+    if (!Number.isFinite(ts) || ts <= 0)
+        return "";
+    return new Date(ts).toISOString().replace(/\.\d{3}Z$/, "Z");
+}
+function eventPrefix(event) {
+    return event.trusted === false ? "System (untrusted)" : "System";
+}
+/**
+ * Format a single event into one or more prompt lines (one per text
+ * line in the event). The first line carries the `[timestamp]`; any
+ * continuation lines carry just the prefix so the model can't mistake
+ * a continuation for fresh user content.
+ */
+function formatEventLines(event, formatTimestamp) {
+    const compacted = compactSystemEventText(event.text);
+    if (!compacted)
+        return [];
+    const prefix = eventPrefix(event);
+    const timestamp = formatTimestamp(event.ts);
+    const timestampLabel = timestamp ? `[${timestamp}] ` : "";
+    const sublines = compacted.split("\n");
+    return sublines.map((subline, index) => index === 0 ? `${prefix}: ${timestampLabel}${subline}` : `${prefix}: ${subline}`);
+}
+/**
+ * Format a `SystemEvent[]` list to a single prompt block (or `undefined`
+ * if every event was filtered out). Pure — does not touch the inbox.
+ */
+export function formatSessionEventBlock(events, opts = {}) {
+    if (events.length === 0)
+        return undefined;
+    const formatTimestamp = opts.formatTimestamp ?? defaultFormatTimestamp;
+    const lines = [];
+    for (const event of events) {
+        for (const formatted of formatEventLines(event, formatTimestamp)) {
+            lines.push(formatted);
+        }
+    }
+    return lines.length === 0 ? undefined : lines.join("\n");
+}
+/**
+ * Drain every queued event for a session and return the formatted prompt
+ * block (or `undefined` if no event survived the filter). The session's
+ * inbox is empty after this call.
+ *
+ * `isMainSession` + `isNewSession` are accepted for upstream-parity but
+ * not yet used — when Brigade lands per-channel status summaries, those
+ * will prepend a "Channel status:" block on the first turn of a fresh
+ * main session.
+ */
+export function drainFormattedSessionEvents(params) {
+    const events = drainSystemEventEntries(params.sessionKey);
+    return formatSessionEventBlock(events, { formatTimestamp: params.formatTimestamp });
+}
+/**
+ * Peek (NO drain). Same composition as `drainFormattedSessionEvents`, but
+ * leaves the inbox intact. Used by the heartbeat preflight to decide
+ * whether to fire a turn; the actual drain only happens later (via
+ * `consumeSystemEventEntries`) if the heartbeat run is going to proceed.
+ *
+ * Returns `undefined` when every event would be filtered — the peek
+ * answer is "no surface-able events" even if the queue technically
+ * contains noise.
+ */
+export function peekFormattedSessionEvents(params) {
+    const events = peekSystemEventEntries(params.sessionKey);
+    return formatSessionEventBlock(events, { formatTimestamp: params.formatTimestamp });
+}
+/**
+ * Inspect the pending events for a session without formatting.
+ *
+ * Returns the array of `SystemEvent` objects (cloned, safe to mutate)
+ * plus two derived flags:
+ *   - `hasSurfaceable` — `true` iff at least one event would survive the
+ *     filter pipeline; used by the heartbeat preflight to decide whether
+ *     to fire a turn at all.
+ *   - `hasUntrusted` — `true` iff any event carries `trusted: false`;
+ *     used to force `senderIsOwner: false` on the resulting turn so the
+ *     model treats the context as third-party.
+ */
+export function inspectPendingSessionEvents(sessionKey) {
+    const events = peekSystemEventEntries(sessionKey);
+    const hasUntrusted = events.some((event) => event.trusted === false);
+    const hasSurfaceable = events.some((event) => compactSystemEventText(event.text) !== null);
+    return { events, hasSurfaceable, hasUntrusted };
+}
+//# sourceMappingURL=session-event-prompt.js.map

package/dist/agents/session-event-prompt.js.map

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

package/dist/agents/session-inbox.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Per-session system-event inbox.
+ *
+ * Brand-scrubbed verbatim lift of upstream's `src/infra/system-events.ts`.
+ * Lightweight, in-memory, ephemeral queue of human-readable events that
+ * the next turn for a session prefixes onto the prompt. Persistence is
+ * intentionally NOT supported — events are wake-up signals, not history.
+ *
+ * Producers (planned):
+ *   - Channel manager (Step 16) → inbound messages while a turn is busy
+ *   - Cron service (later) → fired-job reminders + payloads
+ *   - Sub-agent completion handler (Step 20) → child-result notifications
+ *   - Approval router (Step 17) → operator decisions on tool gates
+ *   - Heartbeat layer (Steps 13-14) → wake signals scoped per session
+ *
+ * Consumer (always one):
+ *   - The session's main turn loop, which calls `drainSystemEventEntries`
+ *     before composing the next user message.
+ *
+ * Concurrency:
+ *   - Map is a global singleton, shared across the gateway process.
+ *   - Mutations are NOT lock-guarded; producers run on the JS event loop
+ *     and the consumer drains under the per-session lane lock that
+ *     `command-queue.ts` already enforces, so the only "drain mid-write"
+ *     race is one producer racing one drainer — and the drainer atomically
+ *     snapshots-then-truncates so the worst case is "next call sees the
+ *     latecomer".
+ *   - 20-event soft cap per session (oldest dropped) prevents a runaway
+ *     producer from starving memory.
+ *   - Consecutive identical `text` is suppressed (returns `false` from
+ *     `enqueueSystemEvent`) so a noisy producer can't fill the queue with
+ *     duplicates.
+ */
+import type { DeliveryContext } from "../utils/delivery-context.js";
+export type SystemEvent = {
+    text: string;
+    ts: number;
+    contextKey?: string | null;
+    deliveryContext?: DeliveryContext;
+    trusted?: boolean;
+};
+type SystemEventOptions = {
+    sessionKey: string;
+    contextKey?: string | null;
+    deliveryContext?: DeliveryContext;
+    trusted?: boolean;
+};
+export declare function awaitInboxMirrorFlush(): Promise<void>;
+/**
+ * `true` iff `contextKey` differs from the most-recently-enqueued event's
+ * key for this session. Used by producers that want to suppress a follow-up
+ * notification when the operator is still inside the same logical context
+ * (e.g. a long-running exec emitting periodic status — only the first
+ * status text needs to wake the session).
+ */
+export declare function isSystemEventContextChanged(sessionKey: string, contextKey?: string | null): boolean;
+/**
+ * Enqueue a human-readable system event for the next turn on `sessionKey`.
+ *
+ * Returns:
+ *   - `true`  → event accepted (queued or replaced a duplicate's metadata)
+ *   - `false` → event dropped (empty text OR consecutive duplicate text)
+ *
+ * Empty-string `text` is dropped silently. Consecutive duplicates by `text`
+ * are suppressed so a noisy producer can't flood the queue.
+ */
+export declare function enqueueSystemEvent(text: string, options: SystemEventOptions): boolean;
+/**
+ * Atomic snapshot-and-truncate: returns every queued event for the session
+ * in FIFO order and resets the queue.
+ *
+ * Empty queues return `[]` (NOT `undefined`). The session's queue entry is
+ * deleted from the global Map after a successful drain so the registry
+ * doesn't grow unbounded under churn.
+ */
+export declare function drainSystemEventEntries(sessionKey: string): SystemEvent[];
+/**
+ * Partial drain. Removes ONLY the events that match the leading prefix of
+ * `consumedEntries` (compared field-wise). If the caller's prefix doesn't
+ * match (events arrived out of order, or were already drained), the queue
+ * is left intact and `[]` is returned.
+ *
+ * Used by Step 12's pending-system-events partial drain: the prompt
+ * assembler peeks at events, formats them, then consumes the exact set it
+ * was about to render — guarantees no event is rendered AND queued at the
+ * same time, even under concurrent writes.
+ */
+export declare function consumeSystemEventEntries(sessionKey: string, consumedEntries: readonly SystemEvent[]): SystemEvent[];
+/** Drain just the text strings (legacy compatible). */
+export declare function drainSystemEvents(sessionKey: string): string[];
+/** Read-only peek at the queued events for a session. */
+export declare function peekSystemEventEntries(sessionKey: string): SystemEvent[];
+/** Read-only peek at the queued event texts for a session. */
+export declare function peekSystemEvents(sessionKey: string): string[];
+/** `true` iff the session has at least one queued event. */
+export declare function hasSystemEvents(sessionKey: string): boolean;
+/**
+ * Remove the FIRST queued event matching `text` + `contextKey` exactly,
+ * wherever it sits in the queue. Returns true when one was removed.
+ *
+ * Exists for producers that enqueue an event BEFORE a dispatch that can
+ * fail (sessions_send enqueues the A2A attribution event, then dispatches
+ * the peer turn): on a failed dispatch the event must be withdrawn or it
+ * ghosts into the peer's NEXT unrelated turn ("A2A from X: …" acted on
+ * hours later). `consumeSystemEventEntries` can't do this — it only
+ * removes exact queue PREFIXES (its drain contract).
+ */
+export declare function removeMatchingSystemEvent(sessionKey: string, match: {
+    text: string;
+    contextKey?: string;
+}): boolean;
+/**
+ * Merge the delivery contexts of `events` into a single context. Later
+ * events override earlier ones field-by-field. Used by the dispatcher to
+ * pick a delivery target when multiple events fired for the same session.
+ */
+export declare function resolveSystemEventDeliveryContext(events: readonly SystemEvent[]): DeliveryContext | undefined;
+/** Test-only — clear every queued event across every session. */
+export declare function resetSessionInboxForTest(): void;
+/**
+ * Wave O0.8 GAP 11 — explicit "force re-hydrate from disk" for the
+ * post-restart replay path. Production callers don't need this (hydration
+ * is lazy on first access of every public read/write entry), but tests
+ * that simulate a gateway restart by clearing the in-memory Map need to
+ * trigger hydration without touching one of the public APIs first.
+ */
+export declare function forceHydrateFromDiskForTests(sessionKey: string): void;
+export {};
+//# sourceMappingURL=session-inbox.d.ts.map

package/dist/agents/session-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-inbox.d.ts","sourceRoot":"","sources":["../../src/agents/session-inbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAcH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAKpE,MAAM,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAiBF,KAAK,kBAAkB,GAAG;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAqGF,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC,CAErD;AAyHD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAC1C,UAAU,EAAE,MAAM,EAClB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB,OAAO,CAKT;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CA8BrF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE,CAezE;AAsBD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACxC,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,SAAS,WAAW,EAAE,GACrC,WAAW,EAAE,CA+Bf;AAED,uDAAuD;AACvD,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAE9D;AAED,yDAAyD;AACzD,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,EAAE,CAGxE;AAED,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAE7D;AAED,4DAA4D;AAC5D,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAG3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACxC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1C,OAAO,CA0BT;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAChD,MAAM,EAAE,SAAS,WAAW,EAAE,GAC5B,eAAe,GAAG,SAAS,CAM7B;AAED,iEAAiE;AACjE,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAErE"}