spb/khaelor Public

1/**2 * KHAELOR3 * File: src/tools/types.ts4 * Description: ToolResult envelope, ToolContext, and tool-emitted event shapes (TOOL_PROTOCOL §1).5 *6 * Author: Simon-Pierre Boucher7 * Contact: contact@spboucher.ai8 */910import type { FileTimeRegistry, ProcessManager, Workspace } from "../workspace/index.js";1112/** The seven V1 tools plus the v2 additions: design (phase gates), remember (memory), symbols/refs (RepoGraph). */13export type ToolName =14  | "read"15  | "write"16  | "edit"17  | "grep"18  | "glob"19  | "bash"20  | "process"21  | "design"22  | "remember"23  | "symbols"24  | "refs";2526/**27 * Coarse capability hint used by the executor/permission layer to derive28 * capability requests. Tools never evaluate permissions themselves —29 * evaluation happens in the Tool Runtime (ARCHITECTURE.md §5.4).30 */31export type ToolCapabilityHint = "file.read" | "file.write" | "process.execute";3233/** Truncation report attached to results that were cut down (TOOL_PROTOCOL §1.3). */34export interface TruncationInfo {35  originalBytes: number;36  originalLines: number;37  shownHeadLines: number;38  shownTailLines: number;39  omittedLines: number;40  /** Absolute path to the full output, if spilled. */41  spillPath?: string;42}4344/** UI/log-facing metadata. Never serialized into model context (TOOL_PROTOCOL §1.1). */45export interface ToolResultMetadata {46  /** Collapsed one-liner shown in the conversation. */47  title: string;48  /** Unified diff for write/edit — powers instant `d` expansion and /diff. */49  diff?: string;50  additions?: number;51  deletions?: number;52  /** grep/glob counts. */53  matches?: number;54  files?: number;55  /** bash/process. */56  exitCode?: number | null;57  processId?: string;58  durationMs: number;59  truncation?: TruncationInfo;60  /** Free-form extras (path, lines, strategy, status, …). */61  extra?: Record<string, unknown>;62}6364/**65 * The result envelope: strict separation of model-facing content from66 * UI-facing metadata (TOOL_PROTOCOL §1.1).67 */68export interface ToolResult {69  /** Exact text the model receives as tool_result content. */70  content: string;71  /** True → tool_result carries is_error: true. The content must be repair prose. */72  isError?: boolean;73  /** UI/log-facing. Never sent to the model. */74  metadata?: ToolResultMetadata;75}7677/**78 * Domain events tools emit. Structurally identical to the corresponding79 * `DurableEventInput` members in `src/session/events.ts` — kept local so80 * tools import only `workspace` and `shared` (ARCHITECTURE.md layering).81 */82export type ToolEmittedEvent =83  | {84      type: "file.read";85      payload: {86        /** Relative to workspace cwd. */87        path: string;88        range?: { start: number; end: number };89        bytes: number;90        mtimeMs: number;91        toolUseId: string;92      };93    }94  | {95      type: "file.modified";96      payload: {97        path: string;98        operation: "write" | "edit";99        diffStats: { added: number; removed: number };100        diff?: string;101        toolUseId: string;102      };103    }104  | {105      type: "memory.written";106      payload: {107        section: string;108        entry: string;109        confidence: "high" | "medium" | "low";110        toolUseId: string;111      };112    };113114// ─────────────────── v2 service facets (structural seams) ───────────────────115// Defined locally so tools keep importing only `workspace` and `shared`116// (ARCHITECTURE.md layering) — the executor injects implementations that are117// structurally identical to the phases/repograph services.118119/** Design artifact shape — structurally identical to session/events DesignArtifact. */120export interface ToolDesignArtifact {121  goal: string;122  filesTouched: string[];123  approach: string;124  risks: string[];125  verification: string;126  outOfScope: string[];127}128129/** Phase-gate facet the `design` tool uses (v2 §1). */130export interface PhaseToolFacet {131  mode: "strict" | "auto" | "off";132  current(): "understand" | "design" | "implement";133  submitDesign(134    artifact: ToolDesignArtifact,135  ): Promise<{ status: "approved" | "rejected" | "pending"; artifactId: string; reason?: string }>;136}137138/** One symbol row returned by the semantic index (v2 §3). */139export interface SymbolHit {140  symbol: string;141  kind: "function" | "class" | "type" | "export" | "variable" | "method";142  file: string;143  line: number;144  signature: string;145  docComment?: string;146}147148/** One reference site returned by the semantic index (v2 §3). */149export interface RefHit {150  file: string;151  line: number;152  context: string;153}154155/** RepoGraph facet the `symbols`/`refs` tools use (v2 §3). */156export interface RepoGraphFacet {157  querySymbols(query: string, kind?: string, scope?: string): Promise<SymbolHit[]>;158  queryRefs(symbol: string, direction: "callers" | "callees" | "importers"): Promise<RefHit[]>;159}160161/**162 * Everything a tool may touch during execution (TOOL_PROTOCOL §1.2).163 * Built by the executor; tools never reach for Node globals (ADR-13).164 */165export interface ToolContext {166  readonly sessionId: string;167  /** Anthropic tool_use id of this call. */168  readonly callId: string;169  /** The ONLY file/exec seam (ADR-13). */170  readonly workspace: Workspace;171  /** Cancellation tree (ADR-11). */172  readonly signal: AbortSignal;173  readonly fileTimes: FileTimeRegistry;174  readonly processes: ProcessManager;175  /** Emit durable domain events (FileRead, FileModified). */176  emit(event: ToolEmittedEvent): void;177  /** Stream UI-facing progress metadata mid-execution (ephemeral). */178  progress(meta: Record<string, unknown>): void;179  /** Spill oversized output; returns the absolute path (TOOL_PROTOCOL §1.3). */180  spill(label: string, content: string): Promise<string>;181  /** Phase-gate facet (v2 §1); absent when gates are unavailable. */182  readonly phases?: PhaseToolFacet;183  /** Semantic-index facet (v2 §3); absent when the index is unavailable. */184  readonly repograph?: RepoGraphFacet;185}186187/** Synthetic content used when a tool call is cancelled (TOOL_PROTOCOL §1.2). */188export const CANCELLED_RESULT_CONTENT = "[Tool execution cancelled by user]";189