@volter/supercode-frontend-vscode 0.1.11

package/dist/host-controls.d.ts

@@ -0,0 +1,58 @@
+/** Optional lifecycle host. The host owns launches; frontend.v2 owns every conversation action. */
+import type { ChatMessage } from '../vendor/supercode-frontend/generated.mjs';
+export interface ChatSelection {
+    harness: string;
+    model: string;
+    effort: string;
+}
+export interface ChatChoice {
+    id: string;
+    name: string;
+    description?: string;
+}
+export interface ManagedChatSession {
+    id: string;
+    selection: ChatSelection;
+    identity: string | null;
+    title: string;
+    created: number;
+}
+export interface HostState {
+    history?: ChatMessage[];
+    historyTruncated?: boolean;
+    activeSession: string | null;
+    openSessionCommand?: string;
+    sessions: ManagedChatSession[];
+    selection: ChatSelection;
+    connection?: Record<string, string>;
+    harnesses: ChatChoice[];
+    models: ChatChoice[];
+    modelsByHarness?: Record<string, ChatChoice[]>;
+    busy: boolean;
+    actualModel?: string | null;
+    configurable: boolean;
+}
+export interface HostSelectionResult extends HostState {
+    connection: Record<string, string>;
+}
+export declare class ChatHostControls {
+    readonly baseUrl: string;
+    private readonly credential;
+    state: HostState;
+    private constructor();
+    static fromEnvironment(env?: NodeJS.ProcessEnv): Promise<ChatHostControls | undefined>;
+    refresh(): Promise<void>;
+    select(selection: ChatSelection): Promise<HostSelectionResult>;
+    remember(id: string, nativeId: string): Promise<void>;
+    open(id: string): Promise<HostSelectionResult>;
+    private request;
+}
+/** Approval policy is captured for one turn, never inferred from connection privileges. */
+export declare function turnPermission(value: string | undefined): 'ask' | 'autoApprove';
+export declare function harnessDisplayName(harness: string | null | undefined): string;
+export declare function runtimeIdentity(harness: string | null | undefined, model: string | null | undefined): {
+    name: string;
+    provider: string | undefined;
+};
+/** Native pickers need a nonempty id; the host uses an empty model for its default. */
+export declare function modelSelection(value: string): string;

package/dist/host-controls.js

