shraga 0.1.67 → 0.1.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",

package/src/server/boot.ts

@@ -25,6 +25,7 @@ import { streamChat, consumeStream, getAgentConfig, saveAgentConfig, getClaudeAu
 import { mountFeatures, registerFeature, resumeFeatureSession, collectFeatureFlags, collectSidecarRoutes } from './features.ts';
 import { registerSpaCatchAll } from './spa-catchall.ts';
 import { slackFeature } from './slack/feature.ts';
+import { paraFeature } from './para/feature.ts';
 import { dataPath } from './paths.ts';
 import { getAllSessions, getSession, getSessionHistory, upsertSession, appendMessage, saveConversation, loadConversation, setSessionDirectives, getAutoApprove, setAutoApprove, getSessionsByScheduleId, getSessionsVisibleTo, isSessionVisibleTo, setRunStatus, incrementRetryCount, getRunningSessions, getActiveLockCount, updateScheduledSessionStatus, setShuttingDown, backfillSessionVisibility, writePartial, readPartial, clearPartial, registerLivePartial, unregisterLivePartial, readLivePartial, acquireSessionLock, releaseSessionLock, replaceSessionLock, isSessionLocked, getSessionAbortController, forkSession, generateSessionTitle, type ConvBlock, type ConvMessage, type SessionMeta } from './sessions.ts';
 import { setBroadcaster } from './session-bus.ts';
@@ -1203,6 +1204,9 @@ if (process.env.SHRAGA_OVERLAY) {
 // so their routes mount ahead of the SPA fallback, identical to the overlay path.
 for (const f of __reg.features ?? []) registerFeature(f);
 registerFeature(slackFeature);
+// para-li external-agent lane — a second medium alongside Slack; both subscribe the owner-notice
+// bus independently, so neither affects the other.
+registerFeature(paraFeature);
 mountFeatures({ app, requireAuth, broadcast, passive: PASSIVE });
 // Fold in feature-contributed sidecar WS proxy routes (the core names none; each add-on adds its own).
 Object.assign(WS_PROXY_ROUTES, collectSidecarRoutes());

package/src/server/notify-owners.ts

@@ -10,12 +10,29 @@ import { emitEvent } from './events/bus.ts';
 
 export type Owner = { name?: string; slackId: string };
 
+/** The OWNERS env list, lowercased. THE definition of "an owner of this deployment" — every
+ *  medium joins on it, each through whatever identity it happens to hold. */
+export function ownerEmails(): string[] {
+  return (process.env.OWNERS ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+}
+
+/** Is this email address an owner of this deployment?
+ *
+ *  Exported because a medium that is not Slack cannot use `resolveOwners`: that returns Slack ids
+ *  (OWNERS ∩ contacts WITH a Slack id), which is a Slack-shaped answer. The para lane holds a
+ *  shraga uid + the email of the API key that opened the link, so it joins on the email instead.
+ *  An empty/unknown address is NOT an owner — the fail-closed direction, since the alternative is
+ *  fanning a deploy report out to whoever happened to link a para. */
+export function isOwnerEmail(email: string | undefined | null): boolean {
+  const e = String(email ?? '').trim().toLowerCase();
+  return !!e && ownerEmails().includes(e);
+}
+
 /** Owners of THIS deployment (OWNERS env ∩ contacts that have a Slack id). */
 export async function resolveOwners(): Promise<Owner[]> {
   const { getAll } = await import('./contacts.ts');
-  const ownerEmails = (process.env.OWNERS ?? '').split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
   return getAll()
-    .filter(c => c.slackIds.length > 0 && c.emails.some(e => ownerEmails.includes(e.toLowerCase())))
+    .filter(c => c.slackIds.length > 0 && c.emails.some(e => isOwnerEmail(e)))
     .map(c => ({ name: c.name, slackId: c.slackIds[0] }));
 }
 
@@ -26,16 +43,22 @@ export function senderStamp(): string {
 }
 
 /**
- * DM the owners. `source` is the event-bus source (used for logging/filtering only) — delivery is
- * keyed on the notice `kind`, so a new subsystem needs no change on the Slack side.
- * Returns false when there was nobody to tell.
+ * Publish an owner notice on the bus. `source` is the event-bus source (used for logging/filtering
+ * only) — delivery is keyed on the notice `kind`, so a new subsystem needs no change on the Slack
+ * side.
+ *
+ * Returns NOTHING, on purpose. It used to return "was there anyone to tell", which was a truthful
+ * answer only while Slack was the sole medium: `resolveOwners` filters on a SLACK id, so once para
+ * subscribes the same bus an empty owner list means "no Slack owner", not "nobody was notified".
+ * Rather than keep a boolean whose meaning depends on which features happen to be registered — no
+ * caller reads it (`data-sync.ts`, `self-upgrade/index.ts`) — the notice is emitted unconditionally
+ * and each subscriber decides for itself. The Slack subscriber already no-ops on an empty
+ * `owners`, so Slack behaviour is unchanged.
  */
-export async function notifyOwners(source: string, text: string): Promise<boolean> {
+export async function notifyOwners(source: string, text: string): Promise<void> {
   const owners = await resolveOwners();
+  emitEvent(source as any, { kind: 'deploy', owners, text: `${text}\n\n_from ${senderStamp()}_` });
   if (!owners.length) {
-    console.warn(`[${source}] No owners (OWNERS env) with Slack IDs found, skipping notification`);
-    return false;
+    console.warn(`[${source}] No owners (OWNERS env) with Slack IDs found — notice emitted for non-Slack subscribers only`);
   }
-  emitEvent(source as any, { kind: 'deploy', owners, text: `${text}\n\n_from ${senderStamp()}_` });
-  return true;
 }

package/src/server/para/feature.ts

@@ -0,0 +1,218 @@
+/**
+ * paraFeature — the sender half of the para-li external-agent lane.
+ *
+ * Mirrors `slackFeature` exactly in shape: one `ServerFeature` that (a) mounts an ingress route and
+ * (b) subscribes the owner-notice event bus so deploy / self-upgrade / downtime notices reach the
+ * medium. Slack is untouched and the two coexist — both subscribe the same bus, neither knows about
+ * the other, and a notice is delivered to each independently.
+ *
+ * TRANSPORT. para-li POSTs one turn here and we stream the answer BACK to it over signed webhook
+ * calls (see `streamer.ts`), rather than holding this response open. para-li's caller is a Bodify
+ * trigger whose lifetime is the turn, so a multi-minute agent run held on one response body dies to
+ * a proxy idle timeout with a half-written row. Two independent requests also give the proactive
+ * lane the same transport for free.
+ *
+ * TRUST. The turn request is authenticated with an ordinary shraga API key (`POST /api/api-keys`),
+ * so reaching this route requires a credential the owner minted. The callback URL + secret arrive
+ * IN that authenticated request — para-li tells us where to answer and with what, per turn, which
+ * is what makes a rotated webhook secret take effect on the very next message with no config here.
+ */
+import type { ServerFeature, FeatureContext } from '../features.ts';
+import crypto from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { subscribeEvents } from '../events/bus.ts';
+import { streamChat } from '../claude.ts';
+import { getMcpConfig } from '../mcp.ts';
+import { dataPath } from '../paths.ts';
+import {
+  appendMessage, upsertSession, setRunStatus, acquireSessionLock, releaseSessionLock,
+  type ConvBlock,
+} from '../sessions.ts';
+import { validateApiKey } from '../api-keys.ts';
+import { isOwnerEmail } from '../notify-owners.ts';
+import { ParaStreamer, postProactive, type ParaCallback } from './streamer.ts';
+
+interface DeployNotice { kind: 'deploy'; owners: { name?: string; slackId: string }[]; text: string }
+
+/** Last known para conversation per connection — the proactive lane's destination.
+ *
+ *  Learned from the first turn rather than configured: para-li already tells us the conv and the
+ *  callback on every turn, so a second source of truth would only be a thing to drift. Persisted
+ *  because a deploy notice fires right after a RESTART, which is exactly when an in-memory map is
+ *  empty — the one moment the feature has to work. Lives beside `api-keys.json` in the data dir and
+ *  holds the webhook secret, so it inherits that file's protection, no more and no less. */
+const LINKS_PATH = dataPath('para-links.json');
+/** `uid` is the shraga user whose API key opened this link. It is the OWNER of the entry — see
+ *  `rememberLink`.
+ *
+ *  `email` is that user's address, recorded so the PROACTIVE lane can answer "is this link's user
+ *  an owner of this deployment?" — `OWNERS` is an email list, and a uid does not join to it. It is
+ *  taken from `validateApiKey`, never from the request body. A link written before this field
+ *  existed has no email and is therefore not an owner: it receives no notices until its next turn
+ *  refreshes the entry. */
+type Link = ParaCallback & { convId: string; at: number; uid: string; email?: string };
+
+function loadLinks(): Record<string, Link> {
+  if (!existsSync(LINKS_PATH)) return {};
+  try { return JSON.parse(readFileSync(LINKS_PATH, 'utf-8')); } catch (err) {
+    console.warn('[para] links file unreadable, starting empty:', (err as Error).message);
+    return {};
+  }
+}
+/** Record (or refresh) a connection's callback.
+ *
+ *  ONE USER OWNS A connId. `connId` is chosen by the caller, so without this an API key for user A
+ *  could claim a connId already linked by user B and re-point every future PROACTIVE notice
+ *  (deploy reports, self-upgrade outcomes) at A's URL + secret. An API key is already full agent
+ *  access to its own user, so this is not a privilege boundary being invented — it is the one
+ *  cross-user step that access does not otherwise imply, so it is refused rather than logged. */
+function rememberLink(link: Link): void {
+  try {
+    const all = loadLinks();
+    const prev = all[link.connId];
+    if (prev?.uid && prev.uid !== link.uid) {
+      console.warn(`[para] refusing to re-link ${link.connId}: owned by another user`);
+      return;
+    }
+    all[link.connId] = link;
+    mkdirSync(dataPath(''), { recursive: true });
+    writeFileSync(LINKS_PATH, JSON.stringify(all, null, 2));
+  } catch (err) {
+    console.warn('[para] could not persist link:', (err as Error).message);
+  }
+}
+
+/** Run one turn, streaming into the para row. Errors settle the row visibly — the owner must never
+ *  be left watching a "typing…" placeholder that will never resolve. */
+async function runParaTurn(args: {
+  callback: ParaCallback; convId: string; msgId: string; sessionId: string; prompt: string;
+  uid: string; userEmail: string;
+}): Promise<void> {
+  const { callback, convId, msgId, sessionId, prompt, uid, userEmail } = args;
+  const streamer = new ParaStreamer({ callback, convId, msgId });
+  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 === 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: 'para' });
+  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: 'para', 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 });
+      }
+      else if (ev.type === 'tool_result') blocks.push({ type: 'tool_result', toolUseId: ev.toolUseId, output: ev.output });
+      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('[para] 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 para saw.
+    if (blocks.length) appendMessage(sessionId, { id: crypto.randomUUID(), role: 'assistant', blocks });
+    if (releaseSessionLock(sessionId, abortController)) setRunStatus(sessionId, 'idle');
+  }
+}
+
+let mounted = false;
+let busSubscribed = false;
+
+export const paraFeature: ServerFeature = {
+  name: 'para',
+
+  // No capability flag. `flags` is the seam's way to tell the CLIENT a surface exists, and nothing
+  // in the client gates on para — the lane is driven entirely by para.li calling in. Declaring one
+  // would be dead public surface on /api/features (slackFeature declares none for the same reason).
+
+  register(ctx: FeatureContext): void {
+    // Owner notices → the linked para conversations OF THIS DEPLOYMENT'S OWNERS. Keyed on the
+    // notice KIND, not the source, for the reason spelled out in slackFeature: self-upgrade emits
+    // under its own source and a source-gated subscriber silently dropped every one of them.
+    //
+    // WHY NOT `payload.owners`. That field is `{name?, slackId}[]` — the SLACK join, computed by
+    // `resolveOwners` as OWNERS ∩ contacts-that-have-a-Slack-id. A para link carries no Slack id,
+    // so the field is unmatchable here. Unfiltered, this loop posted every deploy / self-upgrade /
+    // data-sync report to EVERY entry in para-links.json — and any shraga user with an API key
+    // gets an entry on their first turn (`rememberLink`). The `uid` guard does not help: it stops
+    // STEALING another user's connId, not adding your own.
+    // The join that works is the one OWNERS is actually expressed in — the email of the API key
+    // that opened the link — checked with the same `isOwnerEmail` that backs `resolveOwners`.
+    if (!ctx.passive && !busSubscribed) {
+      busSubscribed = true;
+      subscribeEvents((evt) => {
+        const payload = evt.payload as DeployNotice;
+        if (payload?.kind !== 'deploy' || !payload.text) return;
+        for (const link of Object.values(loadLinks())) {
+          if (!isOwnerEmail(link.email)) continue;
+          postProactive({ url: link.url, secret: link.secret, connId: link.connId }, link.convId, payload.text)
+            .then((ok) => console.log(`[para] owner notice ${ok ? 'delivered' : 'FAILED'} → ${link.convId}`))
+            .catch((err) => console.warn('[para] owner notice failed:', (err as Error).message));
+        }
+      });
+    }
+
+    if (ctx.passive || mounted) return;
+    mounted = true;
+
+    ctx.app.post('/api/para/turn', (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 } = req.body as {
+        connId?: string; convId?: string; sessionId?: string; msgId?: string; prompt?: string;
+        callback?: { url?: string; secret?: string };
+      };
+      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);
+        // We hold the owner's credential and will POST to whatever this says, so it is validated
+        // here too rather than trusted because the request authenticated.
+        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: ParaCallback = { url: callback.url, secret: callback.secret, connId };
+      rememberLink({ ...cb, convId, at: Date.now(), uid: caller.uid, email: caller.email });
+
+      // ACCEPT, then run. The answer arrives on the callback, so holding this response open would
+      // only give para-li's trigger a socket to time out on.
+      res.json({ status: 'accepted', sessionId: sessionId || convId });
+      void runParaTurn({
+        callback: cb, convId, msgId, sessionId: sessionId || convId, prompt,
+        uid: caller.uid, userEmail: caller.email,
+      });
+    });
+
+    console.log('[para] turn ingress mounted at POST /api/para/turn');
+  },
+};

