@crouton-kit/crouter 0.3.57 → 0.3.58

package/dist/clients/web/server.js

@@ -15,6 +15,13 @@
 //                             and relay frames VERBATIM both directions. The relay
 //                             adds NOTHING — the browser is the SAME protocol peer
 //                             as `crtr surface attach`.
+//   • Web push (§push)      → GET  /__crtr/push/vapid-public-key, POST/DELETE
+//                             /__crtr/push/subscribe. A server-side diff engine
+//                             (push-engine.ts) watches the SAME SSE invalidations
+//                             above and sends web-push to a persisted, auth-scoped
+//                             registry (push-registry.ts) — see D8 in the mobile-web
+//                             design. Behind the identical auth boundary as the rest
+//                             of this server.
 //
 // §0 ONE-WRITER INVARIANT: the WS relay is ONLY a socket relay. It NEVER calls
 // reviveNode, NEVER spawns `pi --session`, NEVER touches SessionManager, and
@@ -29,10 +36,12 @@
 // clients) — the broker fans out natively, so there is no bridge-side fan-out.
 import { createServer as createHttpServer } from 'node:http';
 import { createConnection, isIP } from 'node:net';
+import { createHash } from 'node:crypto';
 import { createReadStream, existsSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, extname, join, normalize, resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
+import webpush from 'web-push';
 import { viewSocketPath } from '../../core/canvas/paths.js';
 import { getNode } from '../../core/canvas/index.js';
 import { BROKER_READ_CAPS, CLIENT_READ_CAPS, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
@@ -41,9 +50,13 @@ import { clearFault, recordFault } from '../../core/runtime/fault.js';
 import { createLocalTransport } from '../../core/view/transport-local.js';
 import { createBurstCoalescingTransport } from '../../core/view/transport-cache.js';
 import { runSourceRequest } from '../../core/view/bridge.js';
+import { canvasSnapshotLeaf } from '../../commands/canvas-snapshot.js';
+import { humanList } from '../../commands/human/queue.js';
 import { startEventHub } from './events.js';
 import { createDevServer } from './dev-server.js';
 import { SOURCE_CACHE_TTL_MS, isCoalescableSourceRequest } from './source-cache.js';
+import { PushLastSeenStore, PushRegistryStore, PushRequestError, loadOrCreateVapidKeypair, parsePushDeleteBody, parsePushSubscriptionBody, pushBodyMaxBytes, } from './push-registry.js';
+import { PushDiffEngine } from './push-engine.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** Candidate dirs to serve the shell SPA bundle from, in priority order: an
  *  explicit override, the compiled-module-relative `dist/web-client/` (what
@@ -158,6 +171,32 @@ function readBody(req) {
         req.on('error', rej);
     });
 }
+/** Like `readBody`, but aborts the moment the accumulated body exceeds
+ *  `maxBytes` — so a push endpoint never buffers arbitrary attacker memory
+ *  before validation rejects it. Rejects with PushRequestError(413), which the
+ *  push error handler maps to a 413 response. */
+function readBodyCapped(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on('data', (c) => {
+            total += c.length;
+            if (total > maxBytes) {
+                reject(new PushRequestError(413, 'push subscription body is too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** Derive the persisted auth scope from a bearer token: a short, stable hash so
+ *  the raw secret never touches disk. */
+function scopeForToken(secret) {
+    return `token:${createHash('sha256').update(secret).digest('base64url').slice(0, 16)}`;
+}
 /** Serve a static file from the client dir, with SPA fallback to index.html for
  *  any unmatched (non-asset) GET — so `/` and `/node/<id>` both boot the app
  *  shell. Returns true if it wrote a response. */
@@ -385,13 +424,92 @@ export async function startWebServer(opts) {
             return true;
         return allowedOrigins.has(origin);
     };
-    const requestAllowed = (req) => {
-        if (requestTokenMatches(req, token))
-            return true;
+    const authorizeRequest = (req) => {
+        if (token !== undefined && requestTokenMatches(req, token)) {
+            return { allowed: true, scope: scopeForToken(token) };
+        }
         if (tokenRequired)
-            return false;
-        return originAllowed(req.headers.origin);
+            return { allowed: false };
+        if (!originAllowed(req.headers.origin))
+            return { allowed: false };
+        return { allowed: true, scope: 'local' };
     };
+    // The set of auth scopes this server actually authorizes — the push diff
+    // engine sends ONLY to subscriptions whose authScope is in this set (design
+    // line 252: identical boundary to /__crtr/source). Mirrors authorizeRequest:
+    // a token authorizes scopeForToken(token); a tokenless request is authorized
+    // only when !tokenRequired, as scope 'local'. A record left by a rotated/old
+    // token has a different digest and is therefore excluded.
+    const targetScopes = new Set();
+    if (token !== undefined)
+        targetScopes.add(scopeForToken(token));
+    if (!tokenRequired)
+        targetScopes.add('local');
+    // §push — the server-side web-push registry + diff engine (design D8). One
+    // persisted, auth-scoped subscription registry; one locally-generated VAPID
+    // identity signing every send; one diff engine that re-reads canvas+decks on
+    // the SAME SSE invalidations the browser clients get (via eventHub.subscribe,
+    // no HTTP self-loop) and pushes 'done'/'needs-you' notifications.
+    const pushRegistry = new PushRegistryStore();
+    const pushLastSeen = new PushLastSeenStore();
+    const vapid = loadOrCreateVapidKeypair();
+    webpush.setVapidDetails(vapid.subject, vapid.publicKey, vapid.privateKey);
+    // Page through every pending human ask, keeping only entries with the deck
+    // provenance (job + conversation) the payload/dedupe logic needs.
+    const collectPendingAsks = async () => {
+        const out = [];
+        let cursor;
+        for (let page = 0; page < 50; page++) {
+            const result = (await humanList.run({
+                limit: 100,
+                ...(cursor !== undefined ? { cursor } : {}),
+            }));
+            for (const item of result.items) {
+                if (item.job_id === undefined || item.conversation_id === undefined)
+                    continue;
+                out.push({
+                    id: item.id,
+                    jobId: item.job_id,
+                    title: item.title ?? item.job_id,
+                    conversationId: item.conversation_id,
+                    conversationTitle: item.conversation_title ?? item.conversation_id,
+                    blockedSince: item.blocked_since,
+                });
+            }
+            if (result.next_cursor === null)
+                break;
+            cursor = result.next_cursor;
+        }
+        return out;
+    };
+    const pushEngine = new PushDiffEngine({
+        registry: pushRegistry,
+        lastSeen: pushLastSeen,
+        readCanvasNodes: async () => {
+            const snap = (await canvasSnapshotLeaf.run({}));
+            return snap.nodes;
+        },
+        readPendingAsks: collectPendingAsks,
+        isTargetScope: (s) => targetScopes.has(s),
+        sendPush: async (record, payload) => {
+            try {
+                await webpush.sendNotification({ endpoint: record.endpoint, keys: record.keys }, JSON.stringify(payload));
+                return 'sent';
+            }
+            catch (err) {
+                const statusCode = err.statusCode;
+                return statusCode === 404 || statusCode === 410 ? 'gone' : 'error';
+            }
+        },
+    });
+    // A restart is not an attention event — record current state, send nothing.
+    await pushEngine.seed();
+    const unsubscribePush = eventHub.subscribe((kind) => {
+        if (kind === 'nodes')
+            void pushEngine.onNodesInvalidation();
+        else if (kind === 'inbox')
+            void pushEngine.onInboxInvalidation();
+    });
     // Assigned before listen() when --dev; the request handler closes over it.
     let vite;
     const httpServer = createHttpServer((req, res) => {
@@ -408,7 +526,7 @@ export async function startWebServer(opts) {
                     res.end('method not allowed\n');
                     return;
                 }
-                if (!requestAllowed(req)) {
+                if (!authorizeRequest(req).allowed) {
                     res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
                     res.end('forbidden\n');
                     return;
@@ -434,7 +552,7 @@ export async function startWebServer(opts) {
                     res.end('method not allowed\n');
                     return;
                 }
-                if (!requestAllowed(req)) {
+                if (!authorizeRequest(req).allowed) {
                     res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
                     res.end('forbidden\n');
                     return;
@@ -442,6 +560,70 @@ export async function startWebServer(opts) {
                 eventHub.addClient(res);
                 return;
             }
+            // §push — the VAPID public key a browser needs to subscribe. Read-only,
+            // non-secret, but behind the same auth boundary as everything else so a
+            // foreign page can't even enumerate the surface.
+            if (pathname === '/__crtr/push/vapid-public-key') {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'GET' });
+                    res.end('method not allowed\n');
+                    return;
+                }
+                if (!authorizeRequest(req).allowed) {
+                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('forbidden\n');
+                    return;
+                }
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ publicKey: vapid.publicKey }));
+                return;
+            }
+            // §push — subscribe (POST) / unsubscribe (DELETE). Validation lives in
+            // parsePush*Body, which rejects oversized/malformed/private/http/file
+            // shapes BEFORE any persistence, throwing PushRequestError with a status.
+            if (pathname === '/__crtr/push/subscribe') {
+                const auth = authorizeRequest(req);
+                if (!auth.allowed) {
+                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('forbidden\n');
+                    return;
+                }
+                const handlePushError = (e) => {
+                    if (e instanceof PushRequestError) {
+                        res.writeHead(e.statusCode, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: e.message }));
+                        return;
+                    }
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+                };
+                if (req.method === 'POST') {
+                    void readBodyCapped(req, pushBodyMaxBytes())
+                        .then((body) => {
+                        const record = parsePushSubscriptionBody(body, auth.scope);
+                        const stored = pushRegistry.upsert(record);
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true, id: stored.id, authScope: stored.authScope }));
+                    })
+                        .catch(handlePushError);
+                    return;
+                }
+                if (req.method === 'DELETE') {
+                    void readBodyCapped(req, pushBodyMaxBytes())
+                        .then((body) => {
+                        const { endpoint } = parsePushDeleteBody(body);
+                        // Scoped: a caller may only delete a subscription it owns.
+                        const deleted = pushRegistry.deleteByEndpoint(endpoint, auth.scope);
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true, deleted }));
+                    })
+                        .catch(handlePushError);
+                    return;
+                }
+                res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'POST, DELETE' });
+                res.end('method not allowed\n');
+                return;
+            }
             // --dev: Vite middleware owns all remaining asset/HTML serving (incl. its
             // own SPA fallback). It is mounted AFTER the bridge + SSE checks above, so
             // those never fall through to Vite.
