@mrclrchtr/supi-consulting 0.0.0-stage → 8.0.1

package/src/tool/consulting_run/evidence.ts

@@ -0,0 +1,169 @@
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, normalize as normalizePath, relative, resolve } from "node:path";
+import { hashEvidence } from "../../evidence-hash.ts";
+import type {
+  ClassifiedSource,
+  ClassifiedWorkspaceEvidence,
+  ConsultationAnswer,
+  ConsultationExecutionFacts,
+} from "../../types.ts";
+
+/** Evidence split and safe warnings produced from one Consultation answer. */
+export interface ClassifiedEvidence {
+  observedSources: ClassifiedSource[];
+  claimedSources: ClassifiedSource[];
+  observedWorkspaceEvidence: ClassifiedWorkspaceEvidence[];
+  claimedWorkspaceEvidence: ClassifiedWorkspaceEvidence[];
+  warnings: string[];
+}
+
+/** Validate references, classify observed facts, and omit unsafe references. */
+export function classifyAnswerEvidence(
+  answer: ConsultationAnswer,
+  facts: Pick<ConsultationExecutionFacts, "observedSourceHashes" | "observedWorkspacePathHashes">,
+  workspaceDirectory: string,
+): ClassifiedEvidence {
+  const sources = classifySources(answer.sources, new Set(facts.observedSourceHashes));
+  const workspace = classifyWorkspaceEvidence(
+    answer.workspaceEvidence,
+    new Set(facts.observedWorkspacePathHashes),
+    workspaceDirectory,
+  );
+  return {
+    observedSources: sources.observed,
+    claimedSources: sources.claimed,
+    observedWorkspaceEvidence: workspace.observed,
+    claimedWorkspaceEvidence: workspace.claimed,
+    warnings: [...new Set([...sources.warnings, ...workspace.warnings])],
+  };
+}
+
+interface ClassifiedSourceLists {
+  observed: ClassifiedSource[];
+  claimed: ClassifiedSource[];
+  warnings: string[];
+}
+
+function classifySources(
+  sources: readonly ConsultationAnswer["sources"][number][],
+  observedHashes: ReadonlySet<string>,
+): ClassifiedSourceLists {
+  const result: ClassifiedSourceLists = { observed: [], claimed: [], warnings: [] };
+  for (const source of sources) {
+    const url = source.url.trim();
+    if (!isHttpUrl(url) || !source.title.trim()) {
+      result.warnings.push("Some source references were omitted because they were invalid.");
+      continue;
+    }
+    const classified: ClassifiedSource = {
+      title: source.title.trim(),
+      url,
+      evidence: observedHashes.has(hashEvidence(url)) ? "observed" : "claimed",
+    };
+    addClassified(result, classified);
+  }
+  return result;
+}
+
+function classifyWorkspaceEvidence(
+  evidence: readonly ConsultationAnswer["workspaceEvidence"][number][],
+  observedHashes: ReadonlySet<string>,
+  workspaceDirectory: string,
+): {
+  observed: ClassifiedWorkspaceEvidence[];
+  claimed: ClassifiedWorkspaceEvidence[];
+  warnings: string[];
+} {
+  const result = { observed: [], claimed: [], warnings: [] } as {
+    observed: ClassifiedWorkspaceEvidence[];
+    claimed: ClassifiedWorkspaceEvidence[];
+    warnings: string[];
+  };
+  for (const item of evidence) {
+    if (!isSafeWorkspacePath(item.path, workspaceDirectory) || !item.summary.trim()) {
+      result.warnings.push(
+        "Some workspace references were omitted because they were outside the selected workspace.",
+      );
+      continue;
+    }
+    const normalizedPath = normalizeWorkspacePath(item.path);
+    const classified: ClassifiedWorkspaceEvidence = {
+      path: normalizedPath,
+      summary: item.summary.trim(),
+      evidence: observedHashes.has(hashEvidence(normalizedPath)) ? "observed" : "claimed",
+    };
+    if (classified.evidence === "observed") result.observed.push(classified);
+    else result.claimed.push(classified);
+  }
+  return result;
+}
+
+function addClassified(result: ClassifiedSourceLists, source: ClassifiedSource): void {
+  if (source.evidence === "observed") result.observed.push(source);
+  else result.claimed.push(source);
+}
+
+/** Accept only HTTP and HTTPS source URLs. */
+export function isHttpUrl(value: string): boolean {
+  if (hasControlCharacters(value)) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+/** Check that a returned path is relative and contained by a workspace. */
+export function isSafeWorkspacePath(value: string, workspaceDirectory: string): boolean {
+  if (
+    !value ||
+    hasControlCharacters(value) ||
+    value.startsWith("~") ||
+    isAbsolute(value) ||
+    /^[A-Za-z]:[\\/]/.test(value)
+  ) {
+    return false;
+  }
+  const candidate = normalizeWorkspacePath(value);
+  if (candidate === "." || candidate === ".." || candidate.startsWith("../")) return false;
+  const resolvedWorkspace = safeRealpath(workspaceDirectory);
+  const resolvedCandidate = resolve(resolvedWorkspace, candidate);
+  if (!isContainedPath(resolvedWorkspace, resolvedCandidate)) return false;
+  const existingAncestor = findExistingAncestor(resolvedCandidate);
+  return isContainedPath(resolvedWorkspace, safeRealpath(existingAncestor));
+}
+
+function hasControlCharacters(value: string): boolean {
+  return [...value].some((character) => {
+    const code = character.charCodeAt(0);
+    return code < 32 || code === 127;
+  });
+}
+
+function normalizeWorkspacePath(value: string): string {
+  return normalizePath(value.replaceAll("\\", "/")).replace(/^\.\//, "");
+}
+
+function safeRealpath(value: string): string {
+  try {
+    return realpathSync(value);
+  } catch {
+    return resolve(value);
+  }
+}
+
+function findExistingAncestor(value: string): string {
+  let candidate = value;
+  while (!existsSync(candidate)) {
+    const parent = dirname(candidate);
+    if (parent === candidate) return value;
+    candidate = parent;
+  }
+  return candidate;
+}
+
+function isContainedPath(workspace: string, candidate: string): boolean {
+  const distance = relative(workspace, candidate);
+  return distance !== ".." && !distance.startsWith("../") && !isAbsolute(distance);
+}

package/src/tool/consulting_run/execute.ts

@@ -0,0 +1,201 @@
+import { realpath } from "node:fs/promises";
+import type {
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { ConsultingAgentAdapter, ConsultingAgentAvailability } from "../../agents/types.ts";
+import {
+  appendHandleCreated,
+  appendHandleRetired,
+  type ConversationHandleStore,
+} from "../../conversation/handles.ts";
+import { type ConsultingRunInput, parseConsultingRunInput } from "./input.ts";
+import { buildConsultationResult } from "./result.ts";
+
+/** Dependencies captured by one dynamically registered consulting_run tool. */
+export interface ConsultingRunDependencies {
+  pi: ExtensionAPI;
+  adapter: ConsultingAgentAdapter;
+  availability: ConsultingAgentAvailability;
+  handles: ConversationHandleStore;
+}
+
+type ConsultingExecute = NonNullable<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>;
+
+/** Build the execute function for one immutable agent availability snapshot. */
+export function makeConsultingRunExecute(
+  dependencies: ConsultingRunDependencies,
+): ConsultingExecute {
+  // biome-ignore lint/complexity/useMaxParams: Pi execute contract requires five parameters.
+  return async (_toolCallId, params, signal, onUpdate, ctx) => {
+    const input = parseConsultingRunInput(
+      params,
+      dependencies.availability.agent,
+      dependencies.availability.catalogue,
+    );
+    const startedAt = Date.now();
+    if (input.new) {
+      return runNew({ input, dependencies, signal, onUpdate, ctx, startedAt });
+    }
+    if (!input.continue) throw new Error("consulting_run requires exactly one of new or continue.");
+    return runContinue({
+      continuation: input.continue,
+      prompt: input.prompt,
+      dependencies,
+      signal,
+      onUpdate,
+      ctx,
+      startedAt,
+    });
+  };
+}
+
+interface CommonRunOptions {
+  dependencies: ConsultingRunDependencies;
+  signal: AbortSignal | undefined;
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined;
+  ctx: ExtensionContext;
+  startedAt: number;
+}
+
+interface NewRunOptions extends CommonRunOptions {
+  input: Extract<ConsultingRunInput, { new: object }>;
+}
+
+async function runNew(options: NewRunOptions): Promise<ReturnType<typeof buildConsultationResult>> {
+  const { input, dependencies, signal, onUpdate, ctx, startedAt } = options;
+  const workspaceAccess = input.new.workspace;
+  const cwd = await resolveWorkingDirectory(
+    workspaceAccess,
+    ctx.cwd,
+    dependencies.adapter.consultationWorkspace,
+  );
+  const progress = createProgressReporter(
+    onUpdate,
+    dependencies.adapter.identity,
+    input.new.model,
+    workspaceAccess,
+  );
+  progress("starting Consultation");
+  let hookWarning: string | undefined;
+  const facts = await dependencies.adapter.execute({
+    prompt: input.prompt,
+    model: input.new.model,
+    canonicalWorkingDirectory: cwd,
+    workspaceAccess,
+    signal,
+    onProgress: progress,
+    onWarning: (warning) => {
+      hookWarning = warning;
+      notifyWarning(ctx, warning);
+    },
+  });
+  const record = dependencies.handles.create({
+    agent: dependencies.adapter.identity,
+    model: input.new.model,
+    continuation: facts.continuation,
+    canonicalWorkingDirectory: cwd,
+    workspaceAccess,
+    agentVersion: dependencies.availability.agentVersion,
+  });
+  appendHandleCreated(dependencies.pi, record);
+  return buildConsultationResult({
+    facts,
+    handle: record,
+    durationMs: Date.now() - startedAt,
+    ...(hookWarning ? { hookWarning } : {}),
+  });
+}
+
+interface ContinueRunOptions extends CommonRunOptions {
+  continuation: Extract<ConsultingRunInput, { continue: object }>["continue"];
+  prompt: string;
+}
+
+async function runContinue(
+  options: ContinueRunOptions,
+): Promise<ReturnType<typeof buildConsultationResult>> {
+  const { continuation, prompt, dependencies, signal, onUpdate, ctx, startedAt } = options;
+  const record = dependencies.handles.acquire(continuation.handle, dependencies.adapter.identity);
+  let processStarted = false;
+  try {
+    if (!dependencies.availability.catalogue.includes(record.model)) {
+      throw new Error("The Conversation Handle model is not available in the current catalogue.");
+    }
+    const progress = createProgressReporter(
+      onUpdate,
+      record.agent,
+      record.model,
+      record.workspaceAccess,
+    );
+    progress("starting Consultation follow-up");
+    let hookWarning: string | undefined;
+    const facts = await dependencies.adapter.execute({
+      prompt,
+      model: record.model,
+      canonicalWorkingDirectory: record.canonicalWorkingDirectory,
+      workspaceAccess: record.workspaceAccess,
+      continuation: record.continuation,
+      signal,
+      onProgress: progress,
+      onWarning: (warning) => {
+        hookWarning = warning;
+        notifyWarning(ctx, warning);
+      },
+      onProcessStart: () => {
+        processStarted = true;
+      },
+    });
+    return buildConsultationResult({
+      facts,
+      handle: record,
+      durationMs: Date.now() - startedAt,
+      ...(hookWarning ? { hookWarning } : {}),
+    });
+  } catch (error) {
+    if (processStarted) {
+      const retired = dependencies.handles.retire(record.handle);
+      if (retired) appendHandleRetired(dependencies.pi, retired, "Consultation follow-up failed");
+    }
+    throw error;
+  } finally {
+    dependencies.handles.release(record.handle);
+  }
+}
+
+async function resolveWorkingDirectory(
+  workspaceAccess: boolean,
+  currentDirectory: string,
+  consultationWorkspace: string,
+): Promise<string> {
+  return realpath(workspaceAccess ? currentDirectory : consultationWorkspace);
+}
+
+function createProgressReporter(
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+  agent: string,
+  model: string,
+  workspaceAccess: boolean,
+): (activity: string) => void {
+  return (activity: string) => {
+    onUpdate?.({
+      content: [{ type: "text", text: "Consulting is working…" }],
+      details: {
+        agent,
+        model,
+        workingDirectoryKind: workspaceAccess ? "workspace" : "consultation",
+        workspaceAccess,
+        latestActivity: activity,
+      },
+    });
+  };
+}
+
+function notifyWarning(ctx: ExtensionContext, warning: string): void {
+  try {
+    ctx.ui.notify(warning, "warning");
+  } catch {
+    // A closed UI must not change Consultation execution or handle state.
+  }
+}

package/src/tool/consulting_run/guidance.ts

@@ -0,0 +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.";

package/src/tool/consulting_run/input.ts

@@ -0,0 +1,117 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type TSchema, Type } from "typebox";
+import { Value } from "typebox/value";
+import { buildModelCatalogueEnum, isAvailableModel } from "../../catalogue.ts";
+import type { ConsultingModel } from "../../types.ts";
+
+const MAX_PROMPT_CHARS = 32_000;
+const MAX_HANDLE_CHARS = 128;
+
+/** Input for a new Consultation. */
+export interface NewConsultationInput {
+  agent: string;
+  model: ConsultingModel;
+  workspace: boolean;
+}
+
+/** Input for a Conversation Handle follow-up. */
+export interface ContinueConsultationInput {
+  handle: string;
+}
+
+/** Exact-one consulting_run input contract. */
+export type ConsultingRunInput =
+  | { prompt: string; new: NewConsultationInput; continue?: never }
+  | { prompt: string; new?: never; continue: ContinueConsultationInput };
+
+/** Build the dynamic tool schema from one immutable agent and model snapshot. */
+export function buildConsultingRunSchema(agent: string, catalogue: readonly string[]): TSchema {
+  if (!agent || catalogue.length === 0) {
+    throw new Error("Cannot register consulting_run without an available agent and model.");
+  }
+  const prompt = Type.String({
+    minLength: 1,
+    maxLength: MAX_PROMPT_CHARS,
+    description: "The bounded request for one Consultation.",
+  });
+  return Type.Object(
+    {
+      prompt,
+      new: Type.Optional(
+        Type.Object(
+          {
+            agent: StringEnum([agent], {
+              description: "The Consulting Agent that will perform this Consultation.",
+            }),
+            model: buildModelCatalogueEnum(catalogue),
+            workspace: Type.Boolean({
+              description:
+                "true exposes the current PI workspace; false uses the empty Consultation Workspace.",
+            }),
+          },
+          { additionalProperties: false },
+        ),
+      ),
+      continue: Type.Optional(
+        Type.Object(
+          {
+            handle: Type.String({
+              minLength: 1,
+              maxLength: MAX_HANDLE_CHARS,
+              description: "Conversation Handle returned by consulting_run.",
+            }),
+          },
+          {
+            additionalProperties: false,
+            description: "Continue the existing Consultation with its original selection.",
+          },
+        ),
+      ),
+    },
+    {
+      minProperties: 2,
+      maxProperties: 2,
+      additionalProperties: false,
+    },
+  );
+}
+
+/** Validate exact-one input against the immutable availability snapshot. */
+export function parseConsultingRunInput(
+  value: unknown,
+  agent: string,
+  catalogue: readonly string[],
+): ConsultingRunInput {
+  if (!isRecord(value)) throw new Error("Invalid consulting_run input.");
+  const hasNew = Object.hasOwn(value, "new");
+  const hasContinue = Object.hasOwn(value, "continue");
+  if (hasNew === hasContinue) {
+    throw new Error("consulting_run requires exactly one of new or continue.");
+  }
+  const schema = buildConsultingRunSchema(agent, catalogue);
+  if (!Value.Check(schema, value)) throw new Error("Invalid consulting_run input.");
+  const newInput = isRecord(value.new) ? value.new : undefined;
+  const continueInput = isRecord(value.continue) ? value.continue : undefined;
+  if (newInput) {
+    if (newInput.agent !== agent) throw new Error("The selected Consulting Agent is unavailable.");
+    if (typeof newInput.workspace !== "boolean" || !isAvailableModel(newInput.model, catalogue)) {
+      throw new Error("The selected model is not available in the Consulting Agent catalogue.");
+    }
+    return {
+      prompt: value.prompt as string,
+      new: {
+        agent: newInput.agent,
+        model: newInput.model,
+        workspace: newInput.workspace,
+      },
+    };
+  }
+  if (!continueInput || typeof continueInput.handle !== "string") {
+    throw new Error("Invalid Conversation Handle.");
+  }
+  return { prompt: value.prompt as string, continue: { handle: continueInput.handle } };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tool/consulting_run/register.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ConsultingAgentAdapter, ConsultingAgentAvailability } from "../../agents/types.ts";
+import type { ConversationHandleStore } from "../../conversation/handles.ts";
+import { makeConsultingRunExecute } from "./execute.ts";
+import { toolDescription } from "./guidance.ts";
+import { renderConsultingCall, renderConsultingResult } from "./render.ts";
+import { buildConsultingRunParameters, consultingRunSpec } from "./spec.ts";
+
+/** Dependencies needed by the dynamically registered tool. */
+export interface RegisterConsultingRunOptions {
+  pi: ExtensionAPI;
+  adapter: ConsultingAgentAdapter;
+  availability: ConsultingAgentAvailability;
+  handles: ConversationHandleStore;
+}
+
+/** Register consulting_run from one immutable availability snapshot. */
+export function registerConsultingRunTool(options: RegisterConsultingRunOptions): void {
+  const parameters = buildConsultingRunParameters(
+    options.availability.agent,
+    options.availability.catalogue,
+  );
+  options.pi.registerTool({
+    ...consultingRunSpec,
+    description: toolDescription,
+    parameters,
+    renderCall: renderConsultingCall,
+    renderResult: renderConsultingResult,
+    execute: makeConsultingRunExecute({
+      pi: options.pi,
+      adapter: options.adapter,
+      availability: options.availability,
+      handles: options.handles,
+    }),
+  });
+}