@superblocksteam/gateway 2.0.161 → 2.0.162-next.1

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@superblocksteam/gateway",
-  "version": "2.0.161",
+  "version": "2.0.162-next.1",
   "description": "Gateway v0 — MCP entry for app start/edit/publish",
   "license": "Superblocks Community Software License",
   "bin": {
     "superblocks-gateway": "./dist/main.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "type": "module",
   "main": "dist/index.js",
@@ -16,16 +17,23 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
-    }
+    },
+    "./package.json": "./package.json",
+    "./skills/superblocks-import/SKILL.md": "./skills/superblocks-import/SKILL.md"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@opentelemetry/api": "^1.9.1",
-    "@superblocksteam/library-shared": "2.0.161",
-    "@superblocksteam/mcp-server": "2.0.161",
-    "@superblocksteam/shared": "0.9611.2",
-    "@superblocksteam/telemetry": "2.0.161",
+    "@superblocksteam/library-shared": "2.0.162-next.1",
+    "@superblocksteam/mcp-server": "2.0.162-next.1",
+    "@superblocksteam/shared": "0.9613.1",
+    "@superblocksteam/telemetry": "2.0.162-next.1",
+    "fflate": "^0.8.3",
+    "libpg-query": "^17.7.4",
+    "mdast-util-from-markdown": "2.0.2",
+    "mdast-util-gfm-autolink-literal": "2.0.1",
+    "micromark-extension-gfm-autolink-literal": "2.1.0",
     "playwright": "1.56.0",
     "ws": "8.21.0",
     "zod": "^4.3.6"
@@ -33,6 +41,7 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/express": "^4.17.21",
+    "@types/mdast": "4.0.4",
     "@types/node": "^24",
     "@types/ws": "^8.18.1",
     "eslint": "^9.39.2",

package/skills/superblocks-build/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: superblocks-build
+description: >
+  Use when the user asks to build, create, change, update, edit, or modify an
+  app, dashboard, internal tool, admin panel, form, or CRUD UI - including one
+  they might otherwise make as a local file or artifact. Most requests never
+  say which location they mean. An existing or named app is still ambiguous
+  unless this conversation already established its location. Ask where it
+  should live before creating or editing anything and before using any tool;
+  do not list apps to infer the answer.
+---
+
+# Where does this app get built?
+
+Two places can build what the user just asked for:
+
+- **Superblocks** — a real application. Org datasources, server-side APIs,
+  platform auth and permissions, a deploy story, other people can use it.
+- **Here** — a local file or artifact in this chat. Fast and private, but it
+  reaches no company data and nobody else can run it.
+
+Most requests name neither. Choosing silently is wrong about half the time, and
+the user only finds out once the work already exists in the wrong place.
+
+## Ask first
+
+Before creating or editing anything, ask one short question naming both options,
+then wait for the answer:
+
+> Do you want this built in Superblocks, or as a local artifact here?
+
+If the location is ambiguous, your first action must be the two-option question
+above. Do not call any Superblocks tool, including `list_applications`, or
+create or edit a local artifact until the user answers.
+
+Ask once per request. Do not build a local version "to show them" while waiting.
+Building it is the choice.
+
+## Do not ask when they already answered
+
+- Said Superblocks, or explicitly named a Superblocks app already established in
+  this conversation -> build there.
+- Said local, artifact, file, HTML, "just show me", "quick mockup" -> build here.
+- Answered this question for this same request -> honor it, stay silent.
+- Not an app at all (a script, a chart, an analysis, a document, a snippet)
+  -> just do the work.
+
+## Editing counts too
+
+The same question applies to changing an app, dashboard, or artifact the user
+names, including one already imported into Superblocks. When you cannot tell
+which copy they mean, ask that instead.
+
+## Once they pick Superblocks
+
+- Something new -> `start_app`.
+- Existing source to port -> use the `superblocks-import` skill.
+- An app already in Superblocks -> `list_applications` to find it, then
+  `edit_app`.

