@volter/supercode-frontend-vscode 0.1.11

package/NOTICE.md

@@ -0,0 +1,19 @@
+# Third-party notice
+
+This optional frontend has **no runtime npm dependency**. It builds against `@types/vscode`
+(Copyright (c) Microsoft Corporation, MIT) as an exact devDependency for types only; `vscode` itself
+is supplied by the editor at runtime and is never bundled or redistributed here.
+
+No Microsoft source is copied into this repository. In particular the editor's
+`vscode.proposed.*.d.ts` files are **not** vendored: `src/vscode-proposed.d.ts` is a
+Volter Harness-authored declaration of the narrow proposed-API subset this package calls, written against
+the published proposals rather than copied from them.
+
+The generated attachment client under `vendor/supercode-frontend/` is this repository's own
+`@volter/supercode-frontend`, synced by `scripts/sync-sdk.mjs` and version-pinned by
+`package.json#supercodeFrontendContract`.
+
+Volter Harness-authored integration and presentation code is identified by this package's source history
+and remains under the repository's declared `MIT OR Apache-2.0` license.
+
+The bundled provider/harness SVG marks in media/ are derived from this repository's sdk/ui/src/logo.jsx. Brand marks identify the active provider; they do not imply affiliation.

package/README.md

@@ -0,0 +1,293 @@
+# Volter Harness VS Code frontend
+
+This is an optional VS Code extension that presents an **already-running** Volter Harness SDK runtime in
+the editor's own Chat view. It uses the exact generated `@volter/supercode-frontend` client
+for all session discovery, history, events, and semantic actions, and VS Code's own chat API for all
+presentation — no webview, no React, no stylesheet of its own.
+
+It does not run an agent, load context, authenticate a provider, execute tools,
+import sessions, or write session files. The Rust/headless Volter Harness core does not depend on this
+package or npm.
+
+## Native chat controls
+
+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
+checks. `GET /state` describes the selected harness/model/effort, available choices,
+and current connection; `POST /select` asks the host to start the selected configuration
+and returns its new scoped connection. The host owns validation, process lifetime,
+persistence, and failure handling. Prompts and approvals still use the generated frontend client.
+The contract is in `src/host-controls.ts`.
+
+With that host, **Chat: New Chat: Choose Harness, Model and Reasoning** chooses
+configuration before opening a separate conversation. A conversation's harness, model and
+reasoning settings remain fixed: this integration does not advertise hot swapping. Native
+Chat displays its selected model and provider icon inside the composer and its supported
+approval policy below it. The response author identifies the harness.
+
+The host publishes durable conversation IDs and their exact harness history identities.
+`POST /open` resumes only the requested saved conversation; `POST /remember` binds its
+reported native session ID to discovered history. Unknown or missing bindings fail explicitly,
+never falling back to the currently active runtime. The host may provide an `openSessionCommand`
+to reveal an exact resource through its native widget service. Cached native widgets should
+notify `supercode.frontend.activateSession` when focused. The frontend owns no processes.
+
+The permission group offers **Ask for approval** and, on an answerable interactive attachment,
+**Auto approve**. Policies are scoped by conversation and captured for each turn; automatic
+approval does not bypass harness sandbox rules. Unsupported modes are refused. Unanswerable
+harnesses show **Harness permissions**. Previously answered requests cannot affect another
+connection. Native command-button fallback limitations are documented below.
+
+Text files and selected ranges use native Add Context and attachment chips. Their current
+editor contents are serialized as explicitly labeled user-supplied context through the existing
+prompt protocol. Binary text, more than 256 KiB per attachment, or more than 1 MiB total is
+rejected without truncation. Image and tool attachments remain unavailable. Model inventories,
+mode/tool controls, and context limits are not invented where the runtime has no contract.
+
+These controls use native provider APIs; there is no custom composer or webview.
+`test/bindings.test.mjs`, `test/context.test.mjs`, and `test/host-controls.test.mjs` cover
+routing boundaries, context serialization/limits, identity and approval interpretation.
+Live product acceptance is separate from these frontend unit tests.
+
+## Attaching
+
+Three paths, in precedence order.
+
+1. **A host hands over the connection.** `activate()` returns an API a bundling product calls when
+   it already knows where its runtime is:
+
+   ```ts
+   const supercode = vscode.extensions.getExtension('volter-ai-dev.supercode-frontend-vscode');
+   const api = await supercode.activate();
+   await api.connect({baseUrl, token, permissions: ['observe', 'interact', 'approve']});
+   // api.connections, api.disconnect(id), api.grantedProposals, api.onDidChangeConnections
+   ```
+
+2. **The runtime's environment handover.** At activation the extension reads
+   `SUPERCODE_FRONTEND_URL`, `SUPERCODE_FRONTEND_CLIENT_ID`, `SUPERCODE_FRONTEND_CREDENTIAL_FILE`
+   and `SUPERCODE_FRONTEND_PERMISSIONS` from the extension host's environment — the same shape
+   `crates/cli/src/frontend_client.rs` already uses to launch the pi frontend, without the `PI`
+   infix. A Code-OSS server passes its environment to its extension host, so a product that starts
+   the server hands the connection over with no pasted token. The credential is a *file*, read with
+   `sdk/frontend-pi`'s rules (a regular, private, single-linked file of 64 hex bytes, re-checked
+   across the open). It differs from pi's in one deliberate way: the token is stored in
+   `SecretStorage` **before** the one-shot file is removed, because an extension host outlives one
+   attachment and reloads.
+
+   The credential file is **read, never consumed**. `sdk/frontend-pi` unlinks it, because a pi
+   process is exactly one attachment; an extension host is not — it reloads, and a reload must not
+   lose the runtime it was handed. Nor can the token be kept instead: `SecretStorage` is in-memory
+   in a host with no credential provider (measured in VS Code Web), and there is no durable place
+   an extension may put a bearer token that is better than the runtime's own private 0600 file. The
+   base URL it was handed is remembered in `globalState`, so the next activation reconnects.
+
+   A host that could not start a runtime at all says so with the fourth variable,
+   `SUPERCODE_FRONTEND_UNAVAILABLE` (or `connect({unavailable})`): its own sentence, naming its own
+   harness and the command a person must type. Nothing is attached and that sentence is what the
+   Chat view shows. It is shown as a **session** — `chatViewsWelcome` cannot do it, because
+   `ChatViewPane.shouldShowWelcome()` in
+   `src/vs/workbench/contrib/chat/browser/widgetHosts/viewPane/chatViewPane.ts` begins
+   `const shouldShow = !hasCoreAgent && …`, so the whole welcome control is suppressed whenever any
+   core agent is registered for the Chat location, which a Code-OSS derivative with an agent host
+   always has; the `when` clause is never consulted. The session's `activeResponseCallback` is the
+   one door that writes into a session nobody has typed into, so the reason is on screen where the
+   eye lands rather than waiting for a prompt.
+
+   An attachment that arrives with HISTORY — a resumed runtime, `claude --resume <id>` — opens its
+   own session once, so the panel opens *on* the conversation instead of beside it. A runtime with
+   no history is left alone: there is nothing to show and stealing the panel would be rude.
+
+3. **Settings plus `SecretStorage`.** `supercode.frontend.baseUrl` names the runtime;
+   **Volter Harness: Set Runtime Token** prompts once and stores the credential in `SecretStorage`. The
+   credential is never a setting and never a URL query. `supercode.frontend.permissions` narrows the
+   attachment; `observe` is always included, and every control is still rendered only when the
+   runtime's own descriptor advertises the matching action.
+
+The generated client opens SSE **before** taking the attachment snapshot, so no event falls between
+history and live. Dropping or detaching never closes the runtime.
+
+## API proposals, and what it does without them
+
+The extension asks for five proposals. A host grants them through
+`product.json#extensionEnabledApiProposals` (a Code-OSS derivative that bundles this extension) or
+`--enable-proposed-api volter-ai-dev.supercode-frontend-vscode`. **Stock VS Code grants none, and
+everything below still works there** — the granted set is read back from the extension host at
+runtime (`context.extension.packageJSON.enabledApiProposals` is the *filtered* description, not the
+request), and each part declares its own fallback.
+
+| Proposal | What it buys | Without it |
+|---|---|---|
+| `defaultChatParticipant` | `isDefault` — Volter Harness answers the Chat view with no `@` mention | the ordinary `@supercode` participant; a mention is required |
+| `chatParticipantAdditions` | `ChatToolInvocationPart`, `ChatResponseConfirmationPart`, `ChatResponseWarningPart`, `codeblockUri`, `ChatResponseThinkingProgressPart` | progress lines, labeled Markdown results, typed replies, plain fenced diffs, blockquoted reasoning |
+| `chatSessionsProvider` | the runtime's sessions in the Chat view's session picker, each reopening with its history | the participant still attaches; there is no session list |
+| `chatParticipantPrivate` | dynamic participant identity with the harness and provider icon | static participant identity |
+| `chatProvider` | native fixed-model identity and provider icon | host new-chat configuration |
+
+The session participant uses the exact session type id (`supercode`). With
+`chatParticipantPrivate`, the extension registers its dynamic identity directly and keeps
+`canDelegate` disabled so the workbench does not pre-register a generic agent that masks the
+model name. Model descriptors target only the `supercode` session type, whose contribution declares
+`requiresCustomModels` so the workbench renders and forwards the native model selection. As in Code-OSS's own
+AgentHostLanguageModelProvider, they do not expose a second direct inference endpoint:
+the participant validates model settings against the bound conversation, and the runtime
+owns execution. Unknown token limits remain zero, not invented. Model/reasoning changes
+require an explicitly new conversation; they never reset an existing transcript on send.
+The permission group uses `kind: permissions`; the embedding workbench must expose its
+native permission-picker action for this session type. No composer CSS or bespoke toolbar
+is supplied by this frontend.
+
+Two participant contributions exist for one reason: the workbench refuses a `chatParticipants` entry
+that declares `isDefault` without the grant *and skips it entirely*, so a single entry would leave a
+stock host with no `@supercode` at all. `supercode.chat` carries no proposal-gated manifest field and
+is `when`-gated on `!supercodeChatDefaultParticipant`; `supercode.chat.default` carries `isDefault`,
+`locations: ["panel"]` and `modes: ["ask"]` and is gated on the inverse. The extension sets that
+context key from the grant it actually received. A host that grants nothing logs one line naming the
+refused proposal and runs on the plain participant. (`locations` is omitted from the plain entry on
+purpose: it too needs `chatParticipantAdditions`, and its absence already defaults to the Chat panel
+— `chatParticipant.contribution.ts`, `locations: isNonEmptyArray(...) ? ... : [ChatAgentLocation.Chat]`.)
+
+## The mapping
+
+`src/view.ts` is the whole event-to-chat-part mapping and it is pure: every input is the runtime's
+own sequenced `FrontendEvent`, every output is a description of a VS Code chat part plus the proposal
+it needs and the fallback it degrades to. Each arm names the producer it reads.
+
+| Event kind | Producer | Rendered as |
+|---|---|---|
+| `text_delta` | `crates/runtime/src/event.rs` `AgentEvent::TextDelta` | `response.markdown` (streamed) |
+| `user_message` | `crates/harness/src/server.rs` `submit_claimed` | the request turn in history; dropped live (VS Code already shows it) |
+| `turn_started` / `turn_completed` / `turn_succeeded` | `submit_claimed`; `AgentEvent::TurnCompleted` | lifecycle only — the handler resolves, nothing renders |
+| `turn_interrupted` | `submit_claimed` | an italic notice |
+| `turn_failed` | `submit_claimed` | `ChatResponseWarningPart` → blockquote |
+| `tool_call_started` / `tool_call_completed` | `AgentEvent::ToolCallStarted` / `ToolCallCompleted` | one `ChatToolInvocationPart` per call, updated in place with its result (`enablePartialUpdate`) → a progress line plus a labeled Markdown result |
+| `diff_updated` | `crates/codex-frontend/src/codex_app_server_v0_144.rs` (stock Codex `turn/diff/updated`) | `codeblockUri` + a fenced `diff` block, plus one stable `reference` per file the diff names → the fenced block alone |
+| `request` | `crates/harness/src/server.rs` `FrontendRequestBroker::publish` | a titled markdown block plus one **command button per answer** — stable API, no proposal |
+| `cache_warning` | `AgentEvent::CacheWarning` | `ChatResponseWarningPart` → blockquote |
+| `usage` | `AgentEvent::Usage` | a progress line |
+| `background_output` | `AgentEvent::BackgroundOutput` | a fenced block, saying so when the runtime stopped retaining |
+| `scheduled_prompt_started` / `_deferred` / `_completed` | declared by `frontend_descriptor`'s `display.event_kinds` | a progress line |
+| `scheduler_error` | same | `ChatResponseWarningPart` → blockquote |
+| `reasoning` / `thinking` | no producer in this repository; read because `crates/frontend-model/src/transcript.rs` reads them | `ChatResponseThinkingProgressPart` → blockquote |
+| `stream_error` / `transport_error` / `watch_error` / `runtime_disconnected` | `crates/opencode-frontend/src/server.rs`; `crates/interchange/src/watch.rs`; synthesized by a frontend (`crates/frontend-tui/src/app.rs`); `stream_error` has no producer here | `ChatResponseWarningPart` → blockquote |
+| anything else | opaque by contract | one **bounded** markdown cell that names the kind and shows the payload — never dropped |
+
+**Why `diff_updated` is not an edit part.** Measured: the payload carries one unified-diff *string*
+and nothing else. `ChatResponseTextEditPart` wants ranges and the runtime has already written the
+file, so replaying them would double-apply. `ChatResponseMultiDiffPart` wants an `originalUri` and a
+`modifiedUri` per file — two resources this frontend would have to fabricate and serve.
+`ChatResponseExternalEditPart` brackets a callback that *performs* the edit so the editor can take a
+"before" snapshot; ours would be a no-op after the write, making the editor's undo stop wrong. What
+the payload does state is which files it touched (`+++ b/<path>`), so those become stable references.
+
+**Why a request is buttons.** Two richer mechanisms were tried against a live runtime in the
+editor's own Chat view, and both failed there, so neither ships. `ChatResponseConfirmationPart`
+retires its own buttons on click — but the click answers by sending a **new chat request**
+(`chatConfirmationContentPart.onDidClick`), and a Volter Harness approval is raised **while the turn is
+still running** (`decide_approval` blocks the agent loop), so the editor refuses that request, the
+click does nothing, and the runtime waits forever. `stream.questionCarousel` is the right shape on
+paper — it resolves inside the running turn and the widget retires itself — and the widget did
+render with its three options; but Submit retired it without ever delivering an answer this
+frontend could read, leaving the runtime blocked. A preferred path that silently swallows the
+answer is worse than a plain one that works. A `ChatResponseCommandButtonPart` runs inside the live
+turn, needs no proposal, and carries its own answer per button — so an approval offers `Allow` / `Allow for session` / `Deny`, all three, where a
+confirmation's one `data` payload could only ever have carried two. The command
+(`supercode.frontend.respond`) narrates itself in the status bar, because an action whose success is
+invisible is one nobody can trust. A pushed command button cannot be withdrawn — `chatCommandContentPart`
+enables on `!isStale` and carries no used-state, and only `confirmation`, `mcpAuthenticationRequired`,
+`planReview` and `questionCarousel` have one — so the buttons stay visible after the answer. They are
+inert: the command refuses a request the runtime no longer holds and says "already resolved", and the
+resolution sentence lands directly beneath them. An elicitation that carries a `requested_schema` gets an
+`Answer…` button that asks for the value first; a request still pending while the session is idle
+can also be answered by typing.
+
+**A hosted harness runtime.** When the runtime is one Volter Harness HOSTS — a Claude Code, Codex, pi or
+opencode session it started through `harness.v1.runtimes.start` — an approval it raises is
+**answerable from this view** for every harness whose reply this runtime can translate
+(`crates/harness/src/runtime/hosted.rs`): the canonical `respond {decision}` becomes that harness's
+own envelope, which for Claude Code is `{behavior:'allow'}` / `{behavior:'deny', message}`. The
+request states which decisions its harness protocol actually carries, so this view offers exactly
+those and no button the runtime would refuse — Claude Code has an allow and a deny and no
+always-allow *behavior* at all, so it gets two. A harness with no translation keeps
+`actions.respond: false`, and then the request is rendered as an observation naming who answers it,
+because a control appears only for an action the descriptor advertises. Tool completions name only
+the call they answer (Claude Code's `tool_result` block carries just a `tool_use_id`), so an unnamed
+completion keeps the name the start stated rather than becoming a tool called `tool`.
+
+**Bounds.** The projection is bounded like `@volter/supercode-frontend-browser`'s: 64 KiB per
+part, 256 characters per title, 2 KiB for an opaque payload, 500 history turns. When turns are
+omitted the view says so; the runtime's own history is unchanged and authoritative. Terminal control
+characters never reach a rendered part.
+
+**The turn.** A chat request submits through `frontend.v2.send_input` and resolves on the first
+`turn_succeeded` / `turn_failed` / `turn_interrupted`; the request's cancellation token calls
+`frontend.v2.interrupt`. It *also* resolves when the descriptor goes idle after having been busy:
+the editor holds the chat response open until the handler returns, and a frontend that hangs one
+forever is worse than one that ends it a beat early. A sequence gap is likewise not fatal — it is
+what the cursor exists for, so the session re-takes its snapshot rather than throwing out of the
+live listener and stranding every in-flight turn.
+
+**The lease.** The runtime hands ONE controller a lease and expires it
+(`crates/harness/src/runtime_lease.rs`), so an attachment that may submit takes control on attach
+and heartbeats at a third of the advertised TTL; `controller_required` / `lease_expired` on any
+action is a take-control-and-retry, never something the view reports.
+
+**The system prompt renders nothing.** It is in the runtime's canonical history because the MODEL
+needs it; a reader does not, and a collapsed block is still a reader's problem. No chat product shows
+one to a person, so `role: 'system'` is dropped outright and the transcript starts where the
+conversation does.
+
+**Session times are real or nothing.** `frontend.v2` carries no session timestamp, and the editor's
+session list ALWAYS reads `timing.created`, rendering the epoch ("57 yrs ago") when a provider
+supplies none — there is no path in `agentSessionsViewer` that omits the time. So the item gets the
+true times this frontend does know: when this window attached, and the turn boundaries it watched go
+by. Never a zero dressed up as a date.
+
+**History.** Saved tool results use labeled Markdown and fenced output; raw HTML is
+not supported by native history rendering. A saved call is labeled neutrally because
+a recorded invocation does not prove that permission was granted. VS Code's chat history is request/response **pairs** and drops a response turn with no
+request before it. A runtime transcript legitimately opens with assistant or system content — the
+runtime compacts, so its canonical history can begin `[earlier conversation compacted: N messages]`
+with no user turn left. Rather than drop it, the projection pairs it with a marker turn,
+`⟨supercode runtime history⟩`, which names itself: nothing is presented as a person's words.
+
+## Building and packaging
+
+```
+npm install && npm run build      # sync the generated client, then tsc
+npm test                          # build + the pure mapping over recorded events
+npm run extension                 # write the VS Code extension folder to .extension/
+node scripts/pack-extension.mjs --out .extension --vsix          # and a .vsix
+node scripts/pack-extension.mjs --out .stock --no-proposals      # the stock-host manifest
+```
+
+One `package.json` cannot be both manifests: npm wants the scoped
+`@volter/supercode-frontend-vscode`, while VS Code builds an extension id as
+`${publisher}.${name}` and a scope would put an `@` and a `/` in it. The npm manifest is the source
+of truth and `scripts/pack-extension.mjs` writes the extension's manifest beside the same built
+files, with the plain name that resolves to `volter-ai-dev.supercode-frontend-vscode`. That folder is
+what `--extensions-dir` wants; `--vsix` runs the stock packer over it.
+
+`scripts/pack-extension.mjs` **ships inside the published package**, so a host that bundles this
+extension into its own build runs the same transform rather than reimplementing it:
+
+```
+node node_modules/@volter/supercode-frontend-vscode/scripts/pack-extension.mjs \
+     --out <build>/extensions/supercode-chat
+```
+
+The installed package is already built (`dist/` and `vendor/` are in `files`), so the script writes
+the extension manifest beside those bytes with no build step of its own.
+
+Conversation creation uses `ChatSessionItemController.newChatSessionItemHandler`.
+Permissions use `getChatSessionInputState` and its change/disposal events, with
+per-conversation preferences persisted in workspace state. New untitled chats
+start with Ask; old untitled bindings are read only for backwards compatibility.
+Restored response cancellation interrupts the runtime and waits for acknowledgement.
+Session-list updates consistently prioritize pending input over busy status.
+
+The pinned Code-OSS host needs a resource-scoping repair in its input-state change
+routing: stock code broadcasts changes to all input states of a provider. The
+Volter overlay guards this fix with a native regression test. The former legacy
+option-notification queue is no longer required. The narrow reveal/focus bridge
+remains because the native model catalogue and participant identity are provider-wide.

package/dist/bindings.d.ts

@@ -0,0 +1,7 @@
+/** Resolve only explicit saved bindings. Never substitute the currently active runtime. */
+export declare function resolveSessionBinding(resource: {
+    authority: string;
+    toString(): string;
+}, sessions: readonly {
+    id: string;
+}[], aliases: ReadonlyMap<string, string>): string | undefined;

package/dist/bindings.js

@@ -0,0 +1,5 @@
+/** Resolve only explicit saved bindings. Never substitute the currently active runtime. */
+export function resolveSessionBinding(resource, sessions, aliases) {
+    const candidate = sessions.some(session => session.id === resource.authority) ? resource.authority : aliases.get(resource.toString());
+    return candidate && sessions.some(session => session.id === candidate) ? candidate : undefined;
+}

package/dist/client.d.ts

@@ -0,0 +1,11 @@
+import { FrontendClient } from '../vendor/supercode-frontend/client.mjs';
+export type FrontendPermission = 'observe' | 'interact' | 'approve' | 'terminate';
+export interface VscodeFrontendConnection {
+    baseUrl: string;
+    token: string;
+    clientId?: string;
+    permissions?: FrontendPermission[];
+    fetch?: typeof globalThis.fetch;
+}
+/** Create the only runtime-facing object this presentation package may own. */
+export declare function createFrontendClient(connection: VscodeFrontendConnection): FrontendClient;

package/dist/client.js

@@ -0,0 +1,5 @@
+import { FrontendClient } from '../vendor/supercode-frontend/client.mjs';
+/** Create the only runtime-facing object this presentation package may own. */
+export function createFrontendClient(connection) {
+    return new FrontendClient(connection);
+}

package/dist/context.d.ts

@@ -0,0 +1,6 @@
+/** Text context delivered through the runtime's existing prompt door. No silent truncation. */
+export interface TextContext {
+    name: string;
+    text: string;
+}
+export declare function withTextContext(prompt: string, entries: readonly TextContext[]): string;

package/dist/context.js

@@ -0,0 +1,14 @@
+export function withTextContext(prompt, entries) {
+    let total = 0;
+    for (const entry of entries) {
+        const size = new TextEncoder().encode(entry.text).length;
+        if (size > 256 * 1024)
+            throw new Error(`Attachment ${entry.name} exceeds 256 KiB. Select a smaller range.`);
+        total += size;
+        if (entry.text.includes('\0'))
+            throw new Error(`Attachment ${entry.name} is binary; only text context is supported.`);
+    }
+    if (total > 1024 * 1024)
+        throw new Error('Attached text exceeds 1 MiB. Remove files or select smaller ranges.');
+    return entries.length ? `${prompt}\n\nAttached context (user-supplied document contents):\n${JSON.stringify(entries)}` : prompt;
+}

package/dist/credential.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Read one scoped runtime credential from the file the runtime handed over.
+ *
+ * The rules are `@volter/supercode-frontend-pi`'s (`bin/credential.mjs`):
+ * a regular, private, single-linked file of exactly 64 lowercase hex bytes,
+ * re-checked across the open so a path swap cannot slip a different secret in.
+ * The bytes never enter argv, a setting, or a URL.
+ *
+ * It differs from pi's in ONE way, deliberately: pi UNLINKS the file, because a
+ * pi process is exactly one attachment. An extension host is not — it reloads,
+ * and a reload must not lose the runtime it was handed. Nor can it keep the
+ * secret instead: `SecretStorage` is in-memory in a host with no credential
+ * provider (VS Code Web), and there is no durable place an extension may put a
+ * bearer token that is better than the runtime's own private 0600 file. So the
+ * file is READ and left alone; its lifetime is the runtime's to manage.
+ */
+export declare function readCredentialFile(path: string): Promise<string>;

package/dist/credential.js

@@ -0,0 +1,53 @@
+import { constants } from 'node:fs';
+import { lstat, open } from 'node:fs/promises';
+/**
+ * Read one scoped runtime credential from the file the runtime handed over.
+ *
+ * The rules are `@volter/supercode-frontend-pi`'s (`bin/credential.mjs`):
+ * a regular, private, single-linked file of exactly 64 lowercase hex bytes,
+ * re-checked across the open so a path swap cannot slip a different secret in.
+ * The bytes never enter argv, a setting, or a URL.
+ *
+ * It differs from pi's in ONE way, deliberately: pi UNLINKS the file, because a
+ * pi process is exactly one attachment. An extension host is not — it reloads,
+ * and a reload must not lose the runtime it was handed. Nor can it keep the
+ * secret instead: `SecretStorage` is in-memory in a host with no credential
+ * provider (VS Code Web), and there is no durable place an extension may put a
+ * bearer token that is better than the runtime's own private 0600 file. So the
+ * file is READ and left alone; its lifetime is the runtime's to manage.
+ */
+export async function readCredentialFile(path) {
+    let handle;
+    try {
+        const before = await lstat(path);
+        if (!before.isFile() || before.isSymbolicLink()) {
+            throw new Error('scoped frontend credential must be a regular file');
+        }
+        handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const metadata = await handle.stat();
+        const current = await lstat(path);
+        if (!metadata.isFile() ||
+            before.nlink !== 1 ||
+            metadata.nlink !== 1 ||
+            before.dev !== metadata.dev ||
+            before.ino !== metadata.ino ||
+            current.dev !== metadata.dev ||
+            current.ino !== metadata.ino) {
+            throw new Error('scoped frontend credential path changed while opening');
+        }
+        if (typeof process.getuid === 'function' &&
+            (metadata.uid !== process.getuid() || (metadata.mode & 0o077) !== 0)) {
+            throw new Error('scoped frontend credential file must be private to the current user');
+        }
+        if (metadata.size !== 64)
+            throw new Error('scoped frontend credential is malformed');
+        const bytes = await handle.readFile();
+        if (!bytes.every((byte) => (byte >= 48 && byte <= 57) || (byte >= 97 && byte <= 102))) {
+            throw new Error('scoped frontend credential is malformed');
+        }
+        return bytes.toString('ascii');
+    }
+    finally {
+        await handle?.close().catch(() => { });
+    }
+}

package/dist/extension.d.ts

@@ -0,0 +1,39 @@
+import * as vscode from 'vscode';
+import { type FrontendPermission } from './client.js';
+import { type ProposalName } from './proposals.js';
+export interface SupercodeConnectOptions {
+    baseUrl?: string;
+    token?: string;
+    permissions?: FrontendPermission[];
+    clientId?: string;
+    connectionId?: string;
+    label?: string;
+    /**
+     * Why there is no runtime, in the HOST's own words, when it could not start
+     * one. Given this instead of a `baseUrl`, nothing is attached and the
+     * sentence is what the Chat view shows.
+     */
+    unavailable?: string;
+}
+export interface SupercodeConnectionInfo {
+    readonly id: string;
+    readonly baseUrl: string;
+    readonly label: string;
+    readonly sessionId: string | null;
+    readonly model: string | null;
+    readonly turnState: 'idle' | 'busy' | null;
+}
+/** What `activate` returns: the door a host uses to hand over a connection. */
+export interface SupercodeFrontendApi {
+    /**
+     * Attach to a runtime, or — with `{unavailable}` and no `baseUrl` — say why
+     * there is none, in the host's own words, and have that shown on screen.
+     */
+    connect(options: SupercodeConnectOptions): Promise<SupercodeConnectionInfo | undefined>;
+    disconnect(connectionId?: string): Promise<void>;
+    readonly connections: readonly SupercodeConnectionInfo[];
+    readonly grantedProposals: readonly ProposalName[];
+    onDidChangeConnections: vscode.Event<void>;
+}
+export declare function activate(context: vscode.ExtensionContext): Promise<SupercodeFrontendApi>;
+export declare function deactivate(): void;