@mrclrchtr/supi-consulting 11.1.0 → 11.3.0

package/src/agents/errors.ts

@@ -3,7 +3,8 @@ const FAILURE_MESSAGES = {
   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.",
+  "invalid-continuation":
+    "The Conversation Handle has invalid or incompatible continuation state. Start a new Consultation.",
   "conversation-mismatch":
     "The Consulting Agent returned a different conversation for this handle.",
   execution: "Consultation execution failed.",
@@ -15,6 +16,8 @@ const FAILURE_REASON_MESSAGES = {
   "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.",
+  "unbound-answer":
+    "The Consulting Agent's structured answer could not be verified for the current request. Start a new Consultation.",
   "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.",
@@ -27,9 +30,49 @@ const FAILURE_REASON_MESSAGES = {
 /** 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. */
+const DENIED_OPERATIONS = [
+  "command",
+  "file-read",
+  "file-write",
+  "web-read",
+  "browser",
+  "mcp",
+  "other",
+] as const;
+
+/** Fixed operation categories; raw agent tool names never leave the adapter on failure. */
+export type ConsultingDeniedOperation = (typeof DENIED_OPERATIONS)[number];
+
+/** Maximum distinct requested file targets in each failure resource list. */
+export const MAX_FAILURE_RESOURCES = 8;
+/** Longer paths are unavailable, never silently truncated into a different target. */
+export const MAX_FAILURE_RESOURCE_PATH_CHARS = 1_024;
+
+/** Structured requested file target, not a canonical path, rule decision, or outcome. */
+export interface ConsultingFileResource {
+  operation: "file-read" | "file-write";
+  requestedPath: string;
+}
+
+/** Failure facts plus bounded requested file targets; never raw tool payloads or output. */
 export interface ConsultingFailureDiagnostics {
   permissionDenials?: number;
+  /** Deduplicated denial counts, classified into fixed operation categories. */
+  permissionDenialsByOperation?: Partial<Record<ConsultingDeniedOperation, number>>;
+  /** Denied file operations targeting outside approved roots; not a claim about denial cause. */
+  deniedFileAccessOutsideReadRoots?: number;
+  /** Distinct requested file targets extracted from correlated structured tool parameters. */
+  deniedResources?: readonly ConsultingFileResource[];
+  /** File-denial observations whose known targets were omitted because the list is full. */
+  deniedResourcesOmitted?: number;
+  /** Known file-denial observations without an available, bounded structured target. */
+  deniedResourcePathsUnavailable?: number;
+  /** Requested file targets of calls without a terminal outcome; not attributed to denials. */
+  unfinishedResources?: readonly ConsultingFileResource[];
+  /** Unfinished file observations omitted because their target list is full. */
+  unfinishedResourcesOmitted?: number;
+  /** Unfinished file observations lacking a usable structured target. */
+  unfinishedResourcePathsUnavailable?: number;
   eventCount?: number;
   terminalSeen?: boolean;
   terminalSucceeded?: boolean;
@@ -40,7 +83,7 @@ export interface ConsultingFailureDiagnostics {
 export type ConsultingAgentFailureKind = keyof typeof FAILURE_MESSAGES;
 
 /**
- * A bounded failure with fixed messages and safe execution facts, but no raw cause.
+ * A bounded failure with fixed reason text and extracted execution metadata, but no raw cause.
  * Permission denials are observations, not a claim about the cause of failure.
  */
 export class ConsultingAgentError extends Error {
@@ -55,22 +98,160 @@ export class ConsultingAgentError extends Error {
     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
+    const diagnostics: ConsultingFailureDiagnostics | undefined = facts
       ? {
           permissionDenials: facts.permissionDenials,
+          ...(facts.permissionDenialsByOperation
+            ? {
+                permissionDenialsByOperation: sanitizeOperationCounts(
+                  facts.permissionDenialsByOperation,
+                ),
+              }
+            : {}),
+          ...(facts.deniedFileAccessOutsideReadRoots === undefined
+            ? {}
+            : { deniedFileAccessOutsideReadRoots: facts.deniedFileAccessOutsideReadRoots }),
+          ...(facts.deniedResources
+            ? { deniedResources: sanitizeFileResources(facts.deniedResources) }
+            : {}),
+          deniedResourcesOmitted: facts.deniedResourcesOmitted,
+          deniedResourcePathsUnavailable: facts.deniedResourcePathsUnavailable,
+          ...(facts.unfinishedResources
+            ? { unfinishedResources: sanitizeFileResources(facts.unfinishedResources) }
+            : {}),
+          unfinishedResourcesOmitted: facts.unfinishedResourcesOmitted,
+          unfinishedResourcePathsUnavailable: facts.unfinishedResourcePathsUnavailable,
           eventCount: facts.eventCount,
           terminalSeen: facts.terminalSeen,
           terminalSucceeded: facts.terminalSucceeded,
           exitCode: facts.exitCode,
         }
       : undefined;
+    super(`${message}${formatFailureContext(diagnostics)}`);
+    this.name = "ConsultingAgentError";
+    this.kind = kind;
+    this.reason = options.reason;
+    this.diagnostics = diagnostics;
+  }
+}
+
+function sanitizeFileResources(
+  resources: readonly ConsultingFileResource[],
+): ConsultingFileResource[] {
+  return resources
+    .slice(0, MAX_FAILURE_RESOURCES)
+    .flatMap((resource) =>
+      (resource.operation === "file-read" || resource.operation === "file-write") &&
+      typeof resource.requestedPath === "string" &&
+      resource.requestedPath.length > 0 &&
+      resource.requestedPath.length <= MAX_FAILURE_RESOURCE_PATH_CHARS
+        ? [{ operation: resource.operation, requestedPath: resource.requestedPath }]
+        : [],
+    );
+}
+
+function sanitizeOperationCounts(
+  counts: Partial<Record<ConsultingDeniedOperation, number>>,
+): Partial<Record<ConsultingDeniedOperation, number>> {
+  const result: Partial<Record<ConsultingDeniedOperation, number>> = {};
+  for (const operation of DENIED_OPERATIONS) {
+    const count = counts[operation];
+    if (typeof count === "number" && Number.isSafeInteger(count) && count > 0) {
+      result[operation] = count;
+    }
+  }
+  return result;
+}
+
+function formatFailureContext(facts: ConsultingFailureDiagnostics | undefined): string {
+  if (!facts) return "";
+  const parts: string[] = [];
+  if (facts.terminalSeen !== undefined) {
+    const status = facts.terminalSeen
+      ? facts.terminalSucceeded
+        ? "success"
+        : "unsuccessful"
+      : "not observed";
+    parts.push(`Agent terminal status: ${status}.`);
+  }
+  const denial = formatPermissionDenials(facts);
+  if (denial) parts.push(denial);
+  const unfinished = formatUnfinishedResources(facts);
+  if (unfinished) parts.push(unfinished);
+  return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+
+function formatPermissionDenials(facts: ConsultingFailureDiagnostics): string {
+  if ((facts.permissionDenials ?? 0) === 0) return "";
+  const parts = [`Observed permission denials: ${facts.permissionDenials}.`];
+  const counts = Object.entries(facts.permissionDenialsByOperation ?? {});
+  if (counts.length > 0) {
+    parts.push(
+      `Permission denials by operation: ${counts.map(([operation, count]) => `${operation}=${count}`).join(", ")}.`,
+    );
+  }
+  if ((facts.deniedFileAccessOutsideReadRoots ?? 0) > 0) {
+    parts.push(
+      `Denied file access outside approved read roots: ${facts.deniedFileAccessOutsideReadRoots}.`,
+    );
+  }
+  const resources = formatDeniedResources(facts);
+  if (resources) parts.push(resources);
+  parts.push("Permission denials are observations, not proof of the failure cause.");
+  if (facts.permissionDenialsByOperation?.command) {
+    parts.push("Workspace access does not grant command execution.");
+  }
+  parts.push(
+    "Do not retry denied actions unchanged. Use permitted inspection tools and artifacts in approved read roots, or request a limited/blocked report.",
+  );
+  return parts.join(" ");
+}
+
+function quoteFileResources(resources: readonly ConsultingFileResource[]): string {
+  return JSON.stringify(resources).replace(
+    /[\u007f-\u009f\u2028\u2029]/g,
+    (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`,
+  );
+}
+
+function formatUnfinishedResources(facts: ConsultingFailureDiagnostics): string {
+  const parts: string[] = [];
+  if (facts.unfinishedResources?.length) {
+    parts.push(
+      `Requested file targets of unfinished actions: ${quoteFileResources(facts.unfinishedResources)}.`,
+    );
+  }
+  if ((facts.unfinishedResourcesOmitted ?? 0) > 0) {
+    parts.push(
+      `Additional unfinished file observations omitted: ${facts.unfinishedResourcesOmitted}.`,
+    );
+  }
+  if ((facts.unfinishedResourcePathsUnavailable ?? 0) > 0) {
+    parts.push(
+      `Unfinished file observations with unavailable structured targets: ${facts.unfinishedResourcePathsUnavailable}.`,
+    );
+  }
+  if (parts.length)
+    parts.push("Unfinished file operations have unknown outcomes; they are not confirmed denials.");
+  return parts.join(" ");
+}
+
+function formatDeniedResources(facts: ConsultingFailureDiagnostics): string {
+  const parts: string[] = [];
+  if (facts.deniedResources?.length) {
+    const targets = quoteFileResources(facts.deniedResources);
+    parts.push(`Requested file targets of denied actions: ${targets}.`);
+  }
+  if ((facts.deniedResourcesOmitted ?? 0) > 0) {
+    parts.push(
+      `Additional file-denial observations omitted from target list: ${facts.deniedResourcesOmitted}.`,
+    );
+  }
+  if ((facts.deniedResourcePathsUnavailable ?? 0) > 0) {
+    parts.push(
+      `File-denial observations with unavailable structured targets: ${facts.deniedResourcePathsUnavailable}.`,
+    );
   }
+  return parts.join(" ");
 }

package/src/agents/types.ts

@@ -25,6 +25,8 @@ export interface ConsultingAgentExecutionOptions {
   model: ConsultingModel;
   canonicalWorkingDirectory: string;
   workspaceAccess: boolean;
+  /** Canonical extra directory roots for inspection; writes and commands remain denied. */
+  additionalReadOnlyDirectories?: readonly string[];
   continuation?: string;
   signal?: AbortSignal;
   onProgress?: (activity: string) => void;

package/src/catalogue.ts

@@ -1,12 +1,12 @@
-import { StringEnum } from "@earendil-works/pi-ai";
-import type { TSchema } from "typebox";
+import { type TSchema, Type } 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[]], {
+  return Type.Enum([...catalogue] as [string, ...string[]], {
+    type: "string",
     description: "Model available in the current Consulting Agent catalogue.",
   });
 }

package/src/config.ts

@@ -1,4 +1,7 @@
-import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
+import { constants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import { isAbsolute } from "node:path";
+import { loadSupiConfig, loadSupiConfigForScope } from "@mrclrchtr/supi-core/config";
 
 /** The persisted SuPi configuration section owned by this package. */
 export const CONSULTING_CONFIG_SECTION = "consulting";
@@ -7,20 +10,73 @@ export const CONSULTING_CONFIG_SECTION = "consulting";
 export interface ConsultingConfig extends Record<string, unknown> {
   /** Enable agent availability discovery and the consulting_run tool. */
   agentToolEnabled: boolean;
+  /** Absolute directories available for inspection with either Workspace Access selection. */
+  additionalReadOnlyDirectories: readonly string[];
 }
 
 /** Default Consulting configuration. */
 export const CONSULTING_DEFAULTS: ConsultingConfig = Object.freeze({
   agentToolEnabled: true,
+  additionalReadOnlyDirectories: Object.freeze([]),
 });
 
-/** 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 });
+/** Load trusted scoped configuration; untrusted projects cannot grant external directory access. */
+export function loadConsultingConfig(
+  cwd: string,
+  homeDir?: string,
+  projectTrusted = true,
+): ConsultingConfig {
+  const raw = projectTrusted
+    ? loadSupiConfig(CONSULTING_CONFIG_SECTION, cwd, CONSULTING_DEFAULTS, { homeDir })
+    : loadSupiConfigForScope(CONSULTING_CONFIG_SECTION, cwd, CONSULTING_DEFAULTS, {
+        scope: "global",
+        homeDir,
+      });
   return {
     agentToolEnabled:
       typeof raw.agentToolEnabled === "boolean"
         ? raw.agentToolEnabled
         : CONSULTING_DEFAULTS.agentToolEnabled,
+    additionalReadOnlyDirectories: validateAdditionalReadOnlyDirectories(
+      raw.additionalReadOnlyDirectories,
+    ),
   };
 }
+
+/** Validate directory-list syntax before persistence or execution; paths are literal, not globs. */
+export function validateAdditionalReadOnlyDirectories(value: unknown): string[] {
+  if (
+    !Array.isArray(value) ||
+    value.some((path) => typeof path !== "string" || !isAbsolute(path) || path.includes("\0"))
+  ) {
+    throw new Error(
+      "consulting.additionalReadOnlyDirectories must be a list of absolute directory paths.",
+    );
+  }
+  return [...new Set(value)];
+}
+
+/** Resolve current scoped grants for each run, following directory aliases and failing before process work. */
+export async function resolveAdditionalReadOnlyDirectories(
+  cwd: string,
+  homeDir?: string,
+  projectTrusted = true,
+): Promise<string[]> {
+  const config = loadConsultingConfig(cwd, homeDir, projectTrusted);
+  const directories = await Promise.all(
+    config.additionalReadOnlyDirectories.map(async (path) => {
+      try {
+        const canonical = await realpath(path);
+        if (!(await stat(canonical)).isDirectory()) throw new Error("Not a directory.");
+        await access(canonical, constants.R_OK | constants.X_OK);
+        return canonical;
+      } catch (error) {
+        throw new Error(
+          `Consulting additional read-only directory is missing, inaccessible, or not a directory: ${path}`,
+          { cause: error },
+        );
+      }
+    }),
+  );
+  return [...new Set(directories)];
+}

package/src/runtime.ts

@@ -17,6 +17,7 @@ type FooterState = "idle" | "checking" | "ready";
 /** Context needed to report availability and update the footer. */
 export type ConsultingRefreshContext = {
   ui: Pick<ExtensionContext["ui"], "notify" | "setStatus">;
+  isProjectTrusted?: ExtensionContext["isProjectTrusted"];
 };
 
 /** Session runtime for immutable availability and Conversation Handle state. */
@@ -85,7 +86,7 @@ export class ConsultingRuntime {
     if (context) this.#statusUi = context.ui;
     this.#stopSpinner();
     this.#setFooterState("idle");
-    const config = loadConsultingConfig(cwd, this.#homeDir);
+    const config = loadConsultingConfig(cwd, this.#homeDir, context?.isProjectTrusted?.() ?? true);
     if (!config.agentToolEnabled) {
       this.#deactivateTool();
       return;
@@ -141,6 +142,7 @@ export class ConsultingRuntime {
         adapter: this.adapter,
         availability,
         handles: this.handles,
+        homeDir: this.#homeDir,
       });
       this.#toolRegistered = true;
     }

package/src/settings.ts

@@ -1,6 +1,10 @@
 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 {
+  CONSULTING_CONFIG_SECTION,
+  CONSULTING_DEFAULTS,
+  validateAdditionalReadOnlyDirectories,
+} from "./config.ts";
 import type { ConsultingRuntime } from "./runtime.ts";
 
 /** Register the Consulting setting with an awaited availability refresh. */
@@ -21,6 +25,13 @@ export function registerConsultingSettings(
         label: "Consultation tool",
         description: "Enable consulting_run and its availability checks.",
       },
+      {
+        kind: "stringList" as const,
+        key: "additionalReadOnlyDirectories",
+        label: "Additional read-only directories",
+        description:
+          "Comma-separated absolute directories for every Consultation, including without Workspace Access. No shell expansion or globs; broad paths can expose sensitive files.",
+      },
     ],
     ...(homeDir ? { homeDir } : {}),
   });
@@ -28,9 +39,17 @@ export function registerConsultingSettings(
   registerSettings(pi, {
     ...fixedSettings,
     apply: async (request) => {
+      if (request.fieldKey === "additionalReadOnlyDirectories" && request.action.kind === "set") {
+        validateAdditionalReadOnlyDirectories(
+          request.action.value
+            .split(",")
+            .map((path) => path.trim())
+            .filter(Boolean),
+        );
+      }
       const result = await fixedSettings.apply(request);
       if (request.fieldKey === "agentToolEnabled") {
-        await runtime.refresh(request.cwd, request.ctx ? { ui: request.ctx.ui } : undefined);
+        await runtime.refresh(request.cwd, request.ctx);
       }
       return result;
     },

package/src/tool/consulting_run/execute.ts

@@ -4,7 +4,9 @@ import type {
   ExtensionAPI,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import { ConsultingAgentError } from "../../agents/errors.ts";
 import type { ConsultingAgentAdapter, ConsultingAgentAvailability } from "../../agents/types.ts";
+import { resolveAdditionalReadOnlyDirectories } from "../../config.ts";
 import {
   appendHandleCreated,
   appendHandleRetired,
@@ -19,6 +21,8 @@ export interface ConsultingRunDependencies {
   adapter: ConsultingAgentAdapter;
   availability: ConsultingAgentAvailability;
   handles: ConversationHandleStore;
+  /** Override the user home for scoped configuration loading. */
+  homeDir?: string;
 }
 
 type ConsultingExecute = NonNullable<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>;
@@ -84,6 +88,11 @@ async function runNew(options: NewRunOptions): Promise<ReturnType<typeof buildCo
     model: input.new.model,
     canonicalWorkingDirectory: cwd,
     workspaceAccess,
+    additionalReadOnlyDirectories: await resolveAdditionalReadOnlyDirectories(
+      ctx.cwd,
+      dependencies.homeDir,
+      ctx.isProjectTrusted(),
+    ),
     signal,
     onProgress: progress,
     onWarning: (warning) => {
@@ -136,6 +145,11 @@ async function runContinue(
       model: record.model,
       canonicalWorkingDirectory: record.canonicalWorkingDirectory,
       workspaceAccess: record.workspaceAccess,
+      additionalReadOnlyDirectories: await resolveAdditionalReadOnlyDirectories(
+        ctx.cwd,
+        dependencies.homeDir,
+        ctx.isProjectTrusted(),
+      ),
       continuation: record.continuation,
       signal,
       onProgress: progress,
@@ -154,9 +168,19 @@ async function runContinue(
       ...(hookWarning ? { hookWarning } : {}),
     });
   } catch (error) {
-    if (processStarted) {
+    // Incompatible continuation state can never succeed, so retire it even though
+    // the adapter rejected it before any process work.
+    const incompatible =
+      error instanceof ConsultingAgentError && error.kind === "invalid-continuation";
+    if (processStarted || incompatible) {
       const retired = dependencies.handles.retire(record.handle);
-      if (retired) appendHandleRetired(dependencies.pi, retired, "Consultation follow-up failed");
+      if (retired) {
+        appendHandleRetired(
+          dependencies.pi,
+          retired,
+          incompatible ? "Incompatible continuation state" : "Consultation follow-up failed",
+        );
+      }
     }
     throw error;
   } finally {

package/src/tool/consulting_run/guidance.ts

@@ -1,3 +1,3 @@
 /** Selection guidance for the dynamically activated consulting_run tool. */
 export const toolDescription =
-  "Consult a supported external agent for focused web research, design advice, workspace analysis, or an independent second opinion. Use direct tools for repository facts that do not need external analysis. Expose the current workspace only when the Consultation needs repository evidence.";
+  "Consult an external agent for web research, design advice, workspace analysis, or an independent second opinion. Use direct tools for repository facts. Expose the current workspace only when the Consultation needs repository evidence. Configured extra read-only directories apply to either workspace selection.";

package/src/tool/consulting_run/input.ts

@@ -1,4 +1,3 @@
-import { StringEnum } from "@earendil-works/pi-ai";
 import { type TSchema, Type } from "typebox";
 import { Value } from "typebox/value";
 import { buildModelCatalogueEnum, isAvailableModel } from "../../catalogue.ts";
@@ -40,7 +39,8 @@ export function buildConsultingRunSchema(agent: string, catalogue: readonly stri
       new: Type.Optional(
         Type.Object(
           {
-            agent: StringEnum([agent], {
+            agent: Type.Enum([agent], {
+              type: "string",
               description: "The Consulting Agent that will perform this Consultation.",
             }),
             model: buildModelCatalogueEnum(catalogue),

package/src/tool/consulting_run/register.ts

@@ -12,6 +12,8 @@ export interface RegisterConsultingRunOptions {
   adapter: ConsultingAgentAdapter;
   availability: ConsultingAgentAvailability;
   handles: ConversationHandleStore;
+  /** Override the user home for scoped configuration loading. */
+  homeDir?: string;
 }
 
 /** Register consulting_run from one immutable availability snapshot. */
@@ -31,6 +33,7 @@ export function registerConsultingRunTool(options: RegisterConsultingRunOptions)
       adapter: options.adapter,
       availability: options.availability,
       handles: options.handles,
+      homeDir: options.homeDir,
     }),
   });
 }