@mrclrchtr/supi-consulting 0.0.0-stage → 9.0.0

package/src/conversation/handles.ts

@@ -0,0 +1,187 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ConversationHandleRecord } from "../types.ts";
+
+/** Private custom-entry type used to rebuild handles on the active PI branch. */
+export const CONSULTING_HANDLE_ENTRY_TYPE = "supi-consulting-handle";
+
+interface PersistedHandleEntry {
+  version: 1;
+  action: "created" | "retired";
+  record?: ConversationHandleRecord;
+  handle?: string;
+  reason?: string;
+}
+
+/** Preflight failure for a Conversation Handle request. */
+export class ConversationHandleError extends Error {
+  readonly code: "unknown" | "retired" | "busy" | "unsupported-agent";
+
+  constructor(code: ConversationHandleError["code"]) {
+    const messages = {
+      unknown: "Unknown Conversation Handle.",
+      retired: "That Conversation Handle is retired.",
+      busy: "That Conversation Handle is already in use.",
+      "unsupported-agent": "That Conversation Handle belongs to an unsupported Consulting Agent.",
+    };
+    super(messages[code]);
+    this.name = "ConversationHandleError";
+    this.code = code;
+  }
+}
+
+/** Session-local Conversation Handle state with branch-aware reconstruction. */
+export class ConversationHandleStore {
+  #records = new Map<string, ConversationHandleRecord>();
+  #busy = new Set<string>();
+
+  /** Rebuild valid handles from one current PI branch. */
+  rebuild(branch: readonly unknown[]): void {
+    this.#records.clear();
+    this.#busy.clear();
+    for (const entry of branch) this.#consumeEntry(entry);
+  }
+
+  /** Create a new opaque Conversation Handle after a successful Consultation. */
+  create(record: Omit<ConversationHandleRecord, "handle" | "status">): ConversationHandleRecord {
+    const created: ConversationHandleRecord = Object.freeze({
+      ...record,
+      handle: createOpaqueHandle(),
+      status: "active",
+    });
+    this.#records.set(created.handle, created);
+    return created;
+  }
+
+  /** Return a handle record without changing its state. */
+  get(handle: string): ConversationHandleRecord | undefined {
+    return this.#records.get(handle);
+  }
+
+  /** Acquire a handle after rejecting unknown, unsupported, retired, or busy state. */
+  acquire(handle: string, supportedAgent: string): ConversationHandleRecord {
+    const record = this.#records.get(handle);
+    if (!record) throw new ConversationHandleError("unknown");
+    if (record.agent !== supportedAgent) throw new ConversationHandleError("unsupported-agent");
+    if (record.status === "retired") throw new ConversationHandleError("retired");
+    if (this.#busy.has(handle)) throw new ConversationHandleError("busy");
+    this.#busy.add(handle);
+    return record;
+  }
+
+  /** Release a completed or pre-process follow-up. */
+  release(handle: string): void {
+    this.#busy.delete(handle);
+  }
+
+  /** Retire a handle after a started follow-up fails or is canceled. */
+  retire(handle: string): ConversationHandleRecord | undefined {
+    const record = this.#records.get(handle);
+    if (!record) return undefined;
+    const retired = Object.freeze({ ...record, status: "retired" as const });
+    this.#records.set(handle, retired);
+    this.#busy.delete(handle);
+    return retired;
+  }
+
+  /** Clear all state when the extension instance shuts down. */
+  clear(): void {
+    this.#records.clear();
+    this.#busy.clear();
+  }
+
+  #consumeEntry(entry: unknown): void {
+    if (!isRecord(entry)) return;
+    if (entry.type === "custom" && entry.customType === CONSULTING_HANDLE_ENTRY_TYPE) {
+      this.#consumePersistedData(entry.data);
+      return;
+    }
+    if (entry.type === "message" && isRecord(entry.message)) {
+      const message = entry.message;
+      if (message.role === "toolResult" && message.toolName === "consulting_run") {
+        this.#consumeResultDetails(message.details);
+      }
+    }
+  }
+
+  #consumePersistedData(value: unknown): void {
+    if (!isRecord(value) || value.version !== 1) return;
+    if (value.action === "created" && isHandleRecord(value.record)) {
+      this.#records.set(value.record.handle, Object.freeze({ ...value.record }));
+      return;
+    }
+    if (value.action === "retired" && typeof value.handle === "string") {
+      this.retire(value.handle);
+    }
+  }
+
+  #consumeResultDetails(value: unknown): void {
+    if (!isRecord(value)) return;
+    const record = {
+      handle: value.handle,
+      agent: value.agent,
+      model: value.model,
+      continuation: value.continuation,
+      canonicalWorkingDirectory: value.canonicalWorkingDirectory,
+      workspaceAccess: value.workspaceAccess,
+      agentVersion: value.agentVersion,
+      status: value.handleState,
+    };
+    if (isHandleRecord(record) && !this.#records.has(record.handle)) {
+      this.#records.set(record.handle, Object.freeze({ ...record }));
+    }
+  }
+}
+
+/** Persist a successful handle without adding model-visible content. */
+export function appendHandleCreated(pi: ExtensionAPI, record: ConversationHandleRecord): void {
+  const data: PersistedHandleEntry = { version: 1, action: "created", record };
+  pi.appendEntry(CONSULTING_HANDLE_ENTRY_TYPE, data);
+}
+
+/** Persist a branch-aware retirement without exposing continuation state as model text. */
+export function appendHandleRetired(
+  pi: ExtensionAPI,
+  record: ConversationHandleRecord,
+  reason: string,
+): void {
+  const data: PersistedHandleEntry = {
+    version: 1,
+    action: "retired",
+    handle: record.handle,
+    reason: boundedReason(reason),
+  };
+  pi.appendEntry(CONSULTING_HANDLE_ENTRY_TYPE, data);
+}
+
+function createOpaqueHandle(): string {
+  return `consult_${randomUUID().replaceAll("-", "")}`;
+}
+
+function isHandleRecord(value: unknown): value is ConversationHandleRecord {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.handle === "string" &&
+    /^consult_[0-9a-f]+$/i.test(value.handle) &&
+    typeof value.agent === "string" &&
+    value.agent.length > 0 &&
+    typeof value.model === "string" &&
+    value.model.length > 0 &&
+    typeof value.continuation === "string" &&
+    value.continuation.length > 0 &&
+    value.continuation.length <= 1_000 &&
+    typeof value.canonicalWorkingDirectory === "string" &&
+    value.canonicalWorkingDirectory.length > 0 &&
+    typeof value.workspaceAccess === "boolean" &&
+    typeof value.agentVersion === "string" &&
+    (value.status === "active" || value.status === "retired")
+  );
+}
+
+function boundedReason(value: string): string {
+  return value.replace(/\s+/g, " ").trim().slice(0, 200) || "follow-up failed";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/evidence-hash.ts

@@ -0,0 +1,6 @@
+import { createHash } from "node:crypto";
+
+/** Hash evidence references before they cross the private agent adapter boundary. */
+export function hashEvidence(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}

package/src/extension.ts

@@ -0,0 +1,26 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createAntigravityAdapter } from "./agents/antigravity/adapter.ts";
+import { registerConsultingFooterContribution } from "./footer.ts";
+import { ConsultingRuntime } from "./runtime.ts";
+import { registerConsultingSettings } from "./settings.ts";
+
+/** Register the opt-in Consulting extension with its Antigravity adapter. */
+export default function consultingExtension(pi: ExtensionAPI): void {
+  const runtime = new ConsultingRuntime({ pi, adapter: createAntigravityAdapter() });
+  const footer = registerConsultingFooterContribution(runtime);
+  registerConsultingSettings(pi, runtime);
+
+  pi.on("session_start", (_event, ctx) => {
+    runtime.rebuildHandles(ctx.sessionManager.getBranch());
+    void runtime.startRefresh(ctx.cwd, ctx);
+  });
+
+  pi.on("session_tree", (_event, ctx) => {
+    runtime.rebuildHandles(ctx.sessionManager.getBranch());
+  });
+
+  pi.on("session_shutdown", async () => {
+    await runtime.shutdown();
+    footer.dispose();
+  });
+}