package/skills/superblocks-import/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: superblocks-import
+description: >
+  Import, migrate, or port an existing app (React, Replit, Lovable, v0, Streamlit,
+  a zip on disk, or files in the conversation) into Superblocks. Use when the
+  user has existing source and wants it as a Superblocks application — not when
+  they are only editing an app that already exists in Superblocks.
+---
+
+# Superblocks import (host director)
+
+You plan and slice. **Superblocks writes** the application through Builder MCP
+(`start_app` / `edit_app`). Do not invent Superblocks `client/` or `server/`
+files on the laptop. Superblocks already has its own in-sandbox migration
+skillset; your job is to ask for the right slices.
+
+## Choose the source path
+
+Check source files and archives for secrets and production data before uploading.
+Keep placeholder configuration such as `.env.example`, not real credentials.
+
+When source files are already visible in this conversation, call
+`upload_artifact` with `files: [{ path, content }]`. Keep their original
+relative paths; do not write or zip them first. Pass the returned `artifact` to
+`start_app` in `artifacts` and ask Superblocks to migrate the attached source.
+
+When the source is a readable tree on disk, inventory it locally, then
+archive the source and assets with their original relative paths. Exclude
+`.git`, `node_modules`, build output, secrets, and production data; inspect
+the archive before uploading it. Call `upload_artifact` with the archive's
+`filePath` and pass its returned `artifact` unchanged in `start_app.artifacts`.
+Local paths and prose descriptions are not a substitute for the source artifact:
+Superblocks cannot read the host's workspace. Ask Superblocks to read the
+attached source and preserve its UI and behavior, not recreate it from prose.
+
+For an existing source archive, call `upload_artifact` with
+`filePath` (never `zipBase64`), then pass its `artifact` to `start_app` in
+`artifacts`. Archives over 50 MB are rejected; request a smaller source export
+without dependencies or build output rather than silently omitting source.
+If the gateway cannot read the host path, use `files` for text within the
+tool's limits. For binary assets, ask for an accessible export; never encode
+them as text or silently leave them out.
+
+Keep the returned artifact and application IDs. To resume, reuse the same
+artifact ID with `edit_app` and the same application ID. Do not upload the
+source again, and do not call `start_app` again.
+
+Replit / Lovable / v0: clone or export onto this machine first. Do not ask
+the live-edit environment to fetch those clouds.
+
+## Slice order
+
+1. Inventory locally (routes, env keys, ORMs, `fetch`/`axios`, tests). Keep
+   the source app running if you can. Map secrets from `.env.example` — never
+   paste production `.env` into `edit_app`.
+2. `list_integrations`. Reuse an existing datasource (`find_apps_by_integration`)
+   before `create_integration`.
+3. `start_app` with the user's import request, named integrations, and the
+   uploaded source in `artifacts`. Ask Superblocks to read and migrate that
+   source, preserving its UI and behavior.
+   `start_app` defaults to Plan mode. Pass `mode: "BUILD"` only if the user
+   asks for build mode explicitly (e.g. "use build mode" or "skip the plan").
+   Otherwise, follow the returned `agentInstructions` to present the first
+   plan and collect the user's decision. When `decision.plan` is returned,
+   show it in full, verbatim as Markdown in chat, not inside a form. For this
+   plan decision, use the native form only for `Approve` / `Refine` when
+   instructed, or use the instructed fallback, then wait for their answer.
+   Only if they approve, call `edit_app` with `planAction: "approve"` instead
+   of planning it again. Do not run a second “migrate everything” plan.
+   Mode is per call and never sticks: every `edit_app` below plans unless it
+   passes `mode: "BUILD"`, so send it on each slice.
+4. One backend operation per `edit_app`, then `check_app_progress` while the
+   slice is building, handling any requested decision. For interrupted or
+   unknown turns and errors, follow returned `agentInstructions` and
+   `pendingAction`, including stop or user continuation requirements; missing
+   `recentRuns` alone is not permission to restart. Check the completed slice's
+   runtime outcome in `recentRuns` or Superblocks' report. Only for a completed
+   slice, if verification is missing or failed, send a focused `edit_app` to
+   test or fix the same API, not more polling of a finished turn. Advance only
+   when the API passed or testing was explicitly skipped with a reason
+   reported as unverified. There is no MCP SQL tool.
+5. One UI route per `edit_app`, wired to APIs whose verification was resolved
+   above.
+6. Auth, jobs, leftovers last.
+7. After each slice, `get_application_structure` (and `get_app` URLs). Ground
+   the next prompt in what Superblocks actually wrote. `list_knowledge` /
+   `get_knowledge` for org playbooks.
+
+`list_applications` if `start_app` errors: the app may already exist.
+
+Follow `browserNavigation` by opening its exact URL when returned, and
+`agentInstructions` for editor-only decisions. Do not open an app preview
+before `viewStatus` is ready.
+
+## Primitive map (not Next.js)
+
+- Backend operations are **named APIs** in a registry, not URL routes.
+- Each UI page is a Superblocks page using `useApi` / `useApiData` /
+  `executeApi` from the fullstack template — not Next App Router, not the
+  source app’s QueryClient.
+- Datasources are **org integrations** (UUIDs). Credentials live there, not
+  `process.env` in generated code. Auth is platform user context; drop the
+  source login stack unless Superblocks asks otherwise.
+
+## `edit_app` prompt shape
+
+Ask Superblocks to implement **this slice** as fullstack (APIs vs pages vs
+integrations). Tell it to follow its third-party migration skillset. Reuse the
+uploaded artifact in `edit_app.artifacts` and cite its relative source paths;
+small excerpts can clarify a change but do not replace the attached source.
+
+For every backend slice, include this in the `edit_app` prompt:
+
+> After implementing this API, run `testApi` with representative inputs and
+> verify the expected result, then report the API name, passed/failed/skipped,
+> and the concrete outcome before finishing this slice. For mutating tests,
+> honor the tool's permission checks; if denied or the user explicitly asks
+> to skip testing, report skipped with the reason. Do not claim untested APIs
+> passed.
+
+## Do not
+
+- `browser_evaluate` JWTs; `browser_close` / Playwright `--isolated` between
+  IdP and retry.
+- Dump `.env` or production data into prompts.

