@mrclrchtr/supi-consulting 0.0.0-stage → 8.0.1

package/CLAUDE.md

@@ -0,0 +1,23 @@
+# CLAUDE.md
+
+## Scope
+
+`@mrclrchtr/supi-consulting` owns `consulting_run`, Consulting Agent availability, evidence classification, and Conversation Handle state. Antigravity is the only agent adapter. There is no `supi-agent-runtime` integration.
+
+## Design rules
+
+- Keep agent-specific models, authentication, process code, protocol parsing, and tool-activity classification in `src/agents/antigravity/`. Shared workflow uses the private interface in `src/agents/types.ts`.
+- Keep each Model Catalogue immutable until the next session start or reload. Register `consulting_run` only after agent discovery succeeds.
+- Require explicit agent, model, and Workspace Access for a new Consultation. Keep `new` and `continue` exact-one; follow-ups inherit all selections and their working directory.
+- Acquire a handle before process work. Report process start, including hook probes, through the adapter interface. Reject overlap before startup; retire only after a started follow-up fails or is canceled.
+- Keep raw conversation IDs opaque to shared policy. Persist only new consulting handle records and results; old Antigravity state has no migration or legacy read path.
+- Use `<PI agent dir>/supi/consulting/antigravity/` for Antigravity state. Leave the old `supi/antigravity/` tree untouched.
+- Use the Isolated Antigravity Home for every `agy` process. On macOS, create and unlock its private keychain, exposed as the login keychain, before startup. Do not copy the normal profile, credentials, or PI provider environment.
+- Spawn `agy` directly with an argument array. Keep raw stdout, stderr, tool parameters, tool output, and transcripts out of PI state.
+- Treat the Inspection Permission Set as an Antigravity policy, not an operating-system sandbox. Project hooks and accepted `read_url(*)` targets remain explicit limitations.
+- Build model-visible results in `tool/consulting_run/result.ts`. Renderers use structured details; they never parse result content for presentation.
+- Keep sources and workspace paths bounded. Distinguish observed references from claimed references.
+
+## Verification
+
+Use focused tests and source/test typechecking during changes. Run `pnpm verify:ai` before completion. The live probe requires separate approval and `SUPI_CONSULTING_LIVE=1`; it must not run in normal tests or CI.

package/CONTEXT.md