package/src/footer-constants.ts

@@ -0,0 +1,5 @@
+/** Footer status key shared by the stats-line contribution and PI fallback. */
+export const CONSULTING_FOOTER_KEY = "supi-consulting";
+
+/** Terminal-safe four-point star used for the ready indicator. */
+export const CONSULTING_READY_ICON = "✦";

package/src/footer.ts

@@ -0,0 +1,25 @@
+import { footerContributions } from "@mrclrchtr/supi-core/footer-registry";
+import { CONSULTING_FOOTER_KEY } from "./footer-constants.ts";
+import type { ConsultingRuntime } from "./runtime.ts";
+
+/** Register the Consulting checking spinner and ready icon on the footer stats line. */
+export function registerConsultingFooterContribution(runtime: ConsultingRuntime): {
+  dispose: () => void;
+} {
+  footerContributions.register({
+    key: CONSULTING_FOOTER_KEY,
+    placement: "stats-end",
+    priority: 110,
+    render: () => {
+      const icon = runtime.footerIcon;
+      return icon ? `| ${icon}` : "";
+    },
+  });
+
+  return { dispose: unregisterConsultingFooterContribution };
+}
+
+/** Remove the Consulting ready icon from the footer. */
+export function unregisterConsultingFooterContribution(): void {
+  footerContributions.unregister(CONSULTING_FOOTER_KEY);
+}

