pilotswarm-sdk 0.5.39 → 0.5.40

package/dist/session-proxy.js

@@ -1298,6 +1298,42 @@ artifactStore) {
                         return latest;
                     }
                     let canvasDrawChain = Promise.resolve();
+                    // Per-slot tick throttle (the plane makes ticks cheap; a runaway
+                    // loop must not flood viewers). Execution-scoped, like the chain.
+                    // Keys are `${targetSessionId}:${slot}` — a child ticking its own
+                    // canvas and its parent's dashboard are separate budgets.
+                    const canvasTickClock = new Map();
+                    const CANVAS_TICK_MIN_INTERVAL_MS = 100;
+                    /**
+                     * Cross-session canvas targeting: ANCESTORS ONLY. A sub-agent may
+                     * draw on its parent's (or grandparent's, or the root's) surface —
+                     * never a sibling's, a child's, or a stranger's. Worker-trusted,
+                     * the same stance as fromArtifact; the walk is the catalog's parent
+                     * chain, capped at the spawn-nesting depth.
+                     */
+                    const resolveCanvasTarget = async (requested) => {
+                        const requestedId = String(requested ?? "").trim();
+                        if (!requestedId || requestedId === input.sessionId) {
+                            return { target: input.sessionId, crossSession: false };
+                        }
+                        let cursor = input.sessionId;
+                        for (let depth = 0; depth < 8 && cursor; depth++) {
+                            let row;
+                            try {
+                                row = await catalog?.getSession?.(cursor);
+                            }
+                            catch (err) {
+                                return { error: `could not verify the session lineage: ${err?.message || String(err)}` };
+                            }
+                            const parent = row?.parentSessionId ?? null;
+                            if (!parent)
+                                break;
+                            if (parent === requestedId)
+                                return { target: requestedId, crossSession: true };
+                            cursor = parent;
+                        }
+                        return { error: `session_id ${requestedId} is not an ancestor of this session — canvas tools may target only your parent chain (parent, grandparent, root)` };
+                    };
                     const controlToolBridge = {
                         /**
                          * Send a message to a session AS ITS USER.
@@ -2078,8 +2114,11 @@ artifactStore) {
                                 if (rawName !== undefined && rawName.length > 60) {
                                     return { error: "name must be 60 characters or fewer" };
                                 }
+                                const resolved = await resolveCanvasTarget(args.session_id);
+                                if ("error" in resolved)
+                                    return { error: resolved.error };
+                                const { target, crossSession } = resolved;
                                 const run = canvasDrawChain.then(async () => {
-                                    const rev = (await latestCanvasRev(catalog, input.sessionId, slot)) + 1;
                                     // Source resolution. fromArtifact pulls bytes store-side —
                                     // the same trust stance as read_artifact/write_artifact's
                                     // cross-session paths (the artifact layer is worker-trusted);
@@ -2143,7 +2182,22 @@ artifactStore) {
                                     }
                                     const app = canvasAppCard(extraction.manifest);
                                     const note = args.note ? String(args.note) : undefined;
-                                    await artifactStore.uploadArtifact(input.sessionId, canvasArtifactFilename(slot), html, "text/html", 
+                                    // Atomic rev mint (multi-writer safe), AFTER every
+                                    // validation refusal above: the mint writes latest_rev
+                                    // into the 0045 cache, and a rev minted for a draw
+                                    // that then failed validation would unlock ticks on an
+                                    // empty slot (latestCanvasRev is table-first). The
+                                    // seed from the table/event read floors legacy
+                                    // sessions whose cache row never landed. Residual
+                                    // window: an upload/record failure AFTER the mint
+                                    // burns a phantom rev — infra-failure only, and the
+                                    // next successful draw overwrites it; read_canvas
+                                    // stays honest because it is log-first.
+                                    const seedRev = await latestCanvasRev(catalog, target, slot);
+                                    const rev = typeof catalog.mintCanvasRev === "function"
+                                        ? await catalog.mintCanvasRev(target, slot, seedRev)
+                                        : seedRev + 1;
+                                    await artifactStore.uploadArtifact(target, canvasArtifactFilename(slot), html, "text/html", 
                                     // Pinned on EVERY draw, not just the first: uploads
                                     // replace artifact metadata wholesale, so a pin set
                                     // once at rev 1 was silently erased by rev 2.
@@ -2154,7 +2208,7 @@ artifactStore) {
                                     // The response contract rides the event so every
                                     // client learns it exactly where it learns the rev —
                                     // live push and cold snapshot alike, no extra fetch.
-                                    await catalog.recordEvents(input.sessionId, [{
+                                    await catalog.recordEvents(target, [{
                                             eventType: "session.canvas_updated",
                                             data: {
                                                 rev,
@@ -2164,6 +2218,10 @@ artifactStore) {
                                                 ...(note ? { note } : {}),
                                                 ...(effectiveContract ? { responseContract: effectiveContract } : {}),
                                                 ...(source ? { source } : {}),
+                                                // Attribution: who actually drew this revision.
+                                                // Only present on cross-session draws, so the
+                                                // portal can badge "drawn by sub-agent X".
+                                                ...(crossSession ? { by: input.sessionId } : {}),
                                             },
                                         }], workerNodeId);
                                     // The per-slot cache (migration 0045). Non-fatal on
@@ -2172,9 +2230,21 @@ artifactStore) {
                                     // missing — failing the draw over a cache write would
                                     // invert the dependency.
                                     try {
-                                        await catalog.upsertSessionCanvas?.(input.sessionId, slot, rawName ?? null, rev, sizeBytes);
+                                        await catalog.upsertSessionCanvas?.(target, slot, rawName ?? null, rev, sizeBytes);
                                     }
                                     catch { /* self-heals on the next draw */ }
