@mrclrchtr/supi-consulting 10.0.0 → 11.0.1

package/README.md

@@ -82,6 +82,27 @@ Results report web use, workspace use, observed and claimed references, warnings
 
 Use `/supi-settings` → **Consulting** to disable the tool. Disabling it skips availability checks and removes `consulting_run` from the active tool list.
 
+## Failure diagnostics
+
+Execution failures report a fixed reason when the adapter can identify it:
+
+- Missing final result, missing structured answer, or answer schema mismatch.
+- Unsuccessful final result or data received after the final result.
+- Malformed JSON, a non-object event, or an output limit exceeded.
+- Missing conversation identifier, process failure, timeout, or cancellation.
+
+An observed tool permission denial is reported separately. It does not prove the cause of a later failure. A denial does not fail a Consultation that returns a valid answer. Workspace Access does not grant access to files outside the selected workspace.
+
+When SuPi Debug is enabled, failed executions emit one `consulting/consultation.failed` event at `error` level. Cancellations emit `consulting/consultation.cancelled` at `info` level. Use the `debug` tool:
+
+```json
+{ "source": "consulting", "level": "error", "limit": 10 }
+```
+
+Omit `level` to include cancellations. Add `sessionFile` to inspect events persisted in a saved PI session. A response aborted before the adapter starts has no Consulting event.
+
+Events contain the execution phase, timing, selected model, workspace-access and follow-up flags, failure category and reason, and available event counts, terminal-state flags, permission-denial count, and exit code. They exclude prompts, answers, resource paths, conversation IDs, raw stdout, stderr, tool payloads, and error causes, even when raw Debug access is enabled. The event's `cwd` identifies the selected working directory. Failure messages remain specific when Debug is disabled.
+
 ## 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**.

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "10.0.0",
+  "version": "11.0.1",
   "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-consulting",
-  "version": "10.0.0",
+  "version": "11.0.1",
   "description": "Bounded consultations with explicit agent and workspace selection and observed evidence",
   "license": "MIT",
   "repository": {
@@ -33,11 +33,11 @@
     "scripts/live-probe.ts",
     "README.md",
     "CLAUDE.md",
-    "CONTEXT.md",
+    "GLOSSARY.md",
     "docs/adr/*.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "10.0.0"
+    "@mrclrchtr/supi-core": "11.0.1"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/agents/antigravity/adapter.ts

@@ -1,3 +1,4 @@
+import { startDebugTimer } from "@mrclrchtr/supi-core/debug";
 import type { ConsultationActivity, ConsultationExecutionFacts } from "../../types.ts";
 import { ConsultingAgentError, type ConsultingAgentFailureKind } from "../errors.ts";
 import type {
@@ -13,6 +14,7 @@ import {
   type IsolatedAntigravityPaths,
   prepareIsolatedAntigravityHome,
 } from "./isolated-home.ts";
+import { isCuratedModel } from "./models.ts";
 import { probeProjectHooks } from "./process/hooks.ts";
 import { AntigravityProcessError, runAntigravityConversation } from "./process/runner.ts";
 import { ANTIGRAVITY_ANSWER_SCHEMA } from "./structured-output.ts";
@@ -22,6 +24,8 @@ const MAX_WARNING_COUNT = 24;
 const MAX_WARNING_CHARS = 500;
 const CONTINUATION_PREFIX = "agy1.";
 
+type ExecutionPhase = "preparation" | "hook-probe" | "conversation" | "validation";
+
 /** The one agent supported by Consulting in this package. */
 export const ANTIGRAVITY_AGENT_ID = "antigravity" as const;
 
@@ -65,21 +69,53 @@ class AntigravityAdapter implements ConsultingAgentAdapter {
   }
 
   async execute(options: ConsultingAgentExecutionOptions): Promise<ConsultationExecutionFacts> {
+    const timer = startDebugTimer();
+    let phase: ExecutionPhase = "preparation";
     try {
-      return await this.#execute(options);
+      return await this.#execute(options, (nextPhase) => {
+        timer.mark(phase);
+        phase = nextPhase;
+      });
     } catch (error) {
-      throw safeExecutionFailure(error);
+      const failure = safeExecutionFailure(error);
+      const canceled = failure.kind === "cancelled";
+      timer.finish(
+        () => ({
+          source: "consulting",
+          level: canceled ? "info" : "error",
+          category: canceled ? "consultation.cancelled" : "consultation.failed",
+          message: failure.message,
+          cwd: options.canonicalWorkingDirectory,
+          data: {
+            agent: this.identity,
+            model: isCuratedModel(options.model) ? options.model : "unknown",
+            workspaceAccess: options.workspaceAccess,
+            followUp: options.continuation !== undefined,
+            phase,
+            kind: failure.kind,
+            reason: failure.reason ?? failure.kind,
+            ...failure.diagnostics,
+          },
+        }),
+        phase,
+      );
+      throw failure;
     }
   }
 
