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 (ADR-8). */13export type ToolName = "read" | "write" | "edit" | "grep" | "glob" | "bash" | "process";1415/**16 * Coarse capability hint used by the executor/permission layer to derive17 * capability requests. Tools never evaluate permissions themselves —18 * evaluation happens in the Tool Runtime (ARCHITECTURE.md §5.4).19 */20export type ToolCapabilityHint = "file.read" | "file.write" | "process.execute";2122/** Truncation report attached to results that were cut down (TOOL_PROTOCOL §1.3). */23export interface TruncationInfo {24  originalBytes: number;25  originalLines: number;26  shownHeadLines: number;27  shownTailLines: number;28  omittedLines: number;29  /** Absolute path to the full output, if spilled. */30  spillPath?: string;31}3233/** UI/log-facing metadata. Never serialized into model context (TOOL_PROTOCOL §1.1). */34export interface ToolResultMetadata {35  /** Collapsed one-liner shown in the conversation. */36  title: string;37  /** Unified diff for write/edit — powers instant `d` expansion and /diff. */38  diff?: string;39  additions?: number;40  deletions?: number;41  /** grep/glob counts. */42  matches?: number;43  files?: number;44  /** bash/process. */45  exitCode?: number | null;46  processId?: string;47  durationMs: number;48  truncation?: TruncationInfo;49  /** Free-form extras (path, lines, strategy, status, …). */50  extra?: Record<string, unknown>;51}5253/**54 * The result envelope: strict separation of model-facing content from55 * UI-facing metadata (TOOL_PROTOCOL §1.1).56 */57export interface ToolResult {58  /** Exact text the model receives as tool_result content. */59  content: string;60  /** True → tool_result carries is_error: true. The content must be repair prose. */61  isError?: boolean;62  /** UI/log-facing. Never sent to the model. */63  metadata?: ToolResultMetadata;64}6566/**67 * Domain events tools emit. Structurally identical to the corresponding68 * `DurableEventInput` members in `src/session/events.ts` — kept local so69 * tools import only `workspace` and `shared` (ARCHITECTURE.md layering).70 */71export type ToolEmittedEvent =72  | {73      type: "file.read";74      payload: {75        /** Relative to workspace cwd. */76        path: string;77        range?: { start: number; end: number };78        bytes: number;79        mtimeMs: number;80        toolUseId: string;81      };82    }83  | {84      type: "file.modified";85      payload: {86        path: string;87        operation: "write" | "edit";88        diffStats: { added: number; removed: number };89        diff?: string;90        toolUseId: string;91      };92    };9394/**95 * Everything a tool may touch during execution (TOOL_PROTOCOL §1.2).96 * Built by the executor; tools never reach for Node globals (ADR-13).97 */98export interface ToolContext {99  readonly sessionId: string;100  /** Anthropic tool_use id of this call. */101  readonly callId: string;102  /** The ONLY file/exec seam (ADR-13). */103  readonly workspace: Workspace;104  /** Cancellation tree (ADR-11). */105  readonly signal: AbortSignal;106  readonly fileTimes: FileTimeRegistry;107  readonly processes: ProcessManager;108  /** Emit durable domain events (FileRead, FileModified). */109  emit(event: ToolEmittedEvent): void;110  /** Stream UI-facing progress metadata mid-execution (ephemeral). */111  progress(meta: Record<string, unknown>): void;112  /** Spill oversized output; returns the absolute path (TOOL_PROTOCOL §1.3). */113  spill(label: string, content: string): Promise<string>;114}115116/** Synthetic content used when a tool call is cancelled (TOOL_PROTOCOL §1.2). */117export const CANCELLED_RESULT_CONTENT = "[Tool execution cancelled by user]";118