package/src/server/para/streamer.ts

@@ -0,0 +1,201 @@
+/**
+ * ParaStreamer — progressive delivery of one agent turn into a para-li conversation row.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { createHmac, randomUUID } from 'node:crypto';
+
+export interface ParaCallback {
+  /** Absolute webhook URL, handed to us per-turn by para-li (never configured here). */
+  url: string;
+  /** HMAC key for THIS connection, handed over per-turn so a rotation lands on the next message. */
+  secret: string;
+  /** Connection id — inside the signed material, so a delivery is bound to its connection. */
+  connId: string;
+}
+
+export interface ParaStreamerOptions {
+  callback: ParaCallback;
+  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. */
+  toolMarkers?: boolean;
+  /** Per-POST wall clock. See `POST_TIMEOUT_MS`. Overridable for tests. */
+  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.
+ *
+ *  The DELIVERY id is in the material because para-li'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.
+ *
+ *  UNESCAPED `.` — why the field boundaries cannot be shifted. There are no length prefixes, so in
+ *  general `a.b.c` is ambiguous. It holds here because the receiver PINS every field but the last
+ *  before it verifies: `connId` must be exactly 24 lowercase hex chars (`isConnId`, checked before
+ *  the signature) and `ts` is `Number(header)` re-stringified, so it is a canonical, dot-free digit
+ *  run that must also land within 300s of now. `rawBody` is trailing and can absorb nothing. That
+ *  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 {
+  return 'v1=' + createHmac('sha256', secret).update(`${connId}.${deliveryId}.${ts}.${rawBody}`).digest('hex');
+}
+
+/**
+ * Wall clock on ONE delivery. Mirrors the 20s AbortController on para-li's own `dispatchAgentTurn`,
+ * which is the other half of this lane.
+ *
+ * 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
+ * then never answers (a stalled proxy, a receiver wedged mid-handler, a half-open socket a dead NAT
+ * entry never RSTs) blocks every later delta AND the `final` — for the process's lifetime. The
+ * visible symptom is not an error: the reply freezes mid-sentence, no `final` ever lands, and
+ * nothing is logged, because the failure never returns. A bounded POST turns that permanent wedge
+ * into one logged, skipped delta and a `final` that still arrives.
+ */
+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> {
+  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
+  // 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.
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  try {
+    const res = await fetch(cb.url, {
+      signal: ac.signal,
+      method: 'POST',
+      headers: {
+        '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-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));
+      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);
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export class ParaStreamer {
+  private buffer = '';
+  private fullText = '';
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private flushChain: Promise<void> = Promise.resolve();
+  private aborted = false;
+  private afterTool = false;
+
+  private readonly flushInterval: number;
+  private readonly flushThreshold: number;
+  private readonly toolMarkers: boolean;
+  private readonly postTimeout: number;
+
+  constructor(private readonly opts: ParaStreamerOptions) {
+    this.flushInterval = opts.flushInterval ?? 300;
+    this.flushThreshold = opts.flushThreshold ?? 30;
+    this.toolMarkers = opts.toolMarkers ?? true;
+    this.postTimeout = opts.postTimeout ?? POST_TIMEOUT_MS;
+  }
+
+  feed(ev: { type: string; text?: string; tool?: string }): void {
+    if (this.aborted || !this.opts.msgId) return;
+
+    if (ev.type === 'text_delta' && ev.text) {
+      if (this.afterTool) { this.fullText += '\n'; this.afterTool = false; }
+      this.buffer += ev.text;
+      this.fullText += ev.text;
+      if (this.buffer.length >= this.flushThreshold) this.enqueueFlush();
+      else this.scheduleTimer();
+    } else if (ev.type === 'tool_use' && ev.tool && 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.
+      this.afterTool = true;
+      this.fullText += `\n\n_🔧 ${ev.tool.slice(0, 200)}_\n\n`;
+      this.enqueueFlush();
+    }
+  }
+
+  /** Settle the row with the final text. Returns the text actually sent. */
+  async finish(): Promise<string> {
+    this.clearTimer();
+    this.buffer = '';
+    await this.flushChain;
+    if (this.aborted || !this.opts.msgId) return this.fullText;
+    const text = this.fullText.trim() || '(no output)';
+    await postPara(this.opts.callback, { type: 'final', convId: this.opts.convId, msgId: this.opts.msgId, text }, this.postTimeout);
+    return text;
+  }
+
+  /** Settle the row as a visible failure. The owner sees WHY, in the thread, not only in a log. */
+  async fail(message: string): Promise<void> {
+    this.aborted = true;
+    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);
+  }
+
+  private enqueueFlush(): void {
+    this.clearTimer();
+    if (!this.fullText) return;
+    this.buffer = '';
+    const snapshot = this.fullText;
+    // 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 }, this.postTimeout); })
+      .catch((err) => console.warn('[para-streamer] flush error:', (err as Error).message));
+  }
+
+  private scheduleTimer(): void {
+    this.clearTimer();
+    this.timer = setTimeout(() => this.enqueueFlush(), this.flushInterval);
+  }
+
+  private clearTimer(): void {
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+  }
+}
+
+/** 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 });
+}