@volter/supercode-frontend-vscode 0.1.45 → 0.1.46

package/README.md

@@ -430,3 +430,21 @@ it never submits a new chat prompt. The host guards the addressed conversation,
 disables the choices during dispatch and retires them only after an acknowledged
 response or an already-resolved result. Hosts without this capability retain
 stable command buttons. Other request kinds retain their existing presentation.
+
+## External runtime handoff
+
+`supercode.frontend.connect(handoff)` accepts a `SupercodeRuntimeHandoff` with
+`baseUrl`, `clientId`, `connectionId`, `credentialFile`, optional permissions and
+label. Credentials are read from the private file; command arguments contain no
+raw token. External attachments retain their exact identity across reloads.
+`supercode.frontend.openSession(connectionId)` opens that conversation;
+`supercode.frontend.status(true)` reports connection state, conversation view
+readiness/resource and rendered event cursor. View readiness follows history
+restoration and live-response subscription, rather than a socket alone.
+`supercode.frontend.disconnect(connectionId)` also forgets the saved attachment.
+IDs belonging to managed conversations cannot be reused for external attachments.
+Calling `connect` without arguments retains the interactive settings flow.
+
+These are ordinary connection/view APIs for any external runtime. Playback or
+recording policy belongs to its runtime/controller; a host needs no replay-specific
+commands. [Replay recording](../../docs/guides/replay-recording.md) illustrates a consumer.

package/dist/extension.d.ts

@@ -15,6 +15,12 @@ export interface SupercodeConnectOptions {
      */
     unavailable?: string;
 }
