shraga 0.1.86 → 0.1.88

package/README.md

@@ -85,7 +85,9 @@ The core is deliberately small and grows through documented seams (see
 | **Server features** (`src/server/features.ts`) | Mount new server-side surfaces via `registerFeature`. |
 | **Client slots** (`src/client/lib/slots.tsx`) | Inject UI into typed render slots without touching core. |
 | **Route extensions** (`data/extensions/*.ext.ts`) | Drop-in public routes (webhooks, OAuth callbacks) per deployment. |
+| **Webhook lane** (`src/server/webhook-lane/`) | Give an external chat product a turn ingress that streams the answer back to a signed callback. |
 | **`SHRAGA_OVERLAY`** | Load a whole external add-on module at startup (the optional add-ons above). |
+| **`SHRAGA_CLI_EXT`** | Hand any subcommand the core does not own to an external CLI module. |
 
 ## Use as a library
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "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/cli.ts

@@ -29,19 +29,23 @@ Subcommands:
   ingress                 Run the host-header TCP router (INGRESS_PORT, default 3100)
                           for previews + blue-green flips. Own process, survives restarts.
   user add <email> <pw>   Seed a local username/password user
-  para post [text]        Push a message into a linked para.li conversation.
-                          Text from [text], --file <path>, or stdin (preferred for
-                          multi-line reports). --conn <id> picks a link when several exist.
+  <add-on>                Any other subcommand is handed to SHRAGA_CLI_EXT, if set.
 
 Environment:
   CLOUDFLARE_TUNNEL_TOKEN   If set, starts a Cloudflare Tunnel alongside the server.
                             Get the token from Cloudflare Zero Trust > Tunnels > Configure.
   ANTHROPIC_API_KEY         Claude API key (or use \`claude auth login\` for subscription auth)
   VITE_FIREBASE_CONFIG_PROD Firebase config JSON for auth (prod project)
+  SHRAGA_CLI_EXT            Absolute path to an add-on CLI module. Any subcommand this CLI
+                            does not own is handed to it before the server boots. See the
+                            CLI EXTENSION SEAM comment in src/cli.ts.
 `.trim());
   process.exit(0);
 }
 
+/** Subcommands the core owns. Everything else is offered to SHRAGA_CLI_EXT (see below). */
+const CORE_SUBCOMMANDS = new Set(['user', 'ingress']);
+
 const port = flag('port', 'p');
 const dataDir = flag('data-dir', 'd');
 
@@ -62,58 +66,31 @@ if (args[0] === 'user' && args[1] === 'add') {
   process.exit(0);
 }
 
-// `shraga para post [text]` — the PROACTIVE half of the para.li agent lane.
+// ── CLI EXTENSION SEAM ───────────────────────────────────────────────────────
 //
-// The reactive half (para asks, shraga answers) is driven by para.li calling `/api/para/turn`, and
-// the only other outbound path is the deploy-notice bus subscriber in `para/feature.ts` — which is
-// gated on `kind === 'deploy'`. So a SCHEDULED run (a daily digest) had no way to reach the lane at
-// all: it composes text on its own clock with no inbound turn to answer and no deploy event to ride.
-// This is that door, and it is a CLI rather than a route because the caller is the agent itself,
-// running Bash on this very box: a local process reading the same `para-links.json` the feature
-// writes needs no listener, no API key, and no second copy of the callback secret.
+// The twin of the `registerFeature` / SHRAGA_OVERLAY seam, for the command line. The core owns a
+// short, fixed list of subcommands; ANY other one is handed to the module named by SHRAGA_CLI_EXT,
+// so a downstream distribution can ship its own commands without the core naming them.
 //