-  async #execute(options: ConsultingAgentExecutionOptions): Promise<ConsultationExecutionFacts> {
+  async #execute(
+    options: ConsultingAgentExecutionOptions,
+    onPhase: (phase: ExecutionPhase) => void,
+  ): Promise<ConsultationExecutionFacts> {
     const expectedConversationId = options.continuation
       ? decodeContinuation(options.continuation)
       : undefined;
     await prepareIsolatedAntigravityHome(this.#paths);
+    if (options.workspaceAccess) onPhase("hook-probe");
     const hookWarning = options.workspaceAccess
       ? await inspectProjectHooks(this.#paths, options, options.onWarning)
       : undefined;
+    onPhase("conversation");
     const rawFacts = await runAntigravityConversation({
       paths: this.#paths,
       cwd: options.canonicalWorkingDirectory,
@@ -92,6 +128,7 @@ class AntigravityAdapter implements ConsultingAgentAdapter {
       onActivity: options.onProgress,
       onProcessStart: options.onProcessStart,
     });
+    onPhase("validation");
     if (expectedConversationId && rawFacts.conversationId !== expectedConversationId) {
       throw new ConsultingAgentError("conversation-mismatch");
     }
@@ -179,9 +216,14 @@ function decodeContinuation(value: string): string {
   return conversationId;
 }
 
-/** Drop raw diagnostics on every failure path, including preparation and callbacks. */
+/** Keep only fixed reasons and safe facts, including preparation and callback failures. */
 function safeExecutionFailure(error: unknown): ConsultingAgentError {
-  if (error instanceof ConsultingAgentError) return new ConsultingAgentError(error.kind);
+  if (error instanceof ConsultingAgentError) {
+    return new ConsultingAgentError(error.kind, {
+      reason: error.reason,
+      diagnostics: error.diagnostics,
+    });
+  }
   const processKinds: Record<AntigravityProcessError["kind"], ConsultingAgentFailureKind> = {
     missing: "unavailable",
     timeout: "timeout",
@@ -190,7 +232,9 @@ function safeExecutionFailure(error: unknown): ConsultingAgentError {
     protocol: "invalid-response",
     process: "execution",
   };
-  return new ConsultingAgentError(
-    error instanceof AntigravityProcessError ? processKinds[error.kind] : "execution",
-  );
+  if (!(error instanceof AntigravityProcessError)) return new ConsultingAgentError("execution");
+  return new ConsultingAgentError(processKinds[error.kind], {
+    reason: error.reason,
+    diagnostics: { ...error.diagnostics, exitCode: error.exitCode },
+  });
 }

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

@@ -23,6 +23,7 @@ import {
   toolName,
 } from "./event-values.ts";
 import { normalizeProtocolEvent } from "./protocol.ts";
+import { AntigravityResponseError } from "./response-error.ts";
 import { mergeUsage, readUsage } from "./usage.ts";
 
 interface PendingTool {
@@ -67,8 +68,7 @@ export class AntigravityEventAccumulator {
 
   /** Consume one already-parsed event. */
   consume(event: Record<string, unknown>): void {
-    if (this.#terminalSeen)
-      throw new Error("Antigravity returned events after its terminal event.");
+    if (this.#terminalSeen) throw new AntigravityResponseError("events-after-terminal");
     const normalizedEvent = normalizeProtocolEvent(event);
     this.#conversationId =
       conversationId(event) ?? conversationId(normalizedEvent) ?? this.#conversationId;
@@ -103,14 +103,25 @@ export class AntigravityEventAccumulator {
     }
   }
 
+  /** Return safe execution facts even when the response is incomplete. */
+  get diagnostics(): {
+    permissionDenials: number;
+    terminalSeen: boolean;
+    terminalSucceeded: boolean;
+  } {
+    return {
+      permissionDenials: this.#permissionDenials,
+      terminalSeen: this.#terminalSeen,
+      terminalSucceeded: this.#terminalSucceeded,
+    };
+  }
+
   /** Finish the reduction and validate terminal structured output. */
   finish(): AntigravityExecutionFacts {
-    if (!this.#terminalSeen || !this.#terminalSucceeded) {
-      throw new Error("Antigravity did not return a successful terminal event.");
-    }
-    if (!this.#candidate)
-      throw new Error("Antigravity terminal output was missing structured data.");
-    if (!this.#conversationId) throw new Error("Antigravity did not return a conversation handle.");
+    if (!this.#terminalSeen) throw new AntigravityResponseError("missing-terminal");
+    if (!this.#terminalSucceeded) throw new AntigravityResponseError("terminal-failed");
+    if (!this.#candidate) throw new AntigravityResponseError("missing-answer");
+    if (!this.#conversationId) throw new AntigravityResponseError("missing-conversation");
     return {
       answer: validateAntigravityAnswer(this.#candidate),
       conversationId: this.#conversationId,
@@ -254,7 +265,7 @@ export class AntigravityEventAccumulator {
     this.#terminalSeen = true;
     const status = eventStatus(event);
     if (isErrorStatus(status) || !hasExplicitSuccess(event, status)) {
-      throw new Error("Antigravity returned a non-success terminal status.");
+      throw new AntigravityResponseError("terminal-failed");
     }
     this.#terminalSucceeded = true;
     this.#candidate = answerCandidate(event);

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

@@ -1,3 +1,5 @@
+import { AntigravityResponseError } from "./response-error.ts";
+
 /** Limits for streamed Antigravity output. */
 export const MAX_STDOUT_LINE_BYTES = 128 * 1024;
 export const MAX_STDOUT_BYTES = 5 * 1024 * 1024;
@@ -5,9 +7,9 @@ export const MAX_STREAM_EVENTS = 512;
 export const MAX_RETAINED_STDERR_BYTES = 8 * 1024;
 
 /** Error raised when a process stream exceeds a package-owned bound. */
-export class StreamLimitError extends Error {
-  constructor(message: string) {
-    super(message);
+export class StreamLimitError extends AntigravityResponseError {
+  constructor(reason: "stdout-line-limit" | "stdout-byte-limit" | "event-limit") {
+    super(reason);
     this.name = "StreamLimitError";
   }
 }
@@ -40,7 +42,7 @@ export class BoundedLineParser {
   feed(chunk: Uint8Array, onLine: (line: string) => void): void {
     this.#totalBytes += chunk.byteLength;
     if (this.#totalBytes > this.#maxTotalBytes) {
-      throw new StreamLimitError("Antigravity stdout exceeded its byte limit.");
+      throw new StreamLimitError("stdout-byte-limit");
     }
 
     let start = 0;
@@ -62,7 +64,7 @@ export class BoundedLineParser {
     if (part.byteLength === 0) return;
     this.#lineBytes += part.byteLength;
     if (this.#lineBytes > this.#maxLineBytes) {
-      throw new StreamLimitError("An Antigravity stdout line exceeded its byte limit.");
+      throw new StreamLimitError("stdout-line-limit");
     }
     this.#lineParts.push(Buffer.from(part));
   }
@@ -111,10 +113,10 @@ export function parseNdjsonLine(line: string): Record<string, unknown> | undefin
   try {
     parsed = JSON.parse(line);
   } catch (error) {
-    throw new Error("Antigravity returned malformed NDJSON.", { cause: error });
+    throw new AntigravityResponseError("malformed-json", { cause: error });
   }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new Error("Antigravity returned a non-object NDJSON event.");
+    throw new AntigravityResponseError("invalid-event");
   }
   return parsed as Record<string, unknown>;
 }

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

@@ -9,9 +9,10 @@ export function normalizeProtocolEvent(event: Record<string, unknown>): Record<s
 }
 
 function normalizeResultEnvelope(event: Record<string, unknown>): Record<string, unknown> {
-  return isRecord(event.result)
-    ? { ...event, ...event.result, type: "result" }
-    : { ...event, type: "result" };
+  if (!isRecord(event.result)) return { ...event, type: "result" };
+  // Remove the envelope so its status fields cannot be mistaken for answer data.
+  const { result, ...envelope } = event;
+  return { ...envelope, ...result, type: "result" };
 }
 
 function normalizeStepUpdateEnvelope(event: Record<string, unknown>): Record<string, unknown> {

package/src/agents/antigravity/process/response-error.ts

@@ -0,0 +1,12 @@
+import type { ConsultingFailureReason } from "../../errors.ts";
+
+/** Internal response failure with a fixed reason that survives process error wrapping. */
+export class AntigravityResponseError extends Error {
+  readonly reason: ConsultingFailureReason;
+
+  constructor(reason: ConsultingFailureReason, options?: ErrorOptions) {
+    super(`Antigravity response failure: ${reason}.`, options);
+    this.name = "AntigravityResponseError";
+    this.reason = reason;
+  }
+}

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

@@ -6,6 +6,7 @@ import type { AntigravityExecutionFacts, AntigravityProgressCallback } from "../
 import { eventType, toolName } from "./event-values.ts";
 import { AntigravityEventAccumulator } from "./events.ts";
 import { MAX_STREAM_EVENTS, parseNdjsonLine, StreamLimitError } from "./ndjson.ts";
+import { AntigravityResponseError } from "./response-error.ts";
 import type { AntigravityProbeResult } from "./subprocess.ts";
 import { AntigravityProcessError, runBoundedChildProcess } from "./subprocess.ts";
 
@@ -72,6 +73,8 @@ export async function runAntigravityConversation(options: {
     join(options.schemaDirectoryParent ?? tmpdir(), "supi-consulting-schema-"),
   );
   const schemaPath = join(schemaDirectory, "answer.json");
+  const accumulator = new AntigravityEventAccumulator({ workspaceDirectory: options.cwd });
+  let eventCount = 0;
   try {
     await writeFile(schemaPath, `${JSON.stringify(options.schema)}\n`, { mode: 0o600 });
     const args = buildAntigravityRunArguments(
@@ -80,8 +83,6 @@ export async function runAntigravityConversation(options: {
       options.conversationId,
       options.workspaceDirectory,
     );
-    const accumulator = new AntigravityEventAccumulator({ workspaceDirectory: options.cwd });
-    let eventCount = 0;
     await runBoundedChildProcess({
       args,
       cwd: options.cwd,
@@ -94,7 +95,7 @@ export async function runAntigravityConversation(options: {
         if (!event) return;
         eventCount += 1;
         if (eventCount > MAX_STREAM_EVENTS) {
-          throw new StreamLimitError("Antigravity returned too many stream events.");
+          throw new StreamLimitError("event-limit");
         }
         options.onActivity?.(safeActivityLabel(event));
         accumulator.consume(event);
@@ -103,11 +104,19 @@ export async function runAntigravityConversation(options: {
     });
     return accumulator.finish();
   } catch (error) {
-    if (error instanceof AntigravityProcessError) throw error;
+    const processError = error instanceof AntigravityProcessError ? error : undefined;
     // biome-ignore lint/style/useErrorCause: the custom process error preserves the protocol cause.
-    throw new AntigravityProcessError("Antigravity returned an invalid stream.", "protocol", {
-      cause: error,
-    });
+    throw new AntigravityProcessError(
+      processError?.message ?? "Antigravity returned an invalid stream.",
+      processError?.kind ?? "protocol",
+      {
+        cause: error,
+        reason: error instanceof AntigravityResponseError ? error.reason : processError?.reason,
+        exitCode: processError?.exitCode,
+        stderr: processError?.stderr,
+        diagnostics: { ...accumulator.diagnostics, eventCount },
+      },
+    );
   } finally {
     await rm(schemaDirectory, { recursive: true, force: true });
   }

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

@@ -1,4 +1,5 @@
 import { type ChildProcess, spawn } from "node:child_process";
+import type { ConsultingFailureDiagnostics, ConsultingFailureReason } from "../../errors.ts";
 import { buildAntigravityEnvironment } from "./environment.ts";
 import {
   BoundedLineParser,
@@ -6,6 +7,7 @@ import {
   MAX_STDOUT_BYTES,
   MAX_STDOUT_LINE_BYTES,
 } from "./ndjson.ts";
+import { AntigravityResponseError } from "./response-error.ts";
 
 const COMMAND = "agy";
 const TERMINATION_GRACE_MS = 500;
@@ -24,17 +26,27 @@ export class AntigravityProcessError extends Error {
   readonly exitCode: number | null | undefined;
   /** Bounded stderr retained for an in-memory caller, never put in result details. */
   readonly stderr: string | undefined;
+  readonly reason: ConsultingFailureReason | undefined;
+  readonly diagnostics: ConsultingFailureDiagnostics | undefined;
 
   constructor(
     message: string,
     kind: AntigravityProcessError["kind"],
-    options: { cause?: unknown; exitCode?: number | null; stderr?: string } = {},
+    options: {
+      cause?: unknown;
+      exitCode?: number | null;
+      stderr?: string;
+      reason?: ConsultingFailureReason;
+      diagnostics?: ConsultingFailureDiagnostics;
+    } = {},
   ) {
     super(message, options.cause === undefined ? undefined : { cause: options.cause });
     this.name = "AntigravityProcessError";
     this.kind = kind;
     this.exitCode = options.exitCode;
     this.stderr = options.stderr;
+    this.reason = options.reason;
+    this.diagnostics = options.diagnostics;
   }
 }
 
@@ -125,7 +137,10 @@ export function runBoundedChildProcess(
       } catch (error) {
         terminateAndReject(
           error instanceof Error
-            ? new AntigravityProcessError(error.message, "stream", { cause: error })
+            ? new AntigravityProcessError(error.message, "stream", {
+                cause: error,
+                ...(error instanceof AntigravityResponseError ? { reason: error.reason } : {}),
+              })
             : new AntigravityProcessError("Antigravity stdout exceeded its limits.", "stream"),
         );
       }
@@ -221,6 +236,7 @@ function toProtocolOrProcessError(error: unknown): AntigravityProcessError {
   if (error instanceof AntigravityProcessError) return error;
   return new AntigravityProcessError("Antigravity returned an invalid stream.", "protocol", {
     cause: error,
+    ...(error instanceof AntigravityResponseError ? { reason: error.reason } : {}),
   });
 }
 

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

@@ -1,6 +1,7 @@
 import { type TSchema, Type } from "typebox";
 import { Value } from "typebox/value";
 import type { ConsultationAnswer } from "../../types.ts";
+import { AntigravityResponseError } from "./process/response-error.ts";
 
 /** Maximum length of Antigravity's final answer text. */
 export const MAX_ANSWER_CHARS = 16_000;
@@ -52,7 +53,7 @@ export const ANTIGRAVITY_ANSWER_SCHEMA: TSchema = Type.Object(
 /** 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.");
+    throw new AntigravityResponseError("invalid-answer");
   }
   return value as ConsultationAnswer;
 }

package/src/agents/errors.ts

@@ -9,19 +9,68 @@ const FAILURE_MESSAGES = {
   execution: "Consultation execution failed.",
 } as const;
 
+const FAILURE_REASON_MESSAGES = {
+  "missing-terminal": "The Consulting Agent did not return a final result.",
+  "terminal-failed": "The Consulting Agent reported an unsuccessful final result.",
+  "missing-answer": "The Consulting Agent did not return a final structured answer.",
+  "invalid-answer":
+    "The Consulting Agent returned an answer that does not match the required schema.",
+  "missing-conversation": "The Consulting Agent did not return a conversation identifier.",
+  "events-after-terminal": "The Consulting Agent sent data after its final result.",
+  "malformed-json": "The Consulting Agent returned malformed JSON.",
+  "invalid-event": "The Consulting Agent returned a non-object response event.",
+  "stdout-line-limit": "The Consulting Agent response exceeded the line-size limit.",
+  "stdout-byte-limit": "The Consulting Agent response exceeded the total output-size limit.",
+  "event-limit": "The Consulting Agent response exceeded the event limit.",
+} as const;
+
+/** Fixed failure reasons that do not contain agent output. */
+export type ConsultingFailureReason = keyof typeof FAILURE_REASON_MESSAGES;
+
+/** Execution facts that can leave the adapter on failure. No resource names or raw output. */
+export interface ConsultingFailureDiagnostics {
+  permissionDenials?: number;
+  eventCount?: number;
+  terminalSeen?: boolean;
+  terminalSucceeded?: boolean;
+  exitCode?: number | null;
+}
+
 /** 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.
+ * A bounded failure with fixed messages and safe execution facts, but no raw cause.
+ * Permission denials are observations, not a claim about the cause of failure.
  */
 export class ConsultingAgentError extends Error {
   readonly kind: ConsultingAgentFailureKind;
+  readonly reason: ConsultingFailureReason | undefined;
+  readonly diagnostics: ConsultingFailureDiagnostics | undefined;
 
-  constructor(kind: ConsultingAgentFailureKind) {
-    super(FAILURE_MESSAGES[kind]);
+  constructor(
+    kind: ConsultingAgentFailureKind,
+    options: { reason?: ConsultingFailureReason; diagnostics?: ConsultingFailureDiagnostics } = {},
+  ) {
+    const message = options.reason
+      ? FAILURE_REASON_MESSAGES[options.reason]
+      : FAILURE_MESSAGES[kind];
+    const denial = (options.diagnostics?.permissionDenials ?? 0) > 0;
+    super(
+      `${message}${denial ? " A tool permission denial was observed. Check the requested resources and the Consulting Agent permissions." : ""}`,
+    );
     this.name = "ConsultingAgentError";
     this.kind = kind;
+    this.reason = options.reason;
+    const facts = options.diagnostics;
+    this.diagnostics = facts
+      ? {
+          permissionDenials: facts.permissionDenials,
+          eventCount: facts.eventCount,
+          terminalSeen: facts.terminalSeen,
+          terminalSucceeded: facts.terminalSucceeded,
+          exitCode: facts.exitCode,
+        }
+      : undefined;
   }
 }

package/src/agents/types.ts

@@ -38,6 +38,6 @@ export interface ConsultingAgentAdapter {
   /** 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. */
+  /** Reject with a ConsultingAgentError and safe facts; raw diagnostics and causes stay inside the adapter. */
   execute(options: ConsultingAgentExecutionOptions): Promise<ConsultationExecutionFacts>;
 }