@cleocode/contracts 2026.6.12 → 2026.6.14

package/src/tools/agent-tools.ts

@@ -0,0 +1,270 @@
+/**
+ * Agent-facing tool family I/O contracts (T1741 · epic T11456 · SG-TOOLS).
+ *
+ * The shared, types-only I/O shapes for the six CORE agent-tool families wired
+ * into the {@link ./atomic.js | atomic} primitive layer and surfaced through the
+ * `AgentToolRegistry` (`packages/core/src/tools/agent-registry.ts`):
+ *
+ *   - **terminal** — `run_shell` with PTY + non-PTY modes ({@link RunShellInput}).
+ *   - **file/read** — `read_file` with pagination ({@link ReadFilePagedInput}).
+ *   - **file/patch** — `apply_patch` with fuzzy hunk matching ({@link ApplyPatchInput}).
+ *   - **search** — `search_files` over ripgrep ({@link SearchFilesInput}).
+ *   - **git** — status / diff / log / commit ({@link GitStatusInput} …).
+ *
+ * These compose OVER the atomic `fs`/`shell`/`search` primitives — they never
+ * introduce a new side-effect surface. The implementations
+ * (`packages/core/src/tools/builtin/*`) perform ALL work through the injected
+ * `GuardedToolSurface` (deny-first chokepoint), so the same guardrail policy
+ * applies. Types-only — no runtime logic (Gate 10 `contracts-purity`).
+ *
+ * @epic T11456
+ * @task T1741
+ * @see ./atomic.js — the raw primitive I/O shapes these compose over
+ */
+
+// ---------------------------------------------------------------------------
+// terminal — run_shell (PTY + non-PTY)
+// ---------------------------------------------------------------------------
+
+/**
+ * Execution mode for {@link RunShellInput}.
+ *
+ * - `pty` — allocate a pseudo-terminal (line-discipline, colour, interactive
+ *   programs). Requires the OPTIONAL `node-pty` native dep; when it cannot be
+ *   loaded the implementation transparently falls back to `spawn`.
+ * - `spawn` — plain `child_process.spawn` (no TTY). Always available.
+ * - `auto` — prefer `pty` when `node-pty` is loadable, else `spawn`.
+ */
+export type ShellRunMode = 'pty' | 'spawn' | 'auto';
+
+/** Input for the `run_shell` terminal tool. */
+export interface RunShellInput {
+  /** Executable to run (argv form — NOT a shell string; no shell interpolation). */
+  readonly command: string;
+  /** Arguments for {@link RunShellInput.command}. */
+  readonly args?: readonly string[];
+  /** Working directory. */
+  readonly cwd?: string;
+  /** Extra environment variables (scrubbed at the guard chokepoint). */
+  readonly env?: Readonly<Record<string, string>>;
+  /** Hard timeout in milliseconds; the process is killed when exceeded. */
+  readonly timeoutMs?: number;
+  /** Execution mode. Defaults to `auto`. */
+  readonly mode?: ShellRunMode;
+  /** PTY column count (PTY mode only). Defaults to 80. */
+  readonly cols?: number;
+  /** PTY row count (PTY mode only). Defaults to 24. */
+  readonly rows?: number;
+}
+
+/** Result of the `run_shell` terminal tool. */
+export interface RunShellResult {
+  /**
+   * Combined output. In `spawn` mode this is stdout; in `pty` mode stdout and
+   * stderr are interleaved on the single PTY stream (as a real terminal does).
+   */
+  readonly stdout: string;
+  /** Captured standard error. Empty in PTY mode (merged into {@link RunShellResult.stdout}). */
+  readonly stderr: string;
+  /** Process exit code (0 = success). `null` when killed by signal/timeout. */
+  readonly code: number | null;
+  /** The mode that actually ran (`pty` downgrades to `spawn` when unavailable). */
+  readonly mode: 'pty' | 'spawn';
+  /** Whether a PTY was requested but unavailable, so `spawn` was used instead. */
+  readonly ptyFellBack: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// file — read_file (pagination)
+// ---------------------------------------------------------------------------
+
+/** Input for the paginated `read_file` tool. */
+export interface ReadFilePagedInput {
+  /** Absolute path to read. */
+  readonly path: string;
+  /** 0-based line offset to start from. Defaults to 0. */
+  readonly offset?: number;
+  /** Maximum number of lines to return. Omit for "to end of file". */
+  readonly limit?: number;
+}
+
+/** Result of a paginated read. */
+export interface ReadFilePagedResult {
+  /** Absolute path that was read. */
+  readonly path: string;
+  /** The selected slice of lines (joined with `\n`). */
+  readonly content: string;
+  /** 0-based line offset the slice began at. */
+  readonly offset: number;
+  /** Number of lines returned. */
+  readonly lineCount: number;
+  /** Total number of lines in the file. */
+  readonly totalLines: number;
+  /** Whether more lines exist after the returned slice. */
+  readonly hasMore: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// file — apply_patch (fuzzy)
+// ---------------------------------------------------------------------------
+
+/** Input for the `apply_patch` tool (fuzzy, whitespace-tolerant replacement). */
+export interface ApplyPatchInput {
+  /** Absolute path of the file to patch. */
+  readonly path: string;
+  /** Exact-or-fuzzy block of original text to locate. */
+  readonly oldText: string;
+  /** Replacement text. */
+  readonly newText: string;
+  /**
+   * Permit fuzzy (leading/trailing whitespace-insensitive) matching when an
+   * exact match is not found. Defaults to `true`.
+   */
+  readonly fuzzy?: boolean;
+}
+
+/** Result of an `apply_patch`. */
+export interface ApplyPatchResult {
+  /** Absolute path that was patched. */
+  readonly path: string;
+  /** Whether the replacement was applied. */
+  readonly applied: boolean;
+  /** How the match was located: exact, fuzzy (whitespace-normalised), or none. */
+  readonly matchKind: 'exact' | 'fuzzy' | 'none';
+  /** 0-based line where the replacement began (when applied). */
+  readonly startLine?: number;
+}
+
+// ---------------------------------------------------------------------------
+// search — search_files (ripgrep)
+// ---------------------------------------------------------------------------
+
+/** Input for the ripgrep-backed `search_files` tool. */
+export interface SearchFilesInput {
+  /** Pattern to search for (regex by default — see {@link SearchFilesInput.fixedStrings}). */
+  readonly pattern: string;
+  /** Root directory to search under. */
+  readonly root: string;
+  /** Treat {@link SearchFilesInput.pattern} as a literal string, not a regex. */
+  readonly fixedStrings?: boolean;
+  /** Case-insensitive matching. */
+  readonly ignoreCase?: boolean;
+  /** Restrict to files matching this ripgrep glob (e.g. `*.ts`). */
+  readonly glob?: string;
+  /** Cap on returned matches. Defaults to 1000. */
+  readonly maxResults?: number;
+}
+
+/** A single `search_files` match. */
+export interface SearchFilesMatch {
+  /** Absolute (or root-relative) path of the matching file. */
+  readonly path: string;
+  /** 1-based line number of the match. */
+  readonly line: number;
+  /** The matching line's text (trailing newline stripped). */
+  readonly text: string;
+}
+
+/** Result of `search_files`. */
+export interface SearchFilesResult {
+  /** Matches in ripgrep order. */
+  readonly matches: readonly SearchFilesMatch[];
+  /** Whether {@link SearchFilesInput.maxResults} truncated the results. */
+  readonly truncated: boolean;
+  /**
+   * `true` when ripgrep (`rg`) was unavailable and the search degraded to a
+   * built-in scan, so callers can surface reduced fidelity.
+   */
+  readonly degraded: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// git — status / diff / log / commit
+// ---------------------------------------------------------------------------
+
+/** Common options for the git tools. */
+export interface GitToolBase {
+  /** Repository working directory. Defaults to `process.cwd()`. */
+  readonly cwd?: string;
+  /** Hard timeout in milliseconds. */
+  readonly timeoutMs?: number;
+}
+
+/** Input for `git_status`. */
+export interface GitStatusInput extends GitToolBase {}
+
+/** One porcelain-v1 status entry. */
+export interface GitStatusEntry {
+  /** Two-char XY porcelain status code (e.g. ` M`, `A `, `??`). */
+  readonly status: string;
+  /** Path the status applies to. */
+  readonly path: string;
+}
+
+/** Result of `git_status`. */
+export interface GitStatusResult {
+  /** The current branch name (`HEAD` when detached/unknown). */
+  readonly branch: string;
+  /** Parsed porcelain entries. */
+  readonly entries: readonly GitStatusEntry[];
+  /** Whether the working tree has any uncommitted changes. */
+  readonly clean: boolean;
+}
+
+/** Input for `git_diff`. */
+export interface GitDiffInput extends GitToolBase {
+  /** Show staged (`--cached`) changes instead of the working tree. */
+  readonly staged?: boolean;
+  /** Restrict the diff to these paths. */
+  readonly paths?: readonly string[];
+}
+
+/** Result of `git_diff`. */
+export interface GitDiffResult {
+  /** The unified diff text (empty when there are no changes). */
+  readonly diff: string;
+}
+
+/** Input for `git_log`. */
+export interface GitLogInput extends GitToolBase {
+  /** Maximum number of commits to return. Defaults to 20. */
+  readonly maxCount?: number;
+}
+
+/** One commit in a `git_log` result. */
+export interface GitLogEntry {
+  /** Full commit SHA. */
+  readonly sha: string;
+  /** Author name. */
+  readonly author: string;
+  /** ISO-8601 author date. */
+  readonly date: string;
+  /** Commit subject (first line). */
+  readonly subject: string;
+}
+
+/** Result of `git_log`. */
+export interface GitLogResult {
+  /** Commits newest-first. */
+  readonly commits: readonly GitLogEntry[];
+}
+
+/** Input for `git_commit`. */
+export interface GitCommitInput extends GitToolBase {
+  /** Commit message. */
+  readonly message: string;
+  /** Stage all tracked modifications first (`-a`). Defaults to `false`. */
+  readonly all?: boolean;
+  /** Explicit paths to stage before committing. */
+  readonly paths?: readonly string[];
+}
+
+/** Result of `git_commit`. */
+export interface GitCommitResult {
+  /** Whether the commit was created. */
+  readonly committed: boolean;
+  /** The new commit SHA (when created). */
+  readonly sha?: string;
+  /** Git's stdout/stderr summary (e.g. "nothing to commit"). */
+  readonly summary: string;
+}

package/src/tools/atomic.ts

@@ -36,6 +36,27 @@ export const TOOL_CLASSES = ['fs', 'shell', 'search', 'net', 'notebook'] as cons
 /** One of the canonical {@link TOOL_CLASSES}. */
 export type ToolClass = (typeof TOOL_CLASSES)[number];
 
+/**
+ * Agent-facing **toolset** groups (T1739 · AC4 · epic T11456).
+ *
+ * Where {@link TOOL_CLASSES} groups primitives by their SIDE-EFFECT surface (and
+ * therefore by guardrail policy), a {@link Toolset} groups tools by the
+ * AGENT-FACING CAPABILITY a model selects when reasoning — the dimension Hermes'
+ * `tools/registry.py` exposes to the loop. The two axes are orthogonal: an `fs`
+ * class primitive belongs to the `file` toolset, a `shell` class primitive to the
+ * `terminal` toolset, a `net` class primitive to the `web` toolset, etc.
+ *
+ * - `terminal` — shell / process execution (`executeShell`, `runGit`).
+ * - `file` — filesystem read/write/search (`readFileText`, `writeFileAtomic`, …).
+ * - `web` — outbound network / fetch (`fetch`).
+ * - `agent` — sub-agent / delegation / task orchestration tools.
+ * - `media` — image / audio / notebook authoring (`notebookEdit`, …).
+ */
+export const AGENT_TOOLSETS = ['terminal', 'file', 'web', 'agent', 'media'] as const;
+
+/** One of the canonical {@link AGENT_TOOLSETS}. */
+export type Toolset = (typeof AGENT_TOOLSETS)[number];
+
 /**
  * Descriptor for a single registered tool primitive. The registry of these is
  * the SoT for "what atomic tools exist", consumed by the guardrail chokepoint

package/src/tools/index.ts

@@ -7,6 +7,30 @@
  * @epic T9835
  */
 
+// === Agent-facing tool families (T1741 / T11456) ===
+export type {
+  ApplyPatchInput,
+  ApplyPatchResult,
+  GitCommitInput,
+  GitCommitResult,
+  GitDiffInput,
+  GitDiffResult,
+  GitLogEntry,
+  GitLogInput,
+  GitLogResult,
+  GitStatusEntry,
+  GitStatusInput,
+  GitStatusResult,
+  GitToolBase,
+  ReadFilePagedInput,
+  ReadFilePagedResult,
+  RunShellInput,
+  RunShellResult,
+  SearchFilesInput,
+  SearchFilesMatch,
+  SearchFilesResult,
+  ShellRunMode,
+} from './agent-tools.js';
 export type { FetchBrainEntriesInput, FetchBrainEntriesOutput } from './brain-fetch.js';
 export type { ObserveBrainInput, ObserveBrainOutput } from './brain-observe.js';
 // === BrainTools (T10070 / T9835c) ===
@@ -41,3 +65,25 @@ export type {
   ScoreTaskInput,
   ScoreTaskResult,
 } from './score-task-priority.js';
+// === Web + browser agent tools (T1742 / T11456) ===
+export type {
+  AccessibilityNode,
+  BrowserActionResult,
+  BrowserClickInput,
+  BrowserNavigateInput,
+  BrowserPageState,
+  BrowserPressInput,
+  BrowserScrollDirection,
+  BrowserScrollInput,
+  BrowserScrollResult,
+  BrowserSnapshotResult,
+  BrowserTypeInput,
+  BrowserVisionInput,
+  BrowserVisionResult,
+  WebExtractInput,
+  WebExtractResult,
+  WebSearchBackendId,
+  WebSearchHit,
+  WebSearchInput,
+  WebSearchResult,
+} from './web-tools.js';

package/src/tools/skill-executor.ts

@@ -44,6 +44,7 @@
  * @see ./atomic.js — the tool I/O shapes this seam composes over
  */
 
+import type { RunShellInput, RunShellResult } from './agent-tools.js';
 import type {
   ExecuteShellInput,
   ExecuteShellResult,
@@ -86,6 +87,12 @@ export interface GuardedToolSurface {
   pathExists(input: PathExistsInput): Promise<PathExistsResult>;
   /** Run a command with explicit cwd/env/timeout through the guard. */
   executeShell(input: ExecuteShellInput): Promise<ExecuteShellResult>;
+  /**
+   * Run a command under a pseudo-terminal (PTY) through the guard, falling back
+   * to a non-PTY spawn when a PTY backend is unavailable. Subject to the same
+   * deny-first command policy + env scrubbing as {@link GuardedToolSurface.executeShell}.
+   */
+  executePty(input: RunShellInput): Promise<RunShellResult>;
   /** Run a git subcommand through the guard. */
   runGit(input: RunGitInput): Promise<ExecuteShellResult>;
 }

package/src/tools/web-tools.ts

@@ -0,0 +1,247 @@
+/**
+ * Web + browser agent-tool I/O contracts (T1742 · epic T11456 · SG-TOOLS).
+ *
+ * The shared, types-only I/O shapes for the `web` toolset surfaced through the
+ * `AgentToolRegistry` (`packages/core/src/tools/agent-registry.ts`), on top of
+ * the terminal/file/search/git families ({@link ./agent-tools.js}):
+ *
+ *   - **web_search** — pluggable, backend-agnostic web search
+ *     ({@link WebSearchInput} / {@link WebSearchResult}). NO hard paid-API dep:
+ *     a backend is resolved at call time and the tool degrades gracefully to an
+ *     `unavailable` result when none is configured.
+ *   - **web_extract** — fetch a URL and convert its HTML body to markdown
+ *     ({@link WebExtractInput} / {@link WebExtractResult}).
+ *   - **browser_*** — Playwright-driven browser automation
+ *     ({@link BrowserNavigateInput} … {@link BrowserVisionResult}). Playwright is
+ *     an OPTIONAL, lazily-loaded dependency — these tools' `available()` predicate
+ *     returns `false` (with an install hint) when it is absent.
+ *
+ * The web tools compose over the `net` side-effect surface; the browser tools
+ * over a Playwright-managed `shell`-class process. Like every agent tool, their
+ * executables perform side effects through the injected `GuardedToolSurface` (or,
+ * for the AI call in {@link BrowserVisionResult}, through the E9
+ * `resolveLLMForSystem` chokepoint) — never a raw provider/network bypass.
+ * Types-only — no runtime logic (Gate 10 `contracts-purity`).
+ *
+ * @epic T11456
+ * @task T1742
+ * @see ./agent-tools.js — the terminal/file/search/git family I/O shapes
+ */
+
+// ---------------------------------------------------------------------------
+// web_search — pluggable, backend-agnostic
+// ---------------------------------------------------------------------------
+
+/**
+ * Identifier of a {@link WebSearchInput} backend.
+ *
+ * - `duckduckgo` — DuckDuckGo's keyless HTML endpoint (no API key required).
+ * - `searxng` — a self-hosted / public SearXNG JSON instance (URL via config/env).
+ * - `auto` — try each configured backend in priority order, first success wins.
+ *
+ * NONE require a paid API key; the set is open by design so a deployment can
+ * register its own backend. The string union here is the canonical builtin set.
+ */
+export type WebSearchBackendId = 'duckduckgo' | 'searxng' | 'auto';
+
+/** Input for the `web_search` tool. */
+export interface WebSearchInput {
+  /** Free-text search query. */
+  readonly query: string;
+  /** Maximum number of results to return. Defaults to 10. */
+  readonly maxResults?: number;
+  /**
+   * Preferred backend. Defaults to `auto` — the first configured/reachable
+   * backend answers. An explicit id pins a single backend.
+   */
+  readonly backend?: WebSearchBackendId;
+}
+
+/** A single web-search hit. */
+export interface WebSearchHit {
+  /** Result title. */
+  readonly title: string;
+  /** Absolute result URL. */
+  readonly url: string;
+  /** Snippet / description (may be empty). */
+  readonly snippet: string;
+}
+
+/** Result of `web_search`. */
+export interface WebSearchResult {
+  /** The originating query (echoed for traceability). */
+  readonly query: string;
+  /** Hits in backend-ranked order (empty when none / unavailable). */
+  readonly results: readonly WebSearchHit[];
+  /** The backend that actually answered, or `null` when none was available. */
+  readonly backend: WebSearchBackendId | null;
+  /**
+   * `true` when NO backend could answer (none configured, network egress
+   * denied, or every backend failed). Callers MUST treat this as a soft
+   * "no search capability" signal — it is NOT an error.
+   */
+  readonly unavailable: boolean;
+  /** Human-readable reason when {@link WebSearchResult.unavailable} is `true`. */
+  readonly reason?: string;
+}
+
+// ---------------------------------------------------------------------------
+// web_extract — URL → markdown
+// ---------------------------------------------------------------------------
+
+/** Input for the `web_extract` tool. */
+export interface WebExtractInput {
+  /** Absolute URL to fetch and convert. */
+  readonly url: string;
+  /** Hard timeout in milliseconds. Defaults to 30000. */
+  readonly timeoutMs?: number;
+  /**
+   * Cap on the markdown length (characters). Output beyond this is truncated
+   * and {@link WebExtractResult.truncated} set. Defaults to 100000.
+   */
+  readonly maxChars?: number;
+}
+
+/** Result of `web_extract`. */
+export interface WebExtractResult {
+  /** The fetched URL. */
+  readonly url: string;
+  /** HTTP status code of the fetch. */
+  readonly status: number;
+  /** Document `<title>`, when present. */
+  readonly title: string;
+  /** The page body converted to markdown. */
+  readonly markdown: string;
+  /** Whether {@link WebExtractInput.maxChars} truncated the markdown. */
+  readonly truncated: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// browser_* — Playwright-driven automation
+// ---------------------------------------------------------------------------
+
+/** Input for `browser_navigate`. */
+export interface BrowserNavigateInput {
+  /** Absolute URL to navigate the browser to. */
+  readonly url: string;
+  /**
+   * When to consider navigation complete. Defaults to `load`.
+   * Mirrors Playwright's `waitUntil` states.
+   */
+  readonly waitUntil?: 'load' | 'domcontentloaded' | 'networkidle';
+  /** Per-navigation timeout in milliseconds. Defaults to 30000. */
+  readonly timeoutMs?: number;
+}
+
+/** Result common to navigation / interaction browser tools. */
+export interface BrowserPageState {
+  /** The page's current URL after the operation. */
+  readonly url: string;
+  /** The page's `document.title` after the operation. */
+  readonly title: string;
+}
+
+/** Input for `browser_click`. */
+export interface BrowserClickInput {
+  /** A CSS / Playwright selector for the element to click. */
+  readonly selector: string;
+  /** Per-action timeout in milliseconds. Defaults to 15000. */
+  readonly timeoutMs?: number;
+}
+
+/** Input for `browser_type`. */
+export interface BrowserTypeInput {
+  /** A CSS / Playwright selector for the input element. */
+  readonly selector: string;
+  /** The text to type into the element. */
+  readonly text: string;
+  /** Clear the field before typing. Defaults to `true`. */
+  readonly clear?: boolean;
+  /** Per-action timeout in milliseconds. Defaults to 15000. */
+  readonly timeoutMs?: number;
+}
+
+/** Input for `browser_press` (a single key / chord). */
+export interface BrowserPressInput {
+  /**
+   * The key (or `Modifier+Key` chord) to press, in Playwright key syntax
+   * (e.g. `Enter`, `Tab`, `Control+A`, `ArrowDown`).
+   */
+  readonly key: string;
+  /** Optional selector to focus before pressing. */
+  readonly selector?: string;
+  /** Per-action timeout in milliseconds. Defaults to 15000. */
+  readonly timeoutMs?: number;
+}
+
+/** Result of a `browser_click` / `browser_type` / `browser_press` action. */
+export interface BrowserActionResult extends BrowserPageState {
+  /** The action that was performed. */
+  readonly action: 'click' | 'type' | 'press';
+}
+
+/** A single node in the {@link BrowserSnapshotResult} accessibility tree. */
+export interface AccessibilityNode {
+  /** ARIA role (e.g. `button`, `link`, `textbox`). */
+  readonly role: string;
+  /** Accessible name, when present. */
+  readonly name?: string;
+  /** Current value (form controls). */
+  readonly value?: string;
+  /** Child nodes (depth-first). */
+  readonly children?: readonly AccessibilityNode[];
+}
+
+/** Result of `browser_snapshot` — the page accessibility tree. */
+export interface BrowserSnapshotResult extends BrowserPageState {
+  /** The root of the accessibility tree, or `null` when none is available. */
+  readonly tree: AccessibilityNode | null;
+}
+
+/** Scroll direction for `browser_scroll`. */
+export type BrowserScrollDirection = 'up' | 'down';
+
+/** Input for `browser_scroll`. */
+export interface BrowserScrollInput {
+  /** Direction to scroll. */
+  readonly direction: BrowserScrollDirection;
+  /**
+   * Pixels to scroll by. Defaults to roughly one viewport height (800px).
+   */
+  readonly amountPx?: number;
+}
+
+/** Result of `browser_scroll`. */
+export interface BrowserScrollResult extends BrowserPageState {
+  /** The direction that was scrolled. */
+  readonly direction: BrowserScrollDirection;
+  /** The vertical scroll position (pixels from top) after scrolling. */
+  readonly scrollY: number;
+}
+
+/** Input for `browser_vision` (screenshot + AI analysis). */
+export interface BrowserVisionInput {
+  /**
+   * The question / instruction the vision model should answer about the current
+   * page screenshot (e.g. "What is the primary call-to-action on this page?").
+   */
+  readonly prompt: string;
+  /** Capture the full scrollable page rather than just the viewport. Defaults to `false`. */
+  readonly fullPage?: boolean;
+}
+
+/** Result of `browser_vision`. */
+export interface BrowserVisionResult extends BrowserPageState {
+  /**
+   * The vision model's textual analysis of the screenshot, or `null` when no
+   * LLM credential was reachable (graceful degradation — NOT an error).
+   */
+  readonly analysis: string | null;
+  /** The model id that produced {@link BrowserVisionResult.analysis}, when available. */
+  readonly model?: string;
+  /**
+   * `true` when the AI call was skipped because no LLM credential resolved
+   * through the E9 chokepoint. The screenshot was still captured.
+   */
+  readonly aiUnavailable: boolean;
+}