@mrclrchtr/supi-consulting 0.0.0-stage → 8.0.1

package/src/agents/antigravity/process/subprocess.ts

@@ -0,0 +1,278 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import { buildAntigravityEnvironment } from "./environment.ts";
+import {
+  BoundedLineParser,
+  BoundedStderrCapture,
+  MAX_STDOUT_BYTES,
+  MAX_STDOUT_LINE_BYTES,
+} from "./ndjson.ts";
+
+const COMMAND = "agy";
+const TERMINATION_GRACE_MS = 500;
+
+/** Safe outcomes from a bounded non-stream Antigravity probe. */
+export interface AntigravityProbeResult {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+}
+
+/** Error raised for a failed Antigravity process or protocol. */
+export class AntigravityProcessError extends Error {
+  readonly kind: "missing" | "timeout" | "cancelled" | "stream" | "process" | "protocol";
+  readonly exitCode: number | null | undefined;
+  /** Bounded stderr retained for an in-memory caller, never put in result details. */
+  readonly stderr: string | undefined;
+
+  constructor(
+    message: string,
+    kind: AntigravityProcessError["kind"],
+    options: { cause?: unknown; exitCode?: number | null; stderr?: string } = {},
+  ) {
+    super(message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.name = "AntigravityProcessError";
+    this.kind = kind;
+    this.exitCode = options.exitCode;
+    this.stderr = options.stderr;
+  }
+}
+
+/** Options for one directly spawned, bounded agy process. */
+export interface BoundedChildProcessOptions {
+  args: string[];
+  cwd: string;
+  homeDir: string;
+  prompt?: string;
+  signal?: AbortSignal;
+  timeoutMs: number;
+  onLine: (line: string) => void;
+  maxStdoutBytes?: number;
+  allowNonZero?: boolean;
+  onProcessStart?: () => void;
+}
+
+/** Spawn agy without a shell and apply stream, timeout, and process-group limits. */
+export function runBoundedChildProcess(
+  options: BoundedChildProcessOptions,
+): Promise<AntigravityProbeResult> {
+  if (process.platform !== "darwin" && process.platform !== "linux") {
+    return Promise.reject(
+      new AntigravityProcessError("Antigravity is supported on macOS and Linux only.", "process"),
+    );
+  }
+  if (options.signal?.aborted) {
+    return Promise.reject(
+      new AntigravityProcessError("Antigravity run was canceled.", "cancelled"),
+    );
+  }
+
+  return new Promise((resolve, reject) => {
+    const parser = new BoundedLineParser({
+      maxLineBytes: MAX_STDOUT_LINE_BYTES,
+      maxTotalBytes: options.maxStdoutBytes ?? MAX_STDOUT_BYTES,
+    });
+    const stderr = new BoundedStderrCapture();
+    let child: ChildProcess | undefined;
+    let closed = false;
+    let settled = false;
+    let failure: Error | undefined;
+    let closeResolve: (() => void) | undefined;
+    const closePromise = new Promise<void>((resolveClose) => {
+      closeResolve = resolveClose;
+    });
+
+    const finishReject = (error: Error): void => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+    };
+
+    const terminateAndReject = (error: Error): void => {
+      if (settled || failure) return;
+      failure = error;
+      void terminateProcess(child, closePromise, () => closed).then(() => {
+        finishReject(error);
+      });
+    };
+
+    const timer = setTimeout(() => {
+      terminateAndReject(new AntigravityProcessError("Antigravity process timed out.", "timeout"));
+    }, options.timeoutMs);
+    const onAbort = (): void => {
+      terminateAndReject(new AntigravityProcessError("Antigravity run was canceled.", "cancelled"));
+    };
+    options.signal?.addEventListener("abort", onAbort, { once: true });
+
+    try {
+      child = spawn(COMMAND, options.args, {
+        cwd: options.cwd,
+        env: buildAntigravityEnvironment(options.homeDir),
+        detached: true,
+        shell: false,
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (error) {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", onAbort);
+      terminateAndReject(classifySpawnError(error));
+      return;
+    }
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      try {
+        parser.feed(toBuffer(chunk), options.onLine);
+      } catch (error) {
+        terminateAndReject(
+          error instanceof Error
+            ? new AntigravityProcessError(error.message, "stream", { cause: error })
+            : new AntigravityProcessError("Antigravity stdout exceeded its limits.", "stream"),
+        );
+      }
+    });
+    child.stderr?.on("data", (chunk: Buffer | string) => stderr.feed(toBuffer(chunk)));
+    child.stdin?.on("error", (error) => terminateAndReject(classifySpawnError(error)));
+    child.on("error", (error) => terminateAndReject(classifySpawnError(error)));
+    child.on("close", (exitCode, signal) => {
+      handleChildClose(exitCode, signal, {
+        parser,
+        options,
+        stderr,
+        setClosed: () => {
+          closed = true;
+          closeResolve?.();
+        },
+        clearTimer: () => clearTimeout(timer),
+        removeAbortListener: () => options.signal?.removeEventListener("abort", onAbort),
+        getFailure: () => failure,
+        isSettled: () => settled,
+        resolve: (result) => {
+          settled = true;
+          resolve(result);
+        },
+        fail: terminateAndReject,
+      });
+    });
+
+    try {
+      options.onProcessStart?.();
+      if (options.prompt !== undefined) {
+        const userEvent = JSON.stringify({
+          event: "user",
+          message: { role: "user", content: options.prompt },
+        });
+        child.stdin?.end(`${userEvent}\n`);
+      } else {
+        child.stdin?.end();
+      }
+    } catch (error) {
+      terminateAndReject(classifySpawnError(error));
+    }
+  });
+}
+
+interface ChildCloseState {
+  parser: BoundedLineParser;
+  options: BoundedChildProcessOptions;
+  stderr: BoundedStderrCapture;
+  setClosed: () => void;
+  clearTimer: () => void;
+  removeAbortListener: () => void;
+  getFailure: () => Error | undefined;
+  isSettled: () => boolean;
+  resolve: (result: AntigravityProbeResult) => void;
+  fail: (error: Error) => void;
+}
+
+function handleChildClose(
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+  state: ChildCloseState,
+): void {
+  state.setClosed();
+  state.clearTimer();
+  state.removeAbortListener();
+  if (state.getFailure()) return;
+  try {
+    state.parser.finish(state.options.onLine);
+    ensureSuccessfulExit(exitCode, signal, state.options.allowNonZero, state.stderr.text());
+    if (!state.isSettled()) {
+      state.resolve({ exitCode, signal, stdout: "", stderr: state.stderr.text() });
+    }
+  } catch (error) {
+    state.fail(toProtocolOrProcessError(error));
+  }
+}
+
+function ensureSuccessfulExit(
+  exitCode: number | null,
+  signal: NodeJS.Signals | null,
+  allowNonZero: boolean | undefined,
+  stderr: string,
+): void {
+  if (allowNonZero || (exitCode === 0 && !signal)) return;
+  throw new AntigravityProcessError(processFailureMessage(exitCode, signal), "process", {
+    exitCode,
+    stderr,
+  });
+}
+
+function toProtocolOrProcessError(error: unknown): AntigravityProcessError {
+  if (error instanceof AntigravityProcessError) return error;
+  return new AntigravityProcessError("Antigravity returned an invalid stream.", "protocol", {
+    cause: error,
+  });
+}
+
+async function terminateProcess(
+  child: ChildProcess | undefined,
+  closePromise: Promise<void>,
+  isClosed: () => boolean,
+): Promise<void> {
+  if (!child || isClosed()) return;
+  sendProcessGroupSignal(child, "SIGTERM");
+  await waitForClose(closePromise, TERMINATION_GRACE_MS);
+  if (!isClosed()) {
+    sendProcessGroupSignal(child, "SIGKILL");
+    await waitForClose(closePromise, TERMINATION_GRACE_MS);
+  }
+}
+
+function sendProcessGroupSignal(child: ChildProcess, signal: NodeJS.Signals): void {
+  if (typeof child.pid !== "number") return;
+  try {
+    process.kill(-child.pid, signal);
+    return;
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // The process may have exited between the two kill attempts.
+    }
+  }
+}
+
+async function waitForClose(closePromise: Promise<void>, timeoutMs: number): Promise<void> {
+  await Promise.race([
+    closePromise,
+    new Promise<void>((resolve) => setTimeout(resolve, timeoutMs)),
+  ]);
+}
+
+function toBuffer(chunk: Buffer | string): Buffer {
+  return Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+}
+
+function classifySpawnError(error: unknown): AntigravityProcessError {
+  const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+  return new AntigravityProcessError(
+    code === "ENOENT" ? "Antigravity CLI was not found." : "Could not start Antigravity CLI.",
+    code === "ENOENT" ? "missing" : "process",
+    { cause: error },
+  );
+}
+
+function processFailureMessage(exitCode: number | null, signal: NodeJS.Signals | null): string {
+  if (signal) return `Antigravity process stopped with ${signal}.`;
+  return `Antigravity process exited with code ${String(exitCode)}.`;
+}

