@volter/supercode-frontend-vscode 0.1.16 → 0.1.17

package/README.md

@@ -11,6 +11,88 @@ package or npm.
 
 ## Native chat controls
 
+The optional host-controls state can include `setup: { ready, actions, reason,
+cwd }`. Each action supplies `kind` (`login` or `install`), `harness`, `name` and
+the exact `command` shown before execution. Chat renders native buttons, with
+**Sign in with ChatGPT** for Codex and the reported name for other harnesses.
+Clicking asks the host's authenticated `/setup` door to revalidate `{ kind,
+harness }` and return the action plus a structured `{ program, arguments, cwd, env? }`
+terminal launch. Absolute executables and an optional host-authored PATH keep
+the terminal on the same installation and discovery path as the host's probe.
+It runs directly as the integrated terminal's process, without typing a shell
+command; credentials and
+browser interaction belong to the harness. Failed or cancelled processes can be
+retried, and closing a terminal never counts as successful authentication.
+
+While setup is not ready, Chat refreshes `/state` every three seconds and exposes
+**Check again**. When the host returns a ready runtime connection, it attaches
+and reveals that conversation without a reload. Polling only finishes after both
+attachment and the host's native reveal command succeed for that same session
+and runtime URL. A transient attach/reveal failure stays pending and is retried;
+**Check again** retries that handoff even when the host already reports ready.
+Changed setup resources refresh
+Code-OSS's cached status history after an install. Hosts without these optional
+fields keep the existing runtime-attachment behavior.
+
+`starterPrompts?: {label: string; prompt: string}[]` is project data supplied by
+the host. An eligible new conversation exposes at most three short command links
+in the default participant's native welcome content, outside the transcript.
+The host's `fillInputCommand` receives the exact native session resource and full
+prompt and must return `{sessionResource, input}` after filling that existing
+widget, without submitting. A missing or mismatched receipt is an error.
+The untargeted partial-query command is not used. Links never send or write a turn.
+Presentation and clicks use the same `starterEligibility` calculation; runtime
+and host state changes update the welcome message, and a user turn clears it.
+Native Chat also hides its welcome surface immediately when a request is added.
+Eligibility requires a successful attachment, an idle runtime, no pending request,
+no saved/canonical non-system messages or truncated saved history, and no observed
+user turn. Accepted-input events (`user_message`, `turn_started`) and busy snapshots
+record turn evidence that survives re-attachment and replay eviction. Setup/status
+events can advance cursors without disqualifying a new conversation; system-only
+history also stays eligible. The checks run again after
+project data loads and before filling; a failed attachment never offers starters.
+`supercode.frontend.status(true)` includes each connection's `starterEligibility`:
+attachment state, turn state, pending count, saved-history presence/truncation/count
+and roles, canonical count/roles, sticky turn evidence, both cursors, replay count
+and kinds, active host ID, host busy state, connection identity check, and rejection
+reasons. `lastStarterAttempt` preserves the exact post-attachment guard snapshot
+and native binding from the latest click. These contain no message bodies or tokens.
+A rejected click names its failed conditions instead of a generic new/idle error.
+The pinned Chat session API exposes immutable history, without withdrawal or
+live enablement of a rendered command part. Starters therefore never enter history.
+`defaultChatParticipant.additionalWelcomeMessage` supplies trusted Markdown with
+only `supercode.frontend.fillStarter` allowed; labels are escaped and command
+arguments are encoded. Hosts without that proposal get no starter offer rather
+than permanent transcript buttons. Existing setup actions keep their native status
+presentation. No new workbench API or editor-side contribution is required.
+The pinned Code-OSS `f16dc165` has no `suggestedPrompts` field in either
+`vscode.proposed.defaultChatParticipant.d.ts` or the internal
+`IChatViewWelcomeContent`. `ChatViewWelcomePart` renders `additionalMessage` as
+Markdown; its optional `firstLinkToButton` converts only one anchor and the
+participant welcome never enables that option. The editor's native overlay can
+render standalone trusted command links as welcome buttons without a new extension
+API; other hosts keep Markdown links. The two introductory lines live together in
+this extension's `package.json`: `chatSessions.welcomeMessage` and
+`supercodeFrontendWelcome.starterIntroduction`. Hosts own their project prompt data.
+If `starterPromptsPending` is true, the project configuration is still loading.
+Empty-conversation resolution refreshes the host until that declaration arrives
+(cancellable, with a 30-second timeout), so native Chat does not cache an empty
+offer before the project adapter loads.
+
+W32/W37 passed starter filling and W37 passed healthy refresh with draft retention.
+W44 passed a real boost turn and exposed a presentation defect: transcript starter
+buttons remained after the turn even though the guard rejected them. W50 passed
+the native welcome fix at `29d8fac99`: all three pointer fills, one real HUD turn,
+first-turn disappearance, return-to-idle suppression, and no starters when reopening
+the earlier conversation with seven history entries. The shorter introductory copy
+is source-only; it needs a frontend build plus a workbench overlay copy.
+The accompanying native button and New Session repairs require a Code-OSS compile.
+W50 also found that the generic native New Session action
+bypasses this provider's creation command; its owning host must route that action
+through `chatSessions/newSession` rather than opening an unbound untitled resource.
+Signed-out/install transitions and failed-discovery/attachment recovery remain
+unverified live. A published frontend and rebuilt workbench are needed for npx users.
+
 A bundling host can expose a private lifecycle endpoint through
 `SUPERCODE_FRONTEND_HOST_URL` and `SUPERCODE_FRONTEND_HOST_CREDENTIAL_FILE`.
 The endpoint must be loopback HTTP and the credential follows the runtime credential-file

package/dist/chat-setup.d.ts

@@ -0,0 +1,6 @@
+/** Native Chat presentation; the host supplies inventory, terminal actions and project data. */
+import * as vscode from 'vscode';
+import type { ChatSetupState, ChatStarterPrompt } from './host-controls.js';
+export declare function setupParts(setup: ChatSetupState): Array<vscode.ChatResponseMarkdownPart | vscode.ChatResponseCommandButtonPart>;
+/** Welcome content is owned by the empty-state renderer, never transcript history. */
+export declare function starterWelcome(prompts: readonly ChatStarterPrompt[], session: string, resource: string, introduction: string): vscode.MarkdownString;

package/dist/chat-setup.js

@@ -0,0 +1,29 @@
+/** Native Chat presentation; the host supplies inventory, terminal actions and project data. */
+import * as vscode from 'vscode';
+export function setupParts(setup) {
+    const parts = [
+        new vscode.ChatResponseMarkdownPart('Sign in to use Chat. Complete sign-in in the terminal and browser.'),
+    ];
+    for (const action of setup.actions) {
+        const title = action.kind === 'install' ? `Install ${action.name}`
+            : action.harness === 'codex' ? 'Sign in with ChatGPT' : `Sign in with ${action.name}`;
+        parts.push(new vscode.ChatResponseMarkdownPart(`Runs: \`${action.command.replace(/`/g, '\\`')}\``));
+        parts.push(new vscode.ChatResponseCommandButtonPart({ title, command: 'supercode.frontend.setup', arguments: [action.kind, action.harness] }));
+    }
+    if (!setup.actions.length) {
+        parts.push(new vscode.ChatResponseMarkdownPart(setup.reason || 'No sign-in action is available.'));
+    }
+    parts.push(new vscode.ChatResponseCommandButtonPart({ title: 'Check again', command: 'supercode.frontend.refreshSetup' }));
+    return parts;
+}
+/** Welcome content is owned by the empty-state renderer, never transcript history. */
+export function starterWelcome(prompts, session, resource, introduction) {
+    const message = new vscode.MarkdownString().appendText(introduction).appendMarkdown('\n\n');
+    message.isTrusted = { enabledCommands: ['supercode.frontend.fillStarter'] };
+    for (const [index, starter] of prompts.slice(0, 3).entries()) {
+        const args = encodeURIComponent(JSON.stringify([session, index, resource]));
+        message.appendMarkdown('[').appendText(starter.label)
+            .appendMarkdown(`](command:supercode.frontend.fillStarter?${args})\n\n`);
+    }
+    return message;
+}