package/src/runtime.ts

@@ -0,0 +1,244 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { FOOTER_INVALIDATE_EVENT } from "@mrclrchtr/supi-core/footer-registry";
+import { BRAILLE_SPINNER_FRAMES, SPINNER_INTERVAL_MS } from "@mrclrchtr/supi-core/spinner-frames";
+import type {
+  ConsultingAgentAdapter,
+  ConsultingAgentAvailability,
+  ConsultingAvailability,
+} from "./agents/types.ts";
+import { loadConsultingConfig } from "./config.ts";
+import { ConversationHandleStore } from "./conversation/handles.ts";
+import { CONSULTING_FOOTER_KEY, CONSULTING_READY_ICON } from "./footer-constants.ts";
+import { registerConsultingRunTool } from "./tool/consulting_run/register.ts";
+import { CONSULTING_RUN_TOOL_NAME } from "./tool/consulting_run/spec.ts";
+
+type FooterState = "idle" | "checking" | "ready";
+
+/** Context needed to report availability and update the footer. */
+export type ConsultingRefreshContext = {
+  ui: Pick<ExtensionContext["ui"], "notify" | "setStatus">;
+};
+
+/** Session runtime for immutable availability and Conversation Handle state. */
+export class ConsultingRuntime {
+  readonly handles = new ConversationHandleStore();
+  readonly adapter: ConsultingAgentAdapter;
+  #pi: ExtensionAPI;
+  #homeDir: string | undefined;
+  #availability: ConsultingAgentAvailability | undefined;
+  #refreshGeneration = 0;
+  #refreshAbort: AbortController | undefined;
+  #statusUi: Pick<ExtensionContext["ui"], "setStatus"> | undefined;
+  #footerState: FooterState = "idle";
+  #spinnerTimer: ReturnType<typeof setInterval> | undefined;
+  #spinnerFrame = 0;
+  #toolRegistered = false;
+
+  constructor(options: { pi: ExtensionAPI; adapter: ConsultingAgentAdapter; homeDir?: string }) {
+    this.#pi = options.pi;
+    this.adapter = options.adapter;
+    this.#homeDir = options.homeDir;
+  }
+
+  /** The immutable discovery result, if session discovery has completed. */
+  get availability(): ConsultingAgentAvailability | undefined {
+    return this.#availability;
+  }
+
+  /** Whether the discovered Consultation tool is ready for use. */
+  get isReady(): boolean {
+    return this.#footerState === "ready";
+  }
+
+  /** Return the animated checking icon or the settled ready icon for the footer. */
+  get footerIcon(): string | undefined {
+    if (this.#footerState === "checking") {
+      return BRAILLE_SPINNER_FRAMES[this.#spinnerFrame % BRAILLE_SPINNER_FRAMES.length];
+    }
+    return this.#footerState === "ready" ? CONSULTING_READY_ICON : undefined;
+  }
+
+  /** Rebuild handles from the current PI branch. */
+  rebuildHandles(branch: readonly unknown[]): void {
+    this.handles.rebuild(branch);
+  }
+
+  /** Start availability discovery without making Pi session startup wait. */
+  startRefresh(cwd: string, context?: ConsultingRefreshContext): Promise<void> {
+    return this.refresh(cwd, context).catch((error) => {
+      try {
+        // biome-ignore lint/suspicious/noConsole: unexpected failures must stay visible.
+        console.warn(`[supi-consulting] Availability check failed: ${formatRefreshError(error)}`);
+        context?.ui.notify("Consulting availability check failed. Reload PI to retry.", "warning");
+      } catch {
+        // PI may be shutting down while the refresh completes.
+      }
+    });
+  }
+
+  /** Discover or reuse availability and synchronize the active tool. */
+  async refresh(cwd: string, context?: ConsultingRefreshContext): Promise<void> {
+    const generation = ++this.#refreshGeneration;
+    this.#refreshAbort?.abort();
+    const abortController = new AbortController();
+    this.#refreshAbort = abortController;
+    if (context) this.#statusUi = context.ui;
+    this.#stopSpinner();
+    this.#setFooterState("idle");
+    const config = loadConsultingConfig(cwd, this.#homeDir);
+    if (!config.agentToolEnabled) {
+      this.#deactivateTool();
+      return;
+    }
+    this.#startSpinner();
+
+    let availability: ConsultingAvailability =
+      this.#availability ??
+      (await this.adapter.discover({ signal: abortController.signal }).catch(() => ({
+        status: "unavailable",
+        reason: "discovery",
+        warning:
+          "Consulting Agent availability discovery failed. Check the installation, then reload PI.",
+      })));
+    if (generation !== this.#refreshGeneration || abortController.signal.aborted) return;
+    if (availability.status === "available") {
+      try {
+        availability = freezeAvailability(availability, this.adapter.identity);
+        this.#availability = availability;
+        this.#activateTool(availability);
+      } catch (error) {
+        this.#stopSpinner();
+        this.#setFooterState("idle");
+        throw error;
+      }
+      this.#stopSpinner();
+      this.#setFooterState("ready");
+      return;
+    }
+    this.#stopSpinner();
+    this.#setFooterState("idle");
+    this.#deactivateTool();
+    notifyRefreshWarning(context, availability.warning);
+  }
+
+  /** Stop in-flight discovery and clear session-local state. */
+  async shutdown(): Promise<void> {
+    this.#refreshGeneration += 1;
+    this.#refreshAbort?.abort();
+    this.#refreshAbort = undefined;
+    this.#stopSpinner();
+    this.#setFooterState("idle");
+    this.#deactivateTool();
+    this.#statusUi = undefined;
+    this.handles.clear();
+    await Promise.resolve();
+  }
+
+  #activateTool(availability: ConsultingAgentAvailability): void {
+    if (!this.#toolRegistered) {
+      registerConsultingRunTool({
+        pi: this.#pi,
+        adapter: this.adapter,
+        availability,
+        handles: this.handles,
+      });
+      this.#toolRegistered = true;
+    }
+    const activeTools = this.#pi.getActiveTools();
+    if (!activeTools.includes(CONSULTING_RUN_TOOL_NAME)) {
+      this.#pi.setActiveTools([...activeTools, CONSULTING_RUN_TOOL_NAME]);
+    }
+  }
+
+  #deactivateTool(): void {
+    const activeTools = this.#pi.getActiveTools();
+    if (activeTools.includes(CONSULTING_RUN_TOOL_NAME)) {
+      this.#pi.setActiveTools(activeTools.filter((name) => name !== CONSULTING_RUN_TOOL_NAME));
+    }
+  }
+
+  #startSpinner(): void {
+    this.#stopSpinner();
+    this.#spinnerFrame = 0;
+    this.#setFooterState("checking");
+    this.#spinnerTimer = setInterval(() => {
+      if (this.#footerState !== "checking") return;
+      this.#spinnerFrame = (this.#spinnerFrame + 1) % BRAILLE_SPINNER_FRAMES.length;
+      this.#publishFooter();
+      this.#invalidateFooter();
+    }, SPINNER_INTERVAL_MS);
+    this.#spinnerTimer.unref?.();
+  }
+
+  #stopSpinner(): void {
+    if (this.#spinnerTimer === undefined) return;
+    clearInterval(this.#spinnerTimer);
+    this.#spinnerTimer = undefined;
+  }
+
+  #setFooterState(state: FooterState): void {
+    const changed = this.#footerState !== state;
+    this.#footerState = state;
+    this.#publishFooter();
+    if (!changed) return;
+    this.#invalidateFooter();
+  }
+
+  #publishFooter(): void {
+    try {
+      this.#statusUi?.setStatus(CONSULTING_FOOTER_KEY, this.footerIcon);
+    } catch {
+      // PI may be shutting down while the footer status changes.
+    }
+  }
+
+  #invalidateFooter(): void {
+    try {
+      this.#pi.events.emit(FOOTER_INVALIDATE_EVENT, {});
+    } catch {
+      // Footer refresh is optional and must not change runtime state.
+    }
+  }
+}
+
+function freezeAvailability(
+  availability: ConsultingAgentAvailability,
+  expectedAgent: string,
+): ConsultingAgentAvailability {
+  if (
+    availability.agent !== expectedAgent ||
+    !availability.agentVersion ||
+    availability.catalogue.length === 0 ||
+    availability.catalogue.some((model) => typeof model !== "string" || model.length === 0)
+  ) {
+    throw new Error("Consulting Agent returned an invalid availability snapshot.");
+  }
+  return Object.freeze({
+    ...availability,
+    catalogue: Object.freeze([...availability.catalogue]),
+  });
+}
+
+function formatRefreshError(error: unknown): string {
+  const message =
+    error instanceof Error
+      ? error.message
+      : typeof error === "object" &&
+          error !== null &&
+          "message" in error &&
+          typeof error.message === "string"
+        ? error.message
+        : String(error);
+  return message.replace(/\s+/g, " ").trim().slice(0, 200) || "unknown error";
+}
+
+function notifyRefreshWarning(
+  context: ConsultingRefreshContext | undefined,
+  message: string,
+): void {
+  try {
+    context?.ui.notify(message, "warning");
+  } catch {
+    // PI may be shutting down while the refresh reports its result.
+  }
+}

