shraga 0.1.87 → 0.1.89

package/src/server/scheduler/runner.ts

@@ -219,10 +219,11 @@ export async function runSchedule(
   // task.engine/task.model ride the same prompt-directive channel users type by hand —
   // parseDirectives strips them and resolves aliases. Prepending (vs new plumbing) also persists the
   // choice into the saved prompt, so the session UI shows what the schedule actually requested.
-  if (!resume) {
-    const pins = [task.engine && `engine:${task.engine}`, task.model && `model:${task.model}`].filter(Boolean);
-    if (pins.length) prompt = `[${pins.join(',')}] ${prompt}`;
-  }
+  // Applied on RESUME too: a resume's prompt is a fresh "continue where you left off" string, not the
+  // saved original, so skipping this here silently dropped the schedule's engine/model pin and let the
+  // resumed turn run on the global default — a different engine, and a different vendor's bill.
+  const pins = [task.engine && `engine:${task.engine}`, task.model && `model:${task.model}`].filter(Boolean);
+  if (pins.length) prompt = `[${pins.join(',')}] ${prompt}`;
 
   // Save the synthesized user prompt to the conversation (skip on resume — task prompt already persisted).
   if (!resume) {

package/src/server/sessions.ts

@@ -38,6 +38,9 @@ export interface SessionMeta {
   directives?: Directives;
   /** Actual model the engine resolved at runtime (from the SDK init message) — ground truth, unlike directives.model which is the request. */
   lastModel?: string;
+  /** Engine that actually ran the last turn — ground truth beside `lastModel`, so the UI can report
+   *  what executed instead of inferring the engine from the model id's shape. */
+  lastEngine?: string;
   forkedFrom?: string;
 }
 
@@ -189,19 +192,24 @@ export function setSessionDirectives(sessionId: string, directives: NonNullable<
 // Resolved model per running session (set by the engine from the SDK init message).
 // appendMessage stamps assistant messages from this map so every channel records it.
 const liveModels = new Map<string, string>();
+const liveEngines = new Map<string, string>();
 
 /** Last resolved model for a session (live map first, then persisted lastModel). */
 export function getSessionModel(sessionId: string): string | undefined {
   return liveModels.get(sessionId) ?? loadIndex().find((s) => s.sessionId === sessionId)?.lastModel;
 }
 
-export function setSessionModel(sessionId: string, model: string): void {
-  if (liveModels.get(sessionId) === model) return;
+/** Record the runtime ground truth for a turn. `engine` is the engine that actually ran it — the
+ *  pair is what the header reports, so neither half may be inferred from the other. */
+export function setSessionModel(sessionId: string, model: string, engine?: string): void {
+  if (liveModels.get(sessionId) === model && (!engine || liveEngines.get(sessionId) === engine)) return;
   liveModels.set(sessionId, model);
+  if (engine) liveEngines.set(sessionId, engine);
   const sessions = loadIndex();
   const s = sessions.find((s) => s.sessionId === sessionId);
-  if (s && s.lastModel !== model) {
+  if (s && (s.lastModel !== model || (engine && s.lastEngine !== engine))) {
     s.lastModel = model;
+    if (engine) s.lastEngine = engine;
     saveIndex(sessions);
   }
 }

package/src/server/webhook-lane/feature.ts

@@ -0,0 +1,227 @@
+/**
+ * Webhook lane — the public extension point for wiring an EXTERNAL CHAT PRODUCT to this agent.
+ *
+ * The shape of the problem, name-neutrally: some other product holds the conversation UI. It wants
+ * to hand this agent one turn and render the answer as it is produced. It cannot hold an HTTP
+ * response open for the minutes an agent run takes, and it needs the answer authenticated when it
+ * comes back. So the lane is TWO independent requests:
+ *
+ *   1. INGRESS  — the product POSTs one turn to a route THIS module mounts for you.
+ *   2. CALLBACK — this agent POSTs the answer back, progressively, to a URL the product supplied
+ *                 IN that turn, each delivery HMAC-signed with a secret the product supplied too.
+ *
+ * The core registers NOTHING here, exactly as in `features.ts`. It ships the machinery — the signed
+ * transport, the flush/coalescing policy, the segment wire shape, and the turn-ingress contract —
+ * and an add-on names its own product:
+ *
+ * ```ts
+ * import { registerFeature } from 'shraga/server/features';
+ * import { createWebhookLaneFeature } from 'shraga/server/webhook-lane/feature';
+ *
+ * registerFeature(createWebhookLaneFeature({
+ *   name: 'acme',
+ *   route: '/api/acme/turn',
+ *   onTurnAccepted: (link) => rememberLink(link),   // your persistence, your policy
+ * }));
+ * ```
+ *
+ * WHAT THE ADD-ON OWNS, and why the core cannot: where links are persisted and under what filename,
+ * which links may receive PROACTIVE posts (an owner-notice policy is a product decision — see
+ * `postNotice` in `streamer.ts` for the transport), the route path, and any CLI surface. None of
+ * that is generalizable without inventing policy, so the seam hands it back.
+ *
+ * TRUST. The ingress is authenticated with an ordinary shraga API key (`POST /api/api-keys`), so
+ * reaching the route requires a credential the owner minted. The callback URL + secret arrive IN
+ * that authenticated request — per turn — which is what makes a rotated webhook secret take effect
+ * on the very next message with no configuration on this side. The URL is still validated here
+ * (https, or loopback for development) rather than trusted because the request authenticated: we
+ * hold the owner's credential and will POST to whatever it names.
+ */
+import crypto from 'node:crypto';
+import type { ServerFeature, FeatureContext } from '../features.ts';
+import { streamChat } from '../claude.ts';
+import { getMcpConfig } from '../mcp.ts';
+import {
+  appendMessage, upsertSession, setRunStatus, acquireSessionLock, releaseSessionLock,
+  type ConvBlock,
+} from '../sessions.ts';
+import { validateApiKey } from '../api-keys.ts';
+import { WebhookStreamer, type WebhookTarget } from './streamer.ts';
+
+/** One receiver connection, as learned from a turn. Handed to `onTurnAccepted` so an add-on can
+ *  persist it and later reach the same conversation proactively.
+ *
+ *  `uid` is the shraga user whose API key opened this link, and `email` is that user's address,
+ *  taken from `validateApiKey` and never from the request body. An add-on that fans PROACTIVE
+ *  notices out to "owners" must join on the email — a uid does not join to an owner list. */
+export type WebhookLaneLink = WebhookTarget & { convId: string; at: number; uid: string; email?: string };
+
+export interface WebhookLaneOptions {
+  /** Feature name (must be unique in the registry). Also the default transcript `channel` and
+   *  turn-context `source` tag, so a one-line registration is coherent. */
+  name: string;
+  /** Absolute ingress path to mount, e.g. `/api/acme/turn`. Named by the add-on: the core must not
+   *  contain a product's route. */
+  route: string;
+  /** Transcript channel tag stamped on the user message. Defaults to `name`. */
+  channel?: string;
+  /** `context.source` handed to the turn-context seam. Defaults to `name`. */
+  source?: string;
+  /**
+   * Called once per ACCEPTED turn, before the run starts, with the connection this turn negotiated.
+   * This is the add-on's chance to persist the link for its proactive lane.
+   *
+   * NOTIFICATION, NOT A GATE — and deliberately so. Whether a `connId` may be re-pointed at a
+   * different user's callback is the add-on's model, so the add-on refuses the WRITE inside this
+   * hook; the turn itself still runs and still answers on the callback the caller supplied, because
+   * that caller authenticated with their own API key and is entitled to their own answer. Throwing
+   * is contained: a broken persistence layer must not cost the user their reply.
+   */
+  onTurnAccepted?(link: WebhookLaneLink): void;
+  /** Streamer knobs, if the defaults in `streamer.ts` do not suit the receiver. */
+  streamer?: { flushInterval?: number; flushThreshold?: number; postTimeout?: number };
+}
+
+/** The ingress body, as it arrives on the wire. This IS the contract a receiver implements. */
+export interface TurnRequestBody {
+  /** Stable id for the receiver connection. Inside the signed material of every callback. */
+  connId?: string;
+  /** The receiver's conversation id. Echoed on every callback. */
+  convId?: string;
+  /** Agent session to run in. Defaults to `convId`, so a receiver may omit it entirely. */
+  sessionId?: string;
+  /** The row to patch with the answer. The receiver mints it before calling. */
+  msgId?: string;
+  prompt?: string;
+  callback?: { url?: string; secret?: string };
+  /** Receiver capability negotiation. `'segments'` means "I can store and render structured tool
+   *  segments" — see `WebhookStreamerOptions.sendSegments`. ABSENT means no, and the receiver gets
+   *  the flattened in-text tool markers instead. A list, so it can grow without a new field. */
+  accepts?: unknown;
+}
+
+/** Run one turn, streaming into the receiver's row. Errors settle the row VISIBLY — a reader must
+ *  never be left watching a "typing…" placeholder that will never resolve. Exported so an add-on
+ *  with its own ingress (a queue consumer, say) can reuse the run half without the route half. */
+export async function runWebhookTurn(args: {
+  callback: WebhookTarget; convId: string; msgId: string; sessionId: string; prompt: string;
+  uid: string; userEmail: string; sendSegments: boolean;
+  channel: string; source: string;
+  streamer?: WebhookLaneOptions['streamer'];
+}): Promise<void> {
+  const { callback, convId, msgId, sessionId, prompt, uid, userEmail, sendSegments, channel, source } = args;
+  const streamer = new WebhookStreamer({ callback, convId, msgId, sendSegments, ...(args.streamer ?? {}) });
+  const abortController = new AbortController();
+
+  // Lock origin is 'api': the union in sessions.ts is a closed set ('web'|'slack'|'scheduler'|
+  // 'api') and this is an authenticated API caller. Widening it just to label the medium would
+  // touch recovery and status code paths for no behavioural gain.
+  if (!acquireSessionLock(sessionId, 'api', abortController)) {
+    // sessionId defaults to convId, so this is genuinely "you sent two messages into the same
+    // thread while the first was still running". Say so rather than dropping it silently.
+    await streamer.fail('That conversation is already processing a message — wait for it to finish.');
+    return;
+  }
+  upsertSession(sessionId, prompt, { uid, email: userEmail });
+  appendMessage(sessionId, { id: crypto.randomUUID(), role: 'user', blocks: [{ type: 'text', text: prompt }], channel });
+  setRunStatus(sessionId, 'running', 'web');
+
+  const blocks: ConvBlock[] = [];
+  let text = '';
+  try {
+    for await (const ev of streamChat({
+      prompt, sessionId, uid, userEmail,
+      mcpServers: getMcpConfig(uid),
+      abortController,
+      context: { source, user: userEmail },
+      onPermissionRequest: async () => ({ allow: true }),
+    })) {
+      if (ev.type === 'text_delta') { text += ev.text; streamer.feed({ type: 'text_delta', text: ev.text }); }
+      else if (ev.type === 'tool_use') {
+        if (text) { blocks.push({ type: 'text', text }); text = ''; }
+        blocks.push({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
+        streamer.feed({ type: 'tool_use', tool: ev.tool, toolUseId: ev.toolUseId, input: ev.input });
+      }
+      else if (ev.type === 'tool_result') {
+        blocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
+        // The `running` → `completed`/`error` transition. Fed unconditionally; the streamer ignores
+        // it unless the receiver negotiated segments.
+        streamer.feed({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output, isError: ev.isError });
+      }
+      else if (ev.type === 'done') break;
+      else if (ev.type === 'error') {
+        if (text) { blocks.push({ type: 'text', text }); text = ''; }
+        blocks.push({ type: 'error', text: ev.message });
+        await streamer.fail(ev.message);
+        return;
+      }
+    }
+    if (text) blocks.push({ type: 'text', text });
+    await streamer.finish();
+  } catch (err) {
+    console.error(`[${channel}] turn failed:`, (err as Error).message);
+    await streamer.fail((err as Error).message || 'agent error');
+  } finally {
+    // The transcript is persisted whatever happened, so the shraga UI and the next turn's context
+    // see the same history the receiver saw.
+    if (blocks.length) appendMessage(sessionId, { id: crypto.randomUUID(), role: 'assistant', blocks });
+    if (releaseSessionLock(sessionId, abortController)) setRunStatus(sessionId, 'idle');
+  }
+}
+
+/**
+ * Build a `ServerFeature` that mounts one turn ingress. Register it with `registerFeature()`.
+ *
+ * No capability flag is declared: `flags` tells the CLIENT that a surface exists, and this lane is
+ * driven entirely by the external product calling in — nothing in the client gates on it. An add-on
+ * that DOES have a client surface can declare its own flag by spreading this feature.
+ */
+export function createWebhookLaneFeature(opts: WebhookLaneOptions): ServerFeature {
+  const channel = opts.channel ?? opts.name;
+  const source = opts.source ?? opts.name;
+  // Per-INSTANCE, not module-global: two lanes may be registered, and a shared guard would let the
+  // first one mounted silence the second.
+  let mounted = false;
+
+  return {
+    name: opts.name,
+
+    register(ctx: FeatureContext): void {
+      if (ctx.passive || mounted) return;
+      mounted = true;
+
+      ctx.app.post(opts.route, (req, res) => {
+        const bearer = /^Bearer\s+(.+)$/i.exec(req.get('authorization') ?? '')?.[1];
+        const caller = bearer ? validateApiKey(bearer) : null;
+        if (!caller) return void res.status(401).json({ error: 'unauthorized' });
+
+        const { connId, convId, sessionId, msgId, prompt, callback, accepts } = req.body as TurnRequestBody;
+        if (!connId || !convId || !msgId || !prompt) return void res.status(400).json({ error: 'connId, convId, msgId and prompt are required' });
+        if (!callback?.url || !callback?.secret) return void res.status(400).json({ error: 'callback.url and callback.secret are required' });
+        try {
+          const u = new URL(callback.url);
+          if (u.protocol !== 'https:' && u.hostname !== 'localhost' && u.hostname !== '127.0.0.1') throw new Error('https required');
+        } catch { return void res.status(400).json({ error: 'callback.url must be a valid HTTPS URL' }); }
+
+        const cb: WebhookTarget = { url: callback.url, secret: callback.secret, connId };
+        try {
+          opts.onTurnAccepted?.({ ...cb, convId, at: Date.now(), uid: caller.uid, email: caller.email });
+        } catch (err) {
+          console.warn(`[${opts.name}] onTurnAccepted threw:`, (err as Error).message);
+        }
+
+        // ACCEPT, then run. The answer arrives on the callback, so holding this response open would
+        // only give the caller's trigger a socket to time out on.
+        res.json({ status: 'accepted', sessionId: sessionId || convId });
+        void runWebhookTurn({
+          callback: cb, convId, msgId, sessionId: sessionId || convId, prompt,
+          uid: caller.uid, userEmail: caller.email,
+          sendSegments: Array.isArray(accepts) && accepts.includes('segments'),
+          channel, source, streamer: opts.streamer,
+        });
+      });
+
+      console.log(`[${opts.name}] turn ingress mounted at POST ${opts.route}`);
+    },
+  };
+}

package/src/server/{para → webhook-lane}/streamer.ts

@@ -1,25 +1,30 @@
 /**
- * ParaStreamer — progressive delivery of one agent turn into a para-li conversation row.
+ * WebhookStreamer — progressive delivery of ONE agent turn to an external receiver over signed
+ * webhook callbacks. Name-neutral half of the webhook lane; see `feature.ts` for the seam that
+ * mounts it.
  *
- * WHY NOT `SlackStreamer`. The brief said to reuse `mcp-slack-use/src/streamer.ts` rather than
- * write a second streamer. Its throttling contract IS reused — buffer, `flushInterval` (300ms),
- * `flushThreshold` (30 chars), and a serialized `flushChain` so sends never overtake each other,
- * all mirrored here deliberately and with the same defaults. Its *transport* cannot be: every
- * send in that class is a `slackApi(token, 'chat.appendStream'|'chat.startStream'|'chat.update')`
- * call against Slack's three-call streaming protocol, and it lives in a vendored package in a
- * different repo. Para's transport is one signed POST per flush carrying the accumulated text —
- * there is no start/append/stop handshake and no ts to thread. Forking that package to
- * parameterize the transport would be a larger, riskier change to Slack's live path than these
- * ~60 lines, so the shared thing is the CONTRACT, not the code, and this comment is the seam.
+ * WHY A CALLBACK AND NOT A HELD RESPONSE. The receiver POSTs one turn in and we answer on a second,
+ * independent request rather than streaming down the ingress response. An agent run is minutes
+ * long, so a held body dies to a proxy idle timeout with a half-written row; and a proactive post
+ * (a deploy notice, a scheduled digest) gets the same transport for free, with no inbound turn to
+ * ride.
  *
- * ACCUMULATE, DON'T APPEND: each flush sends the full text so far. para-li patches the message row
- * with a whole-row `set` (its existing partial-update convention), so a dropped or reordered delta
- * self-heals on the next flush instead of leaving a hole. That is worth more than the bytes.
+ * WHY NOT `SlackStreamer`. Its throttling CONTRACT is reused deliberately — buffer, `flushInterval`
+ * (300ms), `flushThreshold` (30 chars), and a serialized `flushChain` so sends never overtake each
+ * other, all mirrored here with the same defaults. Its *transport* cannot be: every send in that
+ * class is a Slack `chat.appendStream`/`chat.startStream`/`chat.update` call against Slack's
+ * three-call streaming protocol. This transport is one signed POST per flush carrying the
+ * accumulated text — no start/append/stop handshake, no ts to thread. So the shared thing is the
+ * CONTRACT, not the code, and this comment is the seam.
+ *
+ * ACCUMULATE, DON'T APPEND: each flush sends the full text so far, and the receiver is expected to
+ * patch the message row with a whole-row `set`. A dropped or reordered delta then self-heals on the
+ * next flush instead of leaving a hole — worth more than the bytes.
  */
 import { createHmac, randomUUID } from 'node:crypto';
 
-export interface ParaCallback {
-  /** Absolute webhook URL, handed to us per-turn by para-li (never configured here). */
+export interface WebhookTarget {
+  /** Absolute webhook URL, handed to us per-turn by the receiver (never configured here). */
   url: string;
   /** HMAC key for THIS connection, handed over per-turn so a rotation lands on the next message. */
   secret: string;
@@ -27,15 +32,15 @@ export interface ParaCallback {
   connId: string;
 }
 
-export interface ParaStreamerOptions {
-  callback: ParaCallback;
+export interface WebhookStreamerOptions {
+  callback: WebhookTarget;
   convId: string;
   /** The row to patch. Omit for a PROACTIVE post (no preceding user turn) — see `post()`. */
   msgId?: string;
   flushInterval?: number;
   flushThreshold?: number;
   /** Show a transient inline marker per tool call, as the Slack streamer does. Default on.
-   *  Ignored when `sendSegments` is on — see `ParaStreamerOptions.sendSegments`. */
+   *  Ignored when `sendSegments` is on — see `WebhookStreamerOptions.sendSegments`. */
   toolMarkers?: boolean;
   /**
    * Emit STRUCTURED segments (`text` + `tool`) alongside the accumulated text.
@@ -54,11 +59,12 @@ export interface ParaStreamerOptions {
   postTimeout?: number;
 }
 
-/** Signature contract, mirrored byte-for-byte in para-li's `lib/agent-conn.ts#signPayload`.
- *  The two repos are separately published, so this is duplicated on purpose; if you change one,
- *  change both — a drift here presents as a silent 401 on every delta.
+/** Signature over one delivery. THIS IS A CROSS-PROCESS CONTRACT: the receiver reimplements it in
+ *  its own codebase, so changing a single byte of the material silently 401s every delta. Anything
+ *  built on this seam should freeze a known-answer vector on BOTH sides (see the frozen digest in
+ *  `__tests__/webhook-streamer.test.ts`).
  *
- *  The DELIVERY id is in the material because para-li's replay guard dedupes on that header alone;
+ *  The DELIVERY id is in the material because a receiver's replay guard dedupes on that header alone;
  *  unsigned, it would be the one field an attacker could vary freely to replay a captured delivery
  *  inside the signature window.
  *
@@ -70,17 +76,15 @@ export interface ParaStreamerOptions {
  *  leaves `deliveryId` as the only free field, and it sits between two fixed-shape neighbours, so
  *  no (deliveryId, ts) pair can be re-cut into a different one. If either check is ever relaxed,
  *  length-prefix the material instead of relying on this. */
-export function signPara(secret: string, connId: string, deliveryId: string, ts: number, rawBody: string): string {
+export function signDelivery(secret: string, connId: string, deliveryId: string, ts: number, rawBody: string): string {
   return 'v1=' + createHmac('sha256', secret).update(`${connId}.${deliveryId}.${ts}.${rawBody}`).digest('hex');
 }
 
 // ── Structured segments ──────────────────────────────────────────────────────
 //
-// SHAPE-COMPATIBLE WITH para-li's OWN `MessageSegment`/`ToolCallInfo` (`lib/para-relay.ts`), which
-// its `ConversationChannel` already renders as collapsible tool pills. This is a deliberate reuse:
-// the external-agent lane emits the SAME shape the Para's own turns do, so no second renderer, no
-// second row field, and no second thing to keep in sync. Duplicated here rather than imported for
-// the same reason `signPara` is — the two repos publish separately.
+// The structured mirror of a turn: what the receiver renders as collapsible tool pills alongside
+// the text. It is a WIRE shape, not an internal one — a receiver reimplements it, so treat a field
+// rename here as a breaking change and version it on both sides.
 
 export interface ToolCallInfo {
   id: string;
@@ -100,13 +104,13 @@ export type MessageSegment =
  * APPEND at the top). Unclamped, one such call would be re-uploaded on every subsequent delta for
  * the rest of the turn and then parked in a database row forever.
  *
- * The caps are chosen against what the pill actually shows: para-li's `ToolPill` renders args as
- * one JSON line and slices the result at 500 chars, so anything past a few KB is invisible detail
- * that still costs bandwidth and storage. Truncation is MARKED with the true length — a silently
+ * The caps are chosen against what a tool pill actually shows: args as one JSON line and a result
+ * sliced at a few hundred chars, so anything past a few KB is invisible detail that still costs
+ * bandwidth and storage. Truncation is MARKED with the true length — a silently
  * shortened `Bash` output is a lie the reader cannot detect.
  *
- * These are the SENDER's caps. para-li re-clamps on ingest (`parseSegments`) because a cap that
- * only exists on the sender is not a cap.
+ * These are the SENDER's caps. A receiver must re-clamp on ingest too, because a cap that only
+ * exists on the sender is not a cap.
  */
 export const MAX_TOOL_ARGS_CHARS = 2_000;
 export const MAX_TOOL_RESULT_CHARS = 4_000;
@@ -140,8 +144,7 @@ export function clampArgs(input: unknown): Record<string, unknown> | undefined {
 }
 
 /**
- * Wall clock on ONE delivery. Mirrors the 20s AbortController on para-li's own `dispatchAgentTurn`,
- * which is the other half of this lane.
+ * Wall clock on ONE delivery.
  *
  * WHY A TIMEOUT IS LOAD-BEARING HERE AND NOT A NICETY: flushes are serialized through `flushChain`,
  * and `finish()` awaits that chain. `fetch` has no default timeout, so ONE POST that connects and
@@ -155,15 +158,15 @@ export const POST_TIMEOUT_MS = 20_000;
 
 /** One signed POST. Returns false on any non-2xx, timeout, or network error, having logged it — the
  *  caller keeps streaming rather than aborting the agent's turn over a transport hiccup. */
-export async function postPara(cb: ParaCallback, payload: object, timeoutMs: number = POST_TIMEOUT_MS): Promise<boolean> {
+export async function postDelivery(cb: WebhookTarget, payload: object, timeoutMs: number = POST_TIMEOUT_MS): Promise<boolean> {
   const raw = JSON.stringify(payload);
   const ts = Date.now();
-  // Per-DELIVERY id, not per-turn: para-li's replay guard dedupes on this, so a shared id across
+  // Per-DELIVERY id, not per-turn: a receiver's replay guard dedupes on this, so a shared id across
   // the deltas of one turn would drop every delta after the first. Minted here so the exact same
   // value goes into the header AND the signature — they must not be able to diverge.
   const delivery = randomUUID();
-  // Abort on a timer rather than `AbortSignal.timeout`: the same shape para-li uses, and the timer
-  // is cleared in `finally` so a fast POST leaves nothing pending on the event loop.
+  // Abort on a timer rather than `AbortSignal.timeout` so the timer can be cleared in `finally` —
+  // a fast POST then leaves nothing pending on the event loop.
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), timeoutMs);
   try {
@@ -174,29 +177,34 @@ export async function postPara(cb: ParaCallback, payload: object, timeoutMs: num
         'Content-Type': 'application/json',
         'x-agent-conn': cb.connId,
         'x-agent-timestamp': String(ts),
-        'x-agent-signature': signPara(cb.secret, cb.connId, delivery, ts, raw),
+        'x-agent-signature': signDelivery(cb.secret, cb.connId, delivery, ts, raw),
         'x-agent-delivery': delivery,
       },
       body: raw,
     });
     if (!res.ok) {
-      console.warn(`[para-streamer] ${(payload as any).type} rejected: ${res.status} ${await res.text().catch(() => '')}`.slice(0, 300));
+      console.warn(`[webhook-lane] ${(payload as any).type} rejected: ${res.status} ${await res.text().catch(() => '')}`.slice(0, 300));
       return false;
     }
     return true;
   } catch (err) {
     const e = err as Error;
-    console.warn('[para-streamer] delivery failed:', e.name === 'AbortError' ? `no response within ${timeoutMs}ms` : e.message);
+    console.warn('[webhook-lane] delivery failed:', e.name === 'AbortError' ? `no response within ${timeoutMs}ms` : e.message);
     return false;
   } finally {
     clearTimeout(timer);
   }
 }
 
-export class ParaStreamer {
+export class WebhookStreamer {
   private buffer = '';
   private fullText = '';
   private timer: ReturnType<typeof setTimeout> | null = null;
+  /** When a TOOL event last forced a delta out, so a burst of them is rate-limited by the same
+   *  `flushInterval` text uses. Deliberately NOT bumped by text flushes: a tool call arriving right
+   *  after the model spoke is exactly the case that must show its pill at once. `0` = never, so the
+   *  first tool of a turn is always immediate. */
+  private lastToolFlushAt = 0;
   private flushChain: Promise<void> = Promise.resolve();
   private aborted = false;
   private afterTool = false;
@@ -213,7 +221,7 @@ export class ParaStreamer {
   private readonly sendSegments: boolean;
   private readonly postTimeout: number;
 
-  constructor(private readonly opts: ParaStreamerOptions) {
+  constructor(private readonly opts: WebhookStreamerOptions) {
     this.flushInterval = opts.flushInterval ?? 300;
     this.flushThreshold = opts.flushThreshold ?? 30;
     this.sendSegments = opts.sendSegments ?? false;
@@ -245,10 +253,10 @@ export class ParaStreamer {
           this.segments.push({ type: 'tool', tool: info });
         }
         this.toolCount++;
-        this.enqueueFlush();
+        this.flushToolChange();
       } else if (this.toolMarkers) {
         // In-band, transient: `finish()` sends the clean final text, which replaces the row wholesale
-        // (para-li writes the whole row), so the marker disappears on its own.
+        // (the receiver writes the whole row), so the marker disappears on its own.
         this.afterTool = true;
         this.fullText += `\n\n_🔧 ${ev.tool.slice(0, 200)}_\n\n`;
         this.enqueueFlush();
@@ -260,13 +268,12 @@ export class ParaStreamer {
       if (!info) return;
       info.status = ev.isError ? 'error' : 'completed';
       if (ev.output) info.result = clampText(ev.output, MAX_TOOL_RESULT_CHARS);
-      this.enqueueFlush();
+      this.flushToolChange();
     }
   }
 
-  /** Grow the trailing text segment, or start one. Mirrors `buildSegmentHost` in para-li's own
-   *  `lib/para-agent.ts` — consecutive text stays ONE segment, so the pills sit between paragraphs
-   *  instead of shredding the answer into a segment per delta. */
+  /** Grow the trailing text segment, or start one: consecutive text stays ONE segment, so the pills
+   *  sit between paragraphs instead of shredding the answer into a segment per delta. */
   private appendSegmentText(text: string): void {
     if (!this.sendSegments) return;
     const last = this.segments[this.segments.length - 1];
@@ -291,7 +298,7 @@ export class ParaStreamer {
     await this.flushChain;
     if (this.aborted || !this.opts.msgId) return this.fullText;
     const text = this.fullText.trim() || '(no output)';
-    await postPara(this.opts.callback, {
+    await postDelivery(this.opts.callback, {
       type: 'final', convId: this.opts.convId, msgId: this.opts.msgId, text,
       ...(this.sendSegments ? { segments: this.segmentSnapshot() } : {}),
     }, this.postTimeout);
@@ -304,15 +311,38 @@ export class ParaStreamer {
     this.clearTimer();
     await this.flushChain;
     if (!this.opts.msgId) return;
-    await postPara(this.opts.callback, { type: 'error', convId: this.opts.convId, msgId: this.opts.msgId, message }, this.postTimeout);
+    await postDelivery(this.opts.callback, { type: 'error', convId: this.opts.convId, msgId: this.opts.msgId, message }, this.postTimeout);
+  }
+
+  /**
+   * Tool events, throttled — but never at the cost of "a tool that is still running reads as
+   * running", which is the whole point of the pill.
+   *
+   * Each flush re-sends the WHOLE accumulated snapshot (up to ~600 KB at the ingest caps) and
+   * costs a whole-row `set` plus a live re-render on the receiver, so a POST per `tool_use` AND
+   * per `tool_result` made a 100-tool turn ~200 POSTs and tens of MB — quadratic in the tool
+   * count. Text has always been throttled for exactly this reason; tool events simply were not.
+   *
+   * So they take the same `flushInterval` budget: go out NOW if nothing has been sent within it
+   * (a turn that opens with a tool still shows its pill immediately), otherwise arm the timer. The
+   * timer is the guarantee — every state change is delivered within `flushInterval`, so no pill is
+   * ever stranded and the receiver's stall watchdog keeps getting fed.
+   */
+  private flushToolChange(): void {
+    if (Date.now() - this.lastToolFlushAt >= this.flushInterval) {
+      this.lastToolFlushAt = Date.now();
+      this.enqueueFlush();
+    } else {
+      this.scheduleTimer();
+    }
   }
 
   private enqueueFlush(): void {
     this.clearTimer();
     // `segments` matters here too: a turn that opens with a tool call has produced NO text yet, and
     // the old guard would have swallowed that flush — so the first pill would not appear until the
-    // model started talking, and, worse, the delta that bumps para-li's stall watchdog
-    // (`lastActivityAt`) would never be sent for a long tool-only stretch.
+    // model started talking, and, worse, the delta that feeds a receiver's stall watchdog would
+    // never be sent for a long tool-only stretch.
     if (!this.fullText && !this.segments.length) return;
     this.buffer = '';
     const snapshot = this.fullText;
@@ -320,8 +350,8 @@ export class ParaStreamer {
     // Serialized: a later, longer snapshot must never be overtaken by an earlier one, or the row
     // visibly rewinds mid-stream.
     this.flushChain = this.flushChain
-      .then(async () => { await postPara(this.opts.callback, { type: 'delta', convId: this.opts.convId, msgId: this.opts.msgId, text: snapshot, ...(segs ? { segments: segs } : {}) }, this.postTimeout); })
-      .catch((err) => console.warn('[para-streamer] flush error:', (err as Error).message));
+      .then(async () => { await postDelivery(this.opts.callback, { type: 'delta', convId: this.opts.convId, msgId: this.opts.msgId, text: snapshot, ...(segs ? { segments: segs } : {}) }, this.postTimeout); })
+      .catch((err) => console.warn('[webhook-lane] flush error:', (err as Error).message));
   }
 
   private scheduleTimer(): void {
@@ -335,7 +365,7 @@ export class ParaStreamer {
 }
 
 /** PROACTIVE post — a scheduled run, a deploy notice, a downtime report. No preceding user turn,
- *  so there is no row to patch: para-li mints one. Same signed transport, same fence. */
-export function postProactive(cb: ParaCallback, convId: string, text: string): Promise<boolean> {
-  return postPara(cb, { type: 'post', convId, text });
+ *  so there is no row to patch: the receiver mints one. Same signed transport, same fence. */
+export function postNotice(cb: WebhookTarget, convId: string, text: string): Promise<boolean> {
+  return postDelivery(cb, { type: 'post', convId, text });
 }