@@ -0,0 +1,66 @@
+import { readCredentialFile } from './credential.js';
+export class ChatHostControls {
+    baseUrl;
+    credential;
+    state;
+    constructor(baseUrl, credential, state) {
+        this.baseUrl = baseUrl;
+        this.credential = credential;
+        this.state = state;
+    }
+    static async fromEnvironment(env = process.env) {
+        if (!env.SUPERCODE_FRONTEND_HOST_URL || !env.SUPERCODE_FRONTEND_HOST_CREDENTIAL_FILE)
+            return;
+        const url = new URL(env.SUPERCODE_FRONTEND_HOST_URL);
+        if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || url.username || url.password || url.pathname !== '/')
+            throw new Error('Chat lifecycle host must be a loopback HTTP endpoint.');
+        const credential = await readCredentialFile(env.SUPERCODE_FRONTEND_HOST_CREDENTIAL_FILE);
+        const host = new ChatHostControls(url.origin, credential, undefined);
+        host.state = await host.request('/state');
+        return host;
+    }
+    async refresh() { this.state = await this.request('/state'); }
+    async select(selection) {
+        const result = await this.request('/select', selection);
+        this.state = result;
+        return result;
+    }
+    async remember(id, nativeId) { this.state = await this.request('/remember', { id, nativeId }); }
+    async open(id) {
+        const result = await this.request('/open', { id });
+        this.state = result;
+        return result;
+    }
+    async request(path, selection) {
+        const response = await fetch(this.baseUrl + path, {
+            method: selection ? 'POST' : 'GET', headers: { Authorization: `Bearer ${this.credential}`, 'Content-Type': 'application/json' },
+            ...(selection ? { body: JSON.stringify(selection) } : {}), signal: AbortSignal.timeout(180_000), redirect: 'error',
+        });
+        const value = await response.json();
+        if (!response.ok)
+            throw new Error(value.error || `Chat host returned ${response.status}`);
+        return value;
+    }
+}
+/** Approval policy is captured for one turn, never inferred from connection privileges. */
+export function turnPermission(value) {
+    if (!value || value === 'default' || value === 'ask')
+        return 'ask';
+    if (value === 'autoApprove')
+        return 'autoApprove';
+    throw new Error(`The selected permission mode (${value}) is not supported by this runtime frontend.`);
+}
+export function harnessDisplayName(harness) {
+    return { 'claude-code': 'Claude Code', codex: 'Codex', gemini: 'Gemini CLI', opencode: 'OpenCode', pi: 'Pi', goose: 'Goose' }[harness || ''] || harness || 'Assistant';
+}
+export function runtimeIdentity(harness, model) {
+    const harnessName = harnessDisplayName(harness);
+    const knownModel = model && model !== harness ? model : '';
+    const modelName = { sonnet: 'Claude Sonnet', opus: 'Claude Opus', haiku: 'Claude Haiku' }[knownModel] || knownModel;
+    const provider = /claude|sonnet|opus|haiku/i.test(modelName) || (!modelName && harness === 'claude-code') ? 'anthropic'
+        : /^(gpt|o[134]|chatgpt)|\/gpt/i.test(modelName) || (!modelName && harness === 'codex') ? 'openai'
+            : /gemini/i.test(modelName) || (!modelName && harness === 'gemini') ? 'google' : undefined;
+    return { name: modelName ? `${modelName} · ${harnessName}` : `${harnessName} · default model`, provider };
+}
+/** Native pickers need a nonempty id; the host uses an empty model for its default. */
+export function modelSelection(value) { return value === "__default__" ? "" : value; }

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createFrontendClient, type FrontendPermission, type VscodeFrontendConnection } from './client.js';
+export { readCredentialFile } from './credential.js';
+export { grantedProposals, PROPOSAL_EFFECTS, REQUESTED_PROPOSALS, type ProposalName, } from './proposals.js';
+export { EventSequenceGapError, LEASE_ERROR_NAMES, RequestNotPendingError, TURN_TERMINAL_KINDS, VscodeFrontendSession, type VscodeFrontendActions, type VscodeRuntimeClient, } from './session.js';
+export { HISTORY_MARKER_PROMPT, VSCODE_CHAT_LIMITS, acceptedDecisions, diffPaths, fence, opaqueText, projectEvent, projectPendingRequests, projectHistory, projectReplayTurns, requestAnswers, requestNeedsTypedReply, requestSubject, requestSummary, resolutionSentence, resolveParts, toolSubject, typedAnswer, type ChatAnswer, type ChatPart, type ProjectedPart, type ProjectedTurn, type ProjectionContext, } from './view.js';
+export type { SupercodeConnectOptions, SupercodeConnectionInfo, SupercodeFrontendApi, } from './extension.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { createFrontendClient } from './client.js';
+export { readCredentialFile } from './credential.js';
+export { grantedProposals, PROPOSAL_EFFECTS, REQUESTED_PROPOSALS, } from './proposals.js';
+export { EventSequenceGapError, LEASE_ERROR_NAMES, RequestNotPendingError, TURN_TERMINAL_KINDS, VscodeFrontendSession, } from './session.js';
+export { HISTORY_MARKER_PROMPT, VSCODE_CHAT_LIMITS, acceptedDecisions, diffPaths, fence, opaqueText, projectEvent, projectPendingRequests, projectHistory, projectReplayTurns, requestAnswers, requestNeedsTypedReply, requestSubject, requestSummary, resolutionSentence, resolveParts, toolSubject, typedAnswer, } from './view.js';