package/dist/extension.js

@@ -2,6 +2,7 @@ import { resolveSessionBinding } from './bindings.js';
 import { withTextContext } from './context.js';
 import { randomUUID } from 'node:crypto';
 import { ChatHostControls, runtimeIdentity, harnessDisplayName, turnPermission } from './host-controls.js';
+import { setupParts, starterWelcome } from './chat-setup.js';
 import * as vscode from 'vscode';
 import { createFrontendClient } from './client.js';
 import { readCredentialFile } from './credential.js';
@@ -32,6 +33,44 @@ const ENV = Object.freeze({
      */
     unavailable: 'SUPERCODE_FRONTEND_UNAVAILABLE',
 });
+/** Transport progress includes setup events; it is not a user-turn count. */
+function conversationEligibility(connection) {
+    const session = connection.session;
+    const inputs = {
+        attachmentState: session.connection,
+        turnState: session.descriptor?.turn_state ?? null,
+        pendingRequestCount: session.pendingRequests.size,
+        historyTruncated: connection.historyTruncated ?? false,
+        persistedHistoryLoaded: connection.persistedHistory !== undefined,
+        persistedHistoryCount: connection.persistedHistory?.length ?? 0,
+        persistedHistoryRoles: connection.persistedHistory?.map(message => message.role) ?? [],
+        canonicalHistoryCount: session.history.length,
+        canonicalHistoryRoles: session.history.map(message => message.role),
+        hasUserTurn: session.hasUserTurn,
+        historyCursor: session.historyCursor,
+        eventCursor: session.cursor,
+        replayLength: session.replay.length,
+        replayKinds: [...new Set(session.replay.map(event => event.kind))],
+        nativeEventKinds: [...new Set(session.replay.filter(event => event.kind === 'native_event')
+                .map(event => event.payload?.kind).filter(kind => typeof kind === 'string'))],
+    };
+    const reasons = [];
+    if (inputs.attachmentState !== 'connected')
+        reasons.push(`attachmentState=${inputs.attachmentState}`);
+    if (inputs.turnState !== 'idle')
+        reasons.push(`turnState=${inputs.turnState}`);
+    if (inputs.pendingRequestCount)
+        reasons.push(`pendingRequestCount=${inputs.pendingRequestCount}`);
+    if (inputs.historyTruncated)
+        reasons.push('saved history is truncated');
+    if (inputs.persistedHistoryRoles.some(role => role !== 'system'))
+        reasons.push('saved history contains a turn');
+    if (inputs.canonicalHistoryRoles.some(role => role !== 'system'))
+        reasons.push('canonical history contains a turn');
+    if (inputs.hasUserTurn)
+        reasons.push('a user turn has been observed');
+    return { ...inputs, eligible: reasons.length === 0, reasons };
+}
 function normalizePermissions(value, fallback) {
     const raw = Array.isArray(value)
         ? value.map(String)
@@ -324,6 +363,24 @@ export async function activate(context) {
     const boundId = (resource) => resolveSessionBinding(resource, controls?.state.sessions ?? [], resourceBindings);
     let applying = Promise.resolve();
     const frontends = new SupercodeFrontends();
+    const starterEligibility = (connection) => {
+        const conversation = conversationEligibility(connection);
+        const activeSession = controls?.state.activeSession ?? null;
+        const hostBusy = Boolean(controls?.state.busy);
+        const connectionMatches = frontends.get(connection.id) === connection;
+        const reasons = [...conversation.reasons];
+        if (!controls)
+            reasons.push('host controls unavailable');
+        if (activeSession !== connection.id)
+            reasons.push(`activeSession=${activeSession}; expected ${connection.id}`);
+        if (hostBusy)
+            reasons.push('hostBusy=true');
+        if (!connectionMatches)
+            reasons.push('connection was replaced');
+        return { ...conversation, controlsAvailable: Boolean(controls), connectionId: connection.id, activeSession, hostBusy, connectionMatches,
+            eligible: reasons.length === 0, reasons };
+    };
+    const lastStarterAttempts = new Map();
     // Runtimes attached by address ("Set Runtime Token", "Attach to Runtime")
     // beside a host's managed conversation. The host's catalogue does not know
     // them, so they open as what they are: attachments, shown as their runtime
@@ -332,6 +389,28 @@ export async function activate(context) {
     const managed = () => frontends.all.find((connection) => !attachedIds.has(connection.id));
     // The attached runtime the person is looking at: the Chat names its harness, not the host's.
     let focusedAttached;
+    const welcomeParticipants = new Set();
+    const welcomeValues = new WeakMap();
+    const starterResources = new Map();
+    const updateStarterWelcome = () => {
+        if (!granted.has('defaultChatParticipant'))
+            return;
+        const connection = managed();
+        const prompts = controls?.state.starterPrompts ?? [];
+        // This is the click guard's exact state, including host activity and connection
+        // identity. A later idle state must not revive an offer after a user turn.
+        const message = connection && !focusedAttached && !controls?.state.starterPromptsPending
+            && prompts.length && starterEligibility(connection).eligible
+            ? starterWelcome(prompts, connection.id, starterResources.get(connection.id) ?? sessionResource(connection).toString(), context.extension.packageJSON.supercodeFrontendWelcome.starterIntroduction)
+            : new vscode.MarkdownString('');
+        for (const participant of welcomeParticipants) {
+            if (welcomeValues.get(participant) === message.value)
+                continue;
+            participant.additionalWelcomeMessage = message;
+            welcomeValues.set(participant, message.value);
+        }
+    };
+    context.subscriptions.push(frontends.onDidChange(updateStarterWelcome), controlsChanged.event(updateStarterWelcome));
     let approvalAvailable = false;
     context.subscriptions.push(frontends.onDidChange(() => {
         const active = managed();
@@ -392,8 +471,11 @@ export async function activate(context) {
             throw new Error('The requested conversation has no runtime connection.');
         const id = controls.state.activeSession;
         const existing = frontends.get(id);
-        if (existing && existing.baseUrl === env.SUPERCODE_FRONTEND_URL)
+        if (existing && existing.baseUrl === env.SUPERCODE_FRONTEND_URL && existing.session.connection !== 'closed') {
+            if (existing.session.connection !== 'connected')
+                await existing.session.attach();
             return existing;
+        }
         for (const connection of frontends.all.filter((entry) => !attachedIds.has(entry.id)))
             await frontends.disconnect(connection.id);
         const connection = await frontends.connect({ connectionId: id, baseUrl: env.SUPERCODE_FRONTEND_URL,
@@ -403,12 +485,124 @@ export async function activate(context) {
             throw new Error('Could not connect to the requested conversation.');
         return connection;
     };
+    let setupHandoff;
+    const setupHandoffComplete = () => {
+        const id = controls?.state.activeSession;
+        const connection = id ? frontends.get(id) : undefined;
+        return Boolean(setupHandoff && setupHandoff.id === id
+            && setupHandoff.baseUrl === controls?.state.connection?.SUPERCODE_FRONTEND_URL
+            && connection?.baseUrl === setupHandoff.baseUrl && connection.session.connection === 'connected');
+    };
     const revealManaged = async () => {
         const id = controls?.state.activeSession;
         if (!id || !controls?.state.openSessionCommand)
             throw new Error('The host cannot reveal this conversation.');
         await vscode.commands.executeCommand(controls.state.openSessionCommand, vscode.Uri.from({ scheme: SESSION_SCHEME, authority: id, path: '/conversation' }).toString());
+        const connection = frontends.get(id);
+        if (controls.state.activeSession !== id || !connection || connection.session.connection !== 'connected'
+            || connection.baseUrl !== controls.state.connection?.SUPERCODE_FRONTEND_URL) {
+            throw new Error('The conversation changed or disconnected before setup could reveal it.');
+        }
+        // Host readiness alone is not completion: the native reveal must succeed too.
+        setupHandoff = { id, baseUrl: connection.baseUrl };
+    };
+    let setupFingerprint = '';
+    const revealSetup = async () => {
+        if (!controls?.state.setup || controls.state.setup.ready || !controls.state.openSessionCommand)
+            return;
+        const fingerprint = JSON.stringify(controls.state.setup);
+        if (setupFingerprint === fingerprint)
+            return;
+        setupFingerprint = fingerprint;
+        // A changed resource avoids Code-OSS reusing cached status history after an install.
+        try {
+            await vscode.commands.executeCommand(controls.state.openSessionCommand, vscode.Uri.from({ scheme: SESSION_SCHEME, path: UNAVAILABLE_PATH, query: encodeURIComponent(fingerprint) }).toString());
+        }
+        catch (error) {
+            setupFingerprint = '';
+            throw error;
+        }
     };
+    let refreshingSetup;
+    const refreshSetup = () => {
+        refreshingSetup ??= (async () => {
+            if (!controls)
+                return;
+            await controls.refresh();
+            if (controls.state.setup?.ready) {
+                await connectManaged();
+                controlsChanged.fire();
+                if (!setupHandoffComplete())
+                    await revealManaged();
+            }
+            else {
+                setupHandoff = undefined;
+                controlsChanged.fire();
+                await revealSetup();
+            }
+        })().finally(() => { refreshingSetup = undefined; });
+        return refreshingSetup;
+    };
+    const setupTerminals = new Map();
+    context.subscriptions.push(vscode.window.onDidCloseTerminal(terminal => {
+        for (const [key, value] of setupTerminals)
+            if (value === terminal)
+                setupTerminals.delete(key);
+    }));
+    context.subscriptions.push(vscode.commands.registerCommand('supercode.frontend.refreshSetup', refreshSetup));
+    context.subscriptions.push(vscode.commands.registerCommand('supercode.frontend.setup', async (kind, harness) => {
+        if (!controls)
+            throw new Error('This host does not expose sign-in.');
+        const key = `${kind}/${harness}`;
+        const existing = setupTerminals.get(key);
+        if (existing && existing.exitStatus === undefined) {
+            existing.show();
+            return;
+        }
+        await controls.refresh();
+        const offered = controls.state.setup?.actions.find(a => a.kind === kind && a.harness === harness);
+        if (!offered) {
+            await refreshSetup();
+            throw new Error('This setup action is no longer available.');
+        }
+        const action = await controls.setup(kind, harness);
+        if (action.command !== offered.command)
+            throw new Error('The setup command changed. Check again before running it.');
+        const terminal = vscode.window.createTerminal({ name: `${action.name} · ${kind === 'login' ? 'sign in' : 'install'}`,
+            cwd: action.cwd, shellPath: action.program, shellArgs: action.arguments, env: action.env });
+        setupTerminals.set(key, terminal);
+        terminal.show();
+    }));
+    context.subscriptions.push(vscode.commands.registerCommand('supercode.frontend.fillStarter', async (session, index, nativeResource) => {
+        if (!controls || !Number.isInteger(index) || index < 0 || index > 2)
+            throw new Error('Invalid starter selection.');
+        const connection = frontends.get(session);
+        if (!connection)
+            throw new Error(`Starter prompt unavailable: connection ${session} is absent.`);
+        const resource = nativeResource ? vscode.Uri.parse(nativeResource)
+            : vscode.Uri.from({ scheme: SESSION_SCHEME, authority: session, path: '/conversation' });
+        if (boundId(resource) !== session)
+            throw new Error('The starter has no matching conversation binding.');
+        await connection.session.attach();
+        const guard = starterEligibility(connection);
+        lastStarterAttempts.set(session, { at: new Date().toISOString(), resource: resource.toString(),
+            boundSession: boundId(resource), guard });
+        while (lastStarterAttempts.size > 50)
+            lastStarterAttempts.delete(lastStarterAttempts.keys().next().value);
+        if (!guard.eligible)
+            throw new Error(`Starter prompt unavailable: ${guard.reasons.join('; ')}.`);
+        const prompt = controls.state.starterPrompts?.[index]?.prompt;
+        if (!prompt)
+            throw new Error('This starter is no longer available.');
+        if (!controls.state.fillInputCommand)
+            throw new Error('This host does not support filling a conversation draft.');
+        // The host addresses the existing native widget, never the default participant or last focus.
+        const receipt = await vscode.commands.executeCommand(controls.state.fillInputCommand, resource.toString(), prompt);
+        if (!receipt || receipt.sessionResource !== resource.toString() || receipt.input !== prompt) {
+            throw new Error('Chat did not confirm the requested draft.');
+        }
+        return receipt;
+    }));
     const connectionFor = async (resource) => {
         if (!controls) {
             const connection = frontends.get(resource.authority);
@@ -500,6 +694,25 @@ export async function activate(context) {
         attached: (connection) => attachedIds.has(connection.id),
         catalogue: () => controls?.state.sessions ?? [],
         bindings: boundId,
+        setup: () => controls?.state.setup,
+        prepareStarters: async (session, resource, token) => {
+            // Project configuration can arrive after the runtime connects. Wait for
+            // its real answer before publishing the conversation's welcome actions.
+            const deadline = Date.now() + 30_000;
+            await controls?.refresh();
+            while (controls?.state.starterPromptsPending) {
+                if (token.isCancellationRequested)
+                    throw new vscode.CancellationError();
+                if (Date.now() >= deadline)
+                    throw new Error('Project configuration is still loading. Reopen Chat once the project is ready.');
+                await new Promise(resolve => setTimeout(resolve, 250));
+                await controls.refresh();
+            }
+            if (token.isCancellationRequested)
+                throw new vscode.CancellationError();
+            starterResources.set(session, resource);
+            controlsChanged.fire();
+        },
     };
     context.subscriptions.push(vscode.commands.registerCommand('supercode.frontend.activateSession', async (resource) => { await connectionFor(vscode.Uri.parse(resource)); }));
     context.subscriptions.push(vscode.commands.registerCommand('supercode.frontend.openSession', async (id) => {
@@ -608,6 +821,11 @@ export async function activate(context) {
     const handler = async (request, chatContext, stream, token) => {
         await applying;
         const requestedResource = chatContext.chatSessionContext?.chatSessionItem?.resource;
+        if (controls?.state.setup && !controls.state.setup.ready) {
+            for (const part of setupParts(controls.state.setup))
+                stream.push(part);
+            return {};
+        }
         const connection = requestedResource
             ? await connectionFor(requestedResource)
             : controls ? undefined : managed();
@@ -657,6 +875,8 @@ export async function activate(context) {
             const participant = vscode.chat.createChatParticipant(id, handler);
             participant.iconPath = icon();
             participants.push(participant);
+            welcomeParticipants.add(participant);
+            updateStarterWelcome();
             context.subscriptions.push(participant);
         }
         catch (error) {
@@ -679,6 +899,8 @@ export async function activate(context) {
                     ? vscode.chat.createDynamicChatParticipant(SESSION_SCHEME, { name: current.name.replace(/[^a-zA-Z0-9]/g, ''), fullName: current.name, publisherName: 'Volter', description: 'Ask a question or describe a task' }, handler)
                     : vscode.chat.createChatParticipant(SESSION_SCHEME, handler);
                 participant.iconPath = icon();
+                welcomeParticipants.add(participant);
+                updateStarterWelcome();
                 return participant;
             };
             let sessionParticipant = makeParticipant();
@@ -687,6 +909,7 @@ export async function activate(context) {
                 if (participantKey() === previousIdentity)
                     return;
                 previousIdentity = participantKey();
+                welcomeParticipants.delete(sessionParticipant);
                 sessionParticipant.dispose();
                 sessionParticipant = makeParticipant();
                 for (const p of participants)
@@ -788,7 +1011,16 @@ export async function activate(context) {
         if (controls)
             await controls.refresh();
         if (inspect === true)
-            return { connections: frontends.all.map(c => ({ ...frontends.info(c), permissions: [...c.session.permissions], pendingRequests: [...c.session.pendingRequests.values()] })), selection: controls?.state.selection, activeSession: controls?.state.activeSession, busy: Boolean(controls?.state.busy || frontends.all.some(c => c.session.descriptor?.turn_state === 'busy' || c.session.pendingRequests.size)), sessions: controls?.state.sessions, permission: currentOptions().permissions, identity: identity() };
+            return {
+                connections: frontends.all.map(c => ({ ...frontends.info(c), permissions: [...c.session.permissions],
+                    pendingRequests: [...c.session.pendingRequests.values()], starterEligibility: starterEligibility(c),
+                    lastStarterAttempt: lastStarterAttempts.get(c.id) ?? null })),
+                selection: controls?.state.selection, activeSession: controls?.state.activeSession,
+                busy: Boolean(controls?.state.busy || frontends.all.some(c => c.session.descriptor?.turn_state === 'busy' || c.session.pendingRequests.size)),
+                setupHandoff: { hostReady: controls?.state.setup?.ready ?? null, complete: setupHandoffComplete(),
+                    revealed: setupHandoff ?? null },
+                sessions: controls?.state.sessions, permission: currentOptions().permissions, identity: identity(),
+            };
         const rows = frontends.all.map((connection) => {
             const info = frontends.info(connection);
             return `${info.label} · ${info.baseUrl} · ${info.model ?? 'unknown model'} · ${info.turnState ?? 'unattached'}`;
@@ -875,6 +1107,10 @@ export async function activate(context) {
         if (!granted.has('chatSessionsProvider'))
             return;
         if (controls) {
+            if (controls.state.setup && !controls.state.setup.ready) {
+                await revealSetup();
+                return;
+            }
             try {
                 await revealManaged();
             }
@@ -906,8 +1142,21 @@ export async function activate(context) {
     // NOT awaited: this opens an editor, and activation must return before the
     // workbench will run one. Awaiting it here left activation hanging and the
     // panel on "Loading…" — observed.
-    const opening = setTimeout(() => void openResumedSession(), 500);
+    const opening = setTimeout(() => void openResumedSession().catch(error => log.warn(`Could not reveal Chat: ${String(error)}`)), 500);
     context.subscriptions.push({ dispose: () => clearTimeout(opening) });
+    // Retry until host readiness has completed both attachment AND native reveal.
+    // A transient failure in either step leaves the handoff pending, even if ready=true.
+    let setupTimer;
+    let setupDisposed = false;
+    const pollSetup = () => {
+        if (setupDisposed || !controls?.state.setup || (controls.state.setup.ready && setupHandoffComplete()))
+            return;
+        setupTimer = setTimeout(() => {
+            void refreshSetup().catch(error => log.warn(`Could not refresh sign-in: ${String(error)}`)).finally(pollSetup);
+        }, 3000);
+    };
+    pollSetup();
+    context.subscriptions.push({ dispose: () => { setupDisposed = true; clearTimeout(setupTimer); } });
     return {
         connect: async (options) => {
             const connection = await frontends.connect(options, log);
@@ -1053,7 +1302,7 @@ function registerSessions(context, frontends, participant, granted, handler, con
     const unavailableItem = () => {
         if (!frontends.unavailable || frontends.all.length > 0)
             return undefined;
-        const item = controller.createChatSessionItem(unavailableResource(), 'Volter Harness · no runtime');
+        const item = controller.createChatSessionItem(unavailableResource(), controls?.setup() ? 'Sign in to Chat' : 'Volter Harness · no runtime');
         item.description = frontends.unavailable.split('\n')[0];
         item.status = vscode.ChatSessionStatus.Failed;
         return item;
@@ -1122,10 +1371,10 @@ function registerSessions(context, frontends, participant, granted, handler, con
                 // the session opens, with no request behind it and nothing to wait
                 // for — which is the whole point, since the person has not typed.
                 return {
-                    title: 'Volter Harness · no runtime',
+                    title: controls?.setup() ? 'Sign in to Chat' : 'Volter Harness · no runtime',
                     history: [
                         new turns.ChatRequestTurn(STATUS_MARKER_PROMPT, undefined, [], participant.id, []),
-                        new turns.ChatResponseTurn([new vscode.ChatResponseMarkdownPart(unavailableMarkdown(frontends.unavailable))], {}, participant.id),
+                        new turns.ChatResponseTurn(controls?.setup() ? setupParts(controls.setup()) : [new vscode.ChatResponseMarkdownPart(unavailableMarkdown(frontends.unavailable))], {}, participant.id),
                     ],
                     requestHandler: boundHandler,
                 };
@@ -1145,8 +1394,9 @@ function registerSessions(context, frontends, participant, granted, handler, con
             // `state.history`), so the copy taken when this window attached is
             // stale as soon as a turn runs. The generated client reuses the
             // already-open event stream, so this is a snapshot, not a reconnect.
-            await connection.session.attach().catch(() => {
+            const attached = await connection.session.attach().then(() => true).catch(() => {
                 // An unreachable runtime replays what this window last saw.
+                return false;
             });
             // The attach snapshot IS the session's history: the runtime's own
             // canonical transcript, replayed as turns.
@@ -1184,6 +1434,12 @@ function registerSessions(context, frontends, participant, granted, handler, con
                 }
                 history.push(new turns.ChatResponseTurn(historyParts(oneRowPerToolCall(turn.parts ?? [])), {}, participant.id));
             }
+            // The public API cannot withdraw a rendered history command part. Keep
+            // starters in the default participant's native welcome content instead:
+            // Chat hides that whole surface as soon as the first request is added.
+            if (attached && history.length === 0 && !controls?.attached(connection) && controls) {
+                await controls.prepareStarters(connection.id, resource.toString(), _token);
+            }
             const busy = connection.session.descriptor?.turn_state === 'busy';
             return {
                 title: connection.label,

package/dist/host-controls.d.ts

@@ -10,6 +10,10 @@ export interface ChatChoice {
     name: string;
     description?: string;
 }
+export interface ChatStarterPrompt {
+    label: string;
+    prompt: string;
+}
 export interface ManagedChatSession {
     id: string;
     selection: ChatSelection;
@@ -17,11 +21,28 @@ export interface ManagedChatSession {
     title: string;
     created: number;
 }
+/** Host-owned operations. The frontend displays commands before the person runs them. */
+export interface ChatSetupAction {
+    kind: 'login' | 'install';
+    harness: string;
+    name: string;
+    command: string;
+}
+export interface ChatSetupState {
+    ready: boolean;
+    actions: ChatSetupAction[];
+    reason: string | null;
+    cwd: string;
+}
 export interface HostState {
     history?: ChatMessage[];
     historyTruncated?: boolean;
     activeSession: string | null;
     openSessionCommand?: string;
+    /** Fill the composer of an exact native session; returns {sessionResource, input}. */
+    fillInputCommand?: string;
+    /** The native renderer supports a leading response with no visible user request. */
+    responseOnlyHistory?: boolean;
     sessions: ManagedChatSession[];
     selection: ChatSelection;
     connection?: Record<string, string>;
@@ -31,6 +52,10 @@ export interface HostState {
     busy: boolean;
     actualModel?: string | null;
     configurable: boolean;
+    setup?: ChatSetupState;
+    starterPrompts?: ChatStarterPrompt[];
+    /** The host's project configuration has not finished loading yet. */
+    starterPromptsPending?: boolean;
 }
 export interface HostSelectionResult extends HostState {
     connection: Record<string, string>;
@@ -45,6 +70,12 @@ export declare class ChatHostControls {
     select(selection: ChatSelection): Promise<HostSelectionResult>;
     remember(id: string, nativeId: string): Promise<void>;
     open(id: string): Promise<HostSelectionResult>;
+    setup(kind: ChatSetupAction['kind'], harness: string): Promise<ChatSetupAction & {
+        cwd: string;
+        program: string;
+        arguments: string[];
+        env?: Record<string, string>;
+    }>;
     private request;
 }
 /** Approval policy is captured for one turn, never inferred from connection privileges. */

package/dist/host-controls.js

@@ -31,6 +31,9 @@ export class ChatHostControls {
         this.state = result;
         return result;
     }
+    async setup(kind, harness) {
+        return this.request('/setup', { kind, harness });
+    }
     async request(path, selection) {
         const response = await fetch(this.baseUrl + path, {
             method: selection ? 'POST' : 'GET', headers: { Authorization: `Bearer ${this.credential}`, 'Content-Type': 'application/json' },

package/dist/session.d.ts

@@ -77,6 +77,8 @@ export declare class VscodeFrontendSession {
     history: ChatMessage[];
     historyCursor: number;
     cursor: number;
+    /** Semantic evidence, retained even when replay is evicted or re-attached. */
+    hasUserTurn: boolean;
     /**
      * Every event this attachment has seen, in order — NOT just the last
      * snapshot's. A re-attach asks `afterSequence: cursor`, so its `replay` is

package/dist/session.js

@@ -44,6 +44,8 @@ export class VscodeFrontendSession {
     history = [];
     historyCursor = 0;
     cursor = 0;
+    /** Semantic evidence, retained even when replay is evicted or re-attached. */
+    hasUserTurn = false;
     /**
      * Every event this attachment has seen, in order — NOT just the last
      * snapshot's. A re-attach asks `afterSequence: cursor`, so its `replay` is
@@ -103,6 +105,8 @@ export class VscodeFrontendSession {
             descriptor: structuredClone(snapshot.descriptor),
             pendingRequests: new Map([...this.pendingRequests].map(([id, request]) => [id, structuredClone(request)])),
             cursor: Math.max(this.cursor, snapshot.history_cursor),
+            hasUserTurn: this.hasUserTurn || snapshot.descriptor.turn_state === 'busy'
+                || snapshot.history.some(message => message.role !== 'system'),
         };
         // Validate and project the whole attachment before any observable field
         // moves or a live listener is registered.
@@ -125,6 +129,7 @@ export class VscodeFrontendSession {
         this.appendTranscript(structuredClone(snapshot.replay));
         this.pendingRequests = staged.pendingRequests;
         this.cursor = staged.cursor;
+        this.hasUserTurn = staged.hasUserTurn;
         this.connection = 'connected';
         this.attachedAtMs ??= Date.now();
         if (!this.#subscribed) {
@@ -252,6 +257,11 @@ export class VscodeFrontendSession {
             throw new EventSequenceGapError(state.cursor + 1, event.sequence);
         }
         state.cursor = event.sequence;
+        // Hosted runtimes publish user_message + turn_started when accepting input.
+        // Native init/status notifications also consume sequence numbers, but are
+        // not user turns. Keep this independent of the bounded replay buffer.
+        if (BUSY_KINDS.has(event.kind))
+            state.hasUserTurn = true;
         const payload = (event.payload ?? {});
         if (event.kind === 'request' && payload.type === 'request') {
             const request = payload.request;

package/dist/view.js

@@ -639,6 +639,9 @@ export function projectReplayTurns(events, granted, context) {
  */
 export function projectHistory(history, granted, pendingToolNames = new Set()) {
     const turns = [];
+    // Keep results inside the native invocation, as the live stream does. A
+    // separate Markdown result bypasses the editor's collapsed tool-step group.
+    const toolRows = new Map();
     const pushAssistant = (parts) => {
         const last = turns[turns.length - 1];
         if (last && last.role === 'assistant' && last.parts) {
@@ -659,6 +662,7 @@ export function projectHistory(history, granted, pendingToolNames = new Set()) {
     for (const message of history) {
         const body = messageText(message);
         if (message.role === 'user') {
+            toolRows.clear();
             turns.push({ role: 'user', prompt: clamp(stripControls(body), VSCODE_CHAT_LIMITS.partCharacters) });
             continue;
         }
@@ -674,14 +678,21 @@ export function projectHistory(history, granted, pendingToolNames = new Set()) {
                 pushAssistant([{ part: 'markdown', value: clamp(stripControls(body), VSCODE_CHAT_LIMITS.partCharacters) }]);
             }
             for (const call of message.tool_calls ?? []) {
+                const subject = toolSubject(call.function.arguments);
+                const label = clamp(stripControls(subject ? `${call.function.name} · ${subject}` : call.function.name), VSCODE_CHAT_LIMITS.titleCharacters);
+                const row = {
+                    part: 'tool',
+                    toolName: call.function.name,
+                    toolCallId: call.id,
+                    invocationMessage: label,
+                    pastTenseMessage: label,
+                    inputText: clamp(stripControls(parseArguments(call.function.arguments)), VSCODE_CHAT_LIMITS.partCharacters),
+                    isComplete: true,
+                };
+                if (call.id)
+                    toolRows.set(call.id, row);
                 pushAssistant(resolveParts([{
-                        emit: {
-                            part: 'tool',
-                            toolName: call.function.name,
-                            toolCallId: call.id,
-                            invocationMessage: clamp(call.function.name, VSCODE_CHAT_LIMITS.titleCharacters),
-                            isComplete: true,
-                        },
+                        emit: row,
                         needs: 'chatParticipantAdditions',
                         fallback: [{
                                 part: 'markdown',
@@ -696,10 +707,43 @@ export function projectHistory(history, granted, pendingToolNames = new Set()) {
         // interruption. Only the final matching tool is affected, never old history.
         const pending = message === history.at(-1) && pendingToolNames.has(message.name ?? '')
             && body === '[no tool result recorded — turn interrupted]';
+        if (pending) {
+            // The pinned editor serializes history tool parts as complete even if
+            // isComplete=false. Keep this explicit marker for matched AND orphan
+            // results; the active response separately restores the approval controls.
+            pushAssistant([{ part: 'markdown', value: '**Awaiting approval** — no tool result yet.' }]);
+            continue;
+        }
+        if (granted.has('chatParticipantAdditions')) {
+            const row = message.tool_call_id ? toolRows.get(message.tool_call_id) : undefined;
+            const output = clamp(stripControls(body), VSCODE_CHAT_LIMITS.partCharacters);
+            if (row) {
+                row.resultText = output;
+                // Canonical ChatMessage has no general error flag. Only this known
+                // synthetic marker establishes interruption; do not guess from prose.
+                if (body === '[no tool result recorded — turn interrupted]')
+                    row.isError = true;
+                toolRows.delete(message.tool_call_id);
+            }
+            else {
+                // A bounded transcript can retain a result whose call was omitted.
+                // Preserve it as an inspectable tool row without inventing its input.
+                const label = clamp(stripControls(message.name || 'Tool result'), VSCODE_CHAT_LIMITS.titleCharacters);
+                pushAssistant([{
+                        part: 'tool',
+                        toolName: message.name || 'tool',
+                        toolCallId: message.tool_call_id || `history-result-${history.indexOf(message)}`,
+                        invocationMessage: label,
+                        pastTenseMessage: label,
+                        isComplete: true,
+                        resultText: output,
+                    }]);
+            }
+            continue;
+        }
         pushAssistant([{
                 part: 'markdown',
-                value: pending ? '**Awaiting approval** — no tool result yet.'
-                    : `**Tool result${message.name ? ` · ${message.name}` : ''}**\n\n${fence(clamp(stripControls(body), VSCODE_CHAT_LIMITS.partCharacters))}`,
+                value: `**Tool result${message.name ? ` · ${message.name}` : ''}**\n\n${fence(clamp(stripControls(body), VSCODE_CHAT_LIMITS.partCharacters))}`,
             }]);
     }
     if (turns.length <= VSCODE_CHAT_LIMITS.historyTurns)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/supercode-frontend-vscode",
   "displayName": "Volter Harness",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "type": "module",
   "description": "VS Code chat-view frontend for an existing Volter Harness SDK runtime",
   "publisher": "volter-ai-dev",
@@ -84,7 +84,7 @@
         "description": "Conversations with your AI assistant",
         "icon": "$(server-process)",
         "welcomeTitle": "Chat",
-        "welcomeMessage": "Ask a question or continue a saved conversation.",
+        "welcomeMessage": "Write a message to your coding agent.",
         "inputPlaceholder": "Ask a question or describe a task",
         "order": 1,
         "capabilities": {
@@ -191,6 +191,9 @@
     "@types/vscode": "1.138.0",
     "typescript": "5.6.3"
   },
+  "supercodeFrontendWelcome": {
+    "starterIntroduction": "Choose an idea to edit before sending:"
+  },
   "supercodeFrontendContract": {
     "name": "@volter/supercode-frontend",
     "version": "0.2.7",