package/src/agents/antigravity/process/usage.ts

@@ -0,0 +1,50 @@
+import type { ConsultationUsage } from "../../../types.ts";
+import { isRecord } from "./event-values.ts";
+
+/** Read bounded token usage from one normalized Antigravity event. */
+export function readUsage(event: Record<string, unknown>): ConsultationUsage | undefined {
+  const value = isRecord(event.usage)
+    ? event.usage
+    : isRecord(event.token_usage)
+      ? event.token_usage
+      : isRecord(event.tokenUsage)
+        ? event.tokenUsage
+        : undefined;
+  if (!value) return undefined;
+  const inputTokens = finiteToken(value.input_tokens ?? value.inputTokens ?? value.prompt_tokens);
+  const outputTokens = finiteToken(
+    value.output_tokens ?? value.outputTokens ?? value.completion_tokens,
+  );
+  const totalTokens = finiteToken(value.total_tokens ?? value.totalTokens ?? value.total);
+  if (inputTokens === undefined && outputTokens === undefined && totalTokens === undefined)
+    return undefined;
+  return {
+    ...(inputTokens === undefined ? {} : { inputTokens }),
+    ...(outputTokens === undefined ? {} : { outputTokens }),
+    ...(totalTokens === undefined ? {} : { totalTokens }),
+  };
+}
+
+/** Merge usage fields without retaining any provider event payload. */
+export function mergeUsage(
+  left: ConsultationUsage | undefined,
+  right: ConsultationUsage | undefined,
+): ConsultationUsage | undefined {
+  if (!left) return right;
+  if (!right) return left;
+  return {
+    ...(left.inputTokens === undefined && right.inputTokens === undefined
+      ? {}
+      : { inputTokens: right.inputTokens ?? left.inputTokens }),
+    ...(left.outputTokens === undefined && right.outputTokens === undefined
+      ? {}
+      : { outputTokens: right.outputTokens ?? left.outputTokens }),
+    ...(left.totalTokens === undefined && right.totalTokens === undefined
+      ? {}
+      : { totalTokens: right.totalTokens ?? left.totalTokens }),
+  };
+}
+
+function finiteToken(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}

