Spectra for VS Code 0.1: set up and chat without the command line (#6) ff39a5e808da

A walkthrough creates the owner's identity, runs Spectra here or connects
to a server with its instance key confirmed, registers the folder as a
project, adds an agent and configures its client. Channels, Agents,
Inbox and Briefs views follow Spectra's stream; channels open as chat
tabs; briefs open as documents and saving signs them in. The extension
holds no key: it signs through spectra bridge. Spec Draft 0.4.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

Author: Andy McCall @andymccall <[email protected]>
via: agent agent:claude@andymccall <[email protected]> · keyless, under your grant for changes,refs,seal · key 6b98b0a34881
When: 1 day ago · 2026-11-03 17:11 UTC
Signature: ◈ sealed by agent:claude@andymccall
Hash: ff39a5e808da5d7a050b4bc2eaf7dd2a755a288d3bb105e16061031ae4dbe02b
Depends on: e6dd9408a3f6
Depended on by: 0bfe88762caa 94e8677a5439 5482605b3353 95a01bce821d 9a80f3825237 06699bcc6e2e 17556ca229a9
In bookmarks: main
Receipts: ✔ check passed in 10.4 s · signed by mars-1 job 14798 · 1 day ago download
✔ package passed in 5.7 s · signed by mars-1 job 14799 · 1 day ago download
Edits: 32 atoms, 37 tree operations, 32 files

Browse the tree at this change

hide whitespace changes

added .flow/pipeline.kdl +24 −0

added .oxyignore +6 −0

added .vscodeignore +10 −0

added CHANGELOG.md +10 −0

added LICENSE +30 −0

added assets/spectra-mono.svg +10 −0

added assets/spectra.png +0 −0

No line changes.

added assets/spectra.svg +13 −0

added docs/spec.md +167 −0

added media/agent.md +5 −0

added media/binary.md +5 −0

added media/hello.md +5 −0

added media/identity.md +7 −0

added media/project.md +5 −0

added media/spectra.md +11 −0

added package-lock.json +2372 −0

added package.json +299 −0

added src/bridge.ts +127 −0

added src/briefs.ts +84 −0

added src/chat.ts +155 −0

added src/cli.ts +71 −0

added src/extension.ts +141 −0

added src/model.ts +91 −0

added src/pure.ts +106 −0

added src/setup.ts +310 −0

added src/spectra-api.d.ts +150 −0

added src/views.ts +103 −0

added test/pure.test.mjs +45 −0

added test/smoke.mjs +52 −0

added test/vscode-stub.mjs +10 −0

added tsconfig.json +18 −0

modified README.md +26 −0

1	+	// spectra-vscode's pipeline (OxygenFlow): typecheck, bundle, unit tests and
2	+	// packaging, offline in a microVM for every push.
3	+	schema-version 1
4	+
5	+	// The OxygenFlow Node image: its npm cache holds every package this
6	+	// repository's package-lock.json needs.
7	+	sandbox "node" {
8	+	runtime "microvm"
9	+	rootfs "cas://blob/836461b613019f62399a960c61a25c482eb74e30054ff2cd44d5594c3305872b"
10	+	memory-limit "4GiB"
11	+	cpu-limit 2
12	+	network "loopback"
13	+	}
14	+
15	+	job "check" {
16	+	sandbox "node"
17	+	exec "sh" "-euc" "npm ci --offline --cache /opt/npm-cache --no-audit --no-fund && npm run check"
18	+	}
19	+
20	+	job "package" {
21	+	sandbox "node"
22	+	depends-on "check"
23	+	exec "sh" "-euc" "npm ci --offline --cache /opt/npm-cache --no-audit --no-fund && npm run build && npm run package -- --baseContentUrl https://oxygenhub.io/andymccall/spectra-vscode/raw/main"
24	+	}

1	+	/node_modules
2	+	/out
3	+	/dist
4	+	*.vsix
5	+	/.vscode-test
6	+	docs/prompts/*

1	+	src/**
2	+	test/**
3	+	out/**
4	+	docs/**
5	+	node_modules/**
6	+	tsconfig.json
7	+	.oxy/**
8	+	.oxyignore
9	+	*.vsix
10	+	dist/*/.map

1	+	# Changelog
2	+
3	+	## Unreleased
4	+
5	+	## 0.1.0: Just works
6	+
7	+	- Added: the setup walkthrough. Find `spectra`, create your identity, run Spectra here or connect to a server with its instance key confirmed, register the folder as a project, add an agent and configure its client.
8	+	- Added: Channels, Agents, Inbox and Briefs views, kept current from Spectra's live stream; channels open as chat tabs; briefs open as documents and saving them signs them into Spectra.
9	+	- Added: the status bar (agents online, unread), Open Radar and Open Constellation.
10	+	- The extension holds no key: it signs through `spectra bridge`.

1	+	Spectra (spectra, spectra-core, spectra-mcp, spectra-api and radar) is licensed under either of
2	+
3	+	* the MIT License (below), or
4	+	* the Apache License, Version 2.0 (https://www.apache.org/licenses/LICENSE-2.0)
5	+
6	+	at your option.
7	+
8	+	---
9	+
10	+	MIT License
11	+
12	+	Copyright (c) 2026 Andy McCall
13	+
14	+	Permission is hereby granted, free of charge, to any person obtaining a copy
15	+	of this software and associated documentation files (the "Software"), to deal
16	+	in the Software without restriction, including without limitation the rights
17	+	to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
18	+	copies of the Software, and to permit persons to whom the Software is
19	+	furnished to do so, subject to the following conditions:
20	+
21	+	The above copyright notice and this permission notice shall be included in all
22	+	copies or substantial portions of the Software.
23	+
24	+	THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25	+	IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26	+	FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
27	+	AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28	+	LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
29	+	OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
30	+	SOFTWARE.

1	+	<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24">
2	+	<!-- Spectra's prism, one colour, for the activity bar. -->
3	+	<line x1="1.5" y1="13" x2="8.5" y2="12" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>
4	+	<path d="M7.5 20 L12 4 L16.5 20 Z" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linejoin="round"/>
5	+	<g stroke="currentColor" stroke-width="1.6" stroke-linecap="round">
6	+	<line x1="14.5" y1="11" x2="22.5" y2="8"/>
7	+	<line x1="15" y1="13" x2="22.5" y2="12.5"/>
8	+	<line x1="15.5" y1="15" x2="22.5" y2="17"/>
9	+	</g>
10	+	</svg>

1	+	<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 32" width="48" height="32" aria-hidden="true">
2	+	<!-- Spectra's mark: one line of light into a prism, out as a band of colour. -->
3	+	<line x1="1" y1="17" x2="17" y2="15" stroke="#f0f6fc" stroke-width="2" stroke-linecap="round" stroke-opacity="0.9"/>
4	+	<path d="M15 27 L24 4 L33 27 Z" fill="none" stroke="#8b949e" stroke-width="2" stroke-linejoin="round"/>
5	+	<g stroke-width="2.2" stroke-linecap="round">
6	+	<line x1="27" y1="13" x2="47" y2="5" stroke="#f85149"/>
7	+	<line x1="27.5" y1="15" x2="47" y2="10" stroke="#ff9e2c"/>
8	+	<line x1="28" y1="17" x2="47" y2="15" stroke="#e3b341"/>
9	+	<line x1="28.5" y1="19" x2="47" y2="20" stroke="#3fb950"/>
10	+	<line x1="29" y1="21" x2="47" y2="25" stroke="#4493f8"/>
11	+	<line x1="29.5" y1="23" x2="47" y2="30" stroke="#a371f7"/>
12	+	</g>
13	+	</svg>

1	+	# Spectra for Visual Studio Code
2	+
3	+	\| \| \|
4	+	\|---\|---\|
5	+	\| Status \| Draft 0.4 \|
6	+	\| Date \| 2026-11-03 \|
7	+	\| Scope \| The control plane in the editor: see the agents, read and post in channels, work the task board, answer the agents' questions, approve their actions, edit the house rules, and watch the live log, without leaving VS Code. The local tool's UI, built on its JSON API. \|
8	+	\| Depends on \| `spectra` (spec Draft 0.6) with `/api/v1`, the SSE event stream, `spectra bridge`, `spectra probe`, briefs, and `spectra-api`'s generated types: Spectra 0.1.x for milestone 0.1; Spectra 0.2 for tasks (0.3); Spectra 0.3 and 0.4 for rules, schedules and permission verdicts (0.4) \|
9	+	\| Companion \| `../spectrahub-vscode/docs/spec.md` builds on this extension's exported API \|
10	+
11	+	## 1. Goals
12	+
13	+	1. It just works. A person who has never used a terminal for Spectra installs the extension and is guided through everything: their identity, a Spectra (on this machine or a server), this folder as a project, an agent with its client configured. Nothing needs the command line.
14	+	2. Everything Radar shows, in the side bar. Agents, channels, tasks, the human inbox, decisions, rules and the log are views; the workspace folder's project is the default context.
15	+	3. The human's fastest surface. An agent's question (`human`) and a relayed permission prompt appear as a notification with the answer buttons on it; a reply to an agent is a keystroke away from the code.
16	+	4. Never lie about state. The extension shows what the daemon reports and nothing it infers; every action is an API call that becomes an event.
17	+	5. Live. Views update from the event stream within a second; nothing polls on a timer while the stream is open.
18	+
19	+	Non-goals for 1.0: running agents, editing agent tokens, administering more than one Spectra (that is `spectrahub-vscode`), a chat with the model itself (the agents have their own clients).
20	+
21	+	## 2. How it compares
22	+
23	+	\| GitHub Pull Requests / Slack in VS Code \| Spectra extension \| Notes \|
24	+	\|---\|---\|---\|
25	+	\| Sign in \| The setup walkthrough; afterwards nothing: the extension signs through `spectra bridge` \| Keys stay with `spectra` \|
26	+	\| Notifications badge \| Status bar: agents online, unread, open human requests \| From `/brief` as the human and the stream \|
27	+	\| Chat channels \| Channels view and a channel editor (a webview with the thread list and a compose box) \| `/channels/{name}/messages` \|
28	+	\| Issues board \| Tasks view grouped by state; a task's page as a webview \| `/tasks`, transitions \|
29	+	\| Review threads \| Inbox view: human requests, permission prompts, mentions, each with inline actions \| `/inbox`, `/tasks/{id}/complete`, relay verdicts \|
30	+	\| Settings \| Briefs view: the overall brief and each project's, edited as documents and saved as signed `brief.set` events \| `/briefs` \|
31	+	\| Output channel \| Log view: the event log tailing, filterable, each event expandable \| `/events?follow=1` \|
32	+
33	+	## 3. Architecture
34	+
35	+	- Language and build. TypeScript, bundled with esbuild. Tests with `@vscode/test-electron` against a `spectra serve --data TMP` started by the test harness.
36	+	- Process model. The API takes only signed requests, and TypeScript has no ML-DSA-65, so the extension starts `spectra bridge` (Spectra spec §18.1) as a child process: it reads the bridge's `{ url, token }` line and sends every API request, and the one SSE connection to `/api/v1/events?follow=1`, through it with the token. The bridge signs as the owner and reaches the daemon wherever it is: the local socket, or a server over pinned TLS. It ends when the extension does. Setup steps run `spectra` commands (`identity create`, `init`, `probe`, `connect`, `project add`, `agent add`) and parse their `--json` output; every confirmation the command line would ask for is a modal dialog here, after which the command runs with `--yes` or `--expect KEY`.
37	+	- Model. One `Spectra` object per configured URL (one by default): the brief, the agents, the channels and their unread counts, the tasks, the inbox; refreshed by fetching the fragment an event names.
38	+	- Project context. The workspace folder is matched to a project by path (`/projects`); the Channels view opens that project's channel first and `say` defaults to it. A folder that is not a project offers Register as Project.
39	+	- URIs. `spectra:` URIs serve read-only documents: `spectra:/channel/<name>`, `spectra:/thread/<id>`, `spectra:/task/<id>` (Markdown rendered from the API), so a thread can be opened as an editor tab and diffed, searched and pinned like a file.
40	+	- Activation. On startup when `spectra` is set up (an identity exists), on the `spectra.*` commands, and on opening the Spectra view.
41	+
42	+	## 4. Machine interface required from `spectra`
43	+
44	+	\| Endpoint \| Used for \|
45	+	\|---\|---\|
46	+	\| `GET /api/v1/brief` (as the human) \| status bar, unread counts, presence summary \|
47	+	\| `GET /api/v1/agents` \| Agents view; `PATCH …/pause` \|
48	+	\| `GET /api/v1/projects`, `POST` \| project matching, Register as Project \|
49	+	\| `GET /api/v1/channels`, `GET/POST …/{name}/messages`, `GET /threads/{id}` \| Channels view and editor \|
50	+	\| `GET /api/v1/inbox`, `POST …/ack` \| Inbox view \|
51	+	\| `GET/POST /api/v1/tasks`, `GET /tasks/{id}`, `POST /tasks/{id}/{transition}` \| Tasks view and task page \|
52	+	\| `GET /api/v1/decisions`, `POST` \| Decisions view; Record Decision \|
53	+	\| `GET /api/v1/rules`, `GET …/versions`, `GET …/diff` \| Rules view; layer files opened from their paths \|
54	+	\| `GET /api/v1/schedules` \| Schedules view \|
55	+	\| `GET /api/v1/search` \| Search History… quick pick \|
56	+	\| `GET /api/v1/events?follow=1` \| the live stream \|
57	+	\| `POST /api/v1/relay/verdict` \| permission prompts answered from the editor \|
58	+	\| `GET /api/v1/version` \| minimum version check \|
59	+
60	+	Spectra 0.1 has the read endpoints, posting and the stream; tasks arrive in 0.2, rules versions and decisions in 0.3, schedules and permission verdicts in 0.4 (spec §18, §25). Shapes come from `spectra-api/ts/index.d.ts`, copied in by `npm run types` and never edited.
61	+
62	+	## 5. User interface
63	+
64	+	### 5.0 Setup walkthrough
65	+
66	+	A VS Code walkthrough, Get started with Spectra, opened on first activation and from Spectra: Set Up. Each step checks its own state and is ticked when done, so it can be left and resumed:
67	+
68	+	1. Find spectra. `spectra.path`, else `spectra` on `PATH`, else Download (the release for this platform) or Locate…; the version is checked.
69	+	2. Your identity. If `spectra identity show --json` has none: Create Identity asks for a name and an optional contact and runs `spectra identity create`. The key is shown, with a note that the `keys` folder is secret.
70	+	3. Your Spectra. On This Machine runs `spectra init` and offers to install and start the user service; On a Server asks for its address, runs `spectra probe`, shows the server's name and instance key in a modal ("The server printed this key when it was set up. Is it the same?"), and on Trust runs `spectra connect URL --expect KEY`. A server that waits for another identity, or belongs to someone else, is explained, not retried.
71	+	4. This folder as a project. Name (from the folder), description; runs `spectra project add FOLDER -d …`. Links to other projects can be added with Link Project….
72	+	5. An agent here. Kind (Claude Code, Antigravity, Kimi Code, Codex, other), name (suggested `<kind>-<project>`), how long it may act for you (8 hours, a day, a week, until disabled); a modal names the agent and the expiry before `spectra agent add … --yes`. Then Connect the Client writes the MCP entry: `claude mcp add` in this folder for Claude Code, a merged `~/.gemini/config/mcp_config.json` for Antigravity, `kimi mcp add` for Kimi Code, or shows the line to paste.
73	+	6. Say hello. Opens the project's channel in the channel editor.
74	+
75	+	### 5.1 Status bar
76	+
77	+	`◈ 3 agents · 2 unread · 1 asking` from the brief, coloured when a human request is open; click opens the Inbox view. A second item shows the current folder's agent and its presence (`claude-oxygen · working`) when one exists.
78	+
79	+	### 5.2 Views (the Spectra container in the activity bar)
80	+
81	+	- Inbox: open human requests first (title, the agent, the options as inline buttons, Answer… for free text), then relayed permission prompts (tool, description, Allow / Deny), then mentions and DMs with Reply. Answering removes the item at once and the stream confirms.
82	+	- Agents: each with kind, project, presence and status; actions Message, Delegate Task…, Pause / Unpause, Open on Radar; a tooltip with the last tool call.
83	+	- Channels: channels with unread counts, the workspace's project channel first; a channel opens the channel editor (§5.3).
84	+	- Tasks: by state, filterable by project and assignee; a task opens the task page (webview: contract, input, result, progress, thread, and the owner's actions); New Task… creates one with a quick pick of assignees.
85	+	- Decisions: per project, newest first; Record Decision….
86	+	- Briefs: the overall brief and each project's, with their versions; opening one opens it as a document (`spectra-brief:/overall`, `spectra-brief:/project/<name>`) and saving it records a signed `brief.set`; Show Diff Since… picks two versions.
87	+	- Schedules: with next and last firing; enable, disable, delete.
88	+	- Log: the newest 200 events, tailing while visible; filter by kind, actor, project; an event expands to its payload.
89	+
90	+	### 5.3 Channel editor
91	+
92	+	A webview per channel: roots newest at the bottom with reply counts, threads expand in place, kinds as pills, payloads folded, attachments linked, `@` and `#` completion, `Ctrl+Enter` posts as the human, Reply in thread, Delegate from this message (opens New Task with the body quoted), Record as decision. Every message is delimited with its author exactly as the API gives it; nothing is merged.
93	+
94	+	### 5.4 Notifications
95	+
96	+	A `human` request and a permission prompt each raise a VS Code notification with the answer buttons (`spectra.notifications`: `all` \| `asks` \| `none`). A mention raises an information message with Open. Nothing else interrupts.
97	+
98	+	### 5.5 Editor integration
99	+
100	+	- Say to Agent from Selection: posts the selected lines (fenced, with the path and line numbers) to a chosen agent or channel.
101	+	- Delegate from Selection: a task whose description quotes the selection.
102	+	- Record Decision from Selection.
103	+	- Edit Brief from the project's channel editor header.
104	+
105	+	### 5.6 Commands (all prefixed `Spectra:`)
106	+
107	+	Set Up, Add Agent…, Register Folder as Project, Link Project…, Edit Overall Brief, Edit Project Brief, Renew Agent…, Open Radar, Open Constellation, Say…, Say to Agent from Selection, Reply…, New Task…, Delegate from Selection, Accept Task, Complete Task…, Cancel Task…, Reassign Task…, Answer Request…, Allow Action, Deny Action, Record Decision…, Record Decision from Selection, Search History…, Open Channel…, Open Thread…, Open Task…, Pause Agent…, Unpause Agent…, Register as Project, Show Rules, Show Rules Diff Since…, Export Rules to CLAUDE.md, Install Claude Code Hooks, Refresh.
108	+
109	+	### 5.7 Settings
110	+
111	+	\| Setting \| Default \| Meaning \|
112	+	\|---\|---\|---\|
113	+	\| `spectra.path` \| `""` \| The `spectra` binary (else `spectra` on `PATH`) \|
114	+	\| `spectra.notifications` \| `asks` \| Which inbox items raise notifications \|
115	+	\| `spectra.logTail` \| `200` \| Events kept in the Log view \|
116	+	\| `spectra.openRadarExternally` \| `true` \| Radar in the browser, else in a webview \|
117	+
118	+	## 6. Behaviour rules
119	+
120	+	- One stream per daemon; views refetch fragments, never whole lists, on an event.
121	+	- Errors from the API appear verbatim with Show output; the output channel logs every request, status and duration.
122	+	- Nothing destructive without confirmation: cancel, pause, deny, redact confirm with a "Don't ask again" per action.
123	+	- Multi-root workspaces: one project context per folder; the status bar follows the active editor's folder.
124	+
125	+	## 7. Repository layout and tooling
126	+
127	+	```
128	+	spectra-vscode/
129	+	package.json contributes: commands, views, menus, keybindings, settings
130	+	src/
131	+	extension.ts activation, wiring
132	+	api.ts typed fetch over /api/v1 and the SSE stream (src/spectraapi.d.ts generated)
133	+	model/ Spectra, agents, channels, tasks, inbox
134	+	views/ inbox, agents, channels, tasks, decisions, rules, schedules, log
135	+	editor/ channel webview, task webview, spectra: content provider, CodeLens
136	+	commands/
137	+	exported.ts the API other extensions consume (§8)
138	+	assets/images/ spectra.svg
139	+	test/
140	+	docs/spec.md
141	+	```
142	+
143	+	Build `npm run build`, test `npm test`, package `vsce package`; CI runs lint, build and tests on Linux, macOS and Windows against a pinned `spectra` release.
144	+
145	+	## 8. Exported API
146	+
147	+	`activate` returns a `SpectraAPI`: the connected Spectras as handles (url, brief, agents, channels, tasks, `fetch(path)`, `events` as an `Event`), `onDidChangeBrief`, `getProjectForFolder(uri)`, and `registerHubProvider(provider)`: a provider gives an id, `matches(url)` and `urlFor(target)` for agent, channel, thread and task targets, so Open on Hub works when `spectrahub-vscode` is installed. The hub extension consumes the handles and adds its own views; it never opens a second stream to a daemon this extension already holds.
148	+
149	+	## 9. Milestones
150	+
151	+	1. 0.1 Just works (needs Spectra 0.1 with `bridge`, `probe` and briefs): the setup walkthrough end to end, the bridge, the status bar, Agents, Channels with the channel editor (read and post), Inbox (read), Briefs (edit), Open Radar and Constellation; the stream.
152	+	2. 0.2 Act: answer human requests, permission verdicts, notifications, editor integration (Say from Selection).
153	+	3. 0.3 Work: Tasks view and page with every transition, Delegate from Selection, Decisions, Search.
154	+	4. 0.4 Automation: Install Claude Code Hooks, Schedules, the Log view.
155	+	5. 1.0: exported API, three-platform tests, Marketplace listing.
156	+
157	+	## 10. Open questions
158	+
159	+	1. Whether the channel editor should be a webview or a custom editor over `spectra:` documents (which would give find, split and diff for free). Likely the latter for threads and a webview for the compose box.
160	+	2. Whether to show other projects' channels at all in a workspace, or only the current project's plus the shared ones. Start with all, folded.
161	+
162	+	## 11. Changelog
163	+
164	+	- Draft 0.4 (2026-11-03): "it just works": a setup walkthrough that does everything the command line did (identity, a local or server Spectra with its key confirmed, the folder as a project, an agent and its client's MCP entry) (§5.0); the extension signs through `spectra bridge` (§3); briefs replace rule files (§5.2); 0.1 is that whole path plus chat.
165	+	- Draft 0.3 (2026-11-03): no reference to other products' extensions; Spectra stands alone (Spectra spec Draft 0.5).
166	+	- Draft 0.2 (2026-11-02): the Spectra version each milestone needs, instead of 0.5 for all; 0.1 can start once Spectra 0.1's API exists.
167	+	- Draft 0.1 (2026-11-02): initial specification.

1	+	# Agents
2	+
3	+	An agent is an AI client (Claude Code, Antigravity, Kimi Code, …) that acts for you in Spectra. You choose how long it may: an overnight agent with 8 hours stops by itself in the morning.
4	+
5	+	The extension can connect the client for you: it adds Spectra to Claude Code or Kimi Code in this folder, or to Antigravity's settings.

1	+	# The spectra program
2	+
3	+	Spectra is one program, `spectra`. The extension finds it on your `PATH`, in `~/.local/bin`, or where the Spectra: Path setting says.
4	+
5	+	In the spectra repository, `make install` builds it and puts it in `~/.local/bin`.

1	+	# Say hello
2	+
3	+	The project's channel is where you and your agents talk. Mention an agent with `@name` and it sees it in its inbox.
4	+
5	+	Give your agents a brief too: the overall brief reaches every agent, and a project's brief reaches its agents. Edit them in the Briefs view; saving signs them into Spectra, and each agent is told on its next call.

1	+	# Your identity
2	+
3	+	Your identity is a key pair that signs as you: an Ed25519 and an ML-DSA-65 key, kept in `~/.config/spectra`.
4	+
5	+	Every agent you add gets a key of its own, and your identity delegates to it, for as long as you say. That is how Spectra knows, and shows, that `claude-book` is your agent.
6	+
7	+	Keep the `keys` folder private: anyone with it can act as you.

1	+	# Projects
2	+
3	+	A project is any work your agents share: a codebase, a manuscript, a set of documents. Each has a channel, `#name`, and can have a brief.
4	+
5	+	Spectra records where the folder is and never reads anything inside it.

1	+	# Where Spectra runs
2	+
3	+	On this machine: the simplest. Spectra keeps its ledger in `~/.local/share/spectra`, and your agents on this machine connect to it.
4	+
5	+	On a server: Spectra runs elsewhere, and you, your keys and your agents stay here. On the server, set it up for your key:
6	+
7	+	```
8	+	spectra init --owner YOUR-KEY --name earth
9	+	```
10	+
11	+	It prints the server's instance key. When you connect, the extension shows the key it sees; trust it only if they match.

1	+	{
2	+	"name": "spectra-vscode",
3	+	"displayName": "Spectra",
4	+	"description": "Spectra in the editor: set up your AI agents, chat with them, and give them their briefs, without the command line",
5	+	"version": "0.1.0",
6	+	"publisher": "andymccall",
7	+	"license": "MIT OR Apache-2.0",
8	+	"repository": {
9	+	"type": "oxygen",
10	+	"url": "https://oxygenhub.io/andymccall/spectra-vscode"
11	+	},
12	+	"icon": "assets/spectra.png",
13	+	"engines": {
14	+	"vscode": "^1.138.0"
15	+	},
16	+	"categories": [
17	+	"AI",
18	+	"Other"
19	+	],
20	+	"keywords": [
21	+	"spectra",
22	+	"agents",
23	+	"mcp",
24	+	"claude",
25	+	"antigravity"
26	+	],
27	+	"main": "./dist/extension.js",
28	+	"activationEvents": [
29	+	"onStartupFinished"
30	+	],
31	+	"contributes": {
32	+	"viewsContainers": {
33	+	"activitybar": [
34	+	{
35	+	"id": "spectra",
36	+	"title": "Spectra",
37	+	"icon": "assets/spectra-mono.svg"
38	+	}
39	+	]
40	+	},
41	+	"views": {
42	+	"spectra": [
43	+	{
44	+	"id": "spectra.welcome",
45	+	"name": "Get started",
46	+	"when": "!spectra.ready"
47	+	},
48	+	{
49	+	"id": "spectra.channels",
50	+	"name": "Channels",
51	+	"when": "spectra.ready"
52	+	},
53	+	{
54	+	"id": "spectra.agents",
55	+	"name": "Agents",
56	+	"when": "spectra.ready"
57	+	},
58	+	{
59	+	"id": "spectra.inbox",
60	+	"name": "Inbox",
61	+	"when": "spectra.ready"
62	+	},
63	+	{
64	+	"id": "spectra.briefs",
65	+	"name": "Briefs",
66	+	"when": "spectra.ready"
67	+	}
68	+	]
69	+	},
70	+	"viewsWelcome": [
71	+	{
72	+	"view": "spectra.welcome",
73	+	"contents": "Spectra lets your AI agents find each other, talk, and follow your briefs.\n[Set Up Spectra](command:spectra.setup)\nThe walkthrough creates your identity, connects to (or starts) a Spectra, registers this folder as a project, and adds an agent with its client configured. No command line needed."
74	+	},
75	+	{
76	+	"view": "spectra.agents",
77	+	"contents": "No agents yet.\n[Add an Agent](command:spectra.addAgent)"
78	+	}
79	+	],
80	+	"walkthroughs": [
81	+	{
82	+	"id": "spectra.setup",
83	+	"title": "Get started with Spectra",
84	+	"description": "Everything Spectra needs, step by step: nothing typed in a terminal.",
85	+	"steps": [
86	+	{
87	+	"id": "binary",
88	+	"title": "Find spectra",
89	+	"description": "The extension drives the `spectra` program.\n[Check for spectra](command:spectra.checkBinary)",
90	+	"media": {
91	+	"markdown": "media/binary.md"
92	+	},
93	+	"completionEvents": [
94	+	"onContext:spectra.hasBinary"
95	+	]
96	+	},
97	+	{
98	+	"id": "identity",
99	+	"title": "Create your identity",
100	+	"description": "A key pair that signs as you. Agents act for you only when you say so.\n[Create Identity](command:spectra.createIdentity)",
101	+	"media": {
102	+	"markdown": "media/identity.md"
103	+	},
104	+	"completionEvents": [
105	+	"onContext:spectra.hasIdentity"
106	+	]
107	+	},
108	+	{
109	+	"id": "spectra",
110	+	"title": "Choose your Spectra",
111	+	"description": "Run it on this machine, or use one on a server you set up.\n[On This Machine](command:spectra.setupHere)\n[On a Server](command:spectra.connectServer)",
112	+	"media": {
113	+	"markdown": "media/spectra.md"
114	+	},
115	+	"completionEvents": [
116	+	"onContext:spectra.ready"
117	+	]
118	+	},
119	+	{
120	+	"id": "project",
121	+	"title": "This folder as a project",
122	+	"description": "A project is any work your agents share: code, a manuscript, documents.\n[Register This Folder](command:spectra.registerFolder)",
123	+	"media": {
124	+	"markdown": "media/project.md"
125	+	},
126	+	"completionEvents": [
127	+	"onContext:spectra.folderIsProject"
128	+	]
129	+	},
130	+	{
131	+	"id": "agent",
132	+	"title": "Add an agent",
133	+	"description": "Claude Code, Antigravity, Kimi Code or another; the extension can configure its client too.\n[Add an Agent](command:spectra.addAgent)",
134	+	"media": {
135	+	"markdown": "media/agent.md"
136	+	},
137	+	"completionEvents": [
138	+	"onContext:spectra.hasAgent"
139	+	]
140	+	},
141	+	{
142	+	"id": "hello",
143	+	"title": "Say hello",
144	+	"description": "Open the project's channel and say hello to your agents.\n[Open the Channel](command:spectra.openProjectChannel)",
145	+	"media": {
146	+	"markdown": "media/hello.md"
147	+	},
148	+	"completionEvents": [
149	+	"onCommand:spectra.openProjectChannel"
150	+	]
151	+	}
152	+	]
153	+	}
154	+	],
155	+	"commands": [
156	+	{
157	+	"command": "spectra.setup",
158	+	"title": "Set Up",
159	+	"category": "Spectra"
160	+	},
161	+	{
162	+	"command": "spectra.checkBinary",
163	+	"title": "Check for spectra",
164	+	"category": "Spectra"
165	+	},
166	+	{
167	+	"command": "spectra.createIdentity",
168	+	"title": "Create Identity",
169	+	"category": "Spectra"
170	+	},
171	+	{
172	+	"command": "spectra.setupHere",
173	+	"title": "Run Spectra on This Machine",
174	+	"category": "Spectra"
175	+	},
176	+	{
177	+	"command": "spectra.connectServer",
178	+	"title": "Connect to a Server",
179	+	"category": "Spectra"
180	+	},
181	+	{
182	+	"command": "spectra.registerFolder",
183	+	"title": "Register Folder as Project",
184	+	"category": "Spectra"
185	+	},
186	+	{
187	+	"command": "spectra.linkProject",
188	+	"title": "Link Project",
189	+	"category": "Spectra"
190	+	},
191	+	{
192	+	"command": "spectra.addAgent",
193	+	"title": "Add Agent",
194	+	"category": "Spectra",
195	+	"icon": "$(add)"
196	+	},
197	+	{
198	+	"command": "spectra.renewAgent",
199	+	"title": "Renew Agent",
200	+	"category": "Spectra"
201	+	},
202	+	{
203	+	"command": "spectra.openChannel",
204	+	"title": "Open Channel",
205	+	"category": "Spectra"
206	+	},
207	+	{
208	+	"command": "spectra.openProjectChannel",
209	+	"title": "Open This Project's Channel",
210	+	"category": "Spectra"
211	+	},
212	+	{
213	+	"command": "spectra.say",
214	+	"title": "Say",
215	+	"category": "Spectra"
216	+	},
217	+	{
218	+	"command": "spectra.editOverallBrief",
219	+	"title": "Edit Overall Brief",
220	+	"category": "Spectra"
221	+	},
222	+	{
223	+	"command": "spectra.editProjectBrief",
224	+	"title": "Edit Project Brief",
225	+	"category": "Spectra"
226	+	},
227	+	{
228	+	"command": "spectra.openRadar",
229	+	"title": "Open Radar",
230	+	"category": "Spectra"
231	+	},
232	+	{
233	+	"command": "spectra.openConstellation",
234	+	"title": "Open Constellation",
235	+	"category": "Spectra"
236	+	},
237	+	{
238	+	"command": "spectra.refresh",
239	+	"title": "Refresh",
240	+	"category": "Spectra",
241	+	"icon": "$(refresh)"
242	+	}
243	+	],
244	+	"menus": {
245	+	"view/title": [
246	+	{
247	+	"command": "spectra.addAgent",
248	+	"when": "view == spectra.agents",
249	+	"group": "navigation"
250	+	},
251	+	{
252	+	"command": "spectra.refresh",
253	+	"when": "view =~ /^spectra\\./",
254	+	"group": "navigation"
255	+	}
256	+	],
257	+	"view/item/context": [
258	+	{
259	+	"command": "spectra.renewAgent",
260	+	"when": "view == spectra.agents && viewItem == agent"
261	+	}
262	+	]
263	+	},
264	+	"configuration": {
265	+	"title": "Spectra",
266	+	"properties": {
267	+	"spectra.path": {
268	+	"type": "string",
269	+	"default": "",
270	+	"description": "The spectra program (empty: spectra on PATH, else ~/.local/bin/spectra)."
271	+	},
272	+	"spectra.agentsHome": {
273	+	"type": "string",
274	+	"default": "~/.spectra-agents",
275	+	"description": "Where new agents' identity homes are made."
276	+	}
277	+	}
278	+	}
279	+	},
280	+	"scripts": {
281	+	"build": "esbuild src/extension.ts --bundle --platform=node --format=cjs --external:vscode --outfile=dist/extension.js --sourcemap",
282	+	"watch": "npm run build -- --watch",
283	+	"typecheck": "tsc --noEmit -p .",
284	+	"types": "cp ../spectra/crates/spectra-api/ts/index.d.ts src/spectra-api.d.ts",
285	+	"pretest": "esbuild src/pure.ts --bundle --platform=node --format=esm --sourcemap --outfile=out/pure.mjs",
286	+	"test": "node --enable-source-maps --test \"test/*/.test.mjs\"",
287	+	"check": "npm run typecheck && npm run build && npm test",
288	+	"package": "vsce package --no-dependencies",
289	+	"smoke": "esbuild src/bridge.ts --bundle --platform=node --format=esm --alias:vscode=./test/vscode-stub.mjs --outfile=out/smoke-bridge.mjs && esbuild src/model.ts --bundle --platform=node --format=esm --alias:vscode=./test/vscode-stub.mjs --outfile=out/smoke-model.mjs && node test/smoke.mjs",
290	+	"vscode:prepublish": "npm run build"
291	+	},
292	+	"devDependencies": {
293	+	"@types/node": "^24.0.0",
294	+	"@types/vscode": "^1.138.0",
295	+	"@vscode/vsce": "^4.0.0",
296	+	"esbuild": "^0.28.0",
297	+	"typescript": "^5.9.0"
298	+	}
299	+	}

1	+	{
2	+	"name": "spectra-vscode",
3	+	"version": "0.1.0",
4	+	"lockfileVersion": 3,
5	+	"requires": true,
6	+	"packages": {
7	+	"": {
8	+	"name": "spectra-vscode",
9	+	"version": "0.1.0",
10	+	"license": "MIT OR Apache-2.0",
11	+	"devDependencies": {
12	+	"@types/node": "^24.0.0",
13	+	"@types/vscode": "^1.100.0",
14	+	"@vscode/vsce": "^4.0.0",
15	+	"esbuild": "^0.28.0",
16	+	"typescript": "^5.9.0"
17	+	},
18	+	"engines": {
19	+	"vscode": "^1.100.0"
20	+	}
21	+	},
22	+	"node_modules/@azure/abort-controller": {
23	+	"version": "2.2.0",
24	+	"resolved": "https://registry.npmjs.org/@azure/abort-controller/-/abort-controller-2.2.0.tgz",
25	+	"integrity": "sha512-fNAjWnA/nZ2jz31kxR/AqRaUT8ewHBw/WuBIosK0moMy1C9e5ValbDfFdIxJzVOOYaYkV/b2F1S4H/aHiqfVQg==",
26	+	"dev": true,
27	+	"license": "MIT",
28	+	"dependencies": {
29	+	"tslib": "^2.6.2"
30	+	},
31	+	"engines": {
32	+	"node": ">=22.0.0"
33	+	}
34	+	},
35	+	"node_modules/@azure/core-auth": {
36	+	"version": "1.11.0",
37	+	"resolved": "https://registry.npmjs.org/@azure/core-auth/-/core-auth-1.11.0.tgz",
38	+	"integrity": "sha512-IUZydyTUkDnYdstOW9pFOOUQlBjAepK5teihDE3x6yxsPJs/hsAaaYpeGxdxrgtOiJbBKSjKW7MDk7AEhb4LRg==",
39	+	"dev": true,
40	+	"license": "MIT",

1	+	// The extension's way to Spectra (spec §3): `spectra bridge` signs every
2	+	// request as the owner, so no key is ever handled here.
3	+	import * as cp from "node:child_process";
4	+	import * as vscode from "vscode";
5	+	import { binary } from "./cli";
6	+	import { SseParser } from "./pure";
7	+
8	+	export class SpectraError extends Error {
9	+	constructor(public status: number, message: string) {
10	+	super(message);
11	+	}
12	+	}
13	+
14	+	export class Bridge implements vscode.Disposable {
15	+	private child: cp.ChildProcess \| undefined;
16	+	private ready: Promise<{ url: string; token: string }> \| undefined;
17	+	private disposed = false;
18	+	private streams = new Set<AbortController>();
19	+	private readonly log: vscode.OutputChannel;
20	+
21	+	constructor(log: vscode.OutputChannel) {
22	+	this.log = log;
23	+	}
24	+
25	+	/** Start the bridge if it is not running. */
26	+	private start(): Promise<{ url: string; token: string }> {
27	+	if (this.ready) return this.ready;
28	+	this.ready = new Promise((resolve, reject) => {
29	+	const bin = binary();
30	+	if (!bin) return reject(new Error("spectra is not installed"));
31	+	const child = cp.spawn(bin, ["bridge"], { stdio: ["pipe", "pipe", "pipe"], env: { ...process.env, NO_COLOR: "1" } });
32	+	this.child = child;
33	+	let out = "";
34	+	let err = "";
35	+	child.stdout!.on("data", (d: Buffer) => {
36	+	out += d.toString();
37	+	const nl = out.indexOf("\n");
38	+	if (nl >= 0) {
39	+	try {
40	+	resolve(JSON.parse(out.slice(0, nl)));

1	+	// Briefs as documents (spec §5.2): `spectra-brief:/overall.md` and
2	+	// `spectra-brief:/project/NAME.md`. Opening one reads it from Spectra;
3	+	// saving it records a signed brief.set, so agents are told.
4	+	import * as vscode from "vscode";
5	+	import type { Briefs } from "./spectra-api";
6	+	import { Bridge } from "./bridge";
7	+
8	+	export const SCHEME = "spectra-brief";
9	+
10	+	export function uriFor(project?: string): vscode.Uri {
11	+	return vscode.Uri.from({ scheme: SCHEME, path: project ? `/project/${project}.md` : "/overall.md" });
12	+	}
13	+
14	+	function projectOf(uri: vscode.Uri): string \| undefined {
15	+	const m = /^\/project\/([a-z0-9][a-z0-9-]*)\.md$/.exec(uri.path);
16	+	if (m) return m[1];
17	+	if (uri.path === "/overall.md") return undefined;
18	+	throw vscode.FileSystemError.FileNotFound(uri);
19	+	}
20	+
21	+	export class BriefFs implements vscode.FileSystemProvider {
22	+	private readonly emitter = new vscode.EventEmitter<vscode.FileChangeEvent[]>();
23	+	readonly onDidChangeFile = this.emitter.event;
24	+	private readonly times = new Map<string, number>();
25	+
26	+	constructor(private readonly bridge: Bridge) {}
27	+
28	+	watch(): vscode.Disposable {
29	+	return new vscode.Disposable(() => undefined);
30	+	}
31	+
32	+	/** Tell open editors that briefs changed in Spectra. */
33	+	changed(): void {
34	+	const now = Date.now();
35	+	const events: vscode.FileChangeEvent[] = [];
36	+	for (const k of this.times.keys()) {
37	+	this.times.set(k, now);
38	+	events.push({ type: vscode.FileChangeType.Changed, uri: vscode.Uri.parse(k) });
39	+	}
40	+	if (events.length) this.emitter.fire(events);

1	+	// A channel as an editor tab (spec §5.3): its messages, newest at the
2	+	// bottom, threads opened in place, and a compose box that posts as you.
3	+	import * as vscode from "vscode";
4	+	import type { Message, Messages, Posted } from "./spectra-api";
5	+	import { Bridge } from "./bridge";
6	+	import { Model } from "./model";
7	+	import { esc, when } from "./pure";
8	+
9	+	const panels = new Map<string, ChannelPanel>();
10	+
11	+	export function openChannel(ctx: vscode.ExtensionContext, bridge: Bridge, model: Model, name: string): void {
12	+	const existing = panels.get(name);
13	+	if (existing) {
14	+	existing.panel.reveal();
15	+	return;
16	+	}
17	+	panels.set(name, new ChannelPanel(ctx, bridge, model, name));
18	+	}
19	+
20	+	class ChannelPanel {
21	+	readonly panel: vscode.WebviewPanel;
22	+	private subs: vscode.Disposable[] = [];
23	+	private openThread: string \| undefined;
24	+
25	+	constructor(ctx: vscode.ExtensionContext, private readonly bridge: Bridge, private readonly model: Model, private readonly name: string) {
26	+	const title = name.startsWith("dm:") ? `@${name.slice(3)}` : `#${name}`;
27	+	this.panel = vscode.window.createWebviewPanel("spectra.channel", title, vscode.ViewColumn.Active, { enableScripts: true, retainContextWhenHidden: true });
28	+	this.panel.iconPath = vscode.Uri.joinPath(ctx.extensionUri, "assets", "spectra.svg");
29	+	this.panel.webview.html = page(this.panel.webview, title);
30	+	this.subs.push(
31	+	this.panel.webview.onDidReceiveMessage((m) => void this.onMessage(m)),
32	+	model.onEvent((e) => {
33	+	if (e.kind === "message.posted" \|\| e.kind === "message.redacted") void this.load();
34	+	}),
35	+	this.panel.onDidDispose(() => {
36	+	panels.delete(name);
37	+	this.subs.forEach((s) => s.dispose());
38	+	}),
39	+	);
40	+	void this.load();

1	+	// Running the spectra program: setup commands, and the bridge.
2	+	import * as cp from "node:child_process";
3	+	import * as fs from "node:fs";
4	+	import * as os from "node:os";
5	+	import * as path from "node:path";
6	+	import * as vscode from "vscode";
7	+
8	+	export interface Ran {
9	+	code: number;
10	+	stdout: string;
11	+	stderr: string;
12	+	}
13	+
14	+	/** The spectra program: the setting, else PATH, else ~/.local/bin. */
15	+	export function binary(): string \| undefined {
16	+	const set = vscode.workspace.getConfiguration("spectra").get<string>("path")?.trim();
17	+	if (set) return set.replace(/^~(?=\/)/, os.homedir());
18	+	for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
19	+	const p = path.join(dir, "spectra");
20	+	if (dir && fs.existsSync(p)) return p;
21	+	}
22	+	const local = path.join(os.homedir(), ".local", "bin", "spectra");
23	+	return fs.existsSync(local) ? local : undefined;
24	+	}
25	+
26	+	export function run(args: string[], cwd?: string, input?: string): Promise<Ran> {
27	+	const bin = binary();
28	+	if (!bin) return Promise.resolve({ code: 127, stdout: "", stderr: "spectra is not installed (Spectra: Check for spectra)" });
29	+	return new Promise((resolve) => {
30	+	const child = cp.execFile(bin, args, { cwd, env: { ...process.env, NO_COLOR: "1" }, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
31	+	const code = err && typeof (err as cp.ExecFileException).code === "number" ? ((err as cp.ExecFileException).code as number) : err ? 1 : 0;
32	+	resolve({ code, stdout: String(stdout), stderr: String(stderr) });
33	+	});
34	+	if (input !== undefined) {
35	+	child.stdin?.end(input);
36	+	}
37	+	});
38	+	}
39	+
40	+	/** Run, and parse stdout as JSON; throw with spectra's own words on failure. */
41	+	export async function json<T>(args: string[], cwd?: string): Promise<T> {
42	+	const r = await run([...args], cwd);
43	+	if (r.code !== 0) throw new Error(why(r));
44	+	return JSON.parse(r.stdout) as T;
45	+	}
46	+
47	+	/** Run; throw with spectra's own words on failure. */
48	+	export async function ok(args: string[], cwd?: string, input?: string): Promise<string> {
49	+	const r = await run(args, cwd, input);
50	+	if (r.code !== 0) throw new Error(why(r));
51	+	return r.stdout;
52	+	}
53	+
54	+	/** The error spectra printed, without its `error:` prefix. */
55	+	export function why(r: Ran): string {
56	+	const text = (r.stderr.trim() \|\| r.stdout.trim()).split("\n").filter((l) => l.trim()).pop() ?? `spectra exited ${r.code}`;
57	+	return text.replace(/^error:\s*/, "");
58	+	}
59	+
60	+	export interface Status {
61	+	version: string;
62	+	home: string;
63	+	identity: { name: string; key: string } \| null;
64	+	server: { url: string; instance: string } \| null;
65	+	local: { data: string; initialised: boolean; serving: boolean };
66	+	reachable: boolean;
67	+	}
68	+
69	+	export function status(): Promise<Status> {
70	+	return json<Status>(["status", "--json"]);
71	+	}

1	+	// Spectra for VS Code: set Spectra up, chat with your agents, and give
2	+	// them their briefs, without the command line (spectra-vscode spec).
3	+	import * as vscode from "vscode";
4	+	import { Bridge } from "./bridge";
5	+	import { BriefFs, SCHEME, uriFor } from "./briefs";
6	+	import { openChannel } from "./chat";
7	+	import * as cli from "./cli";
8	+	import { Model } from "./model";
9	+	import * as setup from "./setup";
10	+	import * as views from "./views";
11	+
12	+	export async function activate(ctx: vscode.ExtensionContext): Promise<void> {
13	+	const log = vscode.window.createOutputChannel("Spectra");
14	+	const bridge = new Bridge(log);
15	+	const model = new Model(bridge);
16	+	const fsp = new BriefFs(bridge);
17	+	ctx.subscriptions.push(log, bridge, model, vscode.workspace.registerFileSystemProvider(SCHEME, fsp, { isCaseSensitive: true }));
18	+
19	+	for (const [id, view] of [
20	+	["spectra.channels", new views.Channels(model)],
21	+	["spectra.agents", new views.Agents(model)],
22	+	["spectra.inbox", new views.Inbox(model)],
23	+	["spectra.briefs", new views.Briefs(model)],
24	+	] as const) {
25	+	ctx.subscriptions.push(vscode.window.registerTreeDataProvider(id, view));
26	+	}
27	+
28	+	const bar = vscode.window.createStatusBarItem(vscode.StatusBarAlignment.Left, 50);
29	+	bar.command = "workbench.view.extension.spectra";
30	+	ctx.subscriptions.push(bar);
31	+
32	+	const set = (key: string, v: boolean) => vscode.commands.executeCommand("setContext", key, v);
33	+	let ready = false;
34	+
35	+	// What is set up, as contexts the walkthrough and views follow.
36	+	async function check(): Promise<void> {
37	+	const hasBinary = !!cli.binary();
38	+	await set("spectra.hasBinary", hasBinary);
39	+	const st = hasBinary ? await cli.status().catch(() => undefined) : undefined;
40	+	await set("spectra.hasIdentity", !!st?.identity);
41	+	const nowReady = !!st?.identity && !!(st.server \|\| st.local.initialised) && st.reachable;
42	+	if (nowReady !== ready) {
43	+	ready = nowReady;
44	+	if (ready) model.start();
45	+	else model.stop();
46	+	}
47	+	await set("spectra.ready", ready);
48	+	if (!ready) {
49	+	bar.text = "$(radio-tower) Spectra: set up";
50	+	bar.tooltip = st?.identity && (st.server \|\| st.local.initialised) ? "Spectra is not answering" : "Set Spectra up";
51	+	bar.command = st?.identity && (st.server \|\| st.local.initialised) ? "spectra.refresh" : "spectra.setup";
52	+	bar.show();
53	+	}
54	+	}
55	+
56	+	model.onDidChange(async () => {
57	+	await set("spectra.folderIsProject", !!model.folderProject());
58	+	await set("spectra.hasAgent", model.agents.some((a) => !a.disabled));
59	+	fsp.changed();
60	+	if (model.error) {
61	+	bar.text = "$(warning) Spectra";
62	+	bar.tooltip = model.error;
63	+	} else {
64	+	const online = model.agents.filter((a) => !a.disabled && a.presence !== "offline").length;
65	+	const unread = model.inbox.length;
66	+	bar.text = `$(radio-tower) ${online} agent${online === 1 ? "" : "s"} · ${unread} unread`;
67	+	bar.tooltip = `Spectra: ${model.agents.filter((a) => !a.disabled).length} agents, ${online} online; ${unread} unread for you`;
68	+	bar.command = unread ? "spectra.inbox.focus" : "workbench.view.extension.spectra";
69	+	}
70	+	bar.show();
71	+	});
72	+
73	+	const hooks: setup.Hooks = {
74	+	changed: async () => {
75	+	bridge.restart();
76	+	if (ready) model.start();
77	+	await check();
78	+	await model.refresh();
79	+	},
80	+	projects: () => model.projects,
81	+	agents: () => model.agents,
82	+	folderProject: () => model.folderProject(),
83	+	};
84	+
85	+	const radar = (page?: string) => {
86	+	const bin = cli.binary();
87	+	if (!bin) return;
88	+	const t = vscode.window.createTerminal({ name: "Spectra Radar", shellPath: bin, shellArgs: ["open", ...(page ? ["--page", page] : [])] });
89	+	t.show(true);
90	+	};
91	+
92	+	const cmd = (id: string, f: (...a: never[]) => unknown) => ctx.subscriptions.push(vscode.commands.registerCommand(id, f));
93	+	cmd("spectra.setup", () => vscode.commands.executeCommand("workbench.action.openWalkthrough", `${ctx.extension.id}#spectra.setup`, false));
94	+	cmd("spectra.checkBinary", async () => {
95	+	await setup.checkBinary();
96	+	await check();
97	+	});
98	+	cmd("spectra.createIdentity", () => setup.createIdentity(hooks));
99	+	cmd("spectra.setupHere", () => setup.setupHere(hooks));
100	+	cmd("spectra.connectServer", () => setup.connectServer(hooks));
101	+	cmd("spectra.registerFolder", () => setup.registerFolder(hooks));
102	+	cmd("spectra.linkProject", () => setup.linkProject(hooks));
103	+	cmd("spectra.addAgent", () => setup.addAgent(hooks));
104	+	cmd("spectra.renewAgent", (item?: vscode.TreeItem) => setup.renewAgent(hooks, typeof item?.label === "string" ? item.label : undefined));
105	+	cmd("spectra.openChannel", async (name?: string) => {
106	+	const pick = name ?? (await vscode.window.showQuickPick(model.channels.map((c) => c.name), { placeHolder: "Which channel?" }));
107	+	if (pick) openChannel(ctx, bridge, model, pick);
108	+	});
109	+	cmd("spectra.openProjectChannel", () => openChannel(ctx, bridge, model, model.folderProject() ?? "general"));
110	+	cmd("spectra.say", async () => {
111	+	const channel = model.folderProject() ?? "general";
112	+	const body = await vscode.window.showInputBox({ prompt: `Say in #${channel}, as yourself` });
113	+	if (!body) return;
114	+	try {
115	+	await bridge.request("POST", `/api/v1/channels/${encodeURIComponent(channel)}/messages`, { body });
116	+	} catch (e) {
117	+	void vscode.window.showErrorMessage(`Spectra: ${(e as Error).message}`);
118	+	}
119	+	});
120	+	cmd("spectra.editOverallBrief", () => vscode.window.showTextDocument(uriFor()));
121	+	cmd("spectra.editProjectBrief", async (project?: string) => {
122	+	const p = project ?? model.folderProject() ?? (await vscode.window.showQuickPick(model.projects.map((x) => x.name), { placeHolder: "Which project's brief?" }));
123	+	if (p) await vscode.window.showTextDocument(uriFor(p));
124	+	});
125	+	cmd("spectra.openRadar", () => radar());
126	+	cmd("spectra.openConstellation", () => radar("constellation"));
127	+	cmd("spectra.refresh", async () => {
128	+	await check();
129	+	if (ready) await model.refresh();
130	+	});
131	+
132	+	await check();
133	+	if (!ready && !ctx.globalState.get("spectra.walkthroughShown")) {
134	+	await ctx.globalState.update("spectra.walkthroughShown", true);
135	+	void vscode.commands.executeCommand("spectra.setup");
136	+	}
137	+	}
138	+
139	+	export function deactivate(): void {
140	+	// The bridge ends with its input, which closes when the extension host does.
141	+	}

1	+	// What the side bar shows, kept current from the event stream.
2	+	import * as vscode from "vscode";
3	+	import type { Agent, Brief, Briefs, Channel, InboxItem, Project } from "./spectra-api";
4	+	import { Bridge } from "./bridge";
5	+	import { projectForFolder } from "./pure";
6	+
7	+	export interface StreamEvent {
8	+	seq: number;
9	+	kind: string;
10	+	actor: string;
11	+	subject?: string \| null;
12	+	}
13	+
14	+	export class Model implements vscode.Disposable {
15	+	brief: Brief \| undefined;
16	+	agents: Agent[] = [];
17	+	channels: Channel[] = [];
18	+	projects: Project[] = [];
19	+	inbox: InboxItem[] = [];
20	+	briefs: Briefs = { overall: null, projects: [] };
21	+	error: string \| undefined;
22	+
23	+	private readonly changed = new vscode.EventEmitter<void>();
24	+	readonly onDidChange = this.changed.event;
25	+	private readonly events = new vscode.EventEmitter<StreamEvent>();
26	+	/** Every event from the stream, for open chats. */
27	+	readonly onEvent = this.events.event;
28	+	private timer: NodeJS.Timeout \| undefined;
29	+	private stream: vscode.Disposable \| undefined;
30	+
31	+	constructor(private readonly bridge: Bridge) {}
32	+
33	+	/** Start following the stream and fetch everything. */
34	+	start(): void {
35	+	this.stream?.dispose();
36	+	this.stream = this.bridge.follow(
37	+	"/api/v1/events?follow=1",
38	+	(data) => {
39	+	try {
40	+	const e = JSON.parse(data) as StreamEvent;
41	+	this.events.fire(e);
42	+	} catch {
43	+	return;
44	+	}
45	+	this.soon();
46	+	},
47	+	() => this.soon(),
48	+	);
49	+	void this.refresh();
50	+	}
51	+
52	+	stop(): void {
53	+	this.stream?.dispose();
54	+	this.stream = undefined;
55	+	}
56	+
57	+	/** Refresh shortly, once for a burst of events. */
58	+	soon(): void {
59	+	if (this.timer) clearTimeout(this.timer);
60	+	this.timer = setTimeout(() => void this.refresh(), 300);
61	+	}
62	+
63	+	async refresh(): Promise<void> {
64	+	try {
65	+	const [brief, agents, channels, projects, inbox, briefs] = await Promise.all([
66	+	this.bridge.request<Brief>("GET", "/api/v1/brief"),
67	+	this.bridge.request<Agent[]>("GET", "/api/v1/agents"),
68	+	this.bridge.request<Channel[]>("GET", "/api/v1/channels"),
69	+	this.bridge.request<Project[]>("GET", "/api/v1/projects"),
70	+	this.bridge.request<InboxItem[]>("GET", "/api/v1/inbox"),
71	+	this.bridge.request<Briefs>("GET", "/api/v1/briefs"),
72	+	]);
73	+	Object.assign(this, { brief, agents, channels, projects, inbox, briefs, error: undefined });
74	+	} catch (e) {
75	+	this.error = (e as Error).message;
76	+	}
77	+	this.changed.fire();
78	+	}
79	+
80	+	/** The project of the first workspace folder, if it is one. */
81	+	folderProject(): string \| undefined {
82	+	const f = vscode.workspace.workspaceFolders?.[0];
83	+	return f ? projectForFolder(this.projects, f.uri.fsPath) : undefined;
84	+	}
85	+
86	+	dispose(): void {
87	+	this.stop();
88	+	this.changed.dispose();
89	+	this.events.dispose();
90	+	}
91	+	}

1	+	// Helpers with no VS Code in them, so they can be tested with node:test.
2	+
3	+	/** Server-sent events: feed chunks, get back each event's data. */
4	+	export class SseParser {
5	+	private buf = "";
6	+	private data: string[] = [];
7	+	push(chunk: string): string[] {
8	+	this.buf += chunk;
9	+	const out: string[] = [];
10	+	let i: number;
11	+	while ((i = this.buf.indexOf("\n")) >= 0) {
12	+	const line = this.buf.slice(0, i).replace(/\r$/, "");
13	+	this.buf = this.buf.slice(i + 1);
14	+	if (line === "") {
15	+	if (this.data.length) out.push(this.data.join("\n"));
16	+	this.data = [];
17	+	} else if (line.startsWith("data:")) {
18	+	this.data.push(line.slice(5).replace(/^ /, ""));
19	+	}
20	+	}
21	+	return out;
22	+	}
23	+	}
24	+
25	+	export const KINDS: { kind: string; label: string; prefix: string }[] = [
26	+	{ kind: "claude-code", label: "Claude Code", prefix: "claude" },
27	+	{ kind: "antigravity", label: "Antigravity", prefix: "agy" },
28	+	{ kind: "kimi-code", label: "Kimi Code", prefix: "kimi" },
29	+	{ kind: "codex", label: "Codex", prefix: "codex" },
30	+	{ kind: "other", label: "Another MCP client", prefix: "agent" },
31	+	];
32	+
33	+	/** A name Spectra accepts: lower-case letters, digits and dashes. */
34	+	export function validName(n: string): boolean {
35	+	return /^[a-z0-9][a-z0-9-]{0,63}$/.test(n);
36	+	}
37	+
38	+	/** A project name from a folder name. */
39	+	export function nameFromFolder(folder: string): string {
40	+	const base = folder.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "";
41	+	const n = base.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+/, "").slice(0, 64);
42	+	return n \|\| "project";
43	+	}
44	+
45	+	/** The suggested agent name for a kind on a project, not already taken. */
46	+	export function suggestAgentName(kind: string, project: string, taken: string[]): string {
47	+	const prefix = KINDS.find((k) => k.kind === kind)?.prefix ?? "agent";
48	+	const base = `${prefix}-${project}`.slice(0, 60);
49	+	if (!taken.includes(base)) return base;
50	+	for (let i = 2; ; i++) if (!taken.includes(`${base}-${i}`)) return `${base}-${i}`;
51	+	}
52	+
53	+	export const EXPIRIES: { label: string; arg: string \| undefined }[] = [
54	+	{ label: "8 hours", arg: "8h" },
55	+	{ label: "A day", arg: "1d" },
56	+	{ label: "A week", arg: "7d" },
57	+	{ label: "Until I disable it", arg: undefined },
58	+	];
59	+
60	+	/** `~/x` with the home directory. */
61	+	export function expandHome(p: string, home: string): string {
62	+	return p === "~" ? home : p.startsWith("~/") ? home.replace(/\/$/, "") + p.slice(1) : p;
63	+	}
64	+
65	+	/** The arguments of the stdio shim for an agent. */
66	+	export function shimArgs(agent: string, home: string): string[] {
67	+	return ["mcp", "--agent", agent, "--home", home];
68	+	}
69	+
70	+	/** Antigravity's mcp_config.json with Spectra's server set, keeping the rest. */
71	+	export function mergeMcpConfig(existing: string, command: string, args: string[]): string {
72	+	let cfg: Record<string, unknown> = {};
73	+	if (existing.trim()) {
74	+	const parsed = JSON.parse(existing);
75	+	if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) cfg = parsed as Record<string, unknown>;
76	+	}
77	+	const servers = (cfg.mcpServers && typeof cfg.mcpServers === "object" ? cfg.mcpServers : {}) as Record<string, unknown>;
78	+	servers.spectra = { command, args };
79	+	cfg.mcpServers = servers;
80	+	return JSON.stringify(cfg, null, 2) + "\n";
81	+	}
82	+
83	+	/** The project whose folder holds `folder`, the deepest if several do. */
84	+	export function projectForFolder(projects: { name: string; path?: string \| null }[], folder: string): string \| undefined {
85	+	const norm = (p: string) => p.replace(/[\\/]+$/, "");
86	+	const f = norm(folder);
87	+	let best: { name: string; len: number } \| undefined;
88	+	for (const p of projects) {
89	+	if (!p.path) continue;
90	+	const q = norm(p.path);
91	+	if ((f === q \|\| f.startsWith(q + "/")) && (!best \|\| q.length > best.len)) best = { name: p.name, len: q.length };
92	+	}
93	+	return best?.name;
94	+	}
95	+
96	+	/** `12:04` today, else `3 Nov 12:04`. */
97	+	export function when(ms: number, now = Date.now()): string {
98	+	const d = new Date(ms);
99	+	const t = d.toTimeString().slice(0, 5);
100	+	return new Date(now).toDateString() === d.toDateString() ? t : `${d.getDate()} ${d.toLocaleString("en-GB", { month: "short" })} ${t}`;
101	+	}
102	+
103	+	/** Text for HTML. */
104	+	export function esc(s: string): string {
105	+	return s.replace(/&/g, "&").replace(/</g, "<").replace(/>/g, ">").replace(/"/g, """).replace(/'/g, "'");
106	+	}

1	+	// Setting Spectra up without the command line (spec §5.0). Each step runs
2	+	// a spectra command; every confirmation spectra would ask at a terminal is
3	+	// a dialog here, after which the command runs with --yes or --expect.
4	+	import * as cp from "node:child_process";
5	+	import * as fs from "node:fs";
6	+	import * as os from "node:os";
7	+	import * as path from "node:path";
8	+	import * as vscode from "vscode";
9	+	import * as cli from "./cli";
10	+	import { EXPIRIES, KINDS, expandHome, mergeMcpConfig, nameFromFolder, shimArgs, suggestAgentName, validName } from "./pure";
11	+	import type { Agent, Project } from "./spectra-api";
12	+
13	+	export interface Hooks {
14	+	/** After a step that changes what Spectra is or who signs. */
15	+	changed(): Promise<void>;
16	+	projects(): Project[];
17	+	agents(): Agent[];
18	+	folderProject(): string \| undefined;
19	+	}
20	+
21	+	function folder(): vscode.WorkspaceFolder \| undefined {
22	+	return vscode.workspace.workspaceFolders?.[0];
23	+	}
24	+
25	+	async function fail(e: unknown): Promise<undefined> {
26	+	void vscode.window.showErrorMessage(`Spectra: ${(e as Error).message}`);
27	+	return undefined;
28	+	}
29	+
30	+	export async function checkBinary(): Promise<boolean> {
31	+	const bin = cli.binary();
32	+	if (bin) {
33	+	const r = await cli.run(["--version"]);
34	+	if (r.code === 0) {
35	+	void vscode.window.showInformationMessage(`Found ${r.stdout.trim()} at ${bin}.`);
36	+	return true;
37	+	}
38	+	}
39	+	const pick = await vscode.window.showWarningMessage(
40	+	"The spectra program was not found. Install it (make install in the spectra repository puts it in ~/.local/bin), or point Spectra at it.",
41	+	"Locate spectra…",
42	+	);
43	+	if (pick) {
44	+	const f = await vscode.window.showOpenDialog({ canSelectMany: false, openLabel: "Use this spectra" });
45	+	if (f?.[0]) {
46	+	await vscode.workspace.getConfiguration("spectra").update("path", f[0].fsPath, vscode.ConfigurationTarget.Global);
47	+	return checkBinary();
48	+	}
49	+	}
50	+	return false;
51	+	}
52	+
53	+	export async function createIdentity(h: Hooks): Promise<void> {
54	+	const st = await cli.status().catch(() => undefined);
55	+	if (st?.identity) {
56	+	void vscode.window.showInformationMessage(`You already have an identity: ${st.identity.name}, key ${st.identity.key.slice(0, 12)}…`);
57	+	return;
58	+	}
59	+	const name = await vscode.window.showInputBox({
60	+	title: "Your identity (1/2)",
61	+	prompt: "Your name, as your agents and Radar will show it",
62	+	value: os.userInfo().username,
63	+	validateInput: (v) => (v.trim() ? undefined : "A name, please"),
64	+	});
65	+	if (!name) return;
66	+	const contact = await vscode.window.showInputBox({ title: "Your identity (2/2)", prompt: "An email or URL to show beside it (optional)" });
67	+	if (contact === undefined) return;
68	+	try {
69	+	const made = await cli.json<{ name: string; key: string; home: string }>(["identity", "create", "--name", name.trim(), "--contact", contact.trim(), "--json"]);
70	+	const copy = await vscode.window.showInformationMessage(
71	+	`Created your identity, ${made.name}. Its key is ${made.key.slice(0, 12)}…; the keys folder in ${made.home} is secret: anyone with it can act as you.`,
72	+	"Copy Key",
73	+	);
74	+	if (copy) await vscode.env.clipboard.writeText(made.key);
75	+	await h.changed();
76	+	} catch (e) {
77	+	await fail(e);
78	+	}
79	+	}
80	+
81	+	export async function setupHere(h: Hooks): Promise<void> {
82	+	const ok = await vscode.window.showInformationMessage(
83	+	"Run Spectra on this machine?",
84	+	{ modal: true, detail: "This makes its ledger in ~/.local/share/spectra, owned by your identity, and starts it. Agents on this machine connect to it." },
85	+	"Run Here",
86	+	);
87	+	if (!ok) return;
88	+	try {
89	+	const st = await cli.status();
90	+	if (!st.local.initialised) await cli.ok(["init"]);
91	+	if (!(await cli.status()).local.serving) startDaemon();
92	+	await new Promise((r) => setTimeout(r, 1500));
93	+	await h.changed();
94	+	} catch (e) {
95	+	await fail(e);
96	+	}
97	+	}
98	+
99	+	/** The user service if it is installed, else a terminal running spectra serve. */
100	+	export function startDaemon(): void {
101	+	const unit = path.join(os.homedir(), ".config", "systemd", "user", "spectra.service");
102	+	if (fs.existsSync(unit)) {
103	+	cp.execFile("systemctl", ["--user", "start", "spectra"], () => undefined);
104	+	return;
105	+	}
106	+	const bin = cli.binary();
107	+	if (!bin) return;
108	+	const t = vscode.window.createTerminal({ name: "Spectra", shellPath: bin, shellArgs: ["serve"], isTransient: false });
109	+	t.show(true);
110	+	}
111	+
112	+	export async function connectServer(h: Hooks): Promise<void> {
113	+	const url = await vscode.window.showInputBox({
114	+	title: "Connect to a server",
115	+	prompt: "The server's address",
116	+	placeHolder: "https://earth.example:7350",
117	+	validateInput: (v) => (/^https:\/\/[^/\s]+/.test(v.trim()) ? undefined : "An https:// address"),
118	+	});
119	+	if (!url) return;
120	+	const st = await cli.status().catch(() => undefined);
121	+	let probe: { name: string; instance: string; owner: string \| null; waiting_for: string \| null; yours: boolean };
122	+	try {
123	+	probe = await cli.json(["probe", url.trim(), "--json"]);
124	+	} catch (e) {
125	+	const msg = (e as Error).message;
126	+	const copy = await vscode.window.showErrorMessage(
127	+	`Spectra: ${msg}. If the server is not set up yet, run there: spectra init --owner ${st?.identity?.key ?? "YOUR-KEY"}`,
128	+	...(st?.identity ? ["Copy That Command"] : []),
129	+	);
130	+	if (copy && st?.identity) await vscode.env.clipboard.writeText(`spectra init --owner ${st.identity.key}`);
131	+	return;
132	+	}
133	+	if (!probe.yours) {
134	+	const whose = probe.owner ? "belongs to someone else" : `waits for another identity (${(probe.waiting_for ?? "").slice(0, 12)}…)`;
135	+	const copy = await vscode.window.showErrorMessage(
136	+	`Spectra: ${probe.name} ${whose}. To set it up for you, run there: spectra init --owner ${st?.identity?.key ?? "YOUR-KEY"}`,
137	+	...(st?.identity ? ["Copy That Command"] : []),
138	+	);
139	+	if (copy && st?.identity) await vscode.env.clipboard.writeText(`spectra init --owner ${st.identity.key}`);
140	+	return;
141	+	}
142	+	const grouped = probe.instance.match(/.{1,4}/g)!.join(" ");
143	+	const trust = await vscode.window.showWarningMessage(
144	+	`Trust ${probe.name} as your Spectra?`,
145	+	{
146	+	modal: true,
147	+	detail: `Its instance key is:\n\n${grouped}\n\nWhen the server was set up, spectra init printed its instance key. Trust it only if this is the same. Your identity will then delegate to it, and this machine will pin its certificate.`,
148	+	},
149	+	"Trust",
150	+	);
151	+	if (!trust) return;
152	+	try {
153	+	await cli.ok(["connect", url.trim(), "--expect", probe.instance]);
154	+	void vscode.window.showInformationMessage(`Connected to ${probe.name}.`);
155	+	await h.changed();
156	+	} catch (e) {
157	+	await fail(e);
158	+	}
159	+	}
160	+
161	+	export async function registerFolder(h: Hooks): Promise<void> {
162	+	const f = folder();
163	+	if (!f) {
164	+	void vscode.window.showWarningMessage("Open a folder first: a project is the work in it.");
165	+	return;
166	+	}
167	+	const already = h.folderProject();
168	+	if (already) {
169	+	void vscode.window.showInformationMessage(`This folder is already the project ${already}.`);
170	+	return;
171	+	}
172	+	const taken = h.projects().map((p) => p.name);
173	+	const name = await vscode.window.showInputBox({
174	+	title: "Register this folder as a project (1/2)",
175	+	prompt: "The project's name; its channel is #name",
176	+	value: nameFromFolder(f.uri.fsPath),
177	+	validateInput: (v) => (!validName(v) ? "Lower-case letters, digits and dashes" : taken.includes(v) ? "Taken" : undefined),
178	+	});
179	+	if (!name) return;
180	+	const description = await vscode.window.showInputBox({ title: "Register this folder as a project (2/2)", prompt: "What the work is, for your agents (optional)" });
181	+	if (description === undefined) return;
182	+	try {
183	+	await cli.ok(["project", "add", f.uri.fsPath, "--name", name, "-d", description]);
184	+	await h.changed();
185	+	} catch (e) {
186	+	await fail(e);
187	+	}
188	+	}
189	+
190	+	export async function linkProject(h: Hooks): Promise<void> {
191	+	const names = h.projects().map((p) => p.name);
192	+	const p = await vscode.window.showQuickPick(names, { title: "Link projects (1/2)", placeHolder: "Which project depends on another?" });
193	+	if (!p) return;
194	+	const q = await vscode.window.showQuickPick(names.filter((n) => n !== p), { title: "Link projects (2/2)", placeHolder: `${p} depends on…` });
195	+	if (!q) return;
196	+	try {
197	+	await cli.ok(["project", "link", p, "--depends-on", q]);
198	+	await h.changed();
199	+	} catch (e) {
200	+	await fail(e);
201	+	}
202	+	}
203	+
204	+	export async function addAgent(h: Hooks): Promise<void> {
205	+	const projects = h.projects().map((p) => p.name);
206	+	if (!projects.length) {
207	+	void vscode.window.showWarningMessage("An agent needs a project: register this folder first.", "Register This Folder").then((x) => {
208	+	if (x) void vscode.commands.executeCommand("spectra.registerFolder");
209	+	});
210	+	return;
211	+	}
212	+	const kind = await vscode.window.showQuickPick(
213	+	KINDS.map((k) => ({ label: k.label, client: k.kind })),
214	+	{ title: "Add an agent (1/4)", placeHolder: "Which client will the agent run in?" },
215	+	);
216	+	if (!kind) return;
217	+	const mine = h.folderProject();
218	+	const project =
219	+	projects.length === 1
220	+	? projects[0]
221	+	: await vscode.window.showQuickPick(
222	+	[...projects].sort((a, b) => Number(b === mine) - Number(a === mine)),
223	+	{ title: "Add an agent (2/4)", placeHolder: "Which project will it work on?" },
224	+	);
225	+	if (!project) return;
226	+	const taken = h.agents().map((a) => a.name);
227	+	const name = await vscode.window.showInputBox({
228	+	title: "Add an agent (3/4)",
229	+	prompt: "Its name",
230	+	value: suggestAgentName(kind.client, project, taken),
231	+	validateInput: (v) => (!validName(v) ? "Lower-case letters, digits and dashes" : taken.includes(v) ? "Taken" : undefined),
232	+	});
233	+	if (!name) return;
234	+	const expiry = await vscode.window.showQuickPick(EXPIRIES.map((e) => ({ label: e.label, arg: e.arg })), {
235	+	title: "Add an agent (4/4)",
236	+	placeHolder: "How long may it act for you? (Renew Agent gives it more time later.)",
237	+	});
238	+	if (!expiry) return;
239	+	const home = expandHome(path.join(vscode.workspace.getConfiguration("spectra").get<string>("agentsHome") \|\| "~/.spectra-agents", name), os.homedir());
240	+	const ok = await vscode.window.showWarningMessage(
241	+	`Let ${name} act for you?`,
242	+	{ modal: true, detail: `${kind.label} on #${project}, ${expiry.arg ? `for ${expiry.label.toLowerCase()}` : "until you disable it"}. Its key is made in ${home}; your identity will delegate to it.` },
243	+	"Let It Act for Me",
244	+	);
245	+	if (!ok) return;
246	+	try {
247	+	const args = ["agent", "add", name, "--kind", kind.client, "--project", project, "--home", home, "--yes", ...(expiry.arg ? ["--expires", expiry.arg] : [])];
248	+	await cli.ok(args);
249	+	await h.changed();
250	+	} catch (e) {
251	+	await fail(e);
252	+	return;
253	+	}
254	+	await configureClient(kind.client, name, home);
255	+	}
256	+
257	+	/** Write the agent's MCP entry for its client, or say how. */
258	+	async function configureClient(kind: string, agent: string, home: string): Promise<void> {
259	+	const bin = cli.binary() ?? "spectra";
260	+	const args = shimArgs(agent, home);
261	+	const line = `${bin} ${args.join(" ")}`;
262	+	const which = KINDS.find((k) => k.kind === kind)?.label ?? kind;
263	+	const go = await vscode.window.showInformationMessage(`Added ${agent}. Connect ${which} to Spectra as ${agent}?`, "Connect It", "Show Me How");
264	+	if (go === "Show Me How" \|\| !go) {
265	+	if (go) {
266	+	const doc = await vscode.workspace.openTextDocument({
267	+	language: "markdown",
268	+	content: `# Connecting ${agent}\n\nIn ${which}, add an MCP server named \`spectra\` that runs:\n\n\`\`\`\n${line}\n\`\`\`\n\nClaude Code: \`claude mcp add spectra -- ${line}\` in the project's folder.\nKimi Code: \`kimi mcp add spectra -- ${line}\`.\nAntigravity: in \`~/.gemini/config/mcp_config.json\`, \`mcpServers.spectra = { "command": "${bin}", "args": ${JSON.stringify(args)} }\`.\n`,
269	+	});
270	+	await vscode.window.showTextDocument(doc);
271	+	}
272	+	return;
273	+	}
274	+	const cwd = folder()?.uri.fsPath;
275	+	try {
276	+	if (kind === "claude-code" \|\| kind === "kimi-code") {
277	+	const tool = kind === "claude-code" ? "claude" : "kimi";
278	+	await new Promise<void>((resolve) => cp.execFile(tool, ["mcp", "remove", "spectra"], { cwd }, () => resolve()));
279	+	await new Promise<void>((resolve, reject) =>
280	+	cp.execFile(tool, ["mcp", "add", "spectra", "--", bin, ...args], { cwd }, (err, _o, stderr) => (err ? reject(new Error(stderr.trim() \|\| err.message)) : resolve())),
281	+	);
282	+	void vscode.window.showInformationMessage(`${which} in this folder now connects to Spectra as ${agent}: start a new session there to pick it up.`);
283	+	} else if (kind === "antigravity") {
284	+	const file = path.join(os.homedir(), ".gemini", "config", "mcp_config.json");
285	+	const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
286	+	if (before) fs.copyFileSync(file, file + ".bak");
287	+	fs.mkdirSync(path.dirname(file), { recursive: true });
288	+	fs.writeFileSync(file, mergeMcpConfig(before, bin, args));
289	+	void vscode.window.showInformationMessage(`Antigravity now connects to Spectra as ${agent} (${file}${before ? ", previous copy kept as .bak" : ""}): restart it to pick it up.`);
290	+	} else {
291	+	await vscode.env.clipboard.writeText(line);
292	+	void vscode.window.showInformationMessage(`Copied the command for ${which}'s MCP settings: ${line}`);
293	+	}
294	+	} catch (e) {
295	+	void vscode.window.showWarningMessage(`Could not configure ${which} (${(e as Error).message}). Add an MCP server named spectra running: ${line}`);
296	+	}
297	+	}
298	+
299	+	export async function renewAgent(h: Hooks, agent?: string): Promise<void> {
300	+	const name = agent ?? (await vscode.window.showQuickPick(h.agents().filter((a) => !a.disabled).map((a) => a.name), { placeHolder: "Which agent?" }));
301	+	if (!name) return;
302	+	const expiry = await vscode.window.showQuickPick(EXPIRIES.map((e) => ({ label: e.label, arg: e.arg ?? "never" })), { placeHolder: `How long may ${name} act for you from now?` });
303	+	if (!expiry) return;
304	+	try {
305	+	await cli.ok(["agent", "renew", name, "--expires", expiry.arg]);
306	+	await h.changed();
307	+	} catch (e) {
308	+	await fail(e);
309	+	}
310	+	}

1	+	// Generated by `cargo run -p spectra-api --bin spectra-api-typescript`; do not edit.
2	+	// Types of the Spectra JSON API (spec §18).
3	+
4	+	export type Problem = {
5	+	detail?: string \| null;
6	+	status: number;
7	+	title: string;
8	+	type: string;
9	+	};
10	+
11	+	export type Version = {
12	+	ledger_format: number;
13	+	mcp_protocol_versions: string[];
14	+	version: string;
15	+	};
16	+
17	+	export type Agent = {
18	+	delegation_expires?: number \| null;
19	+	disabled: boolean;
20	+	display: string;
21	+	key: string;
22	+	kind: string;
23	+	name: string;
24	+	owner: string;
25	+	presence: string;
26	+	project: string;
27	+	state?: string;
28	+	status?: string \| null;
29	+	};
30	+
31	+	export type Project = {
32	+	agents?: string[];
33	+	depended_on_by: string[];
34	+	depends_on: string[];
35	+	description?: string;
36	+	name: string;
37	+	path?: string \| null;
38	+	url?: string \| null;
39	+	};
40	+
41	+	export type Channel = {
42	+	display: string;
43	+	id: string;
44	+	kind: string;
45	+	messages: number;
46	+	name: string;
47	+	purpose?: string \| null;
48	+	};
49	+
50	+	export type Message = {
51	+	at_ms: number;
52	+	author: string;
53	+	author_display: string;
54	+	body: string;
55	+	channel: string;
56	+	id: string;
57	+	kind: string;
58	+	mentions: string[];
59	+	redacted: boolean;
60	+	refs: string[];
61	+	replies: number;
62	+	reply_to?: string \| null;
63	+	};
64	+
65	+	export type Messages = {
66	+	channel: string;
67	+	items: Message[];
68	+	next?: string \| null;
69	+	};
70	+
71	+	export type NewMessage = {
72	+	body: string;
73	+	kind?: string \| null;
74	+	reply_to?: string \| null;
75	+	};
76	+
77	+	export type Posted = {
78	+	channel: string;
79	+	duplicate: boolean;
80	+	id: string;
81	+	};
82	+
83	+	export type InboxItem = {
84	+	at_ms: number;
85	+	channel: string;
86	+	from: string;
87	+	from_display?: string;
88	+	id: string;
89	+	kind: string;
90	+	summary: string;
91	+	};
92	+
93	+	export type Ack = {
94	+	ids: string[];
95	+	reaction?: string \| null;
96	+	};
97	+
98	+	export type Hit = {
99	+	at_ms: number;
100	+	author: string;
101	+	author_display?: string;
102	+	channel: string;
103	+	id: string;
104	+	snippet: string;
105	+	thread?: string \| null;
106	+	};
107	+
108	+	export type ProjectBrief = {
109	+	project: string;
110	+	text: string;
111	+	};
112	+
113	+	export type Briefs = {
114	+	overall?: string \| null;
115	+	projects: ProjectBrief[];
116	+	};
117	+
118	+	export type SetBrief = {
119	+	project?: string \| null;
120	+	text: string;
121	+	};
122	+
123	+	export type EventSummary = {
124	+	actor: string;
125	+	assurance: number;
126	+	at_ms: number;
127	+	hash: string;
128	+	id: string;
129	+	kind: string;
130	+	method: string;
131	+	seq: number;
132	+	subject?: string \| null;
133	+	};
134	+
135	+	export type Events = {
136	+	items: EventSummary[];
137	+	next?: number \| null;
138	+	};
139	+
140	+	export type Brief = {
141	+	actor: string;
142	+	agents: Agent[];
143	+	head: number;
144	+	inbox: InboxItem[];
145	+	project?: string \| null;
146	+	rules_version: string;
147	+	unread: number;
148	+	you: string;
149	+	};
150	+

1	+	// The side bar: Channels, Agents, Inbox and Briefs.
2	+	import * as vscode from "vscode";
3	+	import { Model } from "./model";
4	+	import { when } from "./pure";
5	+
6	+	abstract class View implements vscode.TreeDataProvider<vscode.TreeItem> {
7	+	private readonly emitter = new vscode.EventEmitter<void>();
8	+	readonly onDidChangeTreeData = this.emitter.event;
9	+	constructor(protected readonly model: Model) {
10	+	model.onDidChange(() => this.emitter.fire());
11	+	}
12	+	getTreeItem(i: vscode.TreeItem): vscode.TreeItem {
13	+	return i;
14	+	}
15	+	getChildren(): vscode.TreeItem[] {
16	+	if (this.model.error) {
17	+	const i = new vscode.TreeItem("Spectra is not answering");
18	+	i.description = this.model.error;
19	+	i.tooltip = this.model.error;
20	+	i.iconPath = new vscode.ThemeIcon("warning");
21	+	i.command = { command: "spectra.refresh", title: "Refresh" };
22	+	return [i];
23	+	}
24	+	return this.items();
25	+	}
26	+	protected abstract items(): vscode.TreeItem[];
27	+	}
28	+
29	+	const PRESENCE: Record<string, string> = { online: "charts.green", busy: "charts.purple", idle: "charts.yellow", blocked: "charts.orange", paused: "charts.yellow", offline: "disabledForeground" };
30	+
31	+	export class Agents extends View {
32	+	protected items(): vscode.TreeItem[] {
33	+	return this.model.agents
34	+	.filter((a) => !a.disabled)
35	+	.map((a) => {
36	+	const i = new vscode.TreeItem(a.name);
37	+	i.description = `${a.presence} · #${a.project}${a.status ? ` · ${a.status}` : ""}`;
38	+	const expires = a.delegation_expires ? `\nMay act for you until ${new Date(a.delegation_expires).toLocaleString()}` : "";
39	+	const state = a.state && a.state !== "ok" ? `\n⚠ ${a.state}` : "";
40	+	i.tooltip = `${a.display}\n${a.kind}${expires}${state}`;
41	+	i.iconPath = new vscode.ThemeIcon(a.state && a.state !== "ok" ? "warning" : "circle-filled", new vscode.ThemeColor(PRESENCE[a.presence] ?? "disabledForeground"));
42	+	i.contextValue = "agent";
43	+	i.id = `agent:${a.name}`;
44	+	return i;
45	+	});
46	+	}
47	+	}
48	+
49	+	export class Channels extends View {
50	+	protected items(): vscode.TreeItem[] {
51	+	const mine = this.model.folderProject();
52	+	const rows = [...this.model.channels].filter((c) => c.kind !== "system").sort((a, b) => Number(b.name === mine) - Number(a.name === mine));
53	+	return rows.map((c) => {
54	+	const i = new vscode.TreeItem(c.display);
55	+	i.description = c.purpose ?? undefined;
56	+	i.tooltip = `${c.display}${c.purpose ? `\n${c.purpose}` : ""}\n${c.messages} message(s)`;
57	+	i.iconPath = new vscode.ThemeIcon(c.kind === "direct" ? "mention" : c.name === mine ? "star-full" : "comment-discussion");
58	+	i.command = { command: "spectra.openChannel", title: "Open", arguments: [c.name] };
59	+	i.id = `channel:${c.name}`;
60	+	return i;
61	+	});
62	+	}
63	+	}
64	+
65	+	export class Inbox extends View {
66	+	protected items(): vscode.TreeItem[] {
67	+	if (!this.model.inbox.length) {
68	+	const i = new vscode.TreeItem("Nothing unread");
69	+	i.iconPath = new vscode.ThemeIcon("check");
70	+	return [i];
71	+	}
72	+	return this.model.inbox.map((m) => {
73	+	const i = new vscode.TreeItem(m.summary.replace(/\s+/g, " ").slice(0, 120));
74	+	i.description = `${m.from_display \|\| m.from} · ${m.channel} · ${when(m.at_ms)}`;
75	+	i.iconPath = new vscode.ThemeIcon(m.kind === "dm" ? "mail" : "mention");
76	+	i.command = { command: "spectra.openChannel", title: "Open", arguments: [m.channel.replace(/^#/, "")] };
77	+	return i;
78	+	});
79	+	}
80	+	}
81	+
82	+	export class Briefs extends View {
83	+	protected items(): vscode.TreeItem[] {
84	+	const overall = new vscode.TreeItem("Overall brief");
85	+	overall.description = this.model.briefs.overall ? firstLine(this.model.briefs.overall) : "not set";
86	+	overall.iconPath = new vscode.ThemeIcon("globe");
87	+	overall.command = { command: "spectra.editOverallBrief", title: "Edit" };
88	+	const items = [overall];
89	+	for (const p of this.model.projects) {
90	+	const b = this.model.briefs.projects.find((x) => x.project === p.name);
91	+	const i = new vscode.TreeItem(p.name);
92	+	i.description = b ? firstLine(b.text) : "not set";
93	+	i.iconPath = new vscode.ThemeIcon("note");
94	+	i.command = { command: "spectra.editProjectBrief", title: "Edit", arguments: [p.name] };
95	+	items.push(i);
96	+	}
97	+	return items;
98	+	}
99	+	}
100	+
101	+	function firstLine(s: string): string {
102	+	return s.trim().split("\n")[0].slice(0, 80);
103	+	}

1	+	import { test } from "node:test";
2	+	import assert from "node:assert/strict";
3	+	import { SseParser, validName, nameFromFolder, suggestAgentName, expandHome, shimArgs, mergeMcpConfig, projectForFolder, esc } from "../out/pure.mjs";
4	+
5	+	test("server-sent events are split into their data, across chunks", () => {
6	+	const p = new SseParser();
7	+	assert.deepEqual(p.push(": subscribed\n\nda"), []);
8	+	assert.deepEqual(p.push('ta: {"kind":"message.posted"}\n\ndata: a\r\ndata: b\n\n'), ['{"kind":"message.posted"}', "a\nb"]);
9	+	});
10	+
11	+	test("names are Spectra's", () => {
12	+	assert.ok(validName("claude-oxygen"));
13	+	assert.ok(!validName("Claude"));
14	+	assert.ok(!validName("-x"));
15	+	assert.equal(nameFromFolder("/home/a/My Book/"), "my-book");
16	+	assert.equal(suggestAgentName("claude-code", "book", []), "claude-book");
17	+	assert.equal(suggestAgentName("antigravity", "book", ["agy-book"]), "agy-book-2");
18	+	});
19	+
20	+	test("homes and shim arguments", () => {
21	+	assert.equal(expandHome("~/.spectra-agents/x", "/home/a"), "/home/a/.spectra-agents/x");
22	+	assert.equal(expandHome("/abs", "/home/a"), "/abs");
23	+	assert.deepEqual(shimArgs("claude-book", "/h"), ["mcp", "--agent", "claude-book", "--home", "/h"]);
24	+	});
25	+
26	+	test("Antigravity's config keeps its other servers", () => {
27	+	const before = JSON.stringify({ mcpServers: { other: { command: "x" } }, theme: "dark" });
28	+	const after = JSON.parse(mergeMcpConfig(before, "/bin/spectra", ["mcp", "--agent", "agy-book"]));
29	+	assert.deepEqual(after.mcpServers.other, { command: "x" });
30	+	assert.deepEqual(after.mcpServers.spectra, { command: "/bin/spectra", args: ["mcp", "--agent", "agy-book"] });
31	+	assert.equal(after.theme, "dark");
32	+	assert.deepEqual(JSON.parse(mergeMcpConfig("", "s", [])).mcpServers.spectra, { command: "s", args: [] });
33	+	});
34	+
35	+	test("a folder belongs to the deepest project that holds it", () => {
36	+	const ps = [{ name: "dev", path: "/home/a/dev" }, { name: "book", path: "/home/a/dev/book" }, { name: "idea", path: null }];
37	+	assert.equal(projectForFolder(ps, "/home/a/dev/book"), "book");
38	+	assert.equal(projectForFolder(ps, "/home/a/dev/book/ch3"), "book");
39	+	assert.equal(projectForFolder(ps, "/home/a/dev/other"), "dev");
40	+	assert.equal(projectForFolder(ps, "/home/a/devx"), undefined);
41	+	});
42	+
43	+	test("HTML is escaped", () => {
44	+	assert.equal(esc(`<b a="1">'&`), "<b a="1">'&");
45	+	});

1	+	// Smoke test against a real Spectra (not part of `npm test`): the bridge
2	+	// signs, the model fills from the API, the stream delivers, a brief saved
3	+	// through the API reaches Spectra. Run with: npm run smoke
4	+	import { spawn, execFileSync } from "node:child_process";
5	+	import { mkdtempSync, rmSync } from "node:fs";
6	+	import { tmpdir } from "node:os";
7	+	import { join } from "node:path";
8	+	import assert from "node:assert/strict";
9	+
10	+	const bin = process.env.SPECTRA_BIN;
11	+	assert.ok(bin, "set SPECTRA_BIN to a spectra binary");
12	+	const dir = mkdtempSync(join(process.env.SMOKE_DIR \|\| tmpdir(), "spectra-smoke-"));
13	+	const env = { ...process.env, HOME: dir, SPECTRA_HOME: join(dir, "owner"), SPECTRA_DATA: join(dir, "data"), XDG_DATA_HOME: join(dir, "xdg"), NO_COLOR: "1" };
14	+	Object.assign(process.env, env);
15	+	const sp = (...a) => execFileSync(bin, a, { env }).toString();
16	+	sp("identity", "create", "--name", "Smoke Owner");
17	+	sp("init");
18	+	sp("project", "add", "book", "-d", "the manuscript");
19	+	sp("agent", "add", "claude-book", "--kind", "claude-code", "--project", "book", "--home", join(dir, "agents/claude-book"), "--yes");
20	+	const serve = spawn(bin, ["serve", "--bind", "127.0.0.1:0"], { env, stdio: "ignore" });
21	+	await new Promise((r) => setTimeout(r, 1500));
22	+
23	+	const { Bridge } = await import("../out/smoke-bridge.mjs");
24	+	const { Model } = await import("../out/smoke-model.mjs");
25	+	const log = { append() {}, appendLine() {} };
26	+	const bridge = new Bridge(log);
27	+	const model = new Model(bridge);
28	+	try {
29	+	await model.refresh();
30	+	assert.equal(model.error, undefined);
31	+	assert.equal(model.brief.actor, "human");
32	+	assert.equal(model.agents[0].name, "claude-book");
33	+	assert.ok(model.channels.some((c) => c.name === "book"));
34	+
35	+	const seen = [];
36	+	model.onEvent((e) => seen.push(e.kind));
37	+	model.start();
38	+	await new Promise((r) => setTimeout(r, 800));
39	+	await bridge.request("POST", "/api/v1/channels/book/messages", { body: "hello from the editor" });
40	+	await bridge.request("PUT", "/api/v1/briefs", { project: "book", text: "Chapter 3 becomes chapter 5." });
41	+	await new Promise((r) => setTimeout(r, 1200));
42	+	assert.ok(seen.includes("message.posted"), `the stream delivered: ${seen}`);
43	+	assert.equal(model.briefs.projects[0]?.text, "Chapter 3 becomes chapter 5.");
44	+	assert.match(sp("brief", "show", "--project", "book"), /chapter 5/);
45	+	console.log("smoke: ok");
46	+	} finally {
47	+	model.dispose();
48	+	bridge.dispose();
49	+	serve.kill("SIGTERM");
50	+	await new Promise((r) => setTimeout(r, 1500));
51	+	rmSync(dir, { recursive: true, force: true });
52	+	}

1	+	// The little of the vscode module the bridge and the model use, for the
2	+	// smoke test under plain Node.
3	+	export class EventEmitter {
4	+	constructor() { this.listeners = []; this.event = (l) => { this.listeners.push(l); return { dispose: () => {} }; }; }
5	+	fire(v) { for (const l of this.listeners) l(v); }
6	+	dispose() { this.listeners = []; }
7	+	}
8	+	export class Disposable { constructor(f) { this.f = f; } dispose() { this.f?.(); } }
9	+	export const workspace = { getConfiguration: () => ({ get: (k) => (k === "path" ? process.env.SPECTRA_BIN \|\| "" : undefined) }), workspaceFolders: undefined };
10	+	export const window = {};

Spectra for VS Code 0.1: set up and chat without the command line (#6) ff39a5e808da

Keyboard

1	+	{
2	+	"compilerOptions": {
3	+	"target": "ES2022",
4	+	"module": "Node16",
5	+	"moduleResolution": "Node16",
6	+	"lib": ["ES2022"],
7	+	"strict": true,
8	+	"noImplicitReturns": true,
9	+	"noUnusedLocals": true,
10	+	"noFallthroughCasesInSwitch": true,
11	+	"esModuleInterop": true,
12	+	"skipLibCheck": true,
13	+	"sourceMap": true,
14	+	"outDir": "out",
15	+	"rootDir": "src"
16	+	},
17	+	"include": ["src"]
18	+	}

1	+	# Spectra for Visual Studio Code
2	+
3	+	Set up [Spectra](https://oxygenhub.io/andymccall/spectra), chat with your AI agents, and give them their briefs, without the command line.
4	+
5	+	- Get started: a walkthrough creates your identity, runs Spectra here or connects to one on a server (you confirm its key), registers this folder as a project, and adds an agent with its client (Claude Code, Kimi Code, Antigravity) configured.
6	+	- Channels: each project's channel, `#general` and your direct messages open as chat tabs; you post as yourself, `@name` mentions an agent.
7	+	- Agents: who is online, busy or offline, whose they are, and until when they may act for you; Renew Agent gives more time.
8	+	- Inbox: mentions and direct messages for you.
9	+	- Briefs: the overall brief and each project's open as documents; saving signs them into Spectra and every agent concerned is told on its next call.
10	+	- Radar and the Constellation open in your browser.
11	+
12	+	The extension never holds a key: it starts `spectra bridge`, which signs each request as you. See [docs/spec.md](docs/spec.md).
13	+
14	+	## Building
15	+
16	+	```
17	+	npm install
18	+	npm run check # typecheck, build, unit tests
19	+	SPECTRA_BIN=~/.local/bin/spectra npm run smoke # against a real Spectra in a temporary directory
20	+	npm run package # spectra-vscode-0.1.0.vsix
21	+	code --install-extension spectra-vscode-0.1.0.vsix
22	+	```
23	+
24	+	## Licence
25	+
26	+	MIT or Apache-2.0, at your option.

`/`	Search
`g` `c`	Code
`g` `h`	History
`g` `b`	Bookmarks
`g` `t`	Trust
`y`	Permalink to this state (files and trees)
`?`	This sheet