@mrclrchtr/supi-consulting 0.0.0-stage → 8.0.1

package/src/tool/consulting_run/render.ts

@@ -0,0 +1,261 @@
+/** Compact TUI renderers for Consultation calls and results. */
+import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
+import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import type {
+  ClassifiedSource,
+  ClassifiedWorkspaceEvidence,
+  ConsultationActivity,
+  ConsultationResultDetails,
+} from "../../types.ts";
+import { CONSULTING_RUN_TOOL_LABEL } from "./spec.ts";
+
+const MAX_PROMPT_PREVIEW = 120;
+const MAX_ERROR_PREVIEW = 500;
+
+/** Render the tool label, safe prompt preview, selected agent, model, and workspace. */
+export function renderConsultingCall(args: unknown, theme: Theme, _context?: unknown): Text {
+  const params = isRecord(args) ? args : {};
+  const prompt = typeof params.prompt === "string" ? safePreview(params.prompt) : undefined;
+  const newInput = isRecord(params.new) ? params.new : undefined;
+  const agent = typeof newInput?.agent === "string" ? newInput.agent : undefined;
+  const model = typeof newInput?.model === "string" ? newInput.model : undefined;
+  const workspace = typeof newInput?.workspace === "boolean" ? newInput.workspace : undefined;
+  const continuation = isRecord(params.continue);
+  const parts = [
+    theme.fg("toolTitle", CONSULTING_RUN_TOOL_LABEL),
+    agent ? theme.fg("accent", agent) : undefined,
+    model ? theme.fg("accent", model) : continuation ? theme.fg("accent", "follow-up") : undefined,
+    workspace === undefined
+      ? undefined
+      : theme.fg("dim", workspace ? "workspace" : "Consultation Workspace"),
+    prompt ? theme.fg("dim", `· ${prompt}`) : undefined,
+  ].filter((part): part is string => part !== undefined);
+  return new Text(parts.join(" "), 0, 0);
+}
+
+/** Render partial, collapsed, expanded, and error Consultation states. */
+export function renderConsultingResult(
+  result: {
+    content?: Array<{ type: string; text?: string }>;
+    details?: unknown;
+    isError?: boolean;
+  },
+  options: { expanded: boolean; isPartial: boolean },
+  theme: Theme,
+  context: { isError?: boolean } = {},
+): Container | Text {
+  if (options.isPartial) return renderPartial(result.details, options.expanded, theme);
+  if (result.isError || context.isError)
+    return renderError(result.content, options.expanded, theme);
+  const details = asDetails(result.details);
+  if (!details) return new Text(theme.fg("dim", "Consultation finished."), 0, 0);
+  return options.expanded
+    ? renderExpanded(details, result.content, theme)
+    : renderCollapsed(details, theme);
+}
+
+function renderPartial(detailsValue: unknown, expanded: boolean, theme: Theme): Text | Container {
+  const details = isRecord(detailsValue) ? detailsValue : {};
+  const model = typeof details.model === "string" ? details.model : "model pending";
+  const agent = typeof details.agent === "string" ? details.agent : "agent pending";
+  const workspace = details.workspaceAccess === true ? "workspace" : "Consultation Workspace";
+  const activity =
+    typeof details.latestActivity === "string" ? safePreview(details.latestActivity) : "preparing";
+  const line = theme.fg(
+    "warning",
+    `● ${CONSULTING_RUN_TOOL_LABEL} · ${agent} · ${model} · ${workspace}`,
+  );
+  if (!expanded) return new Text(`${line}\n${theme.fg("dim", activity)}`, 0, 0);
+  const container = new Container();
+  container.addChild(new Text(line, 0, 0));
+  container.addChild(new Text(theme.fg("dim", `activity: ${activity}`), 1, 0));
+  return container;
+}
+
+function renderCollapsed(details: ConsultationResultDetails, theme: Theme): Text {
+  const usage = formatUsage(details.usage);
+  const evidence = [
+    `${details.observedSources.length} observed source${details.observedSources.length === 1 ? "" : "s"}`,
+    `${details.observedWorkspaceEvidence.length} observed path${details.observedWorkspaceEvidence.length === 1 ? "" : "s"}`,
+  ];
+  if (usage) evidence.push(usage);
+  const warning = details.warnings.length > 0 ? ` · ${details.warnings.length} warning(s)` : "";
+  return new Text(
+    `${theme.fg("success", "✓ Consultation complete")} · ${details.agent} · ${details.handle} · ${evidence.join(" · ")}${warning}`,
+    0,
+    0,
+  );
+}
+
+function renderExpanded(
+  details: ConsultationResultDetails,
+  content: Array<{ type: string; text?: string }> | undefined,
+  theme: Theme,
+): Container {
+  const container = new Container();
+  container.addChild(
+    new Text(
+      theme.fg(
+        "accent",
+        `${theme.bold("Consultation complete")} · ${details.agent} · ${details.model} · ${details.workingDirectoryKind}`,
+      ),
+      0,
+      0,
+    ),
+  );
+  container.addChild(new Text(theme.fg("dim", `handle: ${details.handle}`), 1, 0));
+  container.addChild(
+    new Text(
+      theme.fg(
+        "dim",
+        `Agent version: ${details.agentVersion} · ${formatUsage(details.usage) || "usage unavailable"}`,
+      ),
+      1,
+      0,
+    ),
+  );
+  container.addChild(
+    new Text(
+      theme.fg(
+        "dim",
+        `web: ${details.webUsed ? "used" : "not used"} · workspace: ${details.workspaceUsed ? "used" : "not used"} · project guidance: ${details.ambientProjectGuidanceAvailable ? "available" : "not available"}`,
+      ),
+      1,
+      0,
+    ),
+  );
+  renderSources(container, "Observed sources", details.observedSources, theme);
+  renderSources(container, "Claimed sources", details.claimedSources, theme);
+  renderWorkspace(container, "Observed workspace paths", details.observedWorkspaceEvidence, theme);
+  renderWorkspace(container, "Claimed workspace paths", details.claimedWorkspaceEvidence, theme);
+  if (details.warnings.length > 0) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Text(theme.fg("warning", "Warnings"), 1, 0));
+    for (const warning of details.warnings)
+      container.addChild(new Text(theme.fg("dim", `- ${warning}`), 1, 0));
+  }
+  const markdown = content?.find((item) => item.type === "text")?.text;
+  if (markdown) {
+    container.addChild(new Spacer(1));
+    container.addChild(new Markdown(markdown, 1, 0, getMarkdownTheme()));
+  }
+  return container;
+}
+
+function renderSources(
+  container: Container,
+  title: string,
+  sources: readonly ClassifiedSource[],
+  theme: Theme,
+): void {
+  if (sources.length === 0) return;
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(theme.fg("muted", title), 1, 0));
+  for (const source of sources) {
+    container.addChild(
+      new Text(theme.fg("dim", `- ${safePreview(source.title)}: ${source.url}`), 2, 0),
+    );
+  }
+}
+
+function renderWorkspace(
+  container: Container,
+  title: string,
+  evidence: readonly ClassifiedWorkspaceEvidence[],
+  theme: Theme,
+): void {
+  if (evidence.length === 0) return;
+  container.addChild(new Spacer(1));
+  container.addChild(new Text(theme.fg("muted", title), 1, 0));
+  for (const item of evidence) {
+    container.addChild(
+      new Text(theme.fg("dim", `- ${item.path}: ${safePreview(item.summary)}`), 2, 0),
+    );
+  }
+}
+
+function renderError(
+  content: Array<{ type: string; text?: string }> | undefined,
+  expanded: boolean,
+  theme: Theme,
+): Text {
+  const text = content?.find((item) => item.type === "text")?.text;
+  const message = text ? safePreview(text, expanded ? MAX_ERROR_PREVIEW : 160) : "operation failed";
+  return new Text(theme.fg("error", `Consultation failed: ${message}`), 0, 0);
+}
+
+function asDetails(value: unknown): ConsultationResultDetails | undefined {
+  if (!isRecord(value)) return undefined;
+  if (
+    typeof value.agent !== "string" ||
+    typeof value.model !== "string" ||
+    typeof value.agentVersion !== "string" ||
+    typeof value.handle !== "string" ||
+    typeof value.continuation !== "string" ||
+    (value.workingDirectoryKind !== "workspace" && value.workingDirectoryKind !== "consultation") ||
+    !Array.isArray(value.observedActivities) ||
+    !value.observedActivities.every(isConsultationActivity) ||
+    !isActivityCounts(value.activityCounts) ||
+    !Array.isArray(value.observedSources) ||
+    !Array.isArray(value.claimedSources) ||
+    !Array.isArray(value.observedWorkspaceEvidence) ||
+    !Array.isArray(value.claimedWorkspaceEvidence) ||
+    !Array.isArray(value.warnings) ||
+    !value.observedSources.every(isClassifiedSource) ||
+    !value.claimedSources.every(isClassifiedSource) ||
+    !value.observedWorkspaceEvidence.every(isClassifiedWorkspaceEvidence) ||
+    !value.claimedWorkspaceEvidence.every(isClassifiedWorkspaceEvidence) ||
+    !value.warnings.every((warning) => typeof warning === "string")
+  ) {
+    return undefined;
+  }
+  return value as unknown as ConsultationResultDetails;
+}
+
+function formatUsage(
+  usage: { totalTokens?: number; inputTokens?: number; outputTokens?: number } | undefined,
+): string {
+  if (!usage) return "";
+  const total = usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
+  return `${total.toLocaleString("en-US")} tokens`;
+}
+
+function isClassifiedSource(value: unknown): value is ClassifiedSource {
+  return (
+    isRecord(value) &&
+    typeof value.title === "string" &&
+    typeof value.url === "string" &&
+    (value.evidence === "observed" || value.evidence === "claimed")
+  );
+}
+
+function isClassifiedWorkspaceEvidence(value: unknown): value is ClassifiedWorkspaceEvidence {
+  return (
+    isRecord(value) &&
+    typeof value.path === "string" &&
+    typeof value.summary === "string" &&
+    (value.evidence === "observed" || value.evidence === "claimed")
+  );
+}
+
+function isConsultationActivity(value: unknown): value is ConsultationActivity {
+  return value === "web" || value === "workspace" || value === "other";
+}
+
+function isActivityCounts(value: unknown): value is Record<ConsultationActivity, number> {
+  return (
+    isRecord(value) &&
+    ["web", "workspace", "other"].every(
+      (key) => typeof value[key] === "number" && Number.isFinite(value[key]),
+    )
+  );
+}
+
+function safePreview(value: string, maxLength = MAX_PROMPT_PREVIEW): string {
+  const normalized = value.replace(/\s+/g, " ").trim();
+  return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 1)}…`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/tool/consulting_run/result.ts

@@ -0,0 +1,185 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+import type {
+  ClassifiedSource,
+  ClassifiedWorkspaceEvidence,
+  ConsultationExecutionFacts,
+  ConsultationResultDetails,
+  ConversationHandleRecord,
+} from "../../types.ts";
+import { classifyAnswerEvidence } from "./evidence.ts";
+
+/** PI's hard result bounds for model-visible Consultation output. */
+export const MAX_RESULT_BYTES = 50 * 1024;
+export const MAX_RESULT_LINES = 2_000;
+
+/** Inputs needed to assemble one completed Consultation result. */
+export interface ConsultationResultOptions {
+  facts: ConsultationExecutionFacts;
+  handle: ConversationHandleRecord;
+  durationMs: number;
+  hookWarning?: string;
+}
+
+/** Assemble model-visible evidence and free structured renderer details. */
+export function buildConsultationResult(
+  options: ConsultationResultOptions,
+): AgentToolResult<ConsultationResultDetails> {
+  const { facts, handle } = options;
+  const evidence = classifyAnswerEvidence(facts.answer, facts, handle.canonicalWorkingDirectory);
+  const warnings = buildWarnings({
+    agentWarnings: facts.warnings,
+    evidenceWarnings: evidence.warnings,
+    observedSourceCount: evidence.observedSources.length,
+    observedWorkspaceEvidenceCount: evidence.observedWorkspaceEvidence.length,
+    webUsed: facts.webUsed,
+    workspaceUsed: facts.workspaceUsed,
+    permissionDenials: facts.permissionDenials,
+    hookWarning: options.hookWarning,
+  });
+  const details: ConsultationResultDetails = {
+    agent: handle.agent,
+    model: handle.model,
+    workingDirectoryKind: handle.workspaceAccess ? "workspace" : "consultation",
+    canonicalWorkingDirectory: handle.canonicalWorkingDirectory,
+    workspaceAccess: handle.workspaceAccess,
+    agentVersion: handle.agentVersion,
+    durationMs: Math.max(0, Math.floor(options.durationMs)),
+    ...(facts.usage ? { usage: facts.usage } : {}),
+    observedActivities: facts.observedActivities,
+    activityCounts: facts.activityCounts,
+    permissionDenials: facts.permissionDenials,
+    webUsed: facts.webUsed,
+    workspaceUsed: facts.workspaceUsed,
+    ambientProjectGuidanceAvailable: handle.workspaceAccess,
+    ...(options.hookWarning ? { activeProjectHookWarning: options.hookWarning } : {}),
+    handle: handle.handle,
+    continuation: handle.continuation,
+    handleState: "active",
+    observedSources: evidence.observedSources,
+    claimedSources: evidence.claimedSources,
+    observedWorkspaceEvidence: evidence.observedWorkspaceEvidence,
+    claimedWorkspaceEvidence: evidence.claimedWorkspaceEvidence,
+    warnings,
+  };
+  const text = formatModelResult(facts.answer.answer, details);
+  return {
+    content: [{ type: "text", text }],
+    details,
+    ...(facts.usage ? { usage: toPiUsage(facts.usage) } : {}),
+  };
+}
+
+function formatModelResult(answer: string, details: ConsultationResultDetails): string {
+  const sections = [
+    answer.trim(),
+    "",
+    `Web Capability: ${details.webUsed ? "used" : "not used"}`,
+    `Workspace Access: ${details.workspaceAccess ? "current workspace" : "Consultation Workspace"}`,
+    `Ambient Project Guidance: ${details.ambientProjectGuidanceAvailable ? "available" : "not available"}`,
+    formatSources("Observed Sources", details.observedSources),
+    formatSources("Claimed Sources (not observed)", details.claimedSources),
+    formatWorkspace("Observed Workspace Evidence", details.observedWorkspaceEvidence),
+    formatWorkspace("Claimed Workspace Evidence (not observed)", details.claimedWorkspaceEvidence),
+    formatWarnings(details.warnings),
+    `Conversation Handle: ${details.handle}`,
+  ];
+  return boundResult(sections.filter((section) => section.length > 0).join("\n"));
+}
+
+function formatSources(title: string, sources: readonly ClassifiedSource[]): string {
+  if (sources.length === 0) return `${title}: none`;
+  return [
+    title,
+    ...sources.map((source) => `- [${safeMarkdown(source.title)}](${source.url})`),
+  ].join("\n");
+}
+
+function formatWorkspace(title: string, evidence: readonly ClassifiedWorkspaceEvidence[]): string {
+  if (evidence.length === 0) return `${title}: none`;
+  return [title, ...evidence.map((item) => `- ${item.path}: ${safeMarkdown(item.summary)}`)].join(
+    "\n",
+  );
+}
+
+function formatWarnings(warnings: readonly string[]): string {
+  return warnings.length > 0
+    ? ["Warnings", ...warnings.map((warning) => `- ${warning}`)].join("\n")
+    : "Warnings: none";
+}
+
+function buildWarnings(options: {
+  agentWarnings: readonly string[];
+  evidenceWarnings: readonly string[];
+  observedSourceCount: number;
+  observedWorkspaceEvidenceCount: number;
+  webUsed: boolean;
+  workspaceUsed: boolean;
+  permissionDenials: number;
+  hookWarning?: string;
+}): string[] {
+  const warnings = [...options.agentWarnings, ...options.evidenceWarnings];
+  if (options.hookWarning) warnings.push(options.hookWarning);
+  if (options.permissionDenials > 0) {
+    warnings.push(
+      `${options.permissionDenials} agent action(s) were denied by its permission policy.`,
+    );
+  }
+  if (options.webUsed && options.observedSourceCount === 0) {
+    warnings.push("The agent used web capability, but no source URL was observed in the answer.");
+  }
+  if (options.workspaceUsed && options.observedWorkspaceEvidenceCount === 0) {
+    warnings.push(
+      "The agent used workspace access, but no workspace path was observed in the answer.",
+    );
+  }
+  return [...new Set(warnings)].slice(0, 24);
+}
+
+function boundResult(value: string): string {
+  const lines = value.split(/\r?\n/);
+  const result = lines.slice(0, MAX_RESULT_LINES).join("\n");
+  const truncated =
+    lines.length > MAX_RESULT_LINES || Buffer.byteLength(result, "utf8") > MAX_RESULT_BYTES;
+  if (!truncated) return result;
+
+  const marker = "[Consultation result truncated to PI limits]";
+  const markerBytes = Buffer.byteLength(marker, "utf8") + 1;
+  const contentLimit = Math.max(0, MAX_RESULT_BYTES - markerBytes);
+  const contentLines = result.split(/\r?\n/).slice(0, MAX_RESULT_LINES - 1);
+  const content = truncateUtf8(contentLines.join("\n"), contentLimit);
+  return content ? `${content}\n${marker}` : marker;
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  let bytes = 0;
+  let result = "";
+  for (const character of value) {
+    const characterBytes = Buffer.byteLength(character, "utf8");
+    if (bytes + characterBytes > maxBytes) break;
+    result += character;
+    bytes += characterBytes;
+  }
+  return result;
+}
+
+function safeMarkdown(value: string): string {
+  return value
+    .replaceAll("[", "\\[")
+    .replaceAll("]", "\\]")
+    .replace(/[\r\n]/g, " ");
+}
+
+function toPiUsage(usage: NonNullable<ConsultationExecutionFacts["usage"]>): Usage {
+  const input = usage.inputTokens ?? 0;
+  const output = usage.outputTokens ?? 0;
+  const totalTokens = usage.totalTokens ?? input + output;
+  return {
+    input,
+    output,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}

package/src/tool/consulting_run/spec.ts

@@ -0,0 +1,20 @@
+import type { TSchema } from "typebox";
+import { buildConsultingRunSchema } from "./input.ts";
+
+/** Canonical Consulting tool name. */
+export const CONSULTING_RUN_TOOL_NAME = "consulting_run";
+/** Human-facing tool label. */
+export const CONSULTING_RUN_TOOL_LABEL = "Consultation";
+
+/** Build provider-facing parameters from one immutable availability snapshot. */
+export function buildConsultingRunParameters(agent: string, catalogue: readonly string[]): TSchema {
+  return buildConsultingRunSchema(agent, catalogue);
+}
+
+/** Canonical machine-readable metadata for consulting_run. */
+export const consultingRunSpec = {
+  name: CONSULTING_RUN_TOOL_NAME,
+  label: CONSULTING_RUN_TOOL_LABEL,
+  exposure: "model-only",
+  executionMode: "parallel",
+} as const;

package/src/types.ts

@@ -0,0 +1,104 @@
+/** Identity of a supported Consulting Agent. */
+export type ConsultingAgentId = string;
+
+/** Agent-specific model identifier retained as a neutral string. */
+export type ConsultingModel = string;
+
+/** Caller choice to expose the current PI workspace to a Consultation. */
+export type WorkspaceAccess = boolean;
+
+/** An answer source returned by a Consulting Agent. */
+export interface ConsultationSource {
+  title: string;
+  url: string;
+}
+
+/** Workspace evidence returned by a Consulting Agent. */
+export interface ConsultationWorkspaceEvidence {
+  path: string;
+  summary: string;
+}
+
+/** The structured answer required from a Consulting Agent. */
+export interface ConsultationAnswer {
+  answer: string;
+  sources: ConsultationSource[];
+  workspaceEvidence: ConsultationWorkspaceEvidence[];
+}
+
+/** Token accounting returned by a Consulting Agent. */
+export interface ConsultationUsage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+}
+
+/** A validated source classified by observed execution evidence. */
+export interface ClassifiedSource extends ConsultationSource {
+  evidence: "observed" | "claimed";
+}
+
+/** A validated workspace reference classified by observed execution evidence. */
+export interface ClassifiedWorkspaceEvidence extends ConsultationWorkspaceEvidence {
+  evidence: "observed" | "claimed";
+}
+
+/** Normalized activity categories reported by a Consulting Agent adapter. */
+export type ConsultationActivity = "web" | "workspace" | "other";
+
+/** Bounded, protocol-neutral facts from one completed Consultation. */
+export interface ConsultationExecutionFacts {
+  answer: ConsultationAnswer;
+  continuation: string;
+  usage?: ConsultationUsage;
+  observedActivities: ConsultationActivity[];
+  activityCounts: Record<ConsultationActivity, number>;
+  webUsed: boolean;
+  workspaceUsed: boolean;
+  permissionDenials: number;
+  observedSourceHashes: string[];
+  observedWorkspacePathHashes: string[];
+  warnings: string[];
+}
+
+/** Branch-aware state retained for one opaque Conversation Handle. */
+export interface ConversationHandleRecord {
+  handle: string;
+  agent: ConsultingAgentId;
+  model: ConsultingModel;
+  continuation: string;
+  canonicalWorkingDirectory: string;
+  workspaceAccess: WorkspaceAccess;
+  agentVersion: string;
+  status: "active" | "retired";
+}
+
+/** Structured details retained for one completed Consultation. */
+export interface ConsultationResultDetails {
+  agent: ConsultingAgentId;
+  model: ConsultingModel;
+  workingDirectoryKind: "consultation" | "workspace";
+  canonicalWorkingDirectory: string;
+  workspaceAccess: WorkspaceAccess;
+  agentVersion: string;
+  durationMs: number;
+  usage?: ConsultationUsage;
+  observedActivities: ConsultationActivity[];
+  activityCounts: Record<ConsultationActivity, number>;
+  permissionDenials: number;
+  webUsed: boolean;
+  workspaceUsed: boolean;
+  ambientProjectGuidanceAvailable: boolean;
+  activeProjectHookWarning?: string;
+  handle: string;
+  continuation: string;
+  handleState: "active";
+  observedSources: ClassifiedSource[];
+  claimedSources: ClassifiedSource[];
+  observedWorkspaceEvidence: ClassifiedWorkspaceEvidence[];
+  claimedWorkspaceEvidence: ClassifiedWorkspaceEvidence[];
+  warnings: string[];
+}
+
+/** Callback for safe, bounded progress activity. */
+export type ConsultingProgressCallback = (activity: string) => void;