@mrclrchtr/supi-consulting 0.0.0-stage → 8.0.1

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

@@ -0,0 +1,141 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+  type SelectItem,
+  SelectList,
+  type TuiMouseEvent,
+  type TuiMouseEventResult,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+/** The theme methods used by the shared TUI list renderers. */
+export type TuiTheme = Pick<Theme, "fg" | "bold">;
+
+/** Settings for one selectable row in a themed list. */
+export interface SelectableRowOptions {
+  /** The row label. */
+  label: string;
+  /** The value shown beside the label. */
+  value: string;
+  /** The row indent in terminal columns. */
+  indent: number;
+  /** The largest indent used by the list. */
+  maxIndent: number;
+  /** The label column width. */
+  maxLabelWidth: number;
+  /** The row width in terminal columns. */
+  width: number;
+  /** True when this row is selected. */
+  selected: boolean;
+  /** Theme used for row colors. */
+  theme: TuiTheme;
+}
+
+/** Settings for a shared action menu. */
+export interface SelectListMenuOptions {
+  /** The title shown above the choices. */
+  title: string;
+  /** The choices shown in the menu. */
+  items: SelectItem[];
+  /** Theme used for menu colors. */
+  theme: TuiTheme;
+  /** Called when the user selects a choice. */
+  onSelect: (item: SelectItem) => void;
+  /** Called when the user closes the menu without a choice. */
+  onCancel: () => void;
+}
+
+/** Component methods for a shared action menu. */
+export interface SelectListMenuComponent {
+  render(width: number): string[];
+  invalidate(): void;
+  handleInput(data: string): void;
+  handleMouse(event: TuiMouseEvent): TuiMouseEventResult | undefined;
+}
+
+/** Build a title line with optional right-side tabs in the shared TUI style. */
+export function formatTuiTitleLine(title: string, theme: TuiTheme, trailing = ""): string {
+  const titleText = theme.fg("accent", theme.bold(title));
+  return ` ${titleText}${trailing ? `  ${trailing}` : ""}`;
+}
+
+/** Render one row with a selected marker and an aligned value column. */
+export function renderSelectableRow(options: SelectableRowOptions): string {
+  const indent = Math.max(0, options.indent);
+  const maxIndent = Math.max(indent, options.maxIndent);
+  const maxLabelWidth = Math.max(0, options.maxLabelWidth);
+  const width = Math.max(0, options.width);
+  const label = truncateToWidth(options.label, maxLabelWidth, "");
+  const labelWidth = visibleWidth(label);
+  const prefix = options.selected
+    ? `${" ".repeat(Math.max(0, indent - 2))}${options.theme.fg("accent", "→ ")}`
+    : " ".repeat(indent);
+  const labelPadding = " ".repeat(maxIndent - indent + maxLabelWidth - labelWidth);
+  const valueWidth = Math.max(0, width - maxIndent - maxLabelWidth - 4);
+  const value = truncateToWidth(options.value, valueWidth, "");
+  const labelText = options.theme.fg(options.selected ? "accent" : "text", label + labelPadding);
+  const valueText = options.theme.fg(options.selected ? "accent" : "muted", value);
+
+  return truncateToWidth(`${prefix}${labelText}  ${valueText}`, width);
+}
+
+/** Render a fixed-height, four-line description preview for a selected row. */
+export function renderDescriptionViewport(
+  description: string | undefined,
+  width: number,
+): string[] {
+  const height = 4;
+  const indent = "  ";
+  const contentWidth = Math.max(1, width - 4);
+  const wrapped = description ? wrapTextWithAnsi(description, contentWidth) : [];
+  const visible = wrapped.slice(0, height);
+
+  if (wrapped.length > height) {
+    const lastIndex = height - 1;
+    visible[lastIndex] = truncateToWidth(`${visible[lastIndex] ?? ""}…`, contentWidth, "…");
+  }
+
+  while (visible.length < height) visible.push("");
+  return visible.map((line) => (line ? `${indent}${line}` : ""));
+}
+
+/** Render a dimmed hint line with the shared separator and truncation rules. */
+export function renderTuiHintLine(hints: string[], theme: TuiTheme, width: number): string {
+  return truncateToWidth(theme.fg("dim", hints.join(" · ")), width);
+}
+
+/** Build the shared title, choices, and key hints for an action menu. */
+export function createSelectListMenu(options: SelectListMenuOptions): SelectListMenuComponent {
+  const { items, onSelect, onCancel, theme, title } = options;
+  const selectList = new SelectList(items, Math.min(items.length + 2, 15), {
+    selectedPrefix: (text) => theme.fg("accent", text),
+    selectedText: (text) => theme.fg("accent", text),
+    description: (text) => theme.fg("muted", text),
+    scrollInfo: (text) => theme.fg("dim", text),
+    noMatch: (text) => theme.fg("warning", text),
+  });
+  selectList.onSelect = onSelect;
+  selectList.onCancel = onCancel;
+
+  return {
+    render(width) {
+      return [
+        truncateToWidth(theme.fg("accent", `  ${title}`), width),
+        ...selectList.render(width),
+        "",
+        renderTuiHintLine(["  ↑↓ navigate", "Enter select", "Esc cancel"], theme, width),
+      ];
+    },
+    invalidate() {
+      selectList.invalidate();
+    },
+    handleInput(data) {
+      selectList.handleInput(data);
+    },
+    handleMouse(event) {
+      if (event.y < 1) return undefined;
+      return selectList.handleMouse({ ...event, y: event.y - 1 });
+    },
+  };
+}