+/** An external runtime handoff carries a private credential file, never a token in arguments. */
+export interface SupercodeRuntimeHandoff extends Omit<SupercodeConnectOptions, 'token' | 'unavailable'> {
+    baseUrl: string;
+    clientId: string;
+    credentialFile: string;
+}
 export interface SupercodeConnectionInfo {
     readonly id: string;
     readonly baseUrl: string;
@@ -22,6 +28,10 @@ export interface SupercodeConnectionInfo {
     readonly sessionId: string | null;
     readonly model: string | null;
     readonly turnState: 'idle' | 'busy' | null;
+    readonly connectionState: 'disconnected' | 'connected' | 'closed';
+    readonly viewReady: boolean;
+    readonly viewResource: string | null;
+    readonly cursor: number;
 }
 /** What `activate` returns: the door a host uses to hand over a connection. */
 export interface SupercodeFrontendApi {

package/dist/extension.js

@@ -87,6 +87,10 @@ class SupercodeFrontends {
             sessionId: connection.session.descriptor?.session_id ?? null,
             model: connection.session.descriptor?.model ?? null,
             turnState: connection.session.descriptor?.turn_state ?? null,
+            connectionState: connection.session.connection,
+            viewReady: connection.viewReady === true && connection.session.connection === 'connected',
+            viewResource: connection.viewResource ?? null,
+            cursor: connection.session.cursor,
         };
     }
     async connect(options, log) {
@@ -436,6 +440,37 @@ export async function activate(context) {
     // them, so they open as what they are: attachments, shown as their runtime
     // reports them, and never taken for the conversation the host manages.
     const attachedIds = new Set();
+    const savedAttachments = new Map(context.workspaceState.get('supercode.externalAttachments', [])
+        .map(entry => [entry.connectionId, entry]));
+    const restoringAttachments = new Map();
+    const attachmentSecretKey = (id) => `supercode.frontend.attachment:${id}`;
+    const saveAttachments = () => context.workspaceState.update('supercode.externalAttachments', [...savedAttachments.values()]);
+    const restoreAttachment = (id) => {
+        const existing = frontends.get(id);
+        if (existing)
+            return Promise.resolve(existing);
+        const pending = restoringAttachments.get(id);
+        if (pending)
+            return pending;
+        const saved = savedAttachments.get(id);
+        if (!saved)
+            return Promise.resolve(undefined);
+        const restoration = (async () => {
+            const token = saved.credentialFile ? await readCredentialFile(saved.credentialFile) : await context.secrets.get(attachmentSecretKey(id));
+            if (!token)
+                throw new Error('The saved runtime credential is unavailable. Attach to the runtime again.');
+            const connection = await frontends.connect({ ...saved, token }, log);
+            if (connection)
+                attachedIds.add(id);
+            return connection;
+        })().finally(() => restoringAttachments.delete(id));
+        restoringAttachments.set(id, restoration);
+        return restoration;
+    };
+    for (const id of savedAttachments.keys()) {
+        attachedIds.add(id);
+        await restoreAttachment(id).catch(error => log.warn(`Could not restore runtime attachment ${id}: ${String(error)}`));
+    }
     const managed = () => frontends.all.find((connection) => !attachedIds.has(connection.id));
     // The host runs one conversation at a time, so a running or waiting turn refuses a new or another chat. This is
     // the sentence that refusal says to the person; each caller picks the one place it is shown (see its uses).
@@ -448,7 +483,8 @@ export async function activate(context) {
             return `A turn is still running in the current chat. Let it finish or cancel it before ${action}.`;
     };
     // The attached runtime the person is looking at: the Chat names its harness, not the host's.
-    let focusedAttached;
+    const restoredFocus = context.workspaceState.get('supercode.focusedAttachment');
+    let focusedAttached = restoredFocus ? frontends.get(restoredFocus) : undefined;
     let approvalAvailable = false;
     context.subscriptions.push(frontends.onDidChange(() => {
         const active = managed();
@@ -661,7 +697,25 @@ export async function activate(context) {
         terminal.show();
     }));
     const restoring = new Map();
-    const connectionFor = async (resource, activate = true) => {
+    const connectionFor = async (resource, activate = true, token) => {
+        if (savedAttachments.has(resource.authority)) {
+            let attached;
+            while (!attached) {
+                if (token?.isCancellationRequested)
+                    throw new vscode.CancellationError();
+                try {
+                    attached = await restoreAttachment(resource.authority);
+                    if (!attached)
+                        throw new Error('This runtime attachment is no longer saved.');
+                }
+                catch (error) {
+                    log.warn(`Waiting for runtime attachment ${resource.authority}: ${String(error)}`);
+                    if (!token)
+                        throw error;
+                    await new Promise(resolve => setTimeout(resolve, 500));
+                }
+            }
+        }
         if (!controls) {
             const connection = frontends.get(resource.authority);
             if (!connection)
@@ -671,6 +725,7 @@ export async function activate(context) {
         const attached = attachedIds.has(resource.authority) ? frontends.get(resource.authority) : undefined;
         if (activate && focusedAttached !== attached) {
             focusedAttached = attached;
+            await context.workspaceState.update('supercode.focusedAttachment', attached?.id);
             controlsChanged.fire();
         }
         if (attached)
@@ -932,7 +987,7 @@ export async function activate(context) {
                 return undefined;
             }
         },
-        resolve: (resource) => connectionFor(resource, false),
+        resolve: (resource, token) => connectionFor(resource, false, token),
         attached: (connection) => attachedIds.has(connection.id),
         catalogue: () => controls?.state.sessions ?? [],
         bindings: boundId,
@@ -951,7 +1006,13 @@ export async function activate(context) {
         await connectionFor(resource);
         if (generation !== focusGeneration)
             return;
-        await revealManaged();
+        if (attachedIds.has(id)) {
+            if (!controls?.state.openSessionCommand)
+                throw new Error('The host cannot reveal this conversation.');
+            await vscode.commands.executeCommand(controls.state.openSessionCommand, resource.toString());
+        }
+        else
+            await revealManaged();
     }));
     context.subscriptions.push(vscode.commands.registerCommand('supercode.frontend.configure', async (supplied) => {
         if (supplied?.permissions) {
@@ -1391,7 +1452,17 @@ export async function activate(context) {
         await settings.update('baseUrl', baseUrl, vscode.ConfigurationTarget.Global);
         await context.secrets.store(secretKey(baseUrl), token);
         await connectFromSettings();
-    }), vscode.commands.registerCommand('supercode.frontend.connect', () => connectFromSettings()), 
+    }), vscode.commands.registerCommand('supercode.frontend.connect', async (handoff) => {
+        if (handoff === undefined)
+            return connectFromSettings();
+        if (!handoff || typeof handoff.baseUrl !== 'string' || typeof handoff.clientId !== 'string' || !handoff.clientId.trim() || typeof handoff.credentialFile !== 'string') {
+            throw new TypeError('A runtime handoff needs baseUrl, clientId and credentialFile.');
+        }
+        const token = await readCredentialFile(handoff.credentialFile);
+        const connection = await connectExternal({ baseUrl: handoff.baseUrl, token, clientId: handoff.clientId,
+            connectionId: handoff.connectionId, permissions: handoff.permissions, label: handoff.label }, handoff.credentialFile);
+        return connection ? frontends.info(connection) : undefined;
+    }), 
     // The create command the core's own `chatSessions/newSession` menu invokes
     // for this session type (`chatSessions.contribution.ts`
     // `_resolveCreateSubMenuCommandId`). It opens a chat on the supercode
@@ -1404,7 +1475,7 @@ export async function activate(context) {
         }
         const where = position === 'editor' ? 'editor' : 'sidebar';
         await vscode.commands.executeCommand(`workbench.action.chat.openNewChatSessionInPlace.${SESSION_SCHEME}`, where);
-    }), vscode.commands.registerCommand('supercode.frontend.disconnect', () => frontends.disconnect()), 
+    }), vscode.commands.registerCommand('supercode.frontend.disconnect', (id) => disconnectExternal(id)), 
     // The one door an answer button uses. It answers the runtime's pending
     // request through `frontend.v2.respond` and narrates itself, because a
     // click whose effect is invisible is a click nobody can trust.
@@ -1434,6 +1505,40 @@ export async function activate(context) {
                 : REQUESTED_PROPOSALS.map((name) => `${name} not granted: ${PROPOSAL_EFFECTS[name].without}`).join('\n'),
         });
     }));