package/dist/native-session.d.ts

@@ -0,0 +1,6 @@
+import type { CancellationToken } from 'vscode';
+import type { FrontendEvent } from '../vendor/supercode-frontend/generated.mjs';
+import { type VscodeFrontendSession } from './session.js';
+export declare function sessionStatus(session: Pick<VscodeFrontendSession, 'descriptor' | 'pendingRequests'>): 'NeedsInput' | 'InProgress' | 'Completed';
+/** Follow a restored turn, including the interval between snapshot and callback. */
+export declare function observeActiveResponse(session: Pick<VscodeFrontendSession, 'descriptor' | 'onEvent' | 'interrupt'>, token: CancellationToken, write: (event: FrontendEvent) => void): Promise<void>;

package/dist/native-session.js

@@ -0,0 +1,41 @@
+import { TURN_TERMINAL_KINDS } from './session.js';
+export function sessionStatus(session) {
+    return session.pendingRequests.size ? 'NeedsInput' : session.descriptor?.turn_state === 'busy' ? 'InProgress' : 'Completed';
+}
+/** Follow a restored turn, including the interval between snapshot and callback. */
+export async function observeActiveResponse(session, token, write) {
+    let unsubscribe = () => { };
+    let cancellation;
+    try {
+        await new Promise((resolve, reject) => {
+            let cancelling = false;
+            const cancel = () => {
+                if (cancelling)
+                    return;
+                cancelling = true;
+                // Wait for the runtime acknowledgement; a stopped UI is not a stopped harness.
+                void session.interrupt().then(resolve, reject);
+            };
+            unsubscribe = session.onEvent(event => {
+                try {
+                    write(event);
+                }
+                catch (error) {
+                    reject(error);
+                    return;
+                }
+                if (!cancelling && TURN_TERMINAL_KINDS.includes(event.kind))
+                    resolve();
+            });
+            cancellation = token.onCancellationRequested(cancel);
+            if (token.isCancellationRequested)
+                cancel();
+            else if (session.descriptor?.turn_state !== 'busy')
+                resolve();
+        });
+    }
+    finally {
+        unsubscribe();
+        cancellation?.dispose();
+    }
+}

package/dist/proposals.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The complete VS Code API-proposal surface this frontend asks for, and what it
+ * renders when a host grants none of it. A host grants proposals through
+ * `product.json#extensionEnabledApiProposals` (a Code-OSS derivative that
+ * bundles this extension) or `--enable-proposed-api <extension id>`; stock
+ * VS Code grants nothing, and this package must stay useful there.
+ *
+ * The granted set is read back from the extension host at runtime rather than
+ * from this package's own manifest: `IExtensionDescription.enabledApiProposals`
+ * is FILTERED to what the host actually allowed (the request in `package.json`
+ * is nulled when it is not), and `vscode.extensions.getExtension(id).packageJSON`
+ * is that description. Class constructors on the `vscode` namespace are exposed
+ * unconditionally, so a `typeof vscode.ChatResponseConfirmationPart` probe
+ * cannot answer this question — only the description can.
+ */
+export declare const REQUESTED_PROPOSALS: readonly ["defaultChatParticipant", "chatParticipantPrivate", "chatParticipantAdditions", "chatSessionsProvider", "chatProvider"];
+export type ProposalName = (typeof REQUESTED_PROPOSALS)[number];
+/** What each requested proposal buys, and what this frontend does without it. */
+export declare const PROPOSAL_EFFECTS: Readonly<Record<ProposalName, {
+    grants: string;
+    without: string;
+}>>;
+/** Read the proposals the HOST granted this extension, never the ones it asked for. */
+export declare function grantedProposals(packageJSON: unknown): ReadonlySet<ProposalName>;

package/dist/proposals.js

