@superblocksteam/gateway 2.0.0-SNAPSHOT.1d4c72c0ab174c21

package/dist/sabs/session-peer.js

@@ -0,0 +1,11 @@
+export class PromptNotSentError extends Error {
+    recoveryAction;
+    retryable;
+    constructor(message, cause, options = {}) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.name = "PromptNotSentError";
+        this.recoveryAction = options.recoveryAction;
+        this.retryable = options.retryable;
+    }
+}
+//# sourceMappingURL=session-peer.js.map

package/dist/sabs/session-peer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-peer.js","sourceRoot":"","sources":["../../src/sabs/session-peer.ts"],"names":[],"mappings":"AAKA,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAClC,cAAc,CAA8B;IAC5C,SAAS,CAAoB;IAEtC,YACE,OAAe,EACf,KAAe,EACf,UAGI,EAAE;QAEN,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QAC7C,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC;IACrC,CAAC;CACF"}

package/dist/sabs/streamed-reply.d.ts

@@ -0,0 +1,42 @@
+export type StreamedReplyOptions = {
+    /** Injected so the chunking windows are testable without real time. */
+    now?: () => number;
+};
+/**
+ * Clark's reply as it streams, turned into lines a person can read.
+ *
+ * Two jobs, both about presentation rather than about the turn: accumulate the
+ * text deltas into the reply the turn will report, and decide when enough of
+ * it has arrived to be worth showing. It holds a partial sentence back so
+ * lines read as sentences, but never for so long that a slow tool call looks
+ * like a hang.
+ */
+export declare class StreamedReply {
+    private readonly onLine;
+    private readonly deltas;
+    private readonly now;
+    private streamedLen;
+    private lastProgressAt;
+    private lastLine;
+    constructor(onLine: (line: string) => void, options?: StreamedReplyOptions);
+    /** The reply so far, whether or not all of it has been shown. */
+    text(): string;
+    /** A `text-delta` push: more of the message Clark is still writing. */
+    appendDelta(delta: string): void;
+    /**
+     * A final assistant message, which replaces the deltas for the same turn.
+     *
+     * When it finalizes text already shown, only the tail is new; when it is a
+     * fresh message, all of it is.
+     */
+    finalize(content: string): void;
+    /** Show whatever is still unreported, e.g. when the turn ends. */
+    flush(): void;
+    /**
+     * Single door for every progress line: blank lines and a line identical to
+     * the one before it are dropped, because the dev server repeats status
+     * pushes many times per build and repetition buries the text that matters.
+     */
+    emit(line: string): void;
+    private maybeEmit;
+}

package/dist/sabs/streamed-reply.js