package/package.json

@@ -1,6 +1,80 @@
 {
   "name": "@mrclrchtr/supi-consulting",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "8.0.1",
+  "description": "Bounded consultations with explicit agent and workspace selection and observed evidence",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git",
+    "directory": "packages/supi-consulting"
+  },
+  "homepage": "https://github.com/mrclrchtr/supi/tree/main/packages/supi-consulting#readme",
+  "bugs": {
+    "url": "https://github.com/mrclrchtr/supi/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "supi",
+    "consulting",
+    "antigravity",
+    "agent",
+    "web",
+    "workspace"
+  ],
+  "type": "module",
+  "files": [
+    "src/**/*.ts",
+    "scripts/live-probe.ts",
+    "README.md",
+    "CLAUDE.md",
+    "CONTEXT.md",
+    "docs/adr/*.md"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "workspace:*"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "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": {
+    "@mrclrchtr/supi-test-utils": "workspace:*",
+    "@types/node": "25.9.9",
+    "vitest": "5.0.4"
+  },
+  "pi": {
+    "extensions": [
+      "./src/extension.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-consulting/assets/social-preview.png"
+  },
+  "exports": {
+    "./extension": "./src/extension.ts",
+    "./package.json": "./package.json"
+  }
+}

package/scripts/live-probe.ts

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, mkdtemp, readdir, readFile, readlink, realpath, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { createAntigravityAdapter } from "../src/agents/antigravity/adapter.ts";
+import { getIsolatedAntigravityPaths } from "../src/agents/antigravity/isolated-home.ts";
+import { isHttpUrl, isSafeWorkspacePath } from "../src/tool/consulting_run/evidence.ts";
+
+const LIVE_ENVIRONMENT = "SUPI_CONSULTING_LIVE";
+const MODEL = "gemini-3.8-flash-low";
+const CONTEXT_TOKEN = "supi-consulting-context-token";
+
+async function main(): Promise<void> {
+  if (process.env[LIVE_ENVIRONMENT] !== "1") {
+    throw new Error(`Set ${LIVE_ENVIRONMENT}=1 to run the Consulting live probe.`);
+  }
+  const paths = getIsolatedAntigravityPaths();
+  const adapter = createAntigravityAdapter(paths);
+  const availability = await adapter.discover();
+  if (availability.status !== "available" || !availability.catalogue.includes(MODEL)) {
+    throw new Error("The selected model is not available to the isolated Antigravity account.");
+  }
+  const consultationWorkspace = await realpath(paths.consultationWorkspace);
+  const first = await adapter.execute({
+    prompt: `Remember the exact token ${CONTEXT_TOKEN}. Name one current official Node.js documentation page about subprocess cancellation and cite it.`,
+    model: MODEL,
+    canonicalWorkingDirectory: consultationWorkspace,
+    workspaceAccess: false,
+  });
+  requireWebEvidence(first);
+
+  const second = await adapter.execute({
+    prompt: `What exact context token did I give you? Answer in one sentence and include ${CONTEXT_TOKEN}.`,
+    model: MODEL,
+    canonicalWorkingDirectory: consultationWorkspace,
+    workspaceAccess: false,
+    continuation: first.continuation,
+  });
+  if (!second.answer.answer.includes(CONTEXT_TOKEN)) {
+    throw new Error("The follow-up did not retain the Conversation Handle context.");
+  }
+
+  const fixture = await realpath(await mkdtemp(join(tmpdir(), "supi-consulting-live-")));
+  try {
+    await cp(join(import.meta.dirname, "../__tests__/fixtures/subprocess-cancellation"), fixture, {
+      recursive: true,
+    });
+    const before = await digestTree(fixture);
+    const workspace = await adapter.execute({
+      prompt:
+        "Inspect the TypeScript subprocess-cancellation fixture. Consult official Node.js documentation and explain the cancellation risk. Return relative file paths within the fixture and source URLs. Do not return absolute file paths.",
+      model: MODEL,
+      canonicalWorkingDirectory: fixture,
+      workspaceAccess: true,
+    });
+    requireWebEvidence(workspace);
+    requireWorkspaceEvidence(workspace, fixture);
+    if (!workspace.workspaceUsed) {
+      throw new Error("The workspace probe did not observe workspace activity.");
+    }
+    const after = await digestTree(fixture);
+    if (before !== after) throw new Error("The live probe changed the fixture.");
+  } finally {
+    await rm(fixture, { recursive: true, force: true });
+  }
+}
+
+function requireWebEvidence(result: { webUsed: boolean; answer: { sources: unknown[] } }): void {
+  if (!result.webUsed || result.answer.sources.length === 0) {
+    throw new Error("The live probe did not observe web evidence.");
+  }
+  if (
+    !result.answer.sources.every(
+      (source) => isRecord(source) && typeof source.url === "string" && isHttpUrl(source.url),
+    )
+  ) {
+    throw new Error("The live probe returned an invalid source URL.");
+  }
+}
+
+function requireWorkspaceEvidence(
+  result: { answer: { workspaceEvidence: unknown[] } },
+  workspace: string,
+): void {
+  if (
+    result.answer.workspaceEvidence.length === 0 ||
+    !result.answer.workspaceEvidence.every(
+      (item) =>
+        isRecord(item) &&
+        typeof item.path === "string" &&
+        isSafeWorkspacePath(item.path, workspace),
+    )
+  ) {
+    throw new Error("The live probe did not return valid workspace evidence.");
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function digestTree(directory: string): Promise<string> {
+  const hash = createHash("sha256");
+  await digestDirectory(directory, directory, hash);
+  return hash.digest("hex");
+}
+
+async function digestDirectory(
+  directory: string,
+  root: string,
+  hash: ReturnType<typeof createHash>,
+): Promise<void> {
+  const entries = (await readdir(directory, { withFileTypes: true })).sort((left, right) =>
+    left.name.localeCompare(right.name),
+  );
+  for (const entry of entries) {
+    const file = join(directory, entry.name);
+    hash.update(relative(root, file));
+    if (entry.isDirectory()) {
+      hash.update("directory");
+      await digestDirectory(file, root, hash);
+      continue;
+    }
+    if (entry.isSymbolicLink()) {
+      hash.update("link");
+      hash.update(await readlink(file));
+      continue;
+    }
+    if (entry.isFile()) {
+      hash.update("file");
+      hash.update(await readFile(file));
+      continue;
+    }
+    const info = await lstat(file);
+    hash.update(`${info.mode}:${info.size}`);
+  }
+}
+
+await main();

package/src/agents/antigravity/activity.ts

@@ -0,0 +1,22 @@
+import { normalizeToolName } from "./process/event-values.ts";
+
+/** Return whether a successful Antigravity tool name represents web activity. */
+export function isWebToolName(name: string): boolean {
+  const normalized = normalizeToolName(name);
+  return ["search_web", "read_url_content", "read_url", "web_search"].includes(normalized);
+}
+
+/** Return whether a successful Antigravity tool name represents workspace activity. */
+export function isWorkspaceToolName(name: string): boolean {
+  const normalized = normalizeToolName(name);
+  return (
+    normalized.includes("file") ||
+    normalized.includes("directory") ||
+    normalized.includes("code_search") ||
+    normalized.includes("search_code") ||
+    normalized.includes("grep") ||
+    normalized.includes("find") ||
+    normalized.includes("glob") ||
+    ["list_files", "list_dir", "read_file"].includes(normalized)
+  );
+}

package/src/agents/antigravity/adapter.ts

@@ -0,0 +1,196 @@
+import type { ConsultationActivity, ConsultationExecutionFacts } from "../../types.ts";
+import { ConsultingAgentError, type ConsultingAgentFailureKind } from "../errors.ts";
+import type {
+  ConsultingAgentAdapter,
+  ConsultingAgentAvailability,
+  ConsultingAgentExecutionOptions,
+  ConsultingAvailability,
+} from "../types.ts";
+import { isWebToolName, isWorkspaceToolName } from "./activity.ts";
+import { discoverAntigravityAvailability } from "./availability.ts";
+import {
+  getIsolatedAntigravityPaths,
+  type IsolatedAntigravityPaths,
+  prepareIsolatedAntigravityHome,
+} from "./isolated-home.ts";
+import { probeProjectHooks } from "./process/hooks.ts";
+import { AntigravityProcessError, runAntigravityConversation } from "./process/runner.ts";
+import { ANTIGRAVITY_ANSWER_SCHEMA } from "./structured-output.ts";
+
+const MAX_RETAINED_REFERENCE_HASHES = 512;
+const MAX_WARNING_COUNT = 24;
+const MAX_WARNING_CHARS = 500;
+const CONTINUATION_PREFIX = "agy1.";
+
+/** The one agent supported by Consulting in this package. */
+export const ANTIGRAVITY_AGENT_ID = "antigravity" as const;
+
+/** Compose the private Antigravity implementation behind the neutral adapter. */
+export function createAntigravityAdapter(
+  paths: IsolatedAntigravityPaths = getIsolatedAntigravityPaths(),
+): ConsultingAgentAdapter {
+  return new AntigravityAdapter(paths);
+}
+
+class AntigravityAdapter implements ConsultingAgentAdapter {
+  readonly identity = ANTIGRAVITY_AGENT_ID;
+  readonly consultationWorkspace: string;
+  readonly #paths: IsolatedAntigravityPaths;
+
+  constructor(paths: IsolatedAntigravityPaths) {
+    this.#paths = paths;
+    this.consultationWorkspace = paths.consultationWorkspace;
+  }
+
+  async discover(options: { signal?: AbortSignal } = {}): Promise<ConsultingAvailability> {
+    const availability = await discoverAntigravityAvailability({
+      paths: this.#paths,
+      signal: options.signal,
+    });
+    if (availability.status === "available") {
+      const result: ConsultingAgentAvailability = {
+        status: "available",
+        agent: this.identity,
+        agentVersion: availability.cliVersion,
+        catalogue: availability.catalogue,
+      };
+      return Object.freeze({ ...result, catalogue: Object.freeze([...result.catalogue]) });
+    }
+    return {
+      status: "unavailable",
+      reason: availability.reason,
+      warning: availability.warning,
+      ...(availability.cliVersion ? { agentVersion: availability.cliVersion } : {}),
+    };
+  }
+
+  async execute(options: ConsultingAgentExecutionOptions): Promise<ConsultationExecutionFacts> {
+    try {
+      return await this.#execute(options);
+    } catch (error) {
+      throw safeExecutionFailure(error);
+    }
+  }
+
+  async #execute(options: ConsultingAgentExecutionOptions): Promise<ConsultationExecutionFacts> {
+    const expectedConversationId = options.continuation
+      ? decodeContinuation(options.continuation)
+      : undefined;
+    await prepareIsolatedAntigravityHome(this.#paths);
+    const hookWarning = options.workspaceAccess
+      ? await inspectProjectHooks(this.#paths, options, options.onWarning)
+      : undefined;
+    const rawFacts = await runAntigravityConversation({
+      paths: this.#paths,
+      cwd: options.canonicalWorkingDirectory,
+      prompt: options.prompt,
+      model: options.model,
+      ...(expectedConversationId ? { conversationId: expectedConversationId } : {}),
+      ...(options.workspaceAccess ? { workspaceDirectory: options.canonicalWorkingDirectory } : {}),
+      schema: ANTIGRAVITY_ANSWER_SCHEMA as Record<string, unknown>,
+      signal: options.signal,
+      onActivity: options.onProgress,
+      onProcessStart: options.onProcessStart,
+    });
+    if (expectedConversationId && rawFacts.conversationId !== expectedConversationId) {
+      throw new ConsultingAgentError("conversation-mismatch");
+    }
+
+    const warnings = hookWarning ? [hookWarning] : [];
+    return {
+      answer: rawFacts.answer,
+      continuation: encodeContinuation(rawFacts.conversationId),
+      ...(rawFacts.usage ? { usage: rawFacts.usage } : {}),
+      observedActivities: normalizeObservedActivities(rawFacts.observedToolCounts),
+      activityCounts: normalizeActivityCounts(rawFacts.observedToolCounts),
+      webUsed: rawFacts.successfulToolNames.some(isWebToolName),
+      workspaceUsed: rawFacts.successfulToolNames.some(isWorkspaceToolName),
+      permissionDenials: rawFacts.permissionDenials,
+      observedSourceHashes: rawFacts.observedSourceHashes.slice(0, MAX_RETAINED_REFERENCE_HASHES),
+      observedWorkspacePathHashes: rawFacts.observedWorkspacePathHashes.slice(
+        0,
+        MAX_RETAINED_REFERENCE_HASHES,
+      ),
+      warnings: boundWarnings(warnings),
+    };
+  }
+}
+
+async function inspectProjectHooks(
+  paths: IsolatedAntigravityPaths,
+  options: ConsultingAgentExecutionOptions,
+  onWarning: ConsultingAgentExecutionOptions["onWarning"],
+): Promise<string | undefined> {
+  const probe = await probeProjectHooks({
+    paths,
+    cwd: options.canonicalWorkingDirectory,
+    signal: options.signal,
+    onProcessStart: options.onProcessStart,
+  });
+  if (!probe.warning) return undefined;
+  const warning = boundWarning(probe.warning);
+  onWarning?.(warning);
+  return warning;
+}
+
+function normalizeObservedActivities(counts: Record<string, number>): ConsultationActivity[] {
+  const activities = new Set<ConsultationActivity>();
+  for (const name of Object.keys(counts)) activities.add(classifyActivity(name));
+  return [...activities];
+}
+
+function normalizeActivityCounts(
+  counts: Record<string, number>,
+): Record<ConsultationActivity, number> {
+  const result: Record<ConsultationActivity, number> = { web: 0, workspace: 0, other: 0 };
+  for (const [name, count] of Object.entries(counts)) {
+    result[classifyActivity(name)] += Math.max(0, Math.floor(count));
+  }
+  return result;
+}
+
+function classifyActivity(name: string): ConsultationActivity {
+  if (isWebToolName(name)) return "web";
+  if (isWorkspaceToolName(name)) return "workspace";
+  return "other";
+}
+
+function boundWarnings(warnings: readonly string[]): string[] {
+  return [...new Set(warnings.map(boundWarning).filter(Boolean))].slice(0, MAX_WARNING_COUNT);
+}
+
+function boundWarning(warning: string): string {
+  return warning.replace(/\s+/g, " ").trim().slice(0, MAX_WARNING_CHARS);
+}
+
+function encodeContinuation(conversationId: string): string {
+  return `${CONTINUATION_PREFIX}${Buffer.from(conversationId, "utf8").toString("base64url")}`;
+}
+
+function decodeContinuation(value: string): string {
+  if (!value.startsWith(CONTINUATION_PREFIX) || value.length > 1_000) {
+    throw new ConsultingAgentError("invalid-continuation");
+  }
+  const encoded = value.slice(CONTINUATION_PREFIX.length);
+  const conversationId = Buffer.from(encoded, "base64url").toString("utf8");
+  if (!conversationId || Buffer.from(conversationId, "utf8").toString("base64url") !== encoded) {
+    throw new ConsultingAgentError("invalid-continuation");
+  }
+  return conversationId;
+}
+
+/** Drop raw diagnostics on every failure path, including preparation and callbacks. */
+function safeExecutionFailure(error: unknown): ConsultingAgentError {
+  if (error instanceof ConsultingAgentError) return new ConsultingAgentError(error.kind);
+  const processKinds: Record<AntigravityProcessError["kind"], ConsultingAgentFailureKind> = {
+    missing: "unavailable",
+    timeout: "timeout",
+    cancelled: "cancelled",
+    stream: "invalid-response",
+    protocol: "invalid-response",
+    process: "execution",
+  };
+  return new ConsultingAgentError(
+    error instanceof AntigravityProcessError ? processKinds[error.kind] : "execution",
+  );
+}