@volter/supercode-frontend-vscode 0.1.11

package/dist/session.js

@@ -0,0 +1,431 @@
+/** The request this attachment tried to answer is no longer open. */
+export class RequestNotPendingError extends Error {
+    requestId;
+    constructor(requestId) {
+        super(`request #${requestId} is no longer pending`);
+        this.name = 'RequestNotPendingError';
+        this.requestId = requestId;
+    }
+}
+export class EventSequenceGapError extends Error {
+    constructor(expected, actual) {
+        super(`frontend event sequence gap: expected ${expected}, received ${actual}`);
+        this.name = 'EventSequenceGapError';
+    }
+}
+/** The lifecycle kinds that end one submitted turn, from `submit_claimed`. */
+export const TURN_TERMINAL_KINDS = Object.freeze(['turn_succeeded', 'turn_failed', 'turn_interrupted']);
+/**
+ * The runtime hands ONE controller a lease and expires it
+ * (`crates/harness/src/runtime_lease.rs`); an interactive attachment must hold
+ * it, so these two error names are a take-control-and-retry, never a failure
+ * the view reports.
+ */
+export const LEASE_ERROR_NAMES = ['controller_required', 'lease_expired'];
+/**
+ * ONLY the terminal kinds idle the descriptor. `turn_completed` is
+ * `AgentEvent::TurnCompleted` — one model round-trip, fired before a tool even
+ * runs — so treating it as idle ends the turn the moment the model first stops
+ * talking, which is exactly when an approval is about to be raised.
+ */
+const IDLE_KINDS = new Set(TURN_TERMINAL_KINDS);
+const BUSY_KINDS = new Set(['turn_started', 'user_message']);
+/**
+ * One attachment to one already-running Volter Harness SDK runtime: cursor-safe
+ * event projection, permission narrowing, and the semantic actions the runtime
+ * advertises. It owns no agent, no model, no tool and no session file.
+ */
+export class VscodeFrontendSession {
+    id;
+    baseUrl;
+    client;
+    permissions;
+    descriptor = null;
+    history = [];
+    historyCursor = 0;
+    cursor = 0;
+    /**
+     * Every event this attachment has seen, in order — NOT just the last
+     * snapshot's. A re-attach asks `afterSequence: cursor`, so its `replay` is
+     * empty by design; overwriting with it threw away the conversation a hosted
+     * harness keeps there (`HostedHarnessRuntime::attach` returns no canonical
+     * history at all). Bounded, because a long session is a lot of events.
+     */
+    replay = [];
+    pendingRequests = new Map();
+    /**
+     * Requests this attachment has seen resolved. `request_resolved` deletes the
+     * pending entry while it is being projected, so without this the resolution
+     * could only say "request #1" — it would have lost the very thing it needs to
+     * name. Bounded, because a long session resolves a lot of them.
+     */
+    resolvedRequests = new Map();
+    connection = 'disconnected';
+    /**
+     * `frontend.v2`'s descriptor and history carry NO timestamp, so the only
+     * true times this frontend knows are its own: when this window attached, and
+     * the turn boundaries it watched go by. The editor's session list always
+     * reads `timing.created` and renders 1970 when it is absent, so these are
+     * what it gets — never a zero dressed up as a date.
+     */
+    attachedAtMs = null;
+    lastTurnStartedMs = null;
+    lastTurnEndedMs = null;
+    #subscribed = false;
+    #following = null;
+    #heartbeat = null;
+    #resyncing = false;
+    #listeners = new Set();
+    #changeObservers = new Set();
+    #eventListener = (event) => {
+        this.applyEvent(event);
+    };
+    #disconnectListener = () => {
+        if (this.connection === 'connected')
+            this.connection = 'disconnected';
+        this.notify();
+    };
+    constructor(id, baseUrl, client, permissions = ['observe']) {
+        this.id = id;
+        this.baseUrl = baseUrl;
+        this.client = client;
+        this.permissions = new Set(permissions);
+        if (!this.permissions.has('observe'))
+            throw new TypeError('a frontend attachment requires observe');
+    }
+    /**
+     * Take the attachment snapshot. The generated client opens the SSE stream
+     * BEFORE the snapshot RPC, so no event can fall between the two.
+     */
+    async attach(limit = 1000) {
+        const snapshot = await this.client.attach(limit, { afterSequence: this.cursor });
+        const staged = {
+            descriptor: structuredClone(snapshot.descriptor),
+            pendingRequests: new Map([...this.pendingRequests].map(([id, request]) => [id, structuredClone(request)])),
+            cursor: Math.max(this.cursor, snapshot.history_cursor),
+        };
+        // Validate and project the whole attachment before any observable field
+        // moves or a live listener is registered.
+        for (const event of snapshot.replay)
+            this.projectEvent(staged, event);
+        // A request seen in the REPLAY is transcript, not an open ask. The runtime
+        // re-sequences its request history at every turn boundary
+        // (`compact_frontend_request_history`), and that compaction can keep a
+        // `request` whose `request_resolved` is gone — measured on a live runtime,
+        // whose replay read `[[12,"request",1],[13,"turn_succeeded"]]` for a
+        // request it had long since finished with. Answering one of those sends a
+        // dead id. An approval can only be outstanding while a turn is running,
+        // because `decide_approval` blocks the agent loop, so an idle runtime has
+        // none no matter what its replay still carries.
+        if (staged.descriptor?.turn_state !== 'busy')
+            staged.pendingRequests.clear();
+        this.descriptor = staged.descriptor;
+        this.history = structuredClone(snapshot.history);
+        this.historyCursor = snapshot.history_cursor;
+        this.appendTranscript(structuredClone(snapshot.replay));
+        this.pendingRequests = staged.pendingRequests;
+        this.cursor = staged.cursor;
+        this.connection = 'connected';
+        this.attachedAtMs ??= Date.now();
+        if (!this.#subscribed) {
+            this.client.on('event', this.#eventListener);
+            this.client.on('disconnect', this.#disconnectListener);
+            this.#subscribed = true;
+        }
+        this.notify();
+        return snapshot;
+    }
+    /** Start consuming the already-open live stream. Resolves when it ends. */
+    follow() {
+        if (!this.#following) {
+            this.#following = this.client.startEvents({ afterSequence: this.cursor }).finally(() => {
+                this.#following = null;
+            });
+        }
+        return this.#following;
+    }
+    /**
+     * Hold the controller lease for as long as this attachment lasts. Observers
+     * never call this; only a permission that can submit needs the lease.
+     */
+    async takeControlAndHold() {
+        if (!this.permissions.has('interact'))
+            return;
+        const lease = await this.client.takeControl();
+        this.startHeartbeat(lease.lease_ttl_ms);
+    }
+    startHeartbeat(ttlMs) {
+        this.stopHeartbeat();
+        const every = Math.max(1000, Math.floor((Number.isFinite(ttlMs) ? ttlMs : 30000) / 3));
+        this.#heartbeat = setInterval(() => {
+            void this.client.heartbeat().catch(() => {
+                // A lost lease is re-taken on the next action; a failing heartbeat is
+                // never an error this view reports.
+            });
+        }, every);
+    }
+    stopHeartbeat() {
+        if (this.#heartbeat)
+            clearInterval(this.#heartbeat);
+        this.#heartbeat = null;
+    }
+    dispose() {
+        this.stopHeartbeat();
+        this.client.stopEvents();
+        if (this.#subscribed) {
+            this.client.off('event', this.#eventListener);
+            this.client.off('disconnect', this.#disconnectListener);
+            this.#subscribed = false;
+        }
+        this.#listeners.clear();
+        this.#changeObservers.clear();
+    }
+    /** Keep the transcript in order and free of the duplicates a re-attach brings. */
+    appendTranscript(events) {
+        const seen = new Set(this.replay.map((event) => event.sequence));
+        for (const event of events) {
+            if (seen.has(event.sequence))
+                continue;
+            seen.add(event.sequence);
+            this.replay.push(event);
+        }
+        this.replay.sort((left, right) => left.sequence - right.sequence);
+        if (this.replay.length > 2000)
+            this.replay = this.replay.slice(-2000);
+    }
+    applyEvent(event) {
+        let applied;
+        try {
+            applied = this.projectEvent(this, event);
+        }
+        catch (error) {
+            if (!(error instanceof EventSequenceGapError))
+                throw error;
+            // A gap is what the cursor exists for, not a reason to die. Throwing out
+            // of the live listener would tear the subscription down and leave every
+            // in-flight turn waiting for a terminal event that can no longer arrive.
+            // Re-take the snapshot from the current cursor instead; the generated
+            // client reuses the open stream, so this is a resync, not a reconnect.
+            this.resync();
+            return false;
+        }
+        if (!applied)
+            return false;
+        this.appendTranscript([event]);
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A view that throws never stops the projection.
+            }
+        }
+        this.notify();
+        return true;
+    }
+    /** Re-take the attachment snapshot after a sequence gap, once at a time. */
+    resync() {
+        if (this.#resyncing)
+            return;
+        this.#resyncing = true;
+        void this.attach()
+            .catch(() => {
+            // An unreachable runtime is reported by the next action, not here.
+        })
+            .finally(() => {
+            this.#resyncing = false;
+        });
+    }
+    /** Subscribe to every event this session projects, from now on. */
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    onChange(observer) {
+        this.#changeObservers.add(observer);
+        return () => this.#changeObservers.delete(observer);
+    }
+    projectEvent(state, event) {
+        if (event.sequence <= state.cursor)
+            return false;
+        if (event.sequence !== state.cursor + 1) {
+            throw new EventSequenceGapError(state.cursor + 1, event.sequence);
+        }
+        state.cursor = event.sequence;
+        const payload = (event.payload ?? {});
+        if (event.kind === 'request' && payload.type === 'request') {
+            const request = payload.request;
+            if (request && typeof request.id === 'number')
+                state.pendingRequests.set(request.id, structuredClone(request));
+        }
+        if (event.kind === 'request_resolved' && typeof payload.request_id === 'number') {
+            const resolved = state.pendingRequests.get(payload.request_id);
+            if (resolved) {
+                this.resolvedRequests.set(payload.request_id, resolved);
+                while (this.resolvedRequests.size > 50) {
+                    this.resolvedRequests.delete(this.resolvedRequests.keys().next().value);
+                }
+            }
+            state.pendingRequests.delete(payload.request_id);
+        }
+        if (state === this) {
+            if (BUSY_KINDS.has(event.kind))
+                this.lastTurnStartedMs = Date.now();
+            else if (TURN_TERMINAL_KINDS.includes(event.kind))
+                this.lastTurnEndedMs = Date.now();
+        }
+        if (state.descriptor && IDLE_KINDS.has(event.kind)) {
+            state.descriptor = { ...state.descriptor, turn_state: 'idle' };
+        }
+        else if (state.descriptor && BUSY_KINDS.has(event.kind)) {
+            state.descriptor = { ...state.descriptor, turn_state: 'busy' };
+        }
+        return true;
+    }
+    /** What this attachment may do: permission AND the descriptor's own advertisement. */
+    actions() {
+        const advertised = this.descriptor?.actions;
+        const interactive = this.permissions.has('interact');
+        const busy = this.descriptor?.turn_state === 'busy';
+        return {
+            submit: Boolean(advertised?.submit && interactive && !busy),
+            steer: Boolean(advertised?.steer && interactive && busy),
+            interrupt: Boolean(advertised?.interrupt && interactive && busy),
+            respond: Boolean(advertised?.respond && this.permissions.has('approve') && this.pendingRequests.size > 0),
+            detach: Boolean(advertised?.detach && this.permissions.has('observe')),
+            close: Boolean(advertised?.close && this.permissions.has('terminate')),
+            takeover: Boolean(this.descriptor && interactive && this.connection === 'connected'),
+        };
+    }
+    /** Run one controller action, re-taking an expired lease exactly once. */
+    async withControl(action) {
+        try {
+            return await action();
+        }
+        catch (error) {
+            const name = error?.name ?? '';
+            if (!LEASE_ERROR_NAMES.includes(name) || !this.permissions.has('interact'))
+                throw error;
+            const lease = await this.client.takeControl();
+            this.startHeartbeat(lease.lease_ttl_ms);
+            return action();
+        }
+    }
+    async submit(prompt) {
+        this.require('submit');
+        if (prompt.length === 0)
+            throw new TypeError('prompt must not be empty');
+        await this.withControl(() => this.client.sendInput(prompt));
+    }
+    async steer(prompt) {
+        this.require('steer');
+        if (prompt.length === 0)
+            throw new TypeError('prompt must not be empty');
+        await this.withControl(() => this.client.steer(prompt));
+    }
+    async interrupt() {
+        this.require('interrupt');
+        await this.withControl(() => this.client.interrupt());
+    }
+    async respond(response) {
+        this.require('respond');
+        if (!this.pendingRequests.has(response.request_id))
+            throw new RequestNotPendingError(response.request_id);
+        try {
+            await this.withControl(() => this.client.respond(response));
+        }
+        catch (error) {
+            // The runtime is the authority on what is still open. When it says it is
+            // not, this attachment's view of it was stale — drop it rather than let
+            // the same dead id be offered again.
+            if (error?.name === 'not_found' || /not pending|unknown request/i.test(String(error?.message))) {
+                this.pendingRequests.delete(response.request_id);
+                this.notify();
+                throw new RequestNotPendingError(response.request_id);
+            }
+            throw error;
+        }
+    }
+    async detach() {
+        this.require('detach');
+        await this.client.detach();
+        this.connection = 'disconnected';
+        this.notify();
+    }
+    async close() {
+        this.require('close');
+        await this.client.close();
+        this.connection = 'closed';
+        this.notify();
+    }
+    async takeover() {
+        this.require('takeover');
+        const lease = await this.client.takeControl();
+        this.startHeartbeat(lease.lease_ttl_ms);
+        this.notify();
+    }
+    async heartbeat() {
+        if (this.connection !== 'connected')
+            return null;
+        return this.client.heartbeat();
+    }
+    /**
+     * Submit one prompt and feed every event of the resulting turn to `onEvent`,
+     * resolving when the runtime reports the turn finished. The subscription is
+     * registered BEFORE the prompt is sent, so no early delta is lost.
+     */
+    async runTurn(prompt, onEvent, options = {}) {
+        let settle;
+        let fail;
+        const finished = new Promise((resolve, reject) => {
+            settle = resolve;
+            fail = reject;
+        });
+        const unsubscribe = this.onEvent((event) => {
+            try {
+                onEvent(event);
+            }
+            finally {
+                if (TURN_TERMINAL_KINDS.includes(event.kind))
+                    settle?.(event);
+            }
+        });
+        // A turn that never sees its terminal event must still end: the editor
+        // holds the chat response open until this handler resolves, and a frontend
+        // that hangs one is worse than one that ends it a beat early. The
+        // descriptor going idle after the submit is the second, independent signal.
+        let sawBusy = false;
+        const unwatch = this.onChange(() => {
+            const state = this.descriptor?.turn_state;
+            if (state === 'busy')
+                sawBusy = true;
+            else if (sawBusy && state === 'idle')
+                settle?.(null);
+        });
+        options.onCancel?.(() => {
+            void this.interrupt().catch((error) => fail?.(error));
+        });
+        try {
+            await this.submit(prompt);
+            return await finished;
+        }
+        finally {
+            unsubscribe();
+            unwatch();
+        }
+    }
+    require(action) {
+        if (!this.actions()[action])
+            throw new Error(`frontend action ${action} is unavailable`);
+    }
+    notify() {
+        for (const observer of [...this.#changeObservers]) {
+            try {
+                observer();
+            }
+            catch {
+                // An observer that throws never stops the projection.
+            }
+        }
+    }
+}

package/dist/view.d.ts

@@ -0,0 +1,176 @@
+import type { ChatMessage, FrontendEvent, FrontendRequest, FrontendResponse } from '../vendor/supercode-frontend/generated.mjs';
+import type { ProposalName } from './proposals.js';
+/**
+ * The bounded projection this presentation package renders. Mirrors
+ * `@volter/supercode-frontend-browser`'s rule: the view is size-bounded
+ * and says so when it omits something; the runtime's own history is unchanged
+ * and remains authoritative.
+ */
+export declare const VSCODE_CHAT_LIMITS: Readonly<{
+    partCharacters: number;
+    titleCharacters: 256;
+    opaqueCharacters: number;
+    historyTurns: 500;
+}>;
+/**
+ * What one answer button sends back to the runtime.
+ *
+ * MEASURED: `ChatResponseConfirmationPart` is the wrong mechanism here. The
+ * editor answers a confirmation by sending a NEW chat request carrying the
+ * part's data (`chatConfirmationContentPart`), and a supercode approval is
+ * raised WHILE the turn is still running — `decide_approval` in
+ * crates/harness/src/server.rs blocks the agent loop until it is answered — so
+ * the editor refuses that second request and the click does nothing. An
+ * answer is therefore a COMMAND button: it runs inside the live turn, it is
+ * stable API (no proposal), and each button carries its own answer instead of
+ * the one payload a confirmation splits across accepted/rejected.
+ */
+export interface ChatAnswer {
+    connectionId: string;
+    requestId: number;
+    response: FrontendResponse;
+    /** Ask for the content this response should carry before sending it. */
+    promptForContent?: boolean;
+    label: string;
+}
+export type ChatPart = {
+    part: 'markdown';
+    value: string;
+} | {
+    part: 'progress';
+    value: string;
+} | {
+    part: 'warning';
+    value: string;
+} | {
+    part: 'thinking';
+    value: string;
+}
+/** A project-relative path the runtime's own payload named. */
+ | {
+    part: 'reference';
+    path: string;
+} | {
+    part: 'codeblock';
+    uri: string;
+    value: string;
+    language: string;
+} | {
+    part: 'tool';
+    toolName: string;
+    toolCallId: string;
+    invocationMessage: string;
+    inputText?: string;
+    pastTenseMessage?: string;
+    isError?: boolean;
+    isComplete: boolean;
+    resultText?: string;
+} | {
+    part: 'answers';
+    title: string;
+    message: string;
+    answers: ChatAnswer[];
+};
+/**
+ * One rendered part plus the API proposal it needs and what this view renders
+ * instead when the host did not grant it. README.md's proposal table is this
+ * data; nothing else decides which part needs which proposal.
+ */
+export interface ProjectedPart {
+    emit: ChatPart;
+    needs?: ProposalName;
+    fallback?: ChatPart[];
+}
+/** Markdown-safe rendering of an arbitrary JSON payload, bounded. */
+export declare function opaqueText(value: unknown, limit?: number): string;
+/** A fenced block that its own content cannot break out of. */
+export declare function fence(body: string, language?: string): string;
+/**
+ * The files a unified diff says it touched, read from its own `+++ b/<path>`
+ * headers. Nothing else is derived from the diff: this frontend never rebuilds
+ * edits from it (see the `diff_updated` arm).
+ */
+export declare function diffPaths(diff: string): string[];
+/**
+ * The one-line subject a tool call is about, read from its own arguments.
+ * The editor renders `invocationMessage` verbatim, so a bare tool name is a
+ * wasted row; `write_file · hello.txt` says what it did.
+ */
+export declare function toolSubject(argumentsText: string): string | undefined;
+/** The summary line this view shows for a request payload. */
+export declare function requestSummary(request: FrontendRequest): string;
+/** The answers this view offers for a request, one button each. */
+export declare function requestAnswers(request: FrontendRequest, connectionId: string): ChatAnswer[];
+/**
+ * The typed-reply path, for a request that is still pending when the turn is
+ * NOT running: the person types the answer as the next message.
+ */
+export declare function typedAnswer(request: FrontendRequest, reply: string): FrontendResponse;
+/** The decisions a runtime said its harness accepts, when it said so. */
+export declare function acceptedDecisions(request: FrontendRequest): string[] | undefined;
+/** True when this request asks for content a button click cannot carry. */
+export declare function requestNeedsTypedReply(request: FrontendRequest): boolean;
+/**
+ * The resolution of a request as a sentence, built from the response's own
+ * fields and the request it answers — never the raw JSON, which says the same
+ * thing in a form only this protocol's authors can read.
+ */
+export declare function resolutionSentence(response: FrontendResponse | undefined, request: FrontendRequest | undefined, requestId: number): string;
+/** `write_file on hello.txt`, read from the request's own payload. */
+export declare function requestSubject(request: FrontendRequest): string | undefined;
+export interface ProjectionContext {
+    /** Identifies which attached runtime a confirmation click must answer. */
+    connectionId: string;
+    /** Render the runtime's echo of a prompt (history replay does; live does not). */
+    echoOwnPrompts?: boolean;
+    /** The request a `request_resolved` answers, so its sentence can name it. */
+    pendingRequest?: (requestId: number) => FrontendRequest | undefined;
+    /**
+     * Whether the runtime's own descriptor advertises `respond`. A HOSTED
+     * harness runtime sets `actions.respond: false` — the portable contract
+     * cannot carry that harness's native response envelope, so its owner/editor
+     * answers through `harness.v1.approvals.resolve` and this view may only
+     * OBSERVE the request (`crates/harness/src/runtime/hosted.rs`). A control is
+     * rendered only for an action the descriptor advertises, so the answer
+     * buttons are absent rather than dead.
+     */
+    canRespond?: boolean;
+}
+/** Pending requests belong to the live runtime, even when saved transcript
+ * history predates them. Rehydrate their controls before waiting for new events. */
+export declare function projectPendingRequests(requests: Iterable<FrontendRequest>, context: ProjectionContext): ProjectedPart[];
+/**
+ * The event to chat-response-part mapping. Pure: every input is the runtime's
+ * own sequenced event, every output describes a VS Code chat part. Each arm
+ * names the producer it reads.
+ */
+export declare function projectEvent(event: FrontendEvent, context: ProjectionContext): ProjectedPart[];
+/** Replace every part whose proposal the host did not grant with its fallback. */
+export declare function resolveParts(parts: readonly ProjectedPart[], granted: ReadonlySet<string>): ChatPart[];
+/**
+ * The prompt of the marker turn that carries runtime history with no user turn
+ * of its own. It names itself; nothing here is presented as a person's words.
+ */
+export declare const HISTORY_MARKER_PROMPT = "\u27E8supercode runtime history\u27E9";
+export type TurnRole = 'user' | 'assistant';
+export interface ProjectedTurn {
+    role: TurnRole;
+    /** The prompt text for a user turn. */
+    prompt?: string;
+    /** Rendered parts for an assistant turn. */
+    parts?: ChatPart[];
+}
+/**
+ * A HOSTED harness runtime's transcript as chat turns.
+ *
+ * `HostedHarnessRuntime::attach` returns `history: Vec::new()` and puts the
+ * whole conversation in `replay` — the canonical ChatMessage history belongs to
+ * supercode's own agent loop, and a hosted harness has none. So a resumed
+ * Claude Code session's turns are here or nowhere.
+ */
+export declare function projectReplayTurns(events: readonly FrontendEvent[], granted: ReadonlySet<string>, context: ProjectionContext): ProjectedTurn[];
+/**
+ * The attach snapshot's canonical history as chat turns. Bounded: when older
+ * turns are omitted the view says so, the way the browser observer does.
+ */
+export declare function projectHistory(history: readonly ChatMessage[], granted: ReadonlySet<string>, pendingToolNames?: ReadonlySet<string>): ProjectedTurn[];