+                                    // The data plane (migration 0047): doc pointer for
+                                    // live viewers + RESET of the data mirror — the new
+                                    // page starts from its own initial state, never the
+                                    // old page's stale ticks. Non-fatal: the plane is the
+                                    // acceleration path, the event above is the truth.
+                                    try {
+                                        if (await catalog.canvasLiveAvailable?.()) {
+                                            const sha = createHash("sha256").update(html, "utf8").digest("hex");
+                                            await catalog.upsertCanvasLiveDoc?.(target, slot, { rev, sha }, input.sessionId);
+                                        }
+                                    }
+                                    catch { /* live viewers resync from events */ }
                                     return {
                                         rev,
                                         slot,
@@ -2195,25 +2265,87 @@ artifactStore) {
                                 const slot = normalizeCanvasSlot(args.slot);
                                 if (slot === null)
                                     return { error: "slot must be an integer 1-5" };
+                                const resolved = await resolveCanvasTarget(args.session_id);
+                                if ("error" in resolved)
+                                    return { error: resolved.error };
+                                const { target, crossSession } = resolved;
+                                const isPatch = args.patch !== undefined;
+                                const body = isPatch ? args.patch : args.data;
+                                // Rate limit at the source: the plane makes ticks cheap
+                                // enough that a runaway loop could flood viewers. Applies
+                                // per (target, slot) within this execution.
+                                const now = Date.now();
+                                const tickKey = `${target}:${slot}`;
+                                const lastTick = canvasTickClock.get(tickKey) || 0;
+                                if (now - lastTick < CANVAS_TICK_MIN_INTERVAL_MS) {
+                                    return { error: `ticking slot ${slot} faster than ${CANVAS_TICK_MIN_INTERVAL_MS} ms apart — aggregate your changes into fewer, larger ticks` };
+                                }
+                                canvasTickClock.set(tickKey, now);
                                 const run = canvasDrawChain.then(async () => {
-                                    if ((await latestCanvasRev(catalog, input.sessionId, slot)) === 0) {
+                                    if ((await latestCanvasRev(catalog, target, slot)) === 0) {
                                         return { error: `no canvas has been drawn in slot ${slot} — draw_canvas first; ticks patch an existing page` };
                                     }
-                                    const dataRev = (await latestCanvasDataRev(catalog, input.sessionId, slot)) + 1;
-                                    const sizeBytes = Buffer.byteLength(JSON.stringify(args.data), "utf8");
-                                    // The payload rides the durable event — it IS the
-                                    // replay source for cold loads; no artifact write.
-                                    await catalog.recordEvents(input.sessionId, [{
-                                            eventType: "session.canvas_data",
-                                            data: {
-                                                dataRev,
-                                                slot,
-                                                sizeBytes,
-                                                payload: args.data,
-                                                ...(args.note ? { note: String(args.note) } : {}),
-                                            },
-                                        }], workerNodeId);
-                                    return { dataRev, slot, sizeBytes };
+                                    const planeAvailable = await catalog.canvasLiveAvailable?.().catch(() => false);
+                                    // The plane is where merges live. Without it (older
+                                    // deployment), a patch has no current state to merge
+                                    // against — refuse with the actionable alternative
+                                    // instead of guessing.
+                                    if (isPatch && !planeAvailable) {
+                                        return { error: "this deployment predates the canvas data plane — send data (the whole state) instead of patch" };
+                                    }
+                                    // Whole state after this write, whoever computes it:
+                                    // the plane merges patches server-side; a plain PUT is
+                                    // its own whole state.
+                                    let mergedPayload = (body ?? {});
+                                    let planeSeq;
+                                    if (planeAvailable) {
+                                        const live = await catalog.upsertCanvasLiveTick(target, slot, isPatch ? { patch: body } : { data: body }, input.sessionId, 32_768);
+                                        if (live?.refused) {
+                                            return {
+                                                error: `the merged canvas state would exceed 32768 bytes`
+                                                    + (live.currentSizeBytes != null ? ` (currently ${live.currentSizeBytes} bytes)` : "")
+                                                    + `. Aggregate the data, remove stale keys (patch with null deletes), or redraw if the shape truly grew.`,
+                                            };
+                                        }
+                                        mergedPayload = live.payload ?? mergedPayload;
+                                        planeSeq = live.seq;
+                                    }
+                                    const sizeBytes = Buffer.byteLength(JSON.stringify(mergedPayload), "utf8");
+                                    // Dual-write phase: the durable event carries the
+                                    // MERGED whole state so pre-plane readers (older
+                                    // portals, cold loads) stay complete. Flipping
+                                    // PILOTSWARM_CANVAS_DURABLE_TICKS=0 ends this — only
+                                    // after every reader in the environment prefers the
+                                    // plane, and the completion checkpoint ships with
+                                    // that flip.
+                                    let dataRev;
+                                    // The flag only silences durable ticks where the
+                                    // plane actually took the write. Plane absent =
+                                    // today's path stays, whatever the flag says —
+                                    // otherwise a PUT would be written NOWHERE and still
+                                    // report success.
+                                    if (!planeAvailable || process.env.PILOTSWARM_CANVAS_DURABLE_TICKS !== "0") {
+                                        dataRev = (await latestCanvasDataRev(catalog, target, slot)) + 1;
+                                        await catalog.recordEvents(target, [{
+                                                eventType: "session.canvas_data",
+                                                data: {
+                                                    dataRev,
+                                                    slot,
+                                                    sizeBytes,
+                                                    payload: mergedPayload,
+                                                    ...(isPatch ? { patched: true } : {}),
+                                                    ...(crossSession ? { by: input.sessionId } : {}),
+                                                    ...(args.note ? { note: String(args.note) } : {}),
+                                                },
+                                            }], workerNodeId);
+                                    }
+                                    return {
+                                        ...(dataRev !== undefined ? { dataRev } : {}),
+                                        ...(planeSeq !== undefined ? { seq: planeSeq } : {}),
+                                        slot,
+                                        sizeBytes,
+                                        mode: isPatch ? "patch" : "data",
+                                    };
                                 }).catch((err) => ({ error: err?.message || String(err) }));
                                 canvasDrawChain = run.then(() => undefined, () => undefined);
                                 return run;
@@ -2228,13 +2360,17 @@ artifactStore) {
                                 const slot = normalizeCanvasSlot(args.slot);
                                 if (slot === null)
                                     return { error: "slot must be an integer 1-5" };
-                                const rev = await latestCanvasRev(catalog, input.sessionId, slot);
+                                const resolved = await resolveCanvasTarget(args.session_id);
+                                if ("error" in resolved)
+                                    return { error: resolved.error };
+                                const { target, crossSession } = resolved;
+                                const rev = await latestCanvasRev(catalog, target, slot);
                                 if (rev === 0) {
                                     return { error: `nothing has been drawn in slot ${slot} — draw_canvas first; show_canvas only presents an existing canvas` };
                                 }
-                                await catalog.recordEvents(input.sessionId, [{
+                                await catalog.recordEvents(target, [{
                                         eventType: "session.canvas_presented",
-                                        data: { slot, rev },
+                                        data: { slot, rev, ...(crossSession ? { by: input.sessionId } : {}) },
                                     }], workerNodeId);
                                 return { presented: true, slot, rev };
                             },
@@ -2246,6 +2382,27 @@ artifactStore) {
                                 const slot = normalizeCanvasSlot(args.slot);
                                 if (slot === null)
                                     return { error: "slot must be an integer 1-5" };
+                                const resolved = await resolveCanvasTarget(args.session_id);
+                                if ("error" in resolved)
+                                    return { error: resolved.error };
+                                const { target } = resolved;
+                                // "What is the page showing right now?" — the plane's
+                                // last-value row, one PK read. Opt-in (the payload can be
+                                // 32 KB of model context) and independent of paging.
+                                const liveState = async () => {
+                                    if (!args.includeData)
+                                        return {};
+                                    try {
+                                        if (!(await catalog.canvasLiveAvailable?.()))
+                                            return {};
+                                        const rows = await catalog.getCanvasLive?.(target);
+                                        const hit = (rows || []).find((r) => Number(r.slot) === slot);
+                                        return hit ? { live: { seq: hit.seq, data: hit.payload, updatedBy: hit.updatedBy, updatedAt: hit.updatedAt } } : {};
+                                    }
+                                    catch {
+                                        return {};
+                                    }
+                                };
                                 try {
                                     // Log FIRST: the event log is the single authority on
                                     // whether a canvas exists. Orphan bytes from a crashed
@@ -2261,10 +2418,10 @@ artifactStore) {
                                         // ARMED contract from the latest draw event — the
                                         // pair an inheriting agent needs to interpret
                                         // canvas-action messages and author ticks.
-                                        const latest = await latestCanvasEventData(catalog, input.sessionId, slot);
+                                        const latest = await latestCanvasEventData(catalog, target, slot);
                                         if (latest.rev === 0)
                                             return { exists: false };
-                                        const docText = await artifactStore.downloadArtifactText(input.sessionId, canvasArtifactFilename(slot));
+                                        const docText = await artifactStore.downloadArtifactText(target, canvasArtifactFilename(slot));
                                         const extraction = extractCanvasAppManifest(docText);
                                         const card = canvasAppCard(extraction.manifest);
                                         // Events are writable via send_session_event with no
@@ -2279,12 +2436,13 @@ artifactStore) {
                                             ...(card ? { app: card } : {}),
                                             ...(armed.contract ? { responseContract: armed.contract } : {}),
                                             ...(extraction.error ? { manifestError: extraction.error } : {}),
+                                            ...(await liveState()),
                                         };
                                     }
-                                    const rev = await latestCanvasRev(catalog, input.sessionId, slot);
+                                    const rev = await latestCanvasRev(catalog, target, slot);
                                     if (rev === 0)
                                         return { exists: false };
-                                    const text = await artifactStore.downloadArtifactText(input.sessionId, canvasArtifactFilename(slot));
+                                    const text = await artifactStore.downloadArtifactText(target, canvasArtifactFilename(slot));
                                     const offset = Math.max(0, Math.floor(Number(args.offset) || 0));
                                     const maxChars = Math.min(262_144, Math.max(1, Math.floor(Number(args.maxBytes) || 65_536)));
                                     const content = text.slice(offset, offset + maxChars);
@@ -2298,6 +2456,7 @@ artifactStore) {
                                         offset,
                                         content,
                                         truncated: offset + content.length < text.length,
+                                        ...(await liveState()),
                                     };
                                 }
                                 catch (err) {