-// Text comes from stdin by default. A digest is multi-line markdown with backticks and emoji, and
-// making a model shell-quote that into argv is a defect generator; `... | shraga para post` is not.
-if (args[0] === 'para' && args[1] === 'post') {
-  const { loadLinks } = await import('./server/para/feature.ts');
-  const { postProactive } = await import('./server/para/streamer.ts');
-
-  const links = loadLinks();
-  const wanted = flag('conn');
-  const ids = Object.keys(links);
-  // Refuse to guess. Picking "the first" would silently deliver a private report to whichever
-  // connection happened to sort first the day a second one is added.
-  const connId = wanted ?? (ids.length === 1 ? ids[0] : undefined);
-  if (!connId || !links[connId]) {
-    console.error(ids.length
-      ? `usage: shraga para post --conn <connId>   (linked: ${ids.join(', ')})`
-      : 'no para link yet — send one message from para.li to this agent first, then retry.');
-    process.exit(1);
-  }
-  const link = links[connId];
-
-  const file = flag('file');
-  let text: string;
-  if (file) {
-    text = (await import('node:fs')).readFileSync(file, 'utf-8');
-  } else {
-    // A bare positional (not a flag, and not a flag's VALUE) is accepted for one-liners.
-    const flagVals = new Set<string>();
-    for (let i = 0; i < args.length; i++) if (args[i].startsWith('--')) flagVals.add(args[i + 1]);
-    const positional = args.slice(2).find((a) => !a.startsWith('--') && !flagVals.has(a));
-    text = positional ?? await new Response(Bun.stdin.stream()).text();
-  }
-  if (!text.trim()) {
-    console.error('nothing to post: text was empty (pipe it on stdin, pass --file, or give it as an argument)');
+// CONTRACT. The module is imported for side effects, with `process.argv` untouched — it reads argv
+// itself, and calls `process.exit()` when it has handled the command. If it returns without
+// exiting, we fall through to the normal server boot, which is exactly what an unrecognised
+// subcommand does today. It runs AFTER env resolution (so DATA_DIR/PORT are settled and the
+// extension sees the same data dir the server would) and BEFORE any server boot.
+//
+// WHY AN ENV VAR AND NOT A REGISTRY. There is no server process to register against — this is a
+// one-shot CLI. The path must come from the deployment, and the deployment already sets DATA_DIR
+// and friends the same way.
+const cliExt = process.env.SHRAGA_CLI_EXT?.trim();
+if (cliExt && args[0] && !args[0].startsWith('-') && !CORE_SUBCOMMANDS.has(args[0])) {
+  const { pathToFileURL } = await import('node:url');
+  const { resolve } = await import('node:path');
+  try {
+    await import(pathToFileURL(resolve(cliExt)).href);
+  } catch (err) {
+    console.error(`[cli-ext] failed to load ${cliExt}:`, (err as Error)?.stack || err);
     process.exit(1);
   }
-
-  const ok = await postProactive({ url: link.url, secret: link.secret, connId }, link.convId, text);
-  // Exit code is the point: `postProactive` swallows transport failures into `false`, so a caller
-  // that only looked at stdout would read a silent drop as a successful delivery.
-  if (!ok) { console.error(`\u2716 para post FAILED \u2192 ${link.convId}`); process.exit(1); }
-  console.log(`\u2705 posted to ${link.convId}`);
-  process.exit(0);
 }
 
 // `shraga ingress` — host-header TCP router for previews + blue-green flips.

package/src/server/boot.ts

@@ -25,7 +25,6 @@ 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';
@@ -113,7 +112,15 @@ const PASSIVE_FLAG = process.env.SHRAGA_PASSIVE ?? process.env.UNCLAW_PASSIVE;
 const PASSIVE = PASSIVE_FLAG === '1' || PASSIVE_FLAG === 'true';
 if (PASSIVE) console.log('[server] PASSIVE mode — schedulers, consumers and background writers disabled');
 
+// Local-only prep (git config, gitignore, untracking). The NETWORK half — fetch/merge — is
+// deliberately NOT awaited here; it runs via dataSync.syncOnBoot() AFTER listen(). See syncOnBoot().
 if (!PASSIVE) await dataSync.init();
+
+// Kick the boot-time data sync detached, AFTER the port is bound. syncOnBoot() never rejects, and the
+// extra .catch() is belt-and-braces: an unhandled rejection here would hit the process-level handler.
+function bootDataSync(): void {
+  dataSync.syncOnBoot().catch(err => console.error('[data-sync] boot sync error:', (err as Error).message));
+}
 await loadShragaConfig();
 // Programmatic engines register through the same seam an overlay uses — BEFORE initEngines() so
 // getAvailableEngines() includes them and a directive can resolve to one immediately.
@@ -993,8 +1000,8 @@ function proxySidecarWebSocket(req: import('node:http').IncomingMessage, socket:
       // proxy-local reply only proves THIS hop is alive: if the proxy→sidecar leg is half-open, or the
       // sidecar has already dropped this client from its subscriber set, the browser still gets pongs,
       // keeps `readyState === OPEN`, shows a green "connected" dot, and every keystroke disappears.
-      // The probe is only worth anything end-to-end, so the sidecar owns the reply (para-pty answers in
-      // its ws message handler); a sidecar that doesn't reply fails the probe, which is the honest
+      // The probe is only worth anything end-to-end, so the sidecar owns the reply (it answers in its
+      // own ws message handler); a sidecar that doesn't reply fails the probe, which is the honest
       // outcome — the client then reconnects rather than trusting a dead pipe.
       if (targetWs.readyState === WebSocket.OPEN) targetWs.send(data, { binary: isBinary });
       else if (!opened && pending.length < 256) pending.push({ data, isBinary }); // bounded: never buffer unboundedly
@@ -1058,7 +1065,7 @@ server.on('upgrade', (req, socket, head) => {
   } else {
     const port = req.url ? resolveSidecarPort(req.url) : null;
     if (port) {
-      // A sidecar socket is a LIVE ATTACHED SHELL (para-pty) — read/write on the user's terminals. It
+      // A sidecar socket is a LIVE ATTACHED SHELL (a terminal daemon) — read/write on the user's terminals. It
       // must be authenticated BEFORE we bridge it, like the HTTP routes (`requireAuth`) and the `/ws`
       // control socket (its `auth` message). NOTE the limit of this gate: it is IDENTITY-ONLY. It proves
       // the token belongs to a valid user; it does NOT check that the user owns (or may access) the
@@ -1215,9 +1222,6 @@ 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());
@@ -1233,6 +1237,7 @@ async function activateConsumers() {
   activated = true;
   console.log('[server] ACTIVATING — starting consumers and background writers');
   await dataSync.init();
+  bootDataSync();
   syncVendorRepos().catch(err => console.warn('[vendor-sync] error:', (err as Error).message));
   recordBootGap();
   startHeartbeat();
@@ -2150,6 +2155,7 @@ await new Promise<void>((resolve) => {
     catch (err) { console.warn('[self-upgrade] could not deliver report:', (err as Error).message); }
     startSidecars().catch(err => console.error('[sidecar] startup error:', err));
     recoverInterruptedSessions().catch(err => console.error('[recovery] failed:', err));
+    bootDataSync();
     // The disk MCP catalog is warmed off the turn path by whichever engine consumes it — the CE default
     // (Claude Code) hands MCP servers straight to its SDK and needs no catalog. An add-on engine that
     // uses the shared catalog registers its own boot/interval warm-up through the overlay.

package/src/server/data-sync.ts

@@ -66,6 +66,15 @@ export function extractCommitSubject(raw: string): string {
   return '';
 }
 
+/** Paths that are REWRITTEN or discarded by design: per-run worker logs, per-run task files, and
+ *  `.bak-*` copies. The shrink guard exists to catch a shared file being gutted (contacts.json
+ *  111 -> 5 lines); a task file losing 58 lines because the next run rewrote it is not that. And the
+ *  guard aborts the WHOLE commit, so one churn file stalls every other file's sync indefinitely —
+ *  measured 2026-09-07: repeated BLOCKED alerts and a 27-commit push backlog behind two task files. */
+export function isChurnPath(file: string): boolean {
+  return /(^|\/)workspace\/[^/]+\/workers\/(logs|tasks)\//.test(file) || /\.bak(-|\.|$)/.test(file);
+}
+
 export class DataSyncOptions {
   repoUrl = process.env.DATA_SYNC_REPO || '';
   branch = process.env.DATA_SYNC_BRANCH || 'main';
@@ -170,8 +179,31 @@ export class DataSync {
       await this.untrackIgnored();
       this.ready = true;
     }
+  }
 
-    await this.pull();
+  /**
+   * Boot-time NETWORK sync: the remote fetch/merge plus the deferred conflict-scan + integrity audit.
+   * Split out of init() so the HTTP port can bind BEFORE any of this runs.
+   *
+   * Why: this used to be the tail of init(), which bootServer awaits before listen(). A stalled pull
+   * (observed on liv-mac-1: `Could not resolve host: github.com`, plus a 60s LLM commit-message
+   * timeout) therefore held the ENTIRE boot — process alive, no listener on any port, 502s for
+   * minutes. The port watchdog then SIGTERM/SIGKILLed the boot (LastExitStatus=9) and the next boot
+   * re-entered the same stall. Serving possibly-stale data and refreshing a moment later is strictly
+   * better than not serving at all.
+   *
+   * Never rejects: the caller runs this detached, and an unhandled rejection here would reach the
+   * process-level handler.
+   */
+  async syncOnBoot(): Promise<void> {
+    if (!this.ready) return; // init() disabled/aborted — nothing to sync against
+    console.log(`${TAG} Boot sync started (background — the server is already serving)`);
+    try {
+      await this.pull();
+      console.log(`${TAG} Boot sync complete`);
+    } catch (err) {
+      console.error(`${TAG} Boot sync FAILED — serving stale data until the next pull:`, (err as Error).message);
+    }
     // Defer heavy sync I/O (reads all tracked files + execSync) to avoid blocking
     // WS connections and page loads during startup.
     setTimeout(() => {
@@ -180,7 +212,8 @@ export class DataSync {
         // execSync inside the audit blocks too — keep it off the scan's tick so the two
         // never add up into one long freeze.
         .then(() => new Promise<void>(r => setImmediate(r)))
-        .then(() => this.runIntegrityAudit());
+        .then(() => this.runIntegrityAudit())
+        .catch(err => console.warn(`${TAG} Post-init integrity audit failed:`, (err as Error).message));
     }, 60_000);
   }
 
@@ -236,7 +269,7 @@ export class DataSync {
         const [addRaw, delRaw, file] = line.split('\t');
         if (addRaw === '-' || delRaw === '-' || !file) continue; // binary
         const net = (parseInt(delRaw, 10) || 0) - (parseInt(addRaw, 10) || 0);
-        if (net > shrinkThreshold) shrunk.push(`• ${file}  (−${net} net lines)`);
+        if (net > shrinkThreshold && !isChurnPath(file)) shrunk.push(`• ${file}  (−${net} net lines)`);
       }
       if (shrunk.length) {
         console.error(`${TAG} 🚫 BLOCKED large content shrink (${context}): ${shrunk.length} file(s) — net-removal threshold is ${shrinkThreshold}`);

package/src/server/notify-owners.ts

@@ -19,10 +19,10 @@ export function ownerEmails(): string[] {
 /** 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. */
+ *  (OWNERS ∩ contacts WITH a Slack id), which is a Slack-shaped answer. A webhook-lane add-on, for
+ *  instance, 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 open a link. */
 export function isOwnerEmail(email: string | undefined | null): boolean {
   const e = String(email ?? '').trim().toLowerCase();
   return !!e && ownerEmails().includes(e);
@@ -48,8 +48,9 @@ export function senderStamp(): string {
  * 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".
+ * answer only while Slack was the sole medium: `resolveOwners` filters on a SLACK id, so once another
+ * medium 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

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 });
 }

package/src/server/para/feature.ts

@@ -1,229 +0,0 @@
-/**
- * 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. */
-export type Link = ParaCallback & { convId: string; at: number; uid: string; email?: string };
-
-export 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; sendSegments: boolean;
-}): Promise<void> {
-  const { callback, convId, msgId, sessionId, prompt, uid, userEmail, sendSegments } = args;
-  const streamer = new ParaStreamer({ callback, convId, msgId, sendSegments });
-  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, 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('[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, accepts } = req.body as {
-        connId?: string; convId?: string; sessionId?: string; msgId?: string; prompt?: string;
-        callback?: { url?: string; secret?: string };
-        /** Receiver capability negotiation. `'segments'` means "I can store and render structured
-         *  tool segments" — see `ParaStreamerOptions.sendSegments`. ABSENT means no: a para-li that
-         *  predates this field, and a lane (groups) that deliberately declines, both fall back to
-         *  the flattened `_🔧 Tool_` markers in the text. */
-        accepts?: unknown;
-      };
-      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,
-        sendSegments: Array.isArray(accepts) && accepts.includes('segments'),
-      });
-    });
-
-    console.log('[para] turn ingress mounted at POST /api/para/turn');
-  },
-};