package/dist/capabilities/import-prompt.d.ts

@@ -1,11 +0,0 @@
-import type { ImportAppSource } from "./types.js";
-/**
- * Archive names land in instruction-bearing prompt text. Keep a single-line
- * basename so a crafted zip path cannot inject newlines or role-play into Clark.
- */
-export declare function sanitizeArchiveDisplayName(zipFileName: string): string;
-export declare function buildImportPrompt(input: {
-    extraPrompt?: string;
-    source: ImportAppSource;
-    zipFileName: string;
-}): string;

package/dist/capabilities/import-prompt.js

@@ -1,96 +0,0 @@
-/**
- * Migration prompts mirror the browser MigrationModal templates so Clark loads
- * the same skills and inspects the attached archive the same way.
- */
-/**
- * The browser migration flow leans on the `third-party-migration` skill, which
- * ends by deferring verification to "the user running the app" — and is dropped
- * entirely unless the org has `ui.third-party-import.enabled`. Neither holds
- * here: no one is clicking through a headless migration, and the gateway hands
- * Clark the org's integrations plus a live `testApi` on every turn. Say so in
- * the prompt rather than hoping a skill is loaded.
- */
-const API_VERIFICATION_INSTRUCTION = `Nobody is watching this migration in a browser, so you verify your own work. This turn's context lists the org's integrations — use them for the data sources you find in the project. Run every API you create or change through testApi before you report the migration finished, and say what testApi returned, failures included. Do not defer API verification to the user, and do not treat testApi as unavailable during a migration.`;
-function withMigrationSkillInstruction(prompt) {
-    return `Please follow the migration guidelines as detailed in your skillset.
-
-${prompt}`;
-}
-/**
- * Archive names land in instruction-bearing prompt text. Keep a single-line
- * basename so a crafted zip path cannot inject newlines or role-play into Clark.
- */
-export function sanitizeArchiveDisplayName(zipFileName) {
-    const base = zipFileName.replace(/\\/g, "/").split("/").pop() ?? "archive.zip";
-    let cleaned = "";
-    for (const ch of base) {
-        const code = ch.codePointAt(0) ?? 0;
-        // Drop C0 controls and DEL so a crafted basename cannot inject newlines
-        // into instruction-bearing prompt text.
-        if (code >= 32 && code !== 127) {
-            cleaned += ch;
-        }
-    }
-    cleaned = cleaned.trim();
-    return cleaned.length > 0 ? cleaned : "archive.zip";
-}
-function genericImportPrompt(zipFileName) {
-    return withMigrationSkillInstruction(`Import this codebase into Superblocks. The project is attached as ${zipFileName}. Inspect the structure, identify the framework and data sources, then migrate it into the current Superblocks fullstack app.`);
-}
-const SOURCE_PROMPTS = {
-    chatgpt: genericImportPrompt,
-    claude: genericImportPrompt,
-    "claude-design": (zipFileName) => withMigrationSkillInstruction(`Migrate this Claude Design app into Superblocks. The exported project is attached as ${zipFileName}.`),
-    lovable: (zipFileName) => withMigrationSkillInstruction(`Migrate this Lovable app into Superblocks. The exported project is attached as ${zipFileName}.`),
-    replit: (zipFileName) => withMigrationSkillInstruction(`Migrate this Replit app into Superblocks. The exported project is attached as ${zipFileName}.`),
-    streamlit: genericImportPrompt,
-    v0: (zipFileName) => withMigrationSkillInstruction(`Migrate this v0 app into Superblocks. The exported project is attached as ${zipFileName}.`),
-    zip: genericImportPrompt,
-};
-/**
- * Builds the Clark prompt for an import turn. Optional `extraPrompt` is the
- * caller's intent (e.g. "make it more secure"), appended after the template.
- */
-function promptForSource(source, zipFileName) {
-    // Exhaustive switch with direct calls — no dynamic property lookup — so
-    // CodeQL cannot treat `source` as an unvalidated method name.
-    switch (source) {
-        case "chatgpt":
-            return SOURCE_PROMPTS.chatgpt(zipFileName);
-        case "claude":
-            return SOURCE_PROMPTS.claude(zipFileName);
-        case "claude-design":
-            return SOURCE_PROMPTS["claude-design"](zipFileName);
-        case "lovable":
-            return SOURCE_PROMPTS.lovable(zipFileName);
-        case "replit":
-            return SOURCE_PROMPTS.replit(zipFileName);
-        case "streamlit":
-            return SOURCE_PROMPTS.streamlit(zipFileName);
-        case "v0":
-            return SOURCE_PROMPTS.v0(zipFileName);
-        case "zip":
-            return SOURCE_PROMPTS.zip(zipFileName);
-        default: {
-            const _exhaustive = source;
-            throw new Error(`unsupported import source: ${String(_exhaustive)}`);
-        }
-    }
-}
-export function buildImportPrompt(input) {
-    const zipFileName = sanitizeArchiveDisplayName(input.zipFileName);
-    const base = promptForSource(input.source, zipFileName);
-    const extra = input.extraPrompt?.trim();
-    // Verification goes last: a caller asking to "just get it running" should not
-    // end up with a migration that reports untested APIs.
-    const intent = extra
-        ? `${base}
-
-Additional instructions from the user:
-${extra}`
-        : base;
-    return `${intent}
-
-${API_VERIFICATION_INSTRUCTION}`;
-}
-//# sourceMappingURL=import-prompt.js.map