@@ -0,0 +1,110 @@
+/**
+ * How much unshown text is enough to show on its own, without waiting for a
+ * sentence to finish.
+ */
+const PROGRESS_CHAR_CHUNK = 400;
+/** How long between progress lines before a short one is worth showing. */
+const PROGRESS_MS_CHUNK = 1_500;
+/** How long an unfinished sentence may be held back before it is shown anyway. */
+const PROGRESS_STALE_MS = 4_000;
+/**
+ * Clark's reply as it streams, turned into lines a person can read.
+ *
+ * Two jobs, both about presentation rather than about the turn: accumulate the
+ * text deltas into the reply the turn will report, and decide when enough of
+ * it has arrived to be worth showing. It holds a partial sentence back so
+ * lines read as sentences, but never for so long that a slow tool call looks
+ * like a hang.
+ */
+export class StreamedReply {
+    onLine;
+    deltas = [];
+    now;
+    streamedLen = 0;
+    lastProgressAt = 0;
+    lastLine;
+    constructor(onLine, options = {}) {
+        this.onLine = onLine;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** The reply so far, whether or not all of it has been shown. */
+    text() {
+        return this.deltas.join("");
+    }
+    /** A `text-delta` push: more of the message Clark is still writing. */
+    appendDelta(delta) {
+        this.deltas.push(delta);
+        this.maybeEmit();
+    }
+    /**
+     * A final assistant message, which replaces the deltas for the same turn.
+     *
+     * When it finalizes text already shown, only the tail is new; when it is a
+     * fresh message, all of it is.
+     */
+    finalize(content) {
+        const alreadyStreamed = this.text().slice(0, this.streamedLen);
+        this.deltas.length = 0;
+        this.deltas.push(content);
+        if (!alreadyStreamed || !content.startsWith(alreadyStreamed)) {
+            this.streamedLen = 0;
+        }
+        this.flush();
+    }
+    /** Show whatever is still unreported, e.g. when the turn ends. */
+    flush() {
+        const pending = this.text().slice(this.streamedLen);
+        if (!pending.trim()) {
+            return;
+        }
+        this.streamedLen += pending.length;
+        this.emit(pending);
+    }
+    /**
+     * Single door for every progress line: blank lines and a line identical to
+     * the one before it are dropped, because the dev server repeats status
+     * pushes many times per build and repetition buries the text that matters.
+     */
+    emit(line) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed === this.lastLine) {
+            return;
+        }
+        this.lastLine = trimmed;
+        this.onLine(trimmed);
+    }
+    maybeEmit() {
+        const pending = this.text().slice(this.streamedLen);
+        const now = this.now();
+        if (pending.length < PROGRESS_CHAR_CHUNK &&
+            now - this.lastProgressAt < PROGRESS_MS_CHUNK) {
+            return;
+        }
+        // Waiting for a sentence to end keeps lines readable, but Clark can stop
+        // mid-sentence for a long tool call. Once a line has been held that long,
+        // showing it unfinished beats showing nothing.
+        const cut = sentenceCut(pending) ||
+            (now - this.lastProgressAt >= PROGRESS_STALE_MS ? pending.length : 0);
+        if (cut === 0) {
+            return;
+        }
+        this.lastProgressAt = now;
+        this.streamedLen += cut;
+        this.emit(pending.slice(0, cut));
+    }
+}
+function sentenceCut(text) {
+    const boundary = Math.max(text.lastIndexOf(". "), text.lastIndexOf(".\n"), text.lastIndexOf("! "), text.lastIndexOf("? "), text.lastIndexOf(":\n"), text.lastIndexOf("\n"));
+    if (boundary >= 0) {
+        return boundary + 1;
+    }
+    if (text.trimEnd().endsWith(".")) {
+        return text.length;
+    }
+    if (text.length < PROGRESS_CHAR_CHUNK) {
+        return 0;
+    }
+    const space = text.lastIndexOf(" ");
+    return space > 0 ? space : text.length;
+}
+//# sourceMappingURL=streamed-reply.js.map

package/dist/sabs/streamed-reply.js.map

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

package/dist/sabs/turn-collector.d.ts

