@cleocode/contracts 2026.6.11 → 2026.6.13

package/dist/tools/web-tools.d.ts

@@ -0,0 +1,217 @@
+/**
+ * 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
+ */
+/**
+ * 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;
+}
+/** 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;
+}
+/** 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;
+}
+//# sourceMappingURL=web-tools.d.ts.map

package/dist/tools/web-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-tools.d.ts","sourceRoot":"","sources":["../../src/tools/web-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/web-tools.js

@@ -0,0 +1,31 @@
+/**
+ * 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
+ */
+export {};
+//# sourceMappingURL=web-tools.js.map

package/dist/tools/web-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-tools.js","sourceRoot":"","sources":["../../src/tools/web-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.6.11",
+  "version": "2026.6.13",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,6 +22,10 @@
       "types": "./dist/tools/atomic.d.ts",
       "import": "./dist/tools/atomic.js"
     },
+    "./tools/agent-tools": {
+      "types": "./dist/tools/agent-tools.d.ts",
+      "import": "./dist/tools/agent-tools.js"
+    },
     "./tools/composite": {
       "types": "./dist/tools/composite.d.ts",
       "import": "./dist/tools/composite.js"
@@ -182,7 +186,7 @@
   "dependencies": {
     "zod": "^4.3.6",
     "zod-to-json-schema": "^3.25.2",
-    "@cleocode/lafs": "2026.6.11"
+    "@cleocode/lafs": "2026.6.13"
   },
   "scripts": {
     "build": "tsc -b --force && node scripts/copy-assets.mjs && node scripts/emit-schemas.mjs",