package/src/settings.ts

@@ -0,0 +1,38 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { defineConfigSettings, registerSettings } from "@mrclrchtr/supi-core/settings";
+import { CONSULTING_CONFIG_SECTION, CONSULTING_DEFAULTS } from "./config.ts";
+import type { ConsultingRuntime } from "./runtime.ts";
+
+/** Register the Consulting setting with an awaited availability refresh. */
+export function registerConsultingSettings(
+  pi: ExtensionAPI,
+  runtime: ConsultingRuntime,
+  homeDir?: string,
+): void {
+  const fixedSettings = defineConfigSettings({
+    id: CONSULTING_CONFIG_SECTION,
+    label: "Consulting",
+    section: CONSULTING_CONFIG_SECTION,
+    defaults: CONSULTING_DEFAULTS,
+    fields: [
+      {
+        kind: "boolean" as const,
+        key: "agentToolEnabled",
+        label: "Consultation tool",
+        description: "Enable consulting_run and its availability checks.",
+      },
+    ],
+    ...(homeDir ? { homeDir } : {}),
+  });
+
+  registerSettings(pi, {
+    ...fixedSettings,
+    apply: async (request) => {
+      const result = await fixedSettings.apply(request);
+      if (request.fieldKey === "agentToolEnabled") {
+        await runtime.refresh(request.cwd, request.ctx ? { ui: request.ctx.ui } : undefined);
+      }
+      return result;
+    },
+  });
+}