+    async function connectExternal(options, credentialFile) {
+        const id = options.connectionId ?? options.clientId;
+        if (id && controls?.state.sessions.some(session => session.id === id))
+            throw new Error('An external runtime cannot replace a host-managed conversation.');
+        const existing = id ? frontends.get(id) : undefined;
+        if (existing && existing.baseUrl !== options.baseUrl)
+            throw new Error('This connection identity already belongs to another runtime.');
+        const connection = await frontends.connect(options, log);
+        if (connection && options.token) {
+            if (!credentialFile)
+                await context.secrets.store(attachmentSecretKey(connection.id), options.token);
+            savedAttachments.set(connection.id, { baseUrl: connection.baseUrl, clientId: options.clientId ?? connection.id,
+                connectionId: connection.id, permissions: [...connection.session.permissions], label: connection.label, credentialFile });
+            attachedIds.add(connection.id);
+            await saveAttachments();
+            controlsChanged.fire();
+        }
+        return connection;
+    }
+    async function disconnectExternal(id) {
+        const ids = id ? [id] : [...savedAttachments.keys()];
+        for (const target of ids) {
+            savedAttachments.delete(target);
+            attachedIds.delete(target);
+            await context.secrets.delete(attachmentSecretKey(target));
+            if (focusedAttached?.id === target)
+                focusedAttached = undefined;
+        }
+        await saveAttachments();
+        if (!focusedAttached)
+            await context.workspaceState.update('supercode.focusedAttachment', undefined);
+        await frontends.disconnect(id);
+        controlsChanged.fire();
+    }
     async function connectFromSettings() {
         const settings = vscode.workspace.getConfiguration('supercode.frontend');
         const baseUrl = settings.get('baseUrl')?.trim() || context.globalState.get(HANDED_OVER_KEY);
@@ -1444,16 +1549,11 @@ export async function activate(context) {
             log.info('Volter Harness: a base URL is configured but no token is stored; run Volter Harness: Set Runtime Token.');
             return;
         }
-        const connection = await frontends
-            .connect({ baseUrl, token, permissions: normalizePermissions(settings.get('permissions'), ['observe']) }, log)
+        await connectExternal({ baseUrl, token, permissions: normalizePermissions(settings.get('permissions'), ['observe']) })
             .catch((error) => {
             log.error(`Volter Harness could not attach to ${baseUrl}: ${String(error?.message ?? error)}`);
             return undefined;
         });
-        if (controls && connection) {
-            attachedIds.add(connection.id);
-            controlsChanged.fire();
-        }
     }
     /**
      * The handover path: a runtime (or a product that launched this editor's
@@ -1507,6 +1607,12 @@ export async function activate(context) {
     async function openResumedSession() {
         if (!granted.has('chatSessionsProvider'))
             return;
+        const focusedId = context.workspaceState.get('supercode.focusedAttachment');
+        const attached = focusedId ? frontends.get(focusedId) : undefined;
+        if (attached && controls?.state.openSessionCommand) {
+            await vscode.commands.executeCommand('supercode.frontend.openSession', attached.id);
+            return;
+        }
         if (controls) {
             await refreshSetup();
             return;
@@ -1554,10 +1660,10 @@ export async function activate(context) {
     context.subscriptions.push({ dispose: () => { setupDisposed = true; clearTimeout(setupTimer); } });
     return {
         connect: async (options) => {
-            const connection = await frontends.connect(options, log);
+            const connection = await connectExternal(options);
             return connection ? frontends.info(connection) : undefined;
         },
-        disconnect: (connectionId) => frontends.disconnect(connectionId),
+        disconnect: (connectionId) => disconnectExternal(connectionId),
         get connections() {
             return frontends.all.map((connection) => frontends.info(connection));
         },
@@ -1756,12 +1862,14 @@ function registerSessions(context, frontends, participant, granted, handler, his
             const boundHandler = (request, chatContext, stream, token) => handler(request, { ...chatContext, chatSessionContext: { chatSessionItem: { resource, label: 'Conversation' } } }, stream, token);
             // Only a native untitled resource can create a conversation. Existing
             // resources must resolve their exact saved binding; there is no fallback.
-            const connection = controls ? (resource.path.startsWith('/untitled-') && !controls.bindings(resource) ? undefined : await controls.resolve(resource)) : frontends.get(resource.authority);
+            const connection = controls ? (resource.path.startsWith('/untitled-') && !controls.bindings(resource) ? undefined : await controls.resolve(resource, token)) : frontends.get(resource.authority);
             if (token.isCancellationRequested)
                 throw new vscode.CancellationError();
             if (!connection) {
                 return { history: [], requestHandler: boundHandler };
             }
+            connection.viewReady = false;
+            connection.viewResource = resource.toString();
             if (controls && !controls.attached(connection)) {
                 controls.setPermission(resource, inputState.groups.find(group => group.id === 'permissions')?.selected?.id);
                 inputState.groups = controls.options(resource);
@@ -1813,6 +1921,9 @@ function registerSessions(context, frontends, participant, granted, handler, his
                 history.push(new turns.ChatResponseTurn(historyParts(oneRowPerToolCall(turn.parts ?? [])), {}, authorId));
             }
             const busy = connection.session.descriptor?.turn_state === 'busy';
+            const renderedCursor = connection.session.cursor;
+            if (!busy)
+                connection.viewReady = attached;
             return {
                 title: connection.label,
                 options: controls?.attached(connection) ? undefined : controls?.currentOptions(resource),
@@ -1838,9 +1949,10 @@ function registerSessions(context, frontends, participant, granted, handler, his
                                     canRespond: connection.session.descriptor?.actions.respond !== false,
                                 }), granted, state);
                                 watch?.sweep();
-                            });
+                            }, () => { connection.viewReady = true; }, renderedCursor);
                         }
                         finally {
+                            connection.viewReady = connection.session.descriptor?.turn_state !== 'busy';
                             watch?.dispose();
                         }
                     }

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export type { ChatGPTSignInWorkPhase, ChatGPTSignInOperation } from './chat-setu
 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';
+export type { SupercodeConnectOptions, SupercodeRuntimeHandoff, SupercodeConnectionInfo, SupercodeFrontendApi, } from './extension.js';

package/dist/native-session.d.ts

@@ -3,4 +3,4 @@ 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>;
+export declare function observeActiveResponse(session: Pick<VscodeFrontendSession, 'descriptor' | 'onEvent' | 'interrupt' | 'actions' | 'replay'>, token: CancellationToken, write: (event: FrontendEvent) => void, onSubscribed?: () => void, afterSequence?: number): Promise<void>;

package/dist/native-session.js

@@ -3,7 +3,7 @@ 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) {
+export async function observeActiveResponse(session, token, write, onSubscribed, afterSequence) {
     let unsubscribe = () => { };
     let cancellation;
     try {
@@ -13,10 +13,20 @@ export async function observeActiveResponse(session, token, write) {
                 if (cancelling)
                     return;
                 cancelling = true;
+                // Closing an observed view cannot interrupt a runtime that grants no
+                // interrupt action. Stop observing without inventing control authority.
+                if (!session.actions().interrupt) {
+                    resolve();
+                    return;
+                }
                 // Wait for the runtime acknowledgement; a stopped UI is not a stopped harness.
                 void session.interrupt().then(resolve, reject);
             };
-            unsubscribe = session.onEvent(event => {
+            let delivered = afterSequence ?? 0;
+            const consume = (event) => {
+                if (afterSequence !== undefined && event.sequence <= delivered)
+                    return;
+                delivered = event.sequence;
                 try {
                     write(event);
                 }
@@ -26,7 +36,14 @@ export async function observeActiveResponse(session, token, write) {
                 }
                 if (!cancelling && TURN_TERMINAL_KINDS.includes(event.kind))
                     resolve();
-            });
+            };
+            unsubscribe = session.onEvent(consume);
+            if (afterSequence !== undefined) {
+                for (const event of session.replay)
+                    if (event.sequence > afterSequence)
+                        consume(event);
+            }
+            onSubscribed?.();
             cancellation = token.onCancellationRequested(cancel);
             if (token.isCancellationRequested)
                 cancel();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/supercode-frontend-vscode",
   "displayName": "Volter Harness",
-  "version": "0.1.45",
+  "version": "0.1.46",
   "type": "module",
   "description": "VS Code chat-view frontend for an existing Volter Harness SDK runtime",
   "publisher": "volter-ai-dev",
@@ -190,7 +190,7 @@
   },
   "supercodeFrontendContract": {
     "name": "@volter/supercode-frontend",
-    "version": "0.2.7",
+    "version": "0.2.8",
     "mode": "generated-artifact"
   },
   "license": "MIT OR Apache-2.0"

package/vendor/supercode-frontend/contract.json

@@ -73,7 +73,7 @@
         "argument_hint": {"type": "string", "optional": true, "nullable": true}
       }
     },
-    "FrontendOperationKind": {"kind": "enum", "values": ["prompt", "file", "model", "session", "subagent", "image", "reduction"]},
+    "FrontendOperationKind": {"kind": "enum", "values": ["prompt", "file", "model", "session", "subagent", "image", "reduction", "replay"]},
     "FrontendOperationDescriptor": {
       "kind": "object",
       "fields": {
@@ -175,6 +175,10 @@
         "prompt": {
           "operation_id": {"type": "string"},
           "arguments": {"type": "string"}
+        },
+        "replay": {
+          "operation_id": {"type": "string"},
+          "control": {"type": "string"}
         }
       }
     },
@@ -182,7 +186,8 @@
       "kind": "tagged_union",
       "tag": "kind",
       "variants": {
-        "prompt": {"reply": {"type": "string"}}
+        "prompt": {"reply": {"type": "string"}},
+        "replay": {"status": {"type": "JsonValue"}}
       }
     },
     "RuntimeControllerLease": {

package/vendor/supercode-frontend/generated.d.mts

@@ -32,7 +32,7 @@ export interface FrontendCommandDescriptor {
   description: string | null;
   argument_hint?: string | null;
 }
-export type FrontendOperationKind = "prompt" | "file" | "model" | "session" | "subagent" | "image" | "reduction";
+export type FrontendOperationKind = "prompt" | "file" | "model" | "session" | "subagent" | "image" | "reduction" | "replay";
 export interface FrontendOperationDescriptor {
   id: string;
   kind: FrontendOperationKind;
@@ -84,8 +84,8 @@ export interface FrontendAttachSnapshot {
 export type FrontendApprovalDecision = "deny" | "allow" | "allow_for_session";
 export type FrontendElicitationAction = "accept" | "decline" | "cancel";
 export type FrontendResponse = { kind: "approval"; request_id: number; decision: FrontendApprovalDecision } | { kind: "elicitation"; request_id: number; action: FrontendElicitationAction; content?: JsonValue | null } | { kind: "other"; request_id: number; action: FrontendElicitationAction; content?: JsonValue | null };
-export type FrontendOperationInvocation = { kind: "prompt"; operation_id: string; arguments: string };
-export type FrontendOperationResult = { kind: "prompt"; reply: string };
+export type FrontendOperationInvocation = { kind: "prompt"; operation_id: string; arguments: string } | { kind: "replay"; operation_id: string; control: string };
+export type FrontendOperationResult = { kind: "prompt"; reply: string } | { kind: "replay"; status: JsonValue };
 export interface RuntimeControllerLease {
   client_id: string;
   expires_at_ms: number;

package/vendor/supercode-frontend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/supercode-frontend",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "type": "module",
   "description": "Generated language-neutral attachment client for Volter Harness SDK runtimes",
   "exports": {