package/src/agents/antigravity/structured-output.ts

@@ -0,0 +1,58 @@
+import { type TSchema, Type } from "typebox";
+import { Value } from "typebox/value";
+import type { ConsultationAnswer } from "../../types.ts";
+
+/** Maximum length of Antigravity's final answer text. */
+export const MAX_ANSWER_CHARS = 16_000;
+/** Maximum source references accepted from one answer. */
+export const MAX_SOURCES = 8;
+/** Maximum workspace references accepted from one answer. */
+export const MAX_WORKSPACE_EVIDENCE = 8;
+/** Maximum source title length. */
+export const MAX_SOURCE_TITLE_CHARS = 240;
+/** Maximum source URL length. */
+export const MAX_SOURCE_URL_CHARS = 1_024;
+/** Maximum workspace evidence path length. */
+export const MAX_WORKSPACE_PATH_CHARS = 512;
+/** Maximum workspace evidence summary length. */
+export const MAX_EVIDENCE_SUMMARY_CHARS = 1_000;
+
+/** JSON Schema passed to agy for every paid Antigravity Run. */
+export const ANTIGRAVITY_ANSWER_SCHEMA: TSchema = Type.Object(
+  {
+    answer: Type.String({
+      minLength: 1,
+      maxLength: MAX_ANSWER_CHARS,
+      description: "The answer to the user's request.",
+    }),
+    sources: Type.Array(
+      Type.Object(
+        {
+          title: Type.String({ minLength: 1, maxLength: MAX_SOURCE_TITLE_CHARS }),
+          url: Type.String({ minLength: 1, maxLength: MAX_SOURCE_URL_CHARS }),
+        },
+        { additionalProperties: false },
+      ),
+      { maxItems: MAX_SOURCES },
+    ),
+    workspaceEvidence: Type.Array(
+      Type.Object(
+        {
+          path: Type.String({ minLength: 1, maxLength: MAX_WORKSPACE_PATH_CHARS }),
+          summary: Type.String({ minLength: 1, maxLength: MAX_EVIDENCE_SUMMARY_CHARS }),
+        },
+        { additionalProperties: false },
+      ),
+      { maxItems: MAX_WORKSPACE_EVIDENCE },
+    ),
+  },
+  { additionalProperties: false },
+);
+
+/** Validate and return the exact structured answer shape. */
+export function validateAntigravityAnswer(value: unknown): ConsultationAnswer {
+  if (!Value.Check(ANTIGRAVITY_ANSWER_SCHEMA, value)) {
+    throw new Error("Antigravity returned invalid structured output.");
+  }
+  return value as ConsultationAnswer;
+}