package/dist/capabilities/import-prompt.js.map

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

package/dist/capabilities/persisted-progress.d.ts

@@ -1,46 +0,0 @@
-import type { EventSnapshot } from "../events/types.js";
-import type { BuildStatus, GenerationStatus } from "./types.js";
-export type PersistedProgress = {
-    /** Superblocks' own words since this caller last read, oldest first. */
-    activity: string[];
-    /** Set when the build is stuck waiting for an interactive authorization. */
-    authRequiredReason?: string;
-    /** Present once the persisted stream shows the turn reached a terminal state. */
-    generationStatus?: GenerationStatus;
-    /** Newest assistant message, so a resumed caller can report the outcome. */
-    reply?: string;
-    status: BuildStatus;
-};
-/**
- * Reads a build's state out of what was persisted, for a caller that has no
- * live turn to ask.
- *
- * The two halves of a snapshot answer different questions and are used
- * differently. Activity comes from the window after the caller's cursor,
- * because that is what is new *to this caller*. State comes from the tail of
- * the stream regardless of the cursor, because a caller that already consumed
- * the terminal event still needs to be told the build finished — reading
- * state from the after-cursor window would tell it nothing is known and send
- * it back to poll a turn that ended.
- */
-export declare function readPersistedProgress(snapshot: Pick<EventSnapshot, "events" | "tail">, liveness: StreamLiveness, 
-/**
- * The quiet window a `completed` must outlast, which has to be the same one
- * the live turn settled with (`config.clarkSettleMs`). Defaults to the
- * collector's constant so a caller with no config in hand still reads the
- * stream the way an untuned gateway wrote it.
- */
-settleMs?: number): PersistedProgress;
-/**
- * How to judge whether what the stream last said is still true.
- *
- * Required rather than optional so no caller can read a status the rule was
- * never applied to: the whole point of reading state here is that `get_app` and
- * `check_app_progress` stop contradicting each other about one app, and an
- * omitted rule is how they would drift apart again (ENG-5808).
- */
-export type StreamLiveness = {
-    nowMs: number;
-    /** How long the work can be silent before the stream stops meaning it. */
-    staleAfterMs: number;
-};