@@ -0,0 +1,53 @@
+# supi-consulting
+
+Runs bounded Consultations while keeping agent selection, workspace exposure, and observed evidence explicit.
+
+## Language
+
+**Consultation**:
+One bounded request to a Consulting Agent that returns an answer and execution evidence. It can start a conversation or continue one through a Conversation Handle.
+_Avoid_: Antigravity Run, Agent Run, child session
+
+**Consulting Agent**:
+An agent selected to perform a Consultation. Antigravity is the only supported Consulting Agent.
+_Avoid_: Agent Profile, PI model provider, model
+
+**Workspace Access**:
+The caller's decision to expose the current PI workspace to a Consultation. A Consultation without Workspace Access uses the selected agent's Consultation Workspace.
+_Avoid_: consult mode, explore mode, repository mode
+
+**Consultation Workspace**:
+A package-managed empty project for Consultations without access to the current PI workspace. Its stable identity keeps agent-specific permissions and conversations separate from the current workspace.
+_Avoid_: temporary workspace, sandbox, current workspace
+
+**Web Capability**:
+A Consulting Agent's permission-controlled ability to retrieve external sources during a Consultation. SuPi exposes and observes this capability but does not grant it.
+_Avoid_: SuPi web search, automatic web access, web mode
+
+**Isolated Antigravity Home**:
+The package-owned Antigravity profile that separates configuration, authentication, customizations, and conversation state from the user's normal Antigravity profile. It stays stable across Consultations so Conversation Handles can continue.
+_Avoid_: user home, temporary home, sandbox
+
+**Inspection Permission Set**:
+The Antigravity rules that allow external reads and deny known file, command, MCP, and browser-actuation paths. They limit Antigravity tools but are not an operating-system sandbox and do not control project-local hooks.
+_Avoid_: read-only mode, safe mode, SuPi permissions
+
+**Model Catalogue**:
+The immutable model choices available through one Consulting Agent for the current session. A new Consultation selects one entry explicitly.
+_Avoid_: PI model list, default model, all provider models
+
+**Observed Evidence**:
+Bounded execution facts derived from Consulting Agent tool activity and validated result references. Model claims alone are not Observed Evidence.
+_Avoid_: claimed evidence, answer citations, raw event stream
+
+**Web Evidence**:
+Observed Evidence that contains successful web tool activity and at least one validated source URL.
+_Avoid_: source list, cited answer, web claim
+
+**Workspace Evidence**:
+Observed Evidence that contains successful workspace inspection activity and validated workspace-relative paths.
+_Avoid_: code claim, file list, exploration output
+
+**Conversation Handle**:
+An opaque SuPi identifier for an observed conversation with one Consulting Agent. It retains the original agent, model, working directory, and Workspace Access.
+_Avoid_: raw conversation ID, Agent Run Handle, session ID

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @mrclrchtr/supi-consulting
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`@mrclrchtr/supi-consulting` adds the beta `consulting_run` tool to Pi. It runs bounded Consultations with explicit agent, model, and workspace selection and reports observed evidence. **Antigravity is the only supported Consulting Agent.**
+
+## Install
+
+```bash
+pi install npm:@mrclrchtr/supi-consulting
+```
+
+The package is not part of the recommended or full SuPi installer. Run `/reload` after installation.
+
+## Switch from supi-antigravity
+
+This is a clean break. Remove the old package before you install the new one:
+
+```bash
+pi remove npm:@mrclrchtr/supi-antigravity
+pi install npm:@mrclrchtr/supi-consulting
+```
+
+Use the same personal or project scope as the original install. Update local extension paths to `packages/supi-consulting/src/extension.ts`, then reload Pi.
+
+- `antigravity_run` has no alias. Use `consulting_run` and supply `new.agent`.
+- The setting is now `consulting.agentToolEnabled`. The old `antigravity` section is ignored, including an old disabled value. The new setting defaults to `true`; set it to `false` before reload if you want to skip discovery.
+- Old Conversation Handles and tool results are not restored as consulting state. Start a new Consultation.
+- The isolated home has moved to a new namespace. Sign in again. The package does not read, move, copy, or delete the old `<PI agent dir>/supi/antigravity/` data.
+
+## First sign-in
+
+The Antigravity adapter never uses the normal Antigravity profile. It creates these stable, agent-specific directories:
+
+```text
+<PI agent dir>/supi/consulting/antigravity/home/
+<PI agent dir>/supi/consulting/antigravity/consultation-workspace/
+```
+
+After Pi starts, the package checks availability without making startup wait. The footer shows a spinning icon during the check. The tool appears only after discovery succeeds. The ready footer uses the terminal-safe `✦` icon; the SuPi footer shows it on the stats line as `| ✦`.
+
+When sign-in is needed, Pi shows a command with the resolved paths:
+
+```bash
+cd "<consultation-workspace>" &&
+HOME="<isolated-home>" AGY_CLI_DISABLE_AUTO_UPDATE=true agy
+```
+
+On macOS, the adapter creates and unlocks a private keychain inside the Isolated Antigravity Home. It exposes that keychain as the login keychain without prompting for the normal keychain password. Run the displayed command, sign in, exit Antigravity, and reload Pi. The installed `agy` version must be at least `1.1.24`.
+
+If macOS displays `antigravity.` in a warning, the final `.` is sentence punctuation, not part of a keychain name.
+
+## `consulting_run`
+
+A new Consultation requires the agent, an available model, and Workspace Access:
+
+```json
+{
+  "prompt": "Explain this API design.",
+  "new": {
+    "agent": "antigravity",
+    "workspace": false,
+    "model": "gemini-3.8-flash-low"
+  }
+}
+```
+
+The Model Catalogue is the intersection of the curated Antigravity models and the models available to the signed-in account. It stays fixed until the next session start or reload. There is no default model or automatic agent fallback.
+
+Set `workspace` to `true` only when the Consultation needs repository evidence. This exposes the current PI workspace. Set it to `false` to use the empty Consultation Workspace.
+
+A follow-up supplies only a returned Conversation Handle:
+
+```json
+{
+  "prompt": "Now compare the alternatives.",
+  "continue": { "handle": "consult_..." }
+}
+```
+
+Supply exactly one of `new` and `continue`. Follow-ups retain the original agent, model, working directory, and Workspace Access. A handle is opaque and branch-aware. It is retired if a follow-up fails or is canceled after process work starts. Overlapping follow-ups on the same handle are rejected.
+
+Results report web use, workspace use, observed and claimed references, warnings, token use, and the Conversation Handle. An answer can claim a reference without matching tool activity; SuPi labels that reference as claimed, not observed.
+
+Use `/supi-settings` → **Consulting** to disable the tool. Disabling it skips availability checks and removes `consulting_run` from the active tool list.
+
+## Security limits
+
+The Antigravity adapter enforces its Inspection Permission Set in the Isolated Antigravity Home. It allows `read_url(*)` and denies known file writes, commands, unsandboxed actions, MCP, and URL execution. These rules are **not an operating-system sandbox**.
+
+For workspace Consultations, project-local hooks can run commands, read the Antigravity transcript, and cause side effects outside these permission rules. The adapter probes hook state before the paid process and warns when hooks are active or unknown.
+
+`read_url(*)` can reach local, private-network, and link-local endpoints that Antigravity accepts. It does not enforce public-internet-only access.
+
+These limits describe the Antigravity integration. The private adapter interface does not promise that future agents have the same permissions or isolation. There is no `supi-agent-runtime` integration in this package.
+
+## Development and live probe
+
+The repository's [rename plan](https://github.com/mrclrchtr/supi/blob/main/packages/supi-consulting/CONSULTING-RENAME-PLAN.md) records the approved scope and verification criteria. Its [original plan](https://github.com/mrclrchtr/supi/blob/main/packages/supi-consulting/PLAN.md) is the historical Antigravity specification, not the current tool contract.
+
+The live probe requires separate approval and sign-in. It never runs in normal tests or CI:
+
+```bash
+SUPI_CONSULTING_LIVE=1 pnpm exec jiti packages/supi-consulting/scripts/live-probe.ts
+```
+
+It uses the isolated profile and checks web evidence, follow-up context, workspace evidence, and byte-identical fixture state.