package/src/agents/antigravity/types.ts

@@ -0,0 +1,17 @@
+import type { ConsultationAnswer, ConsultationUsage } from "../../types.ts";
+
+/** Process facts retained only inside the Antigravity adapter. */
+export interface AntigravityExecutionFacts {
+  answer: ConsultationAnswer;
+  conversationId: string;
+  usage?: ConsultationUsage;
+  observedToolNames: string[];
+  observedToolCounts: Record<string, number>;
+  successfulToolNames: string[];
+  permissionDenials: number;
+  observedSourceHashes: string[];
+  observedWorkspacePathHashes: string[];
+}
+
+/** Safe, bounded progress from one Antigravity event. */
+export type AntigravityProgressCallback = (activity: string) => void;

package/src/agents/errors.ts

@@ -0,0 +1,27 @@
+const FAILURE_MESSAGES = {
+  unavailable: "The Consulting Agent is unavailable. Reload PI to check availability.",
+  timeout: "The Consultation timed out.",
+  cancelled: "The Consultation was canceled.",
+  "invalid-response": "The Consulting Agent returned an invalid response.",
+  "invalid-continuation": "Invalid Conversation Handle continuation state.",
+  "conversation-mismatch":
+    "The Consulting Agent returned a different conversation for this handle.",
+  execution: "Consultation execution failed.",
+} as const;
+
+/** Safe failure categories that can leave a private Consulting Agent adapter. */
+export type ConsultingAgentFailureKind = keyof typeof FAILURE_MESSAGES;
+
+/**
+ * A bounded failure with no agent diagnostics or error cause.
+ * Construct messages from fixed categories, never from process output.
+ */
+export class ConsultingAgentError extends Error {
+  readonly kind: ConsultingAgentFailureKind;
+
+  constructor(kind: ConsultingAgentFailureKind) {
+    super(FAILURE_MESSAGES[kind]);
+    this.name = "ConsultingAgentError";
+    this.kind = kind;
+  }
+}