@@ -0,0 +1,169 @@
+import type { ClarkPeerEvent } from "./editor-client-methods.js";
+import type { GenerationStatus, ViewStatus } from "./session-peer.js";
+/** Default quiet window after completed/idle before treating the job as done. */
+export declare const DEFAULT_SETTLE_MS = 12000;
+export type TurnDecision = {
+    integrations: Array<{
+        configuration: Record<string, unknown>;
+        /** The plugin's configuration form, so the host needs no lookup. */
+        configurationSchema?: Record<string, unknown>;
+        name?: string;
+        pluginId: string;
+    }>;
+    kind: "missing_integrations";
+} | {
+    kind: "multi_choice";
+    messageId?: string;
+    options: string[];
+    question: string;
+} | {
+    kind: "plan";
+    messageId?: string;
+    plan: string;
+    title?: string;
+};
+export type TurnCollectorOptions = {
+    /**
+     * The generation this turn started, as `aiGenerateWithQueue` named it.
+     *
+     * The ai-service runs generations of its own — the v2->v3 migration turn,
+     * the run an interrupt continues with — and each ends with its own terminal
+     * state on the same socket. Without this, one of those ends this turn and a
+     * build that is still running is reported finished. (APPS-5161)
+     */
+    generationId?: string;
+    initialSyncStatus?: string;
+    settleMs?: number;
+};
+/**
+ * Collects Clark chat and generation-state pushes for one MCP turn wait.
+ *
+ * `completed` / `idle` start a settle window so an acknowledgment turn that
+ * resumes generating is coalesced into the same tool call. `awaiting_user_input`
+ * returns `needs_decision` immediately so Claude can answer via `edit_app`.
+ */
+export declare class TurnCollector {
+    private readonly onProgress?;
+    private readonly labels;
+    private readonly states;
+    private readonly settleMs;
+    private seenGenerating;
+    private terminal;
+    private viewStatus;
+    private draftPending;
+    private syncStatus;
+    private syncPending;
+    private readonly signals;
+    /** Case id to name, so a later per-case update can be reported by name. */
+    private readonly testCaseNames;
+    private readonly awaited;
+    /**
+     * Whether anything has arrived on the channel the dev server binds to a
+     * single editor peer (Clark's messages and generation states). Draft and sync
+     * pushes go to every attached editor, so they say nothing about the binding.
+     */
+    private clarkPushSeen;
+    private lastEventReceivedAt;
+    private notifyClarkPush;
+    private settleTimer;
+    private syncTimer;
+    private notifySettled;
+    private notifyInSync;
+    private generationId;
+    private readonly stream;
+    constructor(onProgress?: ((message: string) => void) | undefined, options?: TurnCollectorOptions);
+    /**
+     * Names the generation this turn is collecting, once the prompt has been
+     * acknowledged.
+     *
+     * Set after the fact because the collector has to be listening before the
+     * prompt goes out - the session starts pushing as soon as it accepts it, and
+     * a collector attached afterwards would miss the opening of its own turn.
+     * Until it is named, every state is taken as this turn's, which is the
+     * behavior from before generations were named at all.
+     */
+    nameGeneration(generationId: string | undefined): void;
+    /**
+     * Whether a generation state is about the generation this turn started.
+     *
+     * Unnamed states are this turn's by default: a dev server from before the
+     * field says nothing about whose generation it is, and treating that silence
+     * as someone else's would leave every turn against an older sandbox waiting
+     * for a terminal state that never arrives.
+     */
+    private belongsToThisTurn;
+    handle(event: ClarkPeerEvent): void;
+    reply(): string;
+    /**
+     * Structured decision Clark is waiting on (plan card or multi_choice).
+     * Prefer plan over multi_choice when both arrived in the same turn.
+     */
+    decision(): TurnDecision | undefined;
+    lastEventAt(): number;
+    status(): GenerationStatus | undefined;
+    isSettling(): boolean;
+    viewableStatus(): ViewStatus;
+    /**
+     * Whether Clark left a draft the gateway still has to accept. Mirrors the
+     * browser editor's `hasAiSuggestedDraft`, which is what gates its
+     * auto-accept.
+     */
+    needsDraftAccept(): boolean;
+    stateSequence(): string[];
+    /**
+     * Which pushes this turn used to decide it built something. Diagnostic: a
+     * headless peer that receives none of them cannot tell an empty job from a
+     * successful one, and that is a session-protocol problem, not a Clark one.
+     */
+    workSignals(): string[];
+    /**
+     * Resolves true once Clark has pushed anything on the single-peer channel, or
+     * false when the budget expires having heard nothing.
+     *
+     * A turn that hears nothing is not a slow turn: `generating` lands within a
+     * second of the prompt being acknowledged. Silence means this peer is not the
+     * one the sandbox is pushing to, and no amount of waiting fixes that.
+     */
+    waitForClarkPush(input: {
+        signal?: AbortSignal;
+        timeoutMs: number;
+    }): Promise<boolean>;
+    waitUntilTerminal(input: {
+        signal?: AbortSignal;
+        timeoutMs: number;
+    }): Promise<GenerationStatus>;
+    /**
+     * Resolves once the dev server has flushed Clark's files. An unreported sync
+     * status counts as in sync, matching the browser editor's `isOutOfSync`,
+     * which blocks on every status where the files have not reached both sides.
+     *
+     * Resolves false when the budget expires with the sync still pending, so the
+     * caller can decline to checkpoint a half-uploaded app.
+     */
+    waitUntilInSync(input: {
+        timeoutMs: number;
+    }): Promise<boolean>;
+    /** Records that the gateway committed Clark's draft into a checkpoint. */
+    markCheckpointed(): void;
+    /**
+     * Drops pending timers and releases anyone still waiting, so a turn that
+     * timed out or threw leaves nothing armed behind it.
+     */
+    dispose(): void;
+    private endSyncWait;
+    /**
+     * Turns a test run into activity lines. Clark names each case only once, in
+     * the run's opening plan, so the names are kept to label the per-case
+     * updates that follow — an update carries an id and nothing else.
+     */
+    private onTestMessage;
+    private onSyncStatus;
+    private onGenerationState;
+    private armSettle;
+    private clearSettleTimer;
+}
+/**
+ * Length of the leading part of `text` that ends on a sentence or line break,
+ * falling back to a word boundary once the text outgrows one chunk. Returns 0
+ * when there is no good place to cut yet.
+ */