package/docs/adr/0001-use-an-isolated-antigravity-home.md

@@ -0,0 +1,5 @@
+# Use an Isolated Antigravity Home
+
+Consultations through Antigravity use a stable Isolated Antigravity Home under PI agent state instead of the user's normal Antigravity profile or a new home for each Consultation. This lets `supi-consulting` enforce the Antigravity Inspection Permission Set and exclude global customizations without changing user settings. Stable conversation state supports Conversation Handles; the trade-off is one separate sign-in and explicit manual cleanup.
+
+On macOS, `agy` uses the system keychain for authentication. An isolated `HOME` has no default keychain until the package creates one. The package creates a package-owned `antigravity.keychain-db` with an empty password and exposes it as `Library/Keychains/login.keychain-db` through a symlink. It unlocks this private keychain before each `agy` process, without prompting for a password. It does not copy or use the normal profile's keychain.

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -0,0 +1,137 @@
+<div align="center">
+  <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-core">
+    <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-core/assets/social-preview.png" alt="SuPi Core" width="100%">
+  </a>
+</div>
+
+# @mrclrchtr/supi-core
+
+[![GitHub stars](https://img.shields.io/github/stars/mrclrchtr/supi)](https://github.com/mrclrchtr/supi/stargazers)
+
+Shared infrastructure for SuPi extensions.
+
+This is a **pure library** — it does not register any pi commands or tools. The `/supi-settings` command is now available through `@mrclrchtr/supi-settings`.
+
+## Install
+
+```bash
+pnpm add @mrclrchtr/supi-core
+```
+
+## Package surfaces
+
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/llm` — PI-owned direct model requests and JSON helpers
+- `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
+- `@mrclrchtr/supi-core/tui` — shared terminal UI helpers for list titles, rows, menus, and descriptions
+
+## What you get from the API
+
+### Config helpers
+
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `replaceSupiConfigSection()` — replace one nested section while preserving other sections
+- `removeSupiConfigKey()` — remove a key or override
+
+Config file locations:
+
+- global: `~/.pi/agent/supi/config.json`
+- project: `.pi/supi/config.json`
+
+### Settings helpers
+
+- `registerSettings(pi, module)` — register one canonical asynchronous settings module
+- `defineConfigSettings(options)` — adapt a fixed SuPi config section to that module interface
+- settings registry helpers and types for the `@mrclrchtr/supi-settings` configuration surface
+
+### Context helpers
+
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
+
+### Model requests
+
+- `completeModelRequest(ctx, model, context, options)` — send API-specific options through PI's model registry.
+- `completeSimpleModelRequest(ctx, model, context, options)` — send provider-neutral options through `streamSimple().result()` on PI 0.86.0 or later. PI supplies model-derived output limits and context guards.
+- `callWithJsonResponse()` — retry a registry request, extract JSON, and validate it with TypeBox.
+
+Both completion helpers require a stable `affinityScope`. PI owns auth and endpoint resolution. The helpers keep cache retention defaults, exclude prompt content from the affinity ID, and add OpenCode headers only when the provider or exact model endpoint matches OpenCode. Use the simple helper when PI should manage output limits; the API-specific helper forwards the caller's limit unchanged.
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry and monotonic phase timers for producers that want shared debug capture
+- optional Debug Operation IDs for exact, directly owned public Tool-call correlation; ambient events stay uncorrelated
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
+
+### TUI helpers
+
+- `formatTuiTitleLine()` — use the shared title style in terminal lists
+- `renderSelectableRow()` — render a selected row with an aligned value
+- `renderDescriptionViewport()` — show a fixed-height description preview
+- `renderTuiHintLine()` — render short key hints in one line
+- `createSelectListMenu()` — build an action menu with shared key hints
+
+### Report helpers
+
+- `clampReportWidth()` — enforce a minimum readable report width
+- `formatReportTitle()` / `formatSectionHeader()` — shared themed headers
+- `formatDimLine()` / `formatKeyValueLine()` — common summary rows
+- `formatOverflowHint()` — consistent preview-overflow hints
+- `wrapReportText()` — ANSI-aware wrapped report blocks with optional indentation
+
+## Example
+
+```ts
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  defineConfigSettings,
+  loadSupiConfig,
+  registerSettings,
+  wrapExtensionContext,
+} from "@mrclrchtr/supi-core/api";
+
+export default function myExtension(pi: ExtensionAPI) {
+  const defaults = { enabled: true };
+  const config = loadSupiConfig("my-extension", process.cwd(), defaults);
+
+  registerSettings(
+    pi,
+    defineConfigSettings({
+      id: "my-extension",
+      label: "My Extension",
+      section: "my-extension",
+      defaults,
+      fields: [
+        {
+          kind: "boolean" as const,
+          key: "enabled",
+          label: "Enabled",
+        },
+      ],
+    }),
+  );
+
+  const message = wrapExtensionContext("my-extension", "hello", {
+    enabled: config.enabled,
+  });
+  void message;
+}
+```
+
+## Source
+
+- `src/api.ts` — exported library surface
+- `src/config.ts` — shared config loading and writing
+- `src/debug-registry.ts` — Debug domain surface, event state, retention, redaction, listeners, and queries
+- `src/debug-timing.ts` — monotonic total and phase timers for Debug Event Producers
+- `src/settings/` — settings registry, schema, scope resolution, and persistence
+- `src/report.ts` — shared text/report rendering helpers
+- `src/tui.ts` — shared terminal UI list and action-menu helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@mrclrchtr/supi-core",
+  "version": "8.0.1",
+  "description": "Shared settings, configuration, reporting, and session infrastructure",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git",
+    "directory": "packages/supi-core"
+  },
+  "homepage": "https://github.com/mrclrchtr/supi/tree/main/packages/supi-core#readme",
+  "bugs": {
+    "url": "https://github.com/mrclrchtr/supi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "supi",
+    "extension-utils",
+    "settings",
+    "configuration"
+  ],
+  "type": "module",
+  "files": [
+    "src/**/*.ts",
+    "!__tests__"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "25.9.9",
+    "vitest": "5.0.4"
+  },
+  "main": "src/api.ts",
+  "exports": {
+    "./api": "./src/api.ts",
+    "./config": "./src/config.ts",
+    "./context": "./src/context.ts",
+    "./debug": "./src/debug.ts",
+    "./evidence-badge": "./src/evidence-badge.ts",
+    "./footer-registry": "./src/footer-registry.ts",
+    "./llm": "./src/llm.ts",
+    "./model-selection": "./src/model-selection.ts",
+    "./package.json": "./package.json",
+    "./path": "./src/path.ts",
+    "./project": "./src/project.ts",
+    "./prompt-surface": "./src/prompt-surface.ts",
+    "./report": "./src/report.ts",
+    "./session": "./src/session.ts",
+    "./settings": "./src/settings.ts",
+    "./spinner-frames": "./src/spinner-frames.ts",
+    "./status-spinner": "./src/status-spinner.ts",
+    "./terminal": "./src/terminal.ts",
+    "./tui": "./src/tui.ts"
+  }
+}

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -0,0 +1,42 @@
+// supi-core — shared infrastructure for SuPi extensions.
+// Provides XML context tag wrapping, unified config, prompt-surface resolution,
+// and shared settings, reporting, and session utilities.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
+
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./context.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./debug.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./evidence-badge.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./footer-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./llm.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./model-selection.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./prompt-surface.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./session.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./spinner-frames.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./status-spinner.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tui.ts";