@@ -0,0 +1,54 @@
+/**
+ * The complete VS Code API-proposal surface this frontend asks for, and what it
+ * renders when a host grants none of it. A host grants proposals through
+ * `product.json#extensionEnabledApiProposals` (a Code-OSS derivative that
+ * bundles this extension) or `--enable-proposed-api <extension id>`; stock
+ * VS Code grants nothing, and this package must stay useful there.
+ *
+ * The granted set is read back from the extension host at runtime rather than
+ * from this package's own manifest: `IExtensionDescription.enabledApiProposals`
+ * is FILTERED to what the host actually allowed (the request in `package.json`
+ * is nulled when it is not), and `vscode.extensions.getExtension(id).packageJSON`
+ * is that description. Class constructors on the `vscode` namespace are exposed
+ * unconditionally, so a `typeof vscode.ChatResponseConfirmationPart` probe
+ * cannot answer this question — only the description can.
+ */
+export const REQUESTED_PROPOSALS = Object.freeze([
+    'defaultChatParticipant',
+    'chatParticipantPrivate',
+    'chatParticipantAdditions',
+    'chatSessionsProvider',
+    'chatProvider',
+]);
+/** What each requested proposal buys, and what this frontend does without it. */
+export const PROPOSAL_EFFECTS = Object.freeze({
+    defaultChatParticipant: {
+        grants: 'the `isDefault` participant contribution — supercode answers the Chat view without an `@` mention',
+        without: 'the ordinary `@supercode` participant answers; a mention is required',
+    },
+    chatParticipantPrivate: {
+        grants: 'the dynamic-participant and participant-detection APIs a bundling host can use to route without a mention',
+        without: 'nothing is lost in this package: it registers no dynamic participant and no detection provider',
+    },
+    chatParticipantAdditions: {
+        grants: 'tool-invocation, confirmation, warning and codeblock-uri response parts',
+        without: 'progress lines, collapsed markdown results, typed replies and plain fenced diffs',
+    },
+    chatProvider: { grants: 'native session model picker and model configuration', without: 'provider option model picker' },
+    chatSessionsProvider: {
+        grants: 'the runtime’s sessions in the Chat view’s session picker, each reopening with its history',
+        without: 'the participant still attaches; there is no session list',
+    },
+});
+/** Read the proposals the HOST granted this extension, never the ones it asked for. */
+export function grantedProposals(packageJSON) {
+    const declared = packageJSON?.enabledApiProposals;
+    if (!Array.isArray(declared))
+        return new Set();
+    const granted = new Set();
+    for (const name of declared) {
+        if (REQUESTED_PROPOSALS.includes(String(name)))
+            granted.add(name);
+    }
+    return granted;
+}

package/dist/session.d.ts