@@ -490,7 +672,7 @@ export async function startWebServer(opts) {
                 socket.destroy();
                 return;
             }
-            if (!requestAllowed(req)) {
+            if (!authorizeRequest(req).allowed) {
                 socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
                 socket.destroy();
                 return;
@@ -533,6 +715,7 @@ export async function startWebServer(opts) {
                 `http://localhost:${port}`,
             ]);
             const close = () => new Promise((done) => {
+                unsubscribePush();
                 eventHub.close();
                 void vite?.close().catch(() => {
                     /* best-effort */

package/dist/clients/web/web-client/shared/protocol.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Shared wire types for the crouter web client/server split.
+ *
+ * The SPA imports the pi payload types it needs from this module — never from
+ * broker-protocol internals. The type-only re-exports below keep the web
+ * package's shared payload shapes in one place.
+ */
+export type { UserMessage, AssistantMessage, ToolResultMessage, TextContent, ToolCall, ImageContent, } from '@earendil-works/pi-ai';
+export type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+export type { RpcExtensionUIRequest, RpcExtensionUIResponse } from '@earendil-works/pi-coding-agent';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
+/**
+ * An `AgentMessage` enriched with a client-side origin tag.
+ * Only `role:'user'` messages can carry `origin:'inbox'`; all others leave
+ * `origin` undefined. `'human'` is reserved for future explicit human-origin
+ * tagging (currently unset — absence means human by default).
+ *
+ * Defined as an intersection (not `interface extends`) because `AgentMessage`
+ * is a union type and TypeScript does not allow extending unions.
+ */
+export type FoldedMessage = AgentMessage & {
+    /** Set to `'inbox'` when this user message is recognized as injected by the
+     *  canvas-inbox-watcher extension (a coalesced inbox digest). */
+    origin?: 'inbox' | 'human';
+};
+/** base session vs orchestrator. */
+export type NodeMode = 'base' | 'orchestrator';
+/** terminal (reaps when done) vs resident (root) node. */
+export type NodeLifecycle = 'terminal' | 'resident';
+/** Canvas lifecycle status. */
+export type NodeLifeStatus = 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+/** broker-hosted (enterable) vs tmux-pane (shown, non-enterable). */
+export type HostKind = 'broker' | 'tmux';
+/** One row from `crtr canvas snapshot --json` — node identity + runtime, no chrome. */
+export interface NodeSummary {
+    node_id: string;
+    name: string;
+    /** Node kind (developer/explore/…) — open set. */
+    kind: string;
+    mode: NodeMode;
+    lifecycle: NodeLifecycle;
+    status: NodeLifeStatus;
+    cwd: string;
+    /** Spine parent node id, or null for a root. */
+    parent: string | null;
+    /** ISO-8601 creation timestamp. */
+    created: string;
+    host_kind: HostKind;
+    /** True iff `host_kind === 'broker'` (the web UI can open a live session). */
+    enterable: boolean;
+    /** Count of pending human asks (blocked-on-human indicator). */
+    attention_count: number;
+    /** Canvas cycle count for this node (revive/yield generations). Optional for
+     *  back-compat with snapshots produced before the field existed. */
+    cycles?: number;
+    /** ISO-8601 of the node's most recent work (session activity), distinct from
+     *  `created`. Optional/back-compat; falls back to `created` when absent. */
+    last_activity?: string;
+}
+/** input/output token burn, with cache reads where the provider reports them. */
+export interface TokenBurn {
+    input: number;
+    output: number;
+    cache?: number;
+}
+/** Live context-window usage. */
+export interface ContextUsage {
+    tokens: number;
+    window: number;
+    percent: number;
+}
+/** Coarse session stats for chrome (distinct from pi's full `SessionStats`). */
+export interface SessionStatsSummary {
+    turns: number;
+    user_messages: number;
+    assistant_messages: number;
+    cost?: number;
+}
+/** Viewer/controller presence for a node. */
+export interface Presence {
+    viewers: number;
+    controller: string | null;
+}
+/** Git working-tree change counts for the meta strip. */
+export interface GitStatus {
+    added: number;
+    modified: number;
+    deleted: number;
+    untracked: number;
+}
+/** `crtr node inspect show --json`'s node payload — `NodeSummary` plus the per-node chrome. */
+export interface NodeDetail extends NodeSummary {
+    branch: string | null;
+    model: string | null;
+    tokens: TokenBurn | null;
+    context: ContextUsage | null;
+    tool_calls: number | null;
+    stats: SessionStatsSummary | null;
+    presence: Presence | null;
+    /** True while a broker is live; false for a dormant (last-known) view. */
+    live: boolean;
+    /** Working-tree change counts for the meta strip (null when unavailable). */
+    git_status?: GitStatus | null;
+}
+/** A slash command in a node's palette (from the broker `get_commands` reply). */
+export interface Command {
+    name: string;
+    description: string;
+    source: 'builtin' | 'command' | 'template';
+    location?: 'user' | 'project' | 'path';
+    path?: string;
+    argument_hint?: string;
+}
+/** `crtr canvas snapshot --json` body. */
+export interface CanvasSnapshot {
+    nodes: NodeSummary[];
+    /** ISO-8601. */
+    generated_at: string;
+}
+/** `crtr node new --json` success. */
+export interface SpawnResponse {
+    node_id: string;
+    name: string;
+    window?: string;
+    session?: string;
+    status: string;
+    follow_up: string;
+}
+/** `crtr node msg --json` success. */
+export interface MessageResponse {
+    mode: string;
+    armed: boolean;
+    target: string;
+    delivered?: boolean;
+    revived?: boolean;
+    guidance: string;
+}
+/** `crtr node lifecycle revive --json` success. */
+export interface ReviveResponse {
+    window: null;
+    session: string | null;
+    resumed: boolean;
+    ready: boolean;
+}
+/** `crtr node lifecycle close --json` success. */
+export interface CloseResponse {
+    closed: boolean;
+    node_id: string;
+    count: number;
+    closed_ids: string[];
+    spared: string[];
+}
+/** `crtr node new` body. Always headless; `root` toggles a resident node. */
+export interface SpawnRequest {
+    prompt: string;
+    kind: string;
+    mode?: NodeMode;
+    root?: boolean;
+    cwd?: string;
+    name?: string;
+    model?: string;
+    parent?: string;
+}
+/** `crtr node msg` body. */
+export interface MessageRequest {
+    body: string;
+    tier?: string;
+}
+/** `crtr node lifecycle revive` body. */
+export interface ReviveRequest {
+    fresh?: boolean;
+}
+/**
+ * The five resolution flows (design §5.2). humanloop's `InteractionKind` also
+ * has `review`; the deck loader normalizes it (and any unknown/absent kind)
+ * onto one of these five so a deck always renders through a known flow.
+ */
+export type DeckKind = 'notify' | 'validation' | 'decision' | 'context' | 'error';
+/** One option of a decision/validation interaction (humanloop InteractionOption). */
+export interface DeckOption {
+    id: string;
+    label: string;
+    /** The option's consequence/explanation (humanloop `description`). */
+    description?: string;
+}
+/** One interaction within a deck (humanloop Interaction, normalized for the web). */
+export interface DeckInteraction {
+    id: string;
+    title: string;
+    subtitle?: string;
+    /** Markdown body (bodyPath already inlined by `crtr human deck`). */
+    body?: string;
+    kind: DeckKind;
+    options: DeckOption[];
+    multiSelect: boolean;
+    allowFreetext: boolean;
+    freetextLabel?: string;
+}
+/**
+ * A pending ask, ranked in the inbox list (design §5.2). Provenance carries
+ * BOTH the conversation-facing summary (rendered by default, never the node
+ * id alone) and the raw asking node, shown alongside it.
+ */
+export interface DeckSummary {
+    /** Opaque, stable inbox-entry id (base64url of the interaction dir). */
+    id: string;
+    /** The interaction job id (basename of the interaction dir). */
+    job_id: string;
+    /** The first interaction's kind — the glyph + flow for the row. */
+    kind: DeckKind;
+    title: string;
+    subtitle?: string;
+    /** ISO-8601 — when the ask started blocking (drives the wait duration + rank). */
+    blocked_since: string;
+    /** The conversation (spine root) this ask belongs to. */
+    conversation_id: string;
+    conversation_title: string;
+    /** The node that raised the ask. */
+    asking_node_id: string;
+    asking_node_name: string;
+    /** The asking node's cwd — sub-DAG scoping. */
+    cwd: string;
+    /** How many interactions the deck holds (a multi-question deck). */
+    interaction_count: number;
+}
+/** The full deck for a resolution flow (`crtr human deck <id> --json`). */
+export interface DeckDetail extends DeckSummary {
+    interactions: DeckInteraction[];
+}
+/** One interaction's answer (humanloop InteractionResponse). */
+export interface DeckAnswer {
+    id: string;
+    selectedOptionId?: string;
+    selectedOptionIds?: string[];
+    freetext?: string;
+    optionComments?: Record<string, string>;
+}
+/** `crtr human resolve <id> --json` body. */
+export interface ResolveDeckRequest {
+    responses: DeckAnswer[];
+}
+/** `crtr human resolve <id> --json` success. */
+export interface ResolveDeckResponse {
+    resolved: true;
+    job_id: string;
+    delivered: boolean;
+}
+/**
+ * Engine state carried in `snapshot.state` — the broker snapshot's `state`
+ * (mirrors `BrokerSnapshot.state`), reconstructed here in pi/primitive types so
+ * the SPA never imports the broker-protocol `BrokerSnapshot`. The SPA's
+ * streaming/idle indicator reads `isStreaming` (spec C.10).
+ */
+export interface SessionState {
+    sessionId: string;
+    sessionFile: string | null;
+    model: string | null;
+    isStreaming: boolean;
+    thinkingLevel: ThinkingLevel;
+    steeringMode: 'all' | 'one-at-a-time';
+    followUpMode: 'all' | 'one-at-a-time';
+    sessionName: string | null;
+    autoCompactionEnabled: boolean;
+    pendingMessageCount: number;
+}
+/** Web role of one browser tab's session connection. */
+export type WebRole = 'observer' | 'controller';
+/** Upstream broker connectivity, surfaced to the tab (spec §6.2). */
+export type BrokerStatus = 'connected' | 'reconnecting' | 'down' | 'revived';
+/** Response payload to an extension dialog (`RpcExtensionUIResponse` minus id/type). */
+export type DialogResponseValue = {
+    value: string;
+} | {
+    confirmed: boolean;
+} | {
+    cancelled: true;
+};
+/**
+ * A typed content block within a view tab. Discriminated union of three
+ * block kinds: inline/sourced markdown, a KPI grid, and a bar-list chart.
+ */
+export type ViewBlock = {
+    kind: 'markdown';
+    source: {
+        node_id: string;
+        path: string;
+    } | {
+        inline: string;
+    };
+} | {
+    kind: 'kpis';
+    items: {
+        label: string;
+        value: string;
+        unit?: string;
+        sub?: string;
+    }[];
+} | {
+    kind: 'barlist';
+    title: string;
+    rows: {
+        label: string;
+        value: number;
+        max?: number;
+        note?: string;
+    }[];
+};

package/dist/clients/web/web-client/shared/protocol.js

@@ -0,0 +1,8 @@
+/**
+ * Shared wire types for the crouter web client/server split.
+ *
+ * The SPA imports the pi payload types it needs from this module — never from
+ * broker-protocol internals. The type-only re-exports below keep the web
+ * package's shared payload shapes in one place.
+ */
+export {};