package/dist/capabilities/persisted-progress.js

@@ -1,246 +0,0 @@
-import { DEFAULT_SETTLE_MS } from "../sabs/turn-collector.js";
-import { buildStatusOf } from "./types.js";
-/**
- * Reads a build's state out of what was persisted, for a caller that has no
- * live turn to ask.
- *
- * The two halves of a snapshot answer different questions and are used
- * differently. Activity comes from the window after the caller's cursor,
- * because that is what is new *to this caller*. State comes from the tail of
- * the stream regardless of the cursor, because a caller that already consumed
- * the terminal event still needs to be told the build finished — reading
- * state from the after-cursor window would tell it nothing is known and send
- * it back to poll a turn that ended.
- */
-export function readPersistedProgress(snapshot, liveness, 
-/**
- * The quiet window a `completed` must outlast, which has to be the same one
- * the live turn settled with (`config.clarkSettleMs`). Defaults to the
- * collector's constant so a caller with no config in hand still reads the
- * stream the way an untuned gateway wrote it.
- */
-settleMs = DEFAULT_SETTLE_MS) {
-    const activity = [];
-    for (const event of snapshot.events) {
-        const line = activityLine(event);
-        // The collector drops a repeated progress line for the same reason: a
-        // build that says "Installing dependencies" twice in a row has not told
-        // the reader anything the second time.
-        if (line && line !== activity[activity.length - 1]) {
-            activity.push(line);
-        }
-    }
-    let authRequiredReason;
-    let generationStatus;
-    let reply;
-    let status = snapshot.tail.length > 0 ? "building" : "unknown";
-    // When the turn last reported it was done, and when its session went away.
-    // Whether the first of those had settled before the second decides which of
-    // them is the outcome.
-    let completedAtMs;
-    let teardownAtMs;
-    for (const event of snapshot.tail) {
-        if (event.payload.kind === "auth_required") {
-            authRequiredReason = event.payload.reason ?? "auth_required";
-            continue;
-        }
-        if (event.payload.kind === "chat_message" &&
-            event.payload.role === "assistant") {
-            reply = event.payload.text;
-            continue;
-        }
-        if (event.payload.kind === "session") {
-            // SABS tearing the live edit down settles a turn that never settled
-            // itself: the dev server exits silently when it loses its lock, so no
-            // terminal generation_state is coming and a caller reading from the
-            // stream would otherwise be told "building" forever.
-            //
-            // Not every teardown is that, though. Every healthy build ends with its
-            // session going away too, and reading that as a dead live edit would
-            // report each finished app as a failure. Which one this is comes down to
-            // whether the turn had really finished first - see `teardownEndsTurn`.
-            if (event.payload.status !== "terminated") {
-                continue;
-            }
-            teardownAtMs = event.occurredAtMs;
-            if (!teardownEndsTurn(generationStatus, completedAtMs, teardownAtMs, settleMs)) {
-                continue;
-            }
-            generationStatus = "live_edit_terminated";
-            status = buildStatusOf(generationStatus);
-            continue;
-        }
-        if (event.payload.kind !== "generation_state") {
-            continue;
-        }
-        // Later states supersede earlier ones: a build that went back to
-        // generating after an idle blip is generating.
-        //
-        // A torn-down live edit is the exception. The dev server cannot report
-        // progress after SABS has killed it, so a non-terminal state stamped
-        // later than the teardown is skew between two producers merged by
-        // `occurredAtMs`, not news that the turn revived. Letting it through
-        // would put the caller back to polling the dead session this status
-        // exists to name. Only another terminal state outranks the teardown.
-        const state = terminalStatus(event.payload.state);
-        if (!state && generationStatus === "live_edit_terminated") {
-            continue;
-        }
-        // A `completed` the teardown already cut short does not come back to life
-        // by being listed second. The two producers stamp their own clocks, so the
-        // tail can carry the pair either way round; the same pair of facts has to
-        // reach the same outcome both times.
-        if (state === "completed" &&
-            generationStatus === "live_edit_terminated" &&
-            teardownAtMs !== undefined &&
-            !outlastedSettleWindow(event.occurredAtMs, teardownAtMs, settleMs)) {
-            continue;
-        }
-        completedAtMs = state === "completed" ? event.occurredAtMs : undefined;
-        generationStatus = state;
-        status = state ? buildStatusOf(state) : "building";
-    }
-    // Applied after the tail, not before it: the loop above assigns `building` for
-    // every non-terminal generation state it sees, so a rule that only set the
-    // initial value would be overwritten by the very events it exists to judge.
-    //
-    // Only a non-terminal reading expires. How a turn ended is a fact - a
-    // completed turn stays completed and a torn-down live edit stays torn down -
-    // and an old terminal state is the answer a caller needs, not a stale one.
-    if (!generationStatus && !reportsLiveWork(snapshot.tail, liveness)) {
-        status = "unknown";
-    }
-    return {
-        activity,
-        ...(authRequiredReason ? { authRequiredReason } : {}),
-        ...(generationStatus ? { generationStatus } : {}),
-        ...(reply ? { reply } : {}),
-        status,
-    };
-}
-/**
- * Whether a `completed` had closed its quiet window before the teardown
- * landed.
- *
- * `completed` is provisional until it settles: the gateway checkpoints Clark's
- * files only once the window closes, and that checkpoint runs over the socket
- * to the dev server. A teardown inside the window therefore means no
- * checkpoint could have landed - the same conclusion the live path draws from
- * the same pair of facts, so a caller holding the turn and a caller reading
- * the stream cannot answer differently. The gateway holds the socket for a
- * release grace that outlasts this window, so a healthy build's teardown is
- * never mistaken for one.
- *
- * Distance, not order: the two producers stamp their own clocks.
- */
-function outlastedSettleWindow(completedAtMs, teardownAtMs, settleMs) {
-    return Math.abs(teardownAtMs - completedAtMs) >= settleMs;
-}
-/**
- * Whether a teardown is this turn's outcome rather than the tail of one that
- * had already finished.
- *
- * Nothing terminal read yet means the dev server never reported an end and
- * never will. `cancelled` and `needs_decision` settle the moment they arrive,
- * so a later teardown leaves them standing. Only `completed` has a window it
- * can be cut short inside.
- */
-function teardownEndsTurn(generationStatus, completedAtMs, teardownAtMs, settleMs) {
-    if (!generationStatus) {
-        return true;
-    }
-    if (generationStatus !== "completed" || completedAtMs === undefined) {
-        return false;
-    }
-    return !outlastedSettleWindow(completedAtMs, teardownAtMs, settleMs);
-}
-/**
- * How a persisted generation state reads as a finished turn, or undefined
- * while the build is still going.
- *
- * `idle` counts as finished for the same reason the live collector treats it
- * that way: it is what Superblocks reports when it has stopped working and is
- * not waiting for anything.
- */
-function terminalStatus(state) {
-    switch (state) {
-        case "awaiting_user_input":
-            return "needs_decision";
-        case "cancelled":
-            return "cancelled";
-        case "completed":
-        case "idle":
-            return "completed";
-        default:
-            return undefined;
-    }
-}
-/**
- * Whether the tail is evidence of a build that is still going, short of any
- * terminal state.
- *
- * Two things disqualify it. The caller's own prompt coming back is not a report
- * of work - which events a producer emits is settled in another package and, for
- * SABS, another repository, so this asks to be shown the work rather than
- * trusting that a user message is never left in a stream on its own. And the
- * tail is bounded, so a turn's terminal event can age out of it and leave a
- * finished build looking like a running one forever; work that has been silent
- * for longer than a turn can last has ended, whatever the stream still holds.
- *
- * Both halves read the same events on purpose. Judging the age by anything the
- * stream carried, the prompt included, let a new prompt hold the clock open over
- * work that had stopped talking a whole turn budget earlier.
- *
- * TODO(ENG-5896): `occurredAtMs` is stamped by the producer, so the age below is
- * arithmetic across two machines' clocks. A stamp from the future is read as
- * fresh here rather than stale, which covers a producer running ahead; a
- * producer running far enough behind still reads as silent. Closing that needs a
- * gateway-side receive timestamp at ingress.
- */
-function reportsLiveWork(tail, liveness) {
-    let newestAtMs;
-    for (const event of tail) {
-        if (reportsWork(event)) {
-            newestAtMs = Math.max(newestAtMs ?? 0, event.occurredAtMs);
-        }
-    }
-    if (newestAtMs === undefined) {
-        return false;
-    }
-    const ageMs = liveness.nowMs - newestAtMs;
-    if (ageMs < 0) {
-        // Not silence: the producer's clock is ahead of ours. Calling that stale
-        // would be reading a clock difference as the end of a build.
-        console.warn("gateway persisted stream is stamped in the future", {
-            newestAtMs,
-            nowMs: liveness.nowMs,
-            skewMs: -ageMs,
-        });
-        return true;
-    }
-    return ageMs <= liveness.staleAfterMs;
-}
-/**
- * Whether an event says something about the work, as opposed to being the
- * caller's own prompt coming back. Anything Superblocks or SABS reports counts -
- * a generation state, a progress line, a reply, an auth prompt, the session
- * itself - so this excludes only the one event a caller produces.
- */
-function reportsWork(event) {
-    return !(event.payload.kind === "chat_message" && event.payload.role === "user");
-}
-function activityLine(event) {
-    switch (event.payload.kind) {
-        case "chat_message":
-            // A user message is the prompt coming back; relaying it would have the
-            // caller read its own words out as if they were news.
-            return event.payload.role === "assistant"
-                ? event.payload.text
-                : undefined;
-        case "progress":
-            return event.payload.label;
-        default:
-            return undefined;
-    }
-}
-//# sourceMappingURL=persisted-progress.js.map

package/dist/capabilities/persisted-progress.js.map

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