@@ -0,0 +1,154 @@
+import type { ChatMessage, FrontendAttachSnapshot, FrontendEvent, FrontendRequest, FrontendResponse, FrontendRuntimeDescriptor, RuntimeLeaseSnapshot } from '../vendor/supercode-frontend/generated.mjs';
+import type { FrontendPermission } from './client.js';
+/**
+ * The subset of the generated client this presentation package uses. Nothing
+ * here is a second protocol: every member is `@volter/supercode-frontend`'s.
+ */
+export interface VscodeRuntimeClient {
+    describe(): Promise<FrontendRuntimeDescriptor>;
+    attach(limit?: number, options?: {
+        afterSequence?: number;
+    }): Promise<FrontendAttachSnapshot>;
+    sendInput(prompt: string): Promise<{
+        accepted: boolean;
+    }>;
+    steer(prompt: string): Promise<{
+        queued: boolean;
+    }>;
+    interrupt(): Promise<{
+        interrupted: boolean;
+    }>;
+    respond(response: FrontendResponse): Promise<{
+        accepted: boolean;
+    }>;
+    detach(): Promise<unknown>;
+    close(): Promise<{
+        closed: boolean;
+    }>;
+    takeControl(): Promise<RuntimeLeaseSnapshot>;
+    heartbeat(): Promise<RuntimeLeaseSnapshot>;
+    on(event: 'event', listener: (event: FrontendEvent) => void): unknown;
+    on(event: 'disconnect', listener: () => void): unknown;
+    off(event: 'event', listener: (event: FrontendEvent) => void): unknown;
+    off(event: 'disconnect', listener: () => void): unknown;
+    startEvents(options?: {
+        afterSequence?: number;
+    }): Promise<void>;
+    stopEvents(): void;
+}
+export interface VscodeFrontendActions {
+    submit: boolean;
+    steer: boolean;
+    interrupt: boolean;
+    respond: boolean;
+    detach: boolean;
+    close: boolean;
+    takeover: boolean;
+}
+/** The request this attachment tried to answer is no longer open. */
+export declare class RequestNotPendingError extends Error {
+    readonly requestId: number;
+    constructor(requestId: number);
+}
+export declare class EventSequenceGapError extends Error {
+    constructor(expected: number, actual: number);
+}
+/** The lifecycle kinds that end one submitted turn, from `submit_claimed`. */
+export declare const TURN_TERMINAL_KINDS: readonly ["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 declare const LEASE_ERROR_NAMES: readonly string[];
+/**
+ * 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 declare class VscodeFrontendSession {
+    #private;
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly client: VscodeRuntimeClient;
+    readonly permissions: ReadonlySet<FrontendPermission>;
+    descriptor: FrontendRuntimeDescriptor | null;
+    history: ChatMessage[];
+    historyCursor: number;
+    cursor: number;
+    /**
+     * 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: FrontendEvent[];
+    pendingRequests: Map<number, FrontendRequest>;
+    /**
+     * 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: Map<number, FrontendRequest>;
+    connection: 'disconnected' | 'connected' | 'closed';
+    /**
+     * `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: number | null;
+    lastTurnStartedMs: number | null;
+    lastTurnEndedMs: number | null;
+    constructor(id: string, baseUrl: string, client: VscodeRuntimeClient, permissions?: FrontendPermission[]);
+    /**
+     * Take the attachment snapshot. The generated client opens the SSE stream
+     * BEFORE the snapshot RPC, so no event can fall between the two.
+     */
+    attach(limit?: number): Promise<FrontendAttachSnapshot>;
+    /** Start consuming the already-open live stream. Resolves when it ends. */
+    follow(): Promise<void>;
+    /**
+     * Hold the controller lease for as long as this attachment lasts. Observers
+     * never call this; only a permission that can submit needs the lease.
+     */
+    takeControlAndHold(): Promise<void>;
+    private startHeartbeat;
+    private stopHeartbeat;
+    dispose(): void;
+    /** Keep the transcript in order and free of the duplicates a re-attach brings. */
+    private appendTranscript;
+    applyEvent(event: FrontendEvent): boolean;
+    /** Re-take the attachment snapshot after a sequence gap, once at a time. */
+    private resync;
+    /** Subscribe to every event this session projects, from now on. */
+    onEvent(listener: (event: FrontendEvent) => void): () => void;
+    onChange(observer: () => void): () => void;
+    private projectEvent;
+    /** What this attachment may do: permission AND the descriptor's own advertisement. */
+    actions(): VscodeFrontendActions;
+    /** Run one controller action, re-taking an expired lease exactly once. */
+    private withControl;
+    submit(prompt: string): Promise<void>;
+    steer(prompt: string): Promise<void>;
+    interrupt(): Promise<void>;
+    respond(response: FrontendResponse): Promise<void>;
+    detach(): Promise<void>;
+    close(): Promise<void>;
+    takeover(): Promise<void>;
+    heartbeat(): Promise<RuntimeLeaseSnapshot | null>;
+    /**
+     * 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.
+     */
+    runTurn(prompt: string, onEvent: (event: FrontendEvent) => void, options?: {
+        onCancel?: (cancel: () => void) => void;
+    }): Promise<FrontendEvent | null>;
+    private require;
+    private notify;
+}