Junio VS Code owner prototype (G5-04J)

Private, dependency-free CommonJS extension. Launch Report audit or Literature review against the generic local Junio service without a terminal.

This is a runnable owner prototype, not a marketplace package and not the full G5 product.

Launch (Extension Development Host)

1. Open the repository worktree (the monorepo root that contains vscode-extension/) in VS Code / Cursor.
2. Select Run Junio Extension in Run and Debug, then press F5. The launch config is at repository-root .vscode/launch.json and opens the same workspace in the Extension Development Host with extensionDevelopmentPath set to ${workspaceFolder}/vscode-extension.
3. A new Extension Development Host opens. You may leave the repository workspace open, or open an owner document workspace (any trusted folder with your .docx / review materials — it does not need Junio source).
4. Trust the workspace when prompted. The extension refuses untrusted workspaces.
5. Open any editor tab, then click the Quiet Spark icon in the editor title bar (or run Junio: Open). Junio opens in the Secondary Side Bar on the right (Copilot-style). If it is hidden, use View → Appearance → Secondary Side Bar.
6. Choose a capability and model in the bottom composer:
   • Mode — Report audit or Literature review
   • Model — GLM 5.2 (glm, needs ZHIPU_KEY), Kimi K2.7 Code (kimi, needs KIMI_KEY + ZHIPU_KEY for embeddings), or Kimi K3 (kimi-k3, same credentials). Readiness is local presence only (Ready / Needs API key / Check API key).
   • + File — workspace .docx for Report audit
   • Send — starts the run (send is the owner authorization for that run)
7. Watch one chronological transcript while a run is active (ordered by event sequence): concise public progress (worker progress carries a quiet Worker N label when correlated), Updated plan snapshots when todos change, compact Explored operation groups at their real time, and distinct Worker N start/end rows for delegated checks. Lifecycle still surfaces as queued / running / succeeded / failed / cancelled. Incomplete audits fail closed (audit_incomplete) and never show a green zero-issue success. Usage rows, successful generic tool-finish noise, raw child ids, and send_progress / update_todos tool names are omitted. Scroll auto-follows only while you stay near the bottom (or right after you send); if you scroll away, new live events surface a quiet New activity ↓ control without yanking the viewport.
8. Cancel run while active; open the Audit report (Markdown, in VS Code) and other artifacts when paths appear; Retry after failures. Auth failures offer Set up API key (native password input → VS Code secrets only). Annotation receipts stay internal custody evidence and are not chat attachments.

Backend lifecycle (privacy-safe): open View → Output, choose channel Junio. Lines are stable status codes only (service_starting, service_ready, service_exited exit_code=…, secret_setup stored name=ZHIPU_KEY, etc.) — no document names, paths, request inputs, secret values, or raw stderr. On run failure the channel may also show one grep-friendly run_failure code=… exception_types=… status_codes=… line built only from revalidated diagnostic fields (never exception text or response bodies).

Python / service child

The extension keeps two roots:

• Runtime root — parent of vscode-extension/ (context.extensionPath/..). Used for interpreter discovery, PYTHONPATH, and child cwd.
• Data workspace root — the trusted folder open in the Extension Development Host. Used for --workspace, initialize workspace_roots, document selection, run storage, and artifact opening.

<python> -m junio.desktop.service --workspace <data-workspace>

Interpreter order (against the runtime root):

1. junio.pythonPath setting
2. <runtime>/.venv/bin/python
3. For a linked Git worktree only: main-checkout .venv/bin/python derived from the small .git gitdir pointer
4. python3

PYTHONPATH includes <runtime>/src. Owner environment is inherited. Process environment values for ZHIPU_KEY / KIMI_KEY always win; otherwise allowlisted secrets from ExtensionContext.secrets are injected into the owned child only. If the Extension Development Host does not carry JUNIO_SUPERDOC_MCP_ENTRY (common when the Code CLI reuses an older VS Code parent), set junio.superdocMcpEntry to the local SuperDoc MCP entry module path — the extension injects only that one variable into the service child. Leave empty to inherit. Lifecycle reports superdoc_mcp_entry source=configured|inherited|missing (never the path). The child is terminated on extension deactivate.

Generic methods only

initialize, list_capabilities, start_run, get_run, cancel_run

• initialize may return a redacted model catalog (id, label, description, ready, missing credential names only).
• start_run accepts top-level model_id separate from capability input. Unknown model IDs are rejected before a run is created.

No audit-named transport methods. Artifacts open only under .junio/runs/<exact-run-id>/artifacts/ after strict validation.

DOCX editor (SuperDoc) and selection-to-chat

Opening a workspace .docx file uses the Junio DOCX Editor custom editor (SuperDoc 2.4.0, editing mode). The bundle is built offline into media/docx-editor/ — no CDN or network deps at runtime.

• Edit — full in-browser DOCX editing via SuperDoc.
• Save — prototype uses save-on-command: press Save (Cmd+S / Ctrl+S) to export from SuperDoc and write bytes back to the workspace file. The tab shows dirty after the first edit.
• Highlight → chat — selecting text in the DOCX editor reads the editor DOM selection (not only SuperDoc observe) and posts the quote to Junio immediately as a composer chip (with a one-line tip). A floating Add to Junio ✚ button also sends the selection. In any text editor, use Junio: Add Selection to Chat (context menu or Cmd+Alt+J / Ctrl+Alt+J). The chip appears above the composer; the next Send includes selection: { quoted_text, file, anchor: null } in the compose input (capped at 4000 chars), then clears the chip. Typing @path in the composer keeps mention chips in sync — deleting the @filename text removes the chip.

AGPL local-use note: SuperDoc is AGPL-licensed. This prototype bundles it for private local use only — not for redistribution, marketplace packaging, or publication without separate licensing.

Build the DOCX editor bundle:

cd vscode-extension/docx-editor && npm install && npm run build

Tests (no npm install for extension itself)

node --test vscode-extension/test/*.test.js
node --check vscode-extension/extension.js
node --check vscode-extension/src/*.js

Out of scope for this slice

• Conversation / plan approval shell
• Marketplace packaging / VSIX publish
• Free-form providers / model discovery / OAuth
• Holding API keys in webview HTML, settings JSON, workspace files, or logs
• Live provider / SuperDoc quality (requires owner environment)
• Secondary Sidebar placement is fixed via secondarySidebar contribution (VS Code 1.106+)