package/src/agents/types.ts

@@ -0,0 +1,43 @@
+import type { ConsultationExecutionFacts, ConsultingAgentId, ConsultingModel } from "../types.ts";
+
+/** Immutable availability returned by one Consulting Agent adapter. */
+export interface ConsultingAgentAvailability {
+  status: "available";
+  agent: ConsultingAgentId;
+  agentVersion: string;
+  catalogue: readonly ConsultingModel[];
+}
+
+/** A bounded reason why a Consulting Agent is not available. */
+export interface ConsultingAgentUnavailable {
+  status: "unavailable";
+  reason: string;
+  warning: string;
+  agentVersion?: string;
+}
+
+/** Result of one session-scoped agent discovery. */
+export type ConsultingAvailability = ConsultingAgentAvailability | ConsultingAgentUnavailable;
+
+/** Inputs to one bounded Consultation executed by an agent adapter. */
+export interface ConsultingAgentExecutionOptions {
+  prompt: string;
+  model: ConsultingModel;
+  canonicalWorkingDirectory: string;
+  workspaceAccess: boolean;
+  continuation?: string;
+  signal?: AbortSignal;
+  onProgress?: (activity: string) => void;
+  onWarning?: (warning: string) => void;
+  onProcessStart?: () => void;
+}
+
+/** Private execution and discovery interface for the supported Consulting Agent. */
+export interface ConsultingAgentAdapter {
+  readonly identity: ConsultingAgentId;
+  /** The agent's stable, package-managed empty Consultation Workspace. */
+  readonly consultationWorkspace: string;
+  discover(options?: { signal?: AbortSignal }): Promise<ConsultingAvailability>;
+  /** Reject with a ConsultingAgentError; raw diagnostics and causes stay inside the adapter. */
+  execute(options: ConsultingAgentExecutionOptions): Promise<ConsultationExecutionFacts>;
+}

package/src/catalogue.ts

@@ -0,0 +1,17 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { TSchema } from "typebox";
+
+/** Build a provider-facing model enum from one immutable agent catalogue. */
+export function buildModelCatalogueEnum(catalogue: readonly string[]): TSchema {
+  if (catalogue.length === 0) {
+    throw new Error("Cannot build a model enum from an empty Consulting Agent catalogue.");
+  }
+  return StringEnum([...catalogue] as [string, ...string[]], {
+    description: "Model available in the current Consulting Agent catalogue.",
+  });
+}
+
+/** Check a model ID against the same discovered catalogue used by the schema. */
+export function isAvailableModel(value: unknown, catalogue: readonly string[]): value is string {
+  return typeof value === "string" && catalogue.includes(value);
+}

package/src/config.ts

@@ -0,0 +1,26 @@
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+
+/** The persisted SuPi configuration section owned by this package. */
+export const CONSULTING_CONFIG_SECTION = "consulting";
+
+/** Configuration for Consulting availability and the consulting_run tool. */
+export interface ConsultingConfig extends Record<string, unknown> {
+  /** Enable agent availability discovery and the consulting_run tool. */
+  agentToolEnabled: boolean;
+}
+
+/** Default Consulting configuration. */
+export const CONSULTING_DEFAULTS: ConsultingConfig = Object.freeze({
+  agentToolEnabled: true,
+});
+
+/** Load only the new consulting configuration section for a workspace. */
+export function loadConsultingConfig(cwd: string, homeDir?: string): ConsultingConfig {
+  const raw = loadSupiConfig(CONSULTING_CONFIG_SECTION, cwd, CONSULTING_DEFAULTS, { homeDir });
+  return {
+    agentToolEnabled:
+      typeof raw.agentToolEnabled === "boolean"
+        ? raw.agentToolEnabled
+        : CONSULTING_DEFAULTS.agentToolEnabled,
+  };
+}