wicked-crew 0.5.0 → 0.7.0

package/dist/interactive/bridge-pool.js

@@ -0,0 +1,244 @@
+/**
+ * The wicked-interactive bridge pool — discovery, health, reuse-or-start (DES-MERGE-001 §5.3/§5.6).
+ *
+ * A bridge is a local `wicked-interactive serve` process that records itself in
+ * `<root>/.wi-serve.json` = `{ port, host, pid, startedAt, version }` (ADR-0022). Its port is
+ * DYNAMIC — the first free port above its base — which is precisely why crew, a server process
+ * that can read that lockfile, proxies it instead of the browser dialling a port literal.
+ *
+ * LOCAL-ONLY BY DESIGN. Every mechanism here (a pid, a file in a directory, spawning a child)
+ * is single-host. That is the slice-1 posture, not an oversight: when the execution seam goes
+ * remote, this module is the seam that gets a remote implementation, and the proxy above it
+ * does not change.
+ *
+ * Pooling is keyed by the RESOLVED root (see `bridge-root.ts`), so two projects that share the
+ * default root share one bridge and one port; projects bound to different roots get their own.
+ *
+ * Health follows ADR-0025's hardened reuse check, and the ORDER matters: a recorded pid that is
+ * alive but slow (cold first hit, busy materializing) must be REUSED, not duplicated — so a
+ * live pid earns three 1.5 s attempts before the bridge is declared dead. Identity is checked
+ * too: `/api/health` must report THIS root, or a recycled port belonging to some other service
+ * would be proxied as if it were ours.
+ *
+ * On start/adopt the pool also records the daemon's own origin with the bridge (crew#298,
+ * `POST /api/studio-origin`, interactive ≥ 0.8.0) so the bridge's `GET /` redirects a direct
+ * visitor into studio instead of its API-only fallback page. Fire-and-forget, once per pooled
+ * bridge: recording can never fail — or slow down — a proxied request.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+export const LOCK_NAME = '.wi-serve.json';
+/** ADR-0025: 1.5 s × 3 while the pid lives. */
+export const HEALTH_TIMEOUT_MS = 1500;
+export const HEALTH_ATTEMPTS = 3;
+/** A cold `npx wicked-interactive serve` may have to resolve and fetch the package first. */
+export const START_TIMEOUT_MS = 60_000;
+/** The 503 the proxy renders as `{"code":"bridge_unavailable","hint":...}` (§5.6). */
+export class BridgeUnavailableError extends Error {
+    /** An ACTIONABLE command an operator can actually run — never a bare "try again". */
+    hint;
+    constructor(message, hint) {
+        super(message);
+        this.name = 'BridgeUnavailableError';
+        this.hint = hint;
+    }
+}
+/** The one command that reproduces a failed start in a terminal, where its output is visible. */
+function serveCommand(root) {
+    return `npx wicked-interactive serve --root ${root}`;
+}
+/**
+ * The daemon's own http origin from its bound server address, or null before `listen`. Wildcard
+ * binds (`0.0.0.0` / `::`) are not dialable from a browser, so they normalize to loopback — the
+ * bridge is local-only anyway, so whoever hits its port can reach the daemon at 127.0.0.1 too.
+ */
+export function boundOrigin(addr) {
+    if (addr === null || typeof addr === 'string')
+        return null;
+    const host = addr.address === '' || addr.address === '0.0.0.0' || addr.address === '::'
+        ? '127.0.0.1'
+        : addr.address.includes(':')
+            ? `[${addr.address}]`
+            : addr.address;
+    return `http://${host}:${addr.port}`;
+}
+/** `<root>/.wi-serve.json`, or null when absent/unparseable/incomplete. */
+export function readLock(root) {
+    try {
+        const raw = JSON.parse(readFileSync(join(root, LOCK_NAME), 'utf8'));
+        if (typeof raw.port !== 'number' || typeof raw.pid !== 'number')
+            return null;
+        return { host: typeof raw.host === 'string' && raw.host !== '' ? raw.host : '127.0.0.1', port: raw.port, pid: raw.pid };
+    }
+    catch {
+        return null;
+    }
+}
+/** Signal 0 probes existence without delivering: EPERM means alive-but-not-ours. */
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/** `GET /api/health` → the root that bridge is serving, or null (timeout, refusal, non-200). */
+async function bridgeIdentity(bridge, timeoutMs) {
+    try {
+        const res = await fetch(`http://${bridge.host}:${bridge.port}/api/health`, {
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.root === 'string' ? body.root : null;
+    }
+    catch {
+        return null;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class InteractiveBridgePool {
+    io;
+    /** Last bridge known good per root — the fast path that keeps the proxy off `fetch` per request. */
+    live = new Map();
+    /** In-flight resolutions per root, so a burst of first requests starts ONE bridge, not N. */
+    inflight = new Map();
+    constructor(io = {}) {
+        this.io = io;
+    }
+    /** Reuse-or-start, idempotent per root. Throws `BridgeUnavailableError` when start is impossible. */
+    async ensure(root) {
+        // Fast path: we started/adopted it and its pid is still alive. A full health round-trip on
+        // every proxied request would put a 1.5 s timeout budget in front of every asset fetch.
+        const cached = this.live.get(root);
+        if (cached && pidAlive(cached.bridge.pid))
+            return cached.bridge;
+        this.live.delete(root);
+        const pending = this.inflight.get(root);
+        if (pending)
+            return pending;
+        const started = this.resolveOrStart(root).finally(() => this.inflight.delete(root));
+        this.inflight.set(root, started);
+        return started;
+    }
+    /** Drop the cached bridge for a root — called when a proxied connection is refused. */
+    invalidate(root) {
+        this.live.delete(root);
+    }
+    /** Live bridges, for tests and future operator introspection. */
+    keys() {
+        return [...this.live.keys()];
+    }
+    async resolveOrStart(root) {
+        // Adopt-or-start; either way the bridge just answered `/api/health` for this root, which is
+        // exactly the moment #298 wants the studio origin recorded — fire-and-forget, so recording
+        // can never delay (let alone fail) the proxied request that triggered the resolution.
+        const bridge = (await this.healthy(root)) ?? (await this.start(root));
+        const entry = { bridge, originRecorded: false };
+        this.live.set(root, entry);
+        this.recordStudioOrigin(entry);
+        return bridge;
+    }
+    /**
+     * POST the daemon's own origin to the bridge's `/api/studio-origin` (#298), so the bridge's
+     * `GET /` redirects a direct visitor into studio instead of the API-only fallback page.
+     * At most one attempt per pooled bridge per process; 404/405 means the bridge predates the
+     * endpoint (interactive < 0.8.0) and is an expected skip, any other failure is a warn — never
+     * an error, because origin recording must never fail a proxy request.
+     */
+    recordStudioOrigin(entry) {
+        if (entry.originRecorded)
+            return;
+        entry.originRecorded = true;
+        const origin = this.io.studioOrigin?.() ?? null;
+        if (origin === null)
+            return; // no origin to record (pool not bootstrapped from a listening daemon)
+        const { host, port } = entry.bridge;
+        const timeout = this.io.healthTimeoutMs ?? HEALTH_TIMEOUT_MS;
+        void (async () => {
+            try {
+                const res = await fetch(`http://${host}:${port}/api/studio-origin`, {
+                    method: 'POST',
+                    headers: { 'content-type': 'application/json' },
+                    body: JSON.stringify({ origin }),
+                    signal: AbortSignal.timeout(timeout),
+                });
+                await res.arrayBuffer().catch(() => undefined); // drain, so the connection is released
+                if (res.status === 404 || res.status === 405) {
+                    this.io.debug?.(`bridge at ${host}:${port} has no /api/studio-origin (interactive < 0.8.0) — skipping origin record`);
+                }
+                else if (!res.ok) {
+                    this.io.log?.(`recording studio origin ${origin} with the bridge at ${host}:${port} failed: HTTP ${res.status}`);
+                }
+            }
+            catch (err) {
+                this.io.log?.(`recording studio origin ${origin} with the bridge at ${host}:${port} failed: ${err.message}`);
+            }
+        })();
+    }
+    /** The lockfile points at a bridge that is alive, answering, and serving THIS root. */
+    async healthy(root) {
+        const lock = readLock(root);
+        if (lock === null || !pidAlive(lock.pid))
+            return null;
+        const timeout = this.io.healthTimeoutMs ?? HEALTH_TIMEOUT_MS;
+        for (let attempt = 0; attempt < HEALTH_ATTEMPTS; attempt++) {
+            const identity = await bridgeIdentity(lock, timeout);
+            if (identity !== null && resolve(identity) === root)
+                return lock;
+            // Only keep retrying while the pid still lives — a bridge that exited mid-probe is dead,
+            // not slow, and burning the remaining attempts on it just delays the restart.
+            if (!pidAlive(lock.pid))
+                return null;
+            if (attempt < HEALTH_ATTEMPTS - 1)
+                await sleep(300);
+        }
+        return null;
+    }
+    async start(root) {
+        try {
+            // `npx` runs with cwd=root; a missing directory fails the spawn with an opaque error.
+            mkdirSync(root, { recursive: true });
+        }
+        catch (err) {
+            throw new BridgeUnavailableError(`interactive root ${root} is not usable: ${err.message}`, `create the docs root and retry: mkdir -p ${root} && ${serveCommand(root)}`);
+        }
+        let spawnFailure = null;
+        const child = (this.io.spawn ?? defaultSpawn)(root);
+        // Detached + unref: the bridge is a SHARED instance keyed by root, so it must outlive the
+        // daemon that happened to start it (and be adoptable by the next one via the lockfile).
+        child.on('error', (err) => {
+            spawnFailure = err.message;
+        });
+        child.unref?.();
+        const deadline = Date.now() + (this.io.startTimeoutMs ?? START_TIMEOUT_MS);
+        while (Date.now() < deadline) {
+            if (spawnFailure !== null) {
+                throw new BridgeUnavailableError(`could not spawn the interactive bridge in ${root}: ${spawnFailure}`, `install Node 22+ so \`npx\` is on PATH, then run: ${serveCommand(root)}`);
+            }
+            const healthy = await this.healthy(root);
+            if (healthy)
+                return healthy;
+            await sleep(150);
+        }
+        this.io.log?.(`interactive bridge for ${root} did not come up within the start budget`);
+        throw new BridgeUnavailableError(`the interactive bridge for ${root} did not become healthy in time`, `run \`${serveCommand(root)}\` in a terminal to see the failure (or check ${join(root, '.wi-serve.log')})`);
+    }
+}
+/** `npx wicked-interactive serve` in `<root>`, detached, output to the bridge's own log. */
+function defaultSpawn(root) {
+    // `--yes` is load-bearing: without it npx PROMPTS when the package is not installed, and a
+    // daemon has no tty to answer with — the request would hang instead of failing to a 503.
+    return nodeSpawn('npx', ['--yes', 'wicked-interactive', 'serve', '--root', root], {
+        cwd: root,
+        detached: true,
+        stdio: 'ignore',
+    });
+}
+//# sourceMappingURL=bridge-pool.js.map

package/dist/interactive/bridge-pool.js.map

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

package/dist/interactive/bridge-root.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Which wicked-interactive document root a crew project speaks to (DES-MERGE-001 §7.1/§7.2).
+ *
+ * §7.1 closed the identity question: a crew Project is THE entity, and an interactive
+ * "instance" (a docs directory) maps onto it through ONE nullable setting, `interactiveRoot`.
+ * Null means "the shared default root" — it is a default, never a constraint (§7.2): two
+ * projects that leave it null share one bridge, a project that sets it gets its own.
+ *
+ * The resolved string is also the BRIDGE POOL KEY, which is why every spelling of the same
+ * directory has to collapse to one value here rather than in the pool. `~/decks`, `decks`
+ * (relative), and `/Users/me/decks/` are the same instance; keying on the raw setting would
+ * start a second `wicked-interactive serve` on a second port for each spelling — exactly the
+ * "why is it on 5 ports" confusion ADR-0025 exists to prevent.
+ */
+/** The setting carrier — a `Project` record or a crew-side settings row both satisfy this. */
+export interface InteractiveRootSetting {
+    /** Absolute or `~`-relative docs root; null/absent ⇒ the shared default. */
+    interactiveRoot?: string | null | undefined;
+}
+/** Env override for the SHARED DEFAULT only (never for an explicit per-project setting).
+ *  Exists so a test harness or an e2e run can point "the default root" at a scratch dir. */
+export declare const ROOT_ENV = "WICKED_INTERACTIVE_ROOT";
+/**
+ * What `wicked-interactive serve` uses with no `--root`: the canonical shared root
+ * `~/wicked-interactive/docs` (ADR-0025 amended, `bin/wicked-interactive.js:181`). Kept
+ * byte-identical to interactive's own default on purpose — that is what lets an operator's
+ * already-running default bridge be ADOPTED by the pool instead of duplicated.
+ */
+export declare function defaultInteractiveRoot(home?: string): string;
+/**
+ * The resolved, canonical docs root for a project — and therefore its bridge pool key.
+ * Precedence: the project's own `interactiveRoot` › `WICKED_INTERACTIVE_ROOT` › the shared
+ * default. A blank/whitespace setting is treated as null, not as "the cwd".
+ */
+export declare function resolveInteractiveRoot(setting: InteractiveRootSetting | null | undefined, env?: Record<string, string | undefined>, home?: string): string;
+//# sourceMappingURL=bridge-root.d.ts.map

package/dist/interactive/bridge-root.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-root.d.ts","sourceRoot":"","sources":["../../src/interactive/bridge-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,8FAA8F;AAC9F,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;CAC7C;AAED;4FAC4F;AAC5F,eAAO,MAAM,QAAQ,4BAA4B,CAAC;AAElD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,MAAkB,GAAG,MAAM,CAEvE;AASD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,sBAAsB,GAAG,IAAI,GAAG,SAAS,EAClD,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,EACrD,IAAI,GAAE,MAAkB,GACvB,MAAM,CAMR"}

package/dist/interactive/bridge-root.js

@@ -0,0 +1,48 @@
+/**
+ * Which wicked-interactive document root a crew project speaks to (DES-MERGE-001 §7.1/§7.2).
+ *
+ * §7.1 closed the identity question: a crew Project is THE entity, and an interactive
+ * "instance" (a docs directory) maps onto it through ONE nullable setting, `interactiveRoot`.
+ * Null means "the shared default root" — it is a default, never a constraint (§7.2): two
+ * projects that leave it null share one bridge, a project that sets it gets its own.
+ *
+ * The resolved string is also the BRIDGE POOL KEY, which is why every spelling of the same
+ * directory has to collapse to one value here rather than in the pool. `~/decks`, `decks`
+ * (relative), and `/Users/me/decks/` are the same instance; keying on the raw setting would
+ * start a second `wicked-interactive serve` on a second port for each spelling — exactly the
+ * "why is it on 5 ports" confusion ADR-0025 exists to prevent.
+ */
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/** Env override for the SHARED DEFAULT only (never for an explicit per-project setting).
+ *  Exists so a test harness or an e2e run can point "the default root" at a scratch dir. */
+export const ROOT_ENV = 'WICKED_INTERACTIVE_ROOT';
+/**
+ * What `wicked-interactive serve` uses with no `--root`: the canonical shared root
+ * `~/wicked-interactive/docs` (ADR-0025 amended, `bin/wicked-interactive.js:181`). Kept
+ * byte-identical to interactive's own default on purpose — that is what lets an operator's
+ * already-running default bridge be ADOPTED by the pool instead of duplicated.
+ */
+export function defaultInteractiveRoot(home = homedir()) {
+    return resolve(home, 'wicked-interactive', 'docs');
+}
+/** Expand a leading `~` and absolutize, so every spelling of one directory keys the same. */
+function canonicalize(value, home) {
+    const expanded = value === '~' ? home : value.startsWith('~/') || value.startsWith('~\\') ? resolve(home, value.slice(2)) : value;
+    return resolve(expanded);
+}
+/**
+ * The resolved, canonical docs root for a project — and therefore its bridge pool key.
+ * Precedence: the project's own `interactiveRoot` › `WICKED_INTERACTIVE_ROOT` › the shared
+ * default. A blank/whitespace setting is treated as null, not as "the cwd".
+ */
+export function resolveInteractiveRoot(setting, env = process.env, home = homedir()) {
+    const own = setting?.interactiveRoot;
+    if (typeof own === 'string' && own.trim() !== '')
+        return canonicalize(own.trim(), home);
+    const shared = env[ROOT_ENV];
+    if (typeof shared === 'string' && shared.trim() !== '')
+        return canonicalize(shared.trim(), home);
+    return defaultInteractiveRoot(home);
+}
+//# sourceMappingURL=bridge-root.js.map

package/dist/interactive/bridge-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-root.js","sourceRoot":"","sources":["../../src/interactive/bridge-root.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQpC;4FAC4F;AAC5F,MAAM,CAAC,MAAM,QAAQ,GAAG,yBAAyB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe,OAAO,EAAE;IAC7D,OAAO,OAAO,CAAC,IAAI,EAAE,oBAAoB,EAAE,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,6FAA6F;AAC7F,SAAS,YAAY,CAAC,KAAa,EAAE,IAAY;IAC/C,MAAM,QAAQ,GACZ,KAAK,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnH,OAAO,OAAO,CAAC,QAAQ,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAkD,EAClD,MAA0C,OAAO,CAAC,GAAG,EACrD,OAAe,OAAO,EAAE;IAExB,MAAM,GAAG,GAAG,OAAO,EAAE,eAAe,CAAC;IACrC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,YAAY,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACxF,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,YAAY,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACjG,OAAO,sBAAsB,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/interactive/chat-events.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Opt-in governed answering of wicked-interactive's conversational ITERATION asks (CREW-UX-5 —
+ * the third interactive leg, beside draft-events.ts and edit-events.ts).
+ *
+ * A finished doc's thread send in wicked-studio does `postFork` (mints a version) and injects
+ * `wicked.interactive.chat.posted` — and NOTHING consumed that topic since the ad-hoc assist
+ * agent retired: crew answers `doc.created` (the first draft) and `feedback.processed` (the
+ * structural handoff), but the plain conversational ask ("make the intro punchier") had no
+ * answerer, so BRIEF-UX-001 J3's "iterate twice" was impossible. This module makes a
+ * crew-governed run the answerer: understand-the-ask → revise, announced back on the SAME
+ * `draft.completed` wire the first draft rides — the service lands the revised full HTML as a
+ * generated version (`materializeDraft` → `applyGeneratedHtml`), which is exactly what an
+ * iteration is.
+ *
+ * Shape mirrors draft-events.ts (dynamic wicked-bus import, graceful degradation, durable
+ * cursor `cursor_init: 'latest'` under a dedicated plugin name, durable replay-dedup ledger,
+ * `wi-crew` narration via status.posted). The chat-specific deltas:
+ *
+ *  - THE TRIGGER IS A CONVERSATION LINE, so the actionable filter is layered (the contract):
+ *    (a) `role: "user"` only — agent narration echoes also ride chat.posted;
+ *    (b) the doc must EXIST under the resolved docs root and not belong to a foreign loop —
+ *        and the disk truth here is subtle: interactive's `initManifest` only ever RECORDS a
+ *        `kind` for demo docs (a real `kind: "source"` doc's versions.json carries NO kind
+ *        field at all — the "source" spelling rides the doc.created EVENT only; verified
+ *        against interactive 0.8.0 and main, src/service/server.js `initWorkspace(dir, html)`).
+ *        So the gate accepts `source` (future manifests may record it) and the absent-default
+ *        `doc`, and rejects explicit foreign kinds (`demo`) — a doc we cannot see is not ours
+ *        to answer either;
+ *    (c) per-doc serialization — an ask on a doc whose draft/edit/chat run is still in flight
+ *        is QUEUED (FIFO per doc), never raced: two concurrent revisions of one doc would
+ *        land as two forks of the same parent and the second would silently drop the first;
+ *    (d) the text must be an ASK, not an echo of a machine-composed message — the feedback
+ *        overlay injects its batch as a chat.posted TOO (same `source_message_id` as its
+ *        `feedback.submitted`), and that batch is already the edit seam's business.
+ *  - VERSION SNAPSHOT AT LAUNCH: the seam copies the doc's CURRENT HEAD html into the chat
+ *    inbox and names the COPY in the task, so (1) the worker never needs read access to the
+ *    doc workspace (the one declared write root covers input + deliverable — crew#263 /
+ *    wicked-core#259: write roots are readable) and (2) a queued second ask snapshots the
+ *    head AFTER the first revision landed — which is what "iterate twice" means.
+ *  - THE LANDING GATE: `draft.completed` is announced by path and the service lands the new
+ *    version ASYNCHRONOUSLY. A queued ask drained the instant our run completes would snapshot
+ *    the stale head and silently drop the revision the user just watched land. So a successful
+ *    completion arms a per-doc gate — drain only once the manifest head ADVANCES past the head
+ *    we launched from, or a timeout passes (the service may be down; waiting forever would
+ *    strand the queue).
+ *  - IDEMPOTENCY KEYING: one doc legitimately produces many asks over its life, so the dedupe
+ *    unit is the ASK — `source_message_id` when the frame carries one (the studio reuses the
+ *    SAME message id on a user-driven resend, so a retry that reached the bus twice dedupes),
+ *    else the bus `event_id` (pure redelivery). Never the doc lifetime.
+ */
+import { InteractiveHandoffLedger } from './ledger.js';
+import type { CoreAdapter } from '../core/adapter.js';
+import type { WorkflowDef } from '../core/types.js';
+export declare const CHAT_POSTED = "wicked.interactive.chat.posted";
+/** Exact-type filter with a domain guard — no wildcard, one event type is the whole trigger. */
+export declare const INTERACTIVE_CHAT_BUS_FILTER = "wicked.interactive.chat.posted@wicked-interactive";
+/** Dedicated durable-cursor identity — NOT the draft/edit seams', so the three interactive
+ *  seams advance independent cursors and stopping one never strands another. */
+export declare const INTERACTIVE_CHAT_BUS_PLUGIN = "wicked-crew-interactive-chat";
+export declare const INTERACTIVE_CHAT_WORKFLOW = "interactive-chat";
+/**
+ * The governed workflow that fulfils an iteration ask. Two agent phases — understand (recon)
+ * then revise (build, creator role) — the draft leg's sibling: the reviser builds on a stated
+ * plan instead of one-shotting a rewrite, and the run narrates a real phase transition.
+ *
+ * The phase `instructions` carry the ITERATION contract: start from the CURRENT document (the
+ * snapshot path named in the task), change only what the ask touches, KEEP every existing
+ * `data-wid` on kept elements (interactive's instrument pass preserves pre-existing anchors —
+ * INV-1 — so feedback deep-links survive the iteration) and mint none on added ones. They are
+ * SINGLE-LINE by contract (PTY seat runner, wicked-core FINDING-011).
+ *
+ * All gates are `auto` with `validator_pin: null` — same rationale as the draft leg: the
+ * acceptance gate for a revision is interactive's instrument+theme pipeline and the user's own
+ * eyes on the canvas.
+ */
+export declare const INTERACTIVE_CHAT_WORKFLOW_DEF: WorkflowDef;
+/** The chat-posted fields this seam acts on. */
+export interface ChatAsk {
+    documentId: string;
+    /** The user's ask, verbatim (flattened later — the problem statement is single-line). */
+    text: string;
+    /** The thread message behind the ask (studio inject wire, §7.7). The studio REUSES the same
+     *  id on a user-driven resend, so this is the dedupe unit when present. */
+    sourceMessageId?: string;
+    /** Present when the doc is project-bound (interactive's DES-PROJECT-001 enrichment). */
+    projectId?: string;
+}
+/**
+ * Parse a bus frame into a {@link ChatAsk}, or `null` when it is not an actionable ask:
+ * wrong type, malformed payload, non-`user` role (contract (a) — agent narration and any
+ * transcript echo ride the same topic), slug-invalid document_id, or empty text. Kind and
+ * existence checks (contract (b)) happen against the filesystem, not the payload — the frame
+ * does not carry `kind`.
+ */
+export declare function parseChatPosted(eventType: string, payload: unknown): ChatAsk | null;
+/** Contract (d): `true` when the text is a conversational ask this seam should answer —
+ *  not the feedback overlay's batch echo (already answered elsewhere). */
+export declare function isIterationAsk(text: string): boolean;
+/** The one dedupe unit of this seam: the ASK — the studio's message id when the frame carries
+ *  one (a resend reuses it), else the bus event id (pure redelivery). Never the doc lifetime. */
+export declare function chatKey(documentId: string, eventId: number, sourceMessageId?: string): string;
+/** Deterministic bus idempotency key for the one revision this seam may land per ask. */
+export declare function chatIdempotencyKey(documentId: string, eventId: number, sourceMessageId?: string): string;
+/** What the versions.json read yields — enough to gate (kind) and snapshot (head html path). */
+export interface DocHead {
+    kind: string;
+    head: number;
+    /** Absolute path of the head version's html artifact. */
+    headHtmlPath: string;
+}
+/**
+ * Read a doc workspace's manifest (interactive's `versions.json`, fsstore.js shape) and resolve
+ * its head html path. `null` when the doc does not exist under this root or the manifest is
+ * unreadable — not ours to answer, per contract (b). Follows interactive's own tolerant read:
+ * `kind` defaults to `"doc"` when absent (listDocs does the same) — and ABSENT is what a real
+ * source doc looks like on disk (interactive records kind only for demo docs), so the caller
+ * gates through {@link isAnswerableDocKind}, never a `=== 'source'` comparison.
+ */
+export declare function readDocHead(docsRoot: string, documentId: string): DocHead | null;
+/**
+ * Contract (b)'s kind half: `true` when a doc of this manifest kind is this seam's to answer.
+ * `source` is the spec's spelling (recorded by no released interactive yet, accepted for the
+ * day a manifest carries it); `doc` is the absent-default every REAL source (and plain html)
+ * doc reads as — interactive's initManifest keeps non-demo kinds implicit. Explicit foreign
+ * kinds (`demo`, anything future) belong to their own loops.
+ */
+export declare function isAnswerableDocKind(kind: string): boolean;
+/**
+ * The run's problem statement (the engine scopes it per phase and folds each phase's
+ * instructions on top). Carries everything ask-specific: identity, the flattened ask, the
+ * CURRENT-version snapshot to read, and the absolute path the revised HTML must land at.
+ *
+ * CREW-UX-8 SPLIT — the revision leg carries NO repo grounding, deliberately. The draft leg
+ * (draft-events.ts) grounds its v1 in a launch-scoped repo snapshot and that shape is proven
+ * live; the SAME shape on the revise turn wedged 2/2 on the real engine (crew#288 comment —
+ * the repo-grounded revise turn hits the known second-turn wedge), while UNGROUNDED revisions
+ * are proven to land (the CREW-UX-5 verification). So bound asks launch exactly like unfiled
+ * ones — head-copy in the external inbox, one write root, no repoRef (wicked-core#293), no
+ * live-repo path in the task (wicked-core#294). Revision grounding returns when either of
+ * those is fixed.
+ */
+export declare function chatProblem(ask: ChatAsk, currentPath: string, outPath: string): string;
+/** Options for {@link startInteractiveChatSubscriber}. */
+export interface InteractiveChatOptions {
+    /** Bus SQLite db path. Omit to let wicked-bus resolve its own default
+     *  (honors `WICKED_BUS_DATA_DIR`) — where interactive's service emits unless redirected. */
+    dbPath?: string;
+    /** Poll cadence, ms (default 2000; tests shorten it). */
+    pollIntervalMs?: number;
+    /** Heartbeat narration cadence while a run is in flight, ms (default 15000 — inside the
+     *  UI's ~20s `status.requested` window so the canvas never reads frozen; the studio's own
+     *  90s silence budget makes the FIRST pickup narration the load-bearing one). */
+    heartbeatMs?: number;
+    /** Ledger file (default `~/.wicked-crew/interactive-chat-ledger.json`). */
+    ledgerPath?: string;
+    /** Root under which each ask gets its own per-run subdirectory (`<chatDir>/<safeKey>/`)
+     *  holding the head snapshot and the revised deliverable; only that subdirectory is declared
+     *  as the run's extra write root (per-run isolation — Copilot, crew#313: declaring the shared
+     *  dir wholesale let one doc's worker read every other doc's head and revision).
+     *  Default `~/.wicked-crew/interactive-chats`. */
+    chatDir?: string;
+    /** Seat roster JSON for the governed run (default: the production council roster).
+     *  The functional-test harness passes a deterministic stub seat here. */
+    clisJson?: string;
+    /** The docs root an ask's doc is read from. Default: the shared-default resolution
+     *  (`WICKED_INTERACTIVE_ROOT` › `~/wicked-interactive/docs`); the server wires the
+     *  per-project `interactiveRoot` setting through here so a project on its own root
+     *  resolves correctly. */
+    resolveDocsRoot?: (projectId: string | undefined) => string;
+    /** Contract (c)'s cross-seam half: `true` while a DRAFT or EDIT run is in flight for the
+     *  doc. The server wires the sibling subscriptions' in-flight sets through here; the chat
+     *  seam's own in-flight runs are tracked internally. */
+    isDocBusy?: (documentId: string) => boolean;
+    /** Queue-drain sweep cadence, ms (default 1000; tests shorten it). */
+    queueSweepMs?: number;
+    /** How long a drained ask waits for the PREVIOUS revision's version to land before
+     *  proceeding on the stale head anyway, ms (default 60000; tests shorten it). */
+    landingGateMs?: number;
+    /** Called after a launch that FILED the run into a project (chat.posted carried
+     *  `project_id`). Same wiring as the sibling seams: the server points this at the launch
+     *  route's post-commit half (membership index tag + membership.attached emit). */
+    onRunFiled?: (runId: string, projectId: string) => void;
+    /** Diagnostics sink (default: console.error). */
+    log?: (message: string) => void;
+}
+/** Handle for a running subscription. */
+export interface InteractiveChatSubscription {
+    stop(): Promise<void> | void;
+    /** The durable ledger (diagnostics / tests). */
+    ledger: InteractiveHandoffLedger;
+    /** Documents with a chat run currently in flight (diagnostics / cross-seam wiring). */
+    inFlightDocs(): string[];
+    /** Asks queued behind a busy doc, per doc (diagnostics / tests). */
+    queuedCount(documentId: string): number;
+}
+/**
+ * Arm the seam: register the `interactive-chat` workflow, open a durable
+ * `wicked.interactive.chat.posted` subscription, and answer each user ask on an existing
+ * answerable doc (contract (b)) with a governed run that ends in `wicked.interactive.draft.completed`
+ * (the service lands the revised full HTML as a generated version).
+ *
+ * Graceful degradation mirrors the sibling seams: a missing wicked-bus package or an
+ * unopenable db LOGS and returns `null` — the daemon must still boot on a machine whose bus
+ * is broken.
+ */
+export declare function startInteractiveChatSubscriber(adapter: CoreAdapter, opts?: InteractiveChatOptions): Promise<InteractiveChatSubscription | null>;
+//# sourceMappingURL=chat-events.d.ts.map

package/dist/interactive/chat-events.d.ts.map

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