@aragon-agent/core 0.1.3

package/dist/sandbox/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * CodeAct Sandbox — Type Definitions
+ *
+ * Interfaces for the isolated-vm JavaScript sandbox execution environment.
+ * The sandbox enables CodeAct-style code execution: LLM-generated JavaScript
+ * runs in a V8 Isolate with bridged tool access, console capture, and HTTP.
+ */
+import type { AgentTool } from '../tools/types.js';
+/** Configuration for creating an IsolatedVmSandbox instance. */
+export interface SandboxConfig {
+    /** V8 Isolate memory limit in megabytes. Default: 128. */
+    memoryLimitMB?: number;
+    /** Default execution timeout in milliseconds. Default: 30_000. */
+    defaultTimeout?: number;
+    /** Tools to bridge into the sandbox as callable async functions. */
+    tools?: AgentTool[];
+    /**
+     * Allowed hostnames for the HTTP bridge (fetch).
+     * An empty array (default) means all HTTP requests are blocked.
+     */
+    allowedHosts?: string[];
+    /** Pre-injected global variables available in the sandbox. */
+    globals?: Record<string, unknown>;
+}
+/** Per-invocation options for CodeActSandbox.execute(). */
+export interface ExecuteOptions {
+    /** Execution timeout in milliseconds. Overrides SandboxConfig.defaultTimeout. */
+    timeout?: number;
+    /** AbortSignal for cooperative cancellation. */
+    signal?: AbortSignal;
+}
+/** The result of a single code execution in the sandbox. */
+export interface ExecuteResult {
+    /** The serialized return value of the code (JSON string), or undefined on error / void. */
+    returnValue?: string;
+    /** Console output entries collected during execution, in chronological order. */
+    consoleOutput: ConsoleEntry[];
+    /** Error information if the execution failed. Absent on success. */
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+    /** Wall-clock execution duration in milliseconds. */
+    duration: number;
+    /** Tool calls made during execution via the tool bridge. */
+    toolCalls: SandboxToolCall[];
+}
+/** A single captured console output entry. */
+export interface ConsoleEntry {
+    level: 'log' | 'warn' | 'error' | 'info';
+    args: string[];
+    timestamp: number;
+}
+/** Record of a single tool invocation made from within the sandbox. */
+export interface SandboxToolCall {
+    toolName: string;
+    args: Record<string, unknown>;
+    result?: string;
+    error?: string;
+    /** Duration of the tool execution in milliseconds. */
+    duration: number;
+}
+/**
+ * The primary sandbox interface for executing JavaScript code in an
+ * isolated V8 environment with bridged tool access.
+ *
+ * Lifecycle:
+ *   1. Construct with config (lazy — no Isolate created yet)
+ *   2. Call execute() — Isolate + Context created on first call
+ *   3. Variables persist across execute() calls within the same Context
+ *   4. Call reset() to clear all state (new Context, re-inject bridges)
+ *   5. Call dispose() when done to release the V8 Isolate
+ */
+export interface CodeActSandbox {
+    /** Execute JavaScript code in the sandbox. */
+    execute(code: string, options?: ExecuteOptions): Promise<ExecuteResult>;
+    /** Reset sandbox state: destroy current Context, create a fresh one, re-inject bridges. */
+    reset(): Promise<void>;
+    /** Dispose the sandbox and release the underlying V8 Isolate. */
+    dispose(): void;
+    /** Whether this sandbox has been disposed. All calls after disposal will throw. */
+    get isDisposed(): boolean;
+}

package/dist/sandbox/types.js

@@ -0,0 +1,8 @@
+/**
+ * CodeAct Sandbox — Type Definitions
+ *
+ * Interfaces for the isolated-vm JavaScript sandbox execution environment.
+ * The sandbox enables CodeAct-style code execution: LLM-generated JavaScript
+ * runs in a V8 Isolate with bridged tool access, console capture, and HTTP.
+ */
+export {};

package/dist/skills/constants.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Skill budgets and format constants — the single source of truth (spec §11.1).
+ *
+ * UNIT DISCIPLINE (D19 / R16): every `*_BYTES` constant below is measured in
+ * UTF-8 BYTES, never in JS string length. `ToolExecutor`'s own ceiling
+ * (`DEFAULT_MAX_OUTPUT_SIZE = 100_000`) is a byte count and `truncateUtf8()`
+ * cuts on byte boundaries, so a "30 000 characters" budget silently becomes
+ * 90 000 bytes for CJK text and gets halved by the executor — taking the
+ * closing `</skill>` tag with it. Always measure with `Buffer.byteLength`.
+ *
+ * No magic numbers anywhere else in the skills subsystem.
+ */
+/** Whole `<available_skills>` block ceiling, UTF-8 bytes. */
+export declare const SKILL_CATALOG_MAX_BYTES = 6000;
+/** Per-entry description cap (characters — this one is a display width, not a budget). */
+export declare const SKILL_DESC_LINE_MAX = 220;
+/**
+ * INTEGER BUCKETS, NEVER FLOATS. The Level 1 catalog order is a hard
+ * determinism requirement (§5.1): a score computed from, say, a decayed
+ * timestamp would make truncation depend on when the test ran and leave the
+ * byte-budget suites unpinnable. Buckets keep the comparison exact.
+ */
+export declare const USAGE_RECENCY_HOUR_MS: number;
+export declare const USAGE_RECENCY_DAY_MS: number;
+export declare const USAGE_RECENCY_WEEK_MS: number;
+/** `useCount` thresholds for the frequency bucket (2 / 1 / 0). */
+export declare const USAGE_FREQ_HIGH = 10;
+export declare const USAGE_FREQ_LOW = 3;
+/**
+ * Scope outweighs every usage signal by construction: a `project` skill was put
+ * there FOR THIS REPOSITORY, so even an unused one is closer to the task at hand
+ * than a frequently used global. Usage only reorders within one scope.
+ */
+export declare const SCOPE_SCORE_WEIGHT = 1000;
+export declare const RECENCY_SCORE_WEIGHT = 10;
+/** Whole `<skill_search_results>` block ceiling, UTF-8 bytes. */
+export declare const SKILL_FIND_MAX_BYTES = 8000;
+/** Results returned when the model does not ask for a specific count. */
+export declare const SKILL_FIND_DEFAULT_LIMIT = 10;
+/** Hard ceiling on `limit`; a larger request is clamped, not rejected. */
+export declare const SKILL_FIND_MAX_LIMIT = 25;
+/** Query tokens honoured. Extra words are dropped rather than failing the call. */
+export declare const SKILL_FIND_MAX_TOKENS = 8;
+/** SKILL.md body ceiling inside a `skill` tool result, UTF-8 bytes. */
+export declare const SKILL_BODY_MAX_BYTES = 30000;
+/**
+ * Hard ceiling on the ENTIRE `skill` tool result, UTF-8 bytes.
+ *
+ * Deliberately 40 KB below `ToolExecutor`'s 100 000-byte cap so this tool can
+ * never trigger upstream truncation — which would append `... [truncated]`
+ * after eating the closing tag and hand the model a structurally broken block.
+ */
+export declare const SKILL_RESULT_MAX_BYTES = 60000;
+/** Max bundled-file entries listed in `<skill_files>`. */
+export declare const SKILL_FILES_MAX = 50;
+/**
+ * Hard ceiling on the whole `/<skill-name>` invocation MESSAGE, UTF-8 bytes.
+ *
+ * Same number as `SKILL_RESULT_MAX_BYTES`, deliberately a SEPARATE name (D-G12).
+ * The two ceilings exist for DIFFERENT reasons: the tool-result one dodges
+ * `ToolExecutor`'s 100 000-byte cut, which would eat the closing tag; this one
+ * exists because one injected reference document must not swallow the context
+ * window. Sharing a constant would make "it is safe to raise one" read as "it is
+ * safe to raise the other".
+ *
+ * WHY 60 000 IS ALWAYS ENOUGH TODAY: `skills.bodyMaxBytes` is clamped to at most
+ * 50 000 (`cli/src/config/schema.ts::BODY_BYTES_RANGE.max`), which leaves 10 KB
+ * for tags, the file list and the guidance. THAT CLAMP IS THE PREMISE — if it is
+ * ever raised, this constant has to move with it, and nothing else would go red.
+ */
+export declare const SKILL_INVOCATION_MAX_BYTES = 60000;
+/**
+ * Ceiling for the repeat-load digest (§7.2), UTF-8 bytes.
+ *
+ * The digest carries the open tag, the description line, the omitted-body note,
+ * `<skill_files>` and the guidance — everything except the body itself. When it
+ * still does not fit, `<skill_files>` rows are reclaimed; the structure is never
+ * sacrificed, exactly as in `renderSkillBody`.
+ */
+export declare const SKILL_DIGEST_MAX_BYTES = 4000;
+/**
+ * Refusals of the SAME tool within one turn before the refusal escalates (§5.5).
+ *
+ * "Do not retry this tool" is a request, not a mechanism. Without a counter a
+ * single mis-declared skill can burn an entire turn on one blocked tool.
+ */
+export declare const TOOL_POLICY_DENY_ESCALATE_AT = 3;
+/**
+ * Bundled files that are "something you RUN" rather than "something you READ"
+ * (§8.2). Used by `classifyBundledFile()`; a `scripts/` prefix counts too.
+ */
+export declare const SKILL_SCRIPT_EXTENSIONS: readonly [".py", ".js", ".mjs", ".cjs", ".ts", ".sh", ".ps1", ".bat", ".cmd"];
+/** Combined ceiling for all always-on skill bodies in the system prompt, UTF-8 bytes. */
+export declare const ALWAYS_SKILLS_MAX_BYTES = 12000;
+/** Largest SKILL.md the scanner will read, UTF-8 bytes. */
+export declare const SKILL_MD_MAX_BYTES: number;
+/** Frontmatter block hard limits (§4.3 rule 8) — defence against malformed files. */
+export declare const FRONTMATTER_MAX_BYTES: number;
+export declare const FRONTMATTER_MAX_LINES = 200;
+/** Directories scanned per root before the scanner gives up (§6.2 step 6). */
+export declare const SKILL_SCAN_MAX_DIRS = 500;
+/** Soft wall-clock ceiling for one full discovery pass, milliseconds. */
+export declare const SKILL_SCAN_SOFT_TIMEOUT_MS = 1500;
+/** Staging leftovers older than this are reclaimed on the next discover() (P2-10). */
+export declare const STAGING_TTL_MS: number;
+/** `name` must be kebab-case ASCII. Also the dynamic slash-command name. */
+export declare const SKILL_NAME_PATTERN: RegExp;
+export declare const SKILL_NAME_MAX = 64;
+export declare const SKILL_DESC_MAX = 1024;
+export declare const SKILL_META_MAX = 256;
+export declare const SKILL_KEYWORDS_MAX = 16;
+export declare const SKILL_KEYWORD_LEN_MAX = 32;
+export declare const SKILL_ALLOWED_TOOLS_MAX = 32;
+export declare const STAGED_MAX_FILE_BYTES: number;
+export declare const STAGED_MAX_TOTAL_BYTES: number;
+export declare const STAGED_MAX_FILES = 200;
+export declare const STAGED_MAX_DEPTH = 5;
+/** `skill_create` inline file limits (§8.4). */
+export declare const CREATE_MAX_FILE_BYTES: number;
+export declare const CREATE_MAX_FILES = 20;
+/** Windows device names that can never be used as a path segment. */
+export declare const WINDOWS_RESERVED_NAMES: Set<string>;

package/dist/skills/constants.js

@@ -0,0 +1,179 @@
+/**
+ * Skill budgets and format constants — the single source of truth (spec §11.1).
+ *
+ * UNIT DISCIPLINE (D19 / R16): every `*_BYTES` constant below is measured in
+ * UTF-8 BYTES, never in JS string length. `ToolExecutor`'s own ceiling
+ * (`DEFAULT_MAX_OUTPUT_SIZE = 100_000`) is a byte count and `truncateUtf8()`
+ * cuts on byte boundaries, so a "30 000 characters" budget silently becomes
+ * 90 000 bytes for CJK text and gets halved by the executor — taking the
+ * closing `</skill>` tag with it. Always measure with `Buffer.byteLength`.
+ *
+ * No magic numbers anywhere else in the skills subsystem.
+ */
+// ---------------------------------------------------------------------------
+// Level 1 — catalog block (system prompt)
+// ---------------------------------------------------------------------------
+/** Whole `<available_skills>` block ceiling, UTF-8 bytes. */
+export const SKILL_CATALOG_MAX_BYTES = 6000;
+/** Per-entry description cap (characters — this one is a display width, not a budget). */
+export const SKILL_DESC_LINE_MAX = 220;
+// ---------------------------------------------------------------------------
+// Catalog ranking buckets (§5.2)
+// ---------------------------------------------------------------------------
+/**
+ * INTEGER BUCKETS, NEVER FLOATS. The Level 1 catalog order is a hard
+ * determinism requirement (§5.1): a score computed from, say, a decayed
+ * timestamp would make truncation depend on when the test ran and leave the
+ * byte-budget suites unpinnable. Buckets keep the comparison exact.
+ */
+export const USAGE_RECENCY_HOUR_MS = 60 * 60 * 1000;
+export const USAGE_RECENCY_DAY_MS = 24 * USAGE_RECENCY_HOUR_MS;
+export const USAGE_RECENCY_WEEK_MS = 7 * USAGE_RECENCY_DAY_MS;
+/** `useCount` thresholds for the frequency bucket (2 / 1 / 0). */
+export const USAGE_FREQ_HIGH = 10;
+export const USAGE_FREQ_LOW = 3;
+/**
+ * Scope outweighs every usage signal by construction: a `project` skill was put
+ * there FOR THIS REPOSITORY, so even an unused one is closer to the task at hand
+ * than a frequently used global. Usage only reorders within one scope.
+ */
+export const SCOPE_SCORE_WEIGHT = 1000;
+export const RECENCY_SCORE_WEIGHT = 10;
+// ---------------------------------------------------------------------------
+// `skill_find` — the escape hatch for a truncated catalog (§5.4)
+// ---------------------------------------------------------------------------
+/** Whole `<skill_search_results>` block ceiling, UTF-8 bytes. */
+export const SKILL_FIND_MAX_BYTES = 8000;
+/** Results returned when the model does not ask for a specific count. */
+export const SKILL_FIND_DEFAULT_LIMIT = 10;
+/** Hard ceiling on `limit`; a larger request is clamped, not rejected. */
+export const SKILL_FIND_MAX_LIMIT = 25;
+/** Query tokens honoured. Extra words are dropped rather than failing the call. */
+export const SKILL_FIND_MAX_TOKENS = 8;
+// ---------------------------------------------------------------------------
+// Level 2 — `skill` tool result
+// ---------------------------------------------------------------------------
+/** SKILL.md body ceiling inside a `skill` tool result, UTF-8 bytes. */
+export const SKILL_BODY_MAX_BYTES = 30_000;
+/**
+ * Hard ceiling on the ENTIRE `skill` tool result, UTF-8 bytes.
+ *
+ * Deliberately 40 KB below `ToolExecutor`'s 100 000-byte cap so this tool can
+ * never trigger upstream truncation — which would append `... [truncated]`
+ * after eating the closing tag and hand the model a structurally broken block.
+ */
+export const SKILL_RESULT_MAX_BYTES = 60_000;
+/** Max bundled-file entries listed in `<skill_files>`. */
+export const SKILL_FILES_MAX = 50;
+/**
+ * Hard ceiling on the whole `/<skill-name>` invocation MESSAGE, UTF-8 bytes.
+ *
+ * Same number as `SKILL_RESULT_MAX_BYTES`, deliberately a SEPARATE name (D-G12).
+ * The two ceilings exist for DIFFERENT reasons: the tool-result one dodges
+ * `ToolExecutor`'s 100 000-byte cut, which would eat the closing tag; this one
+ * exists because one injected reference document must not swallow the context
+ * window. Sharing a constant would make "it is safe to raise one" read as "it is
+ * safe to raise the other".
+ *
+ * WHY 60 000 IS ALWAYS ENOUGH TODAY: `skills.bodyMaxBytes` is clamped to at most
+ * 50 000 (`cli/src/config/schema.ts::BODY_BYTES_RANGE.max`), which leaves 10 KB
+ * for tags, the file list and the guidance. THAT CLAMP IS THE PREMISE — if it is
+ * ever raised, this constant has to move with it, and nothing else would go red.
+ */
+export const SKILL_INVOCATION_MAX_BYTES = 60_000;
+/**
+ * Ceiling for the repeat-load digest (§7.2), UTF-8 bytes.
+ *
+ * The digest carries the open tag, the description line, the omitted-body note,
+ * `<skill_files>` and the guidance — everything except the body itself. When it
+ * still does not fit, `<skill_files>` rows are reclaimed; the structure is never
+ * sacrificed, exactly as in `renderSkillBody`.
+ */
+export const SKILL_DIGEST_MAX_BYTES = 4_000;
+/**
+ * Refusals of the SAME tool within one turn before the refusal escalates (§5.5).
+ *
+ * "Do not retry this tool" is a request, not a mechanism. Without a counter a
+ * single mis-declared skill can burn an entire turn on one blocked tool.
+ */
+export const TOOL_POLICY_DENY_ESCALATE_AT = 3;
+/**
+ * Bundled files that are "something you RUN" rather than "something you READ"
+ * (§8.2). Used by `classifyBundledFile()`; a `scripts/` prefix counts too.
+ */
+export const SKILL_SCRIPT_EXTENSIONS = [
+    '.py',
+    '.js',
+    '.mjs',
+    '.cjs',
+    '.ts',
+    '.sh',
+    '.ps1',
+    '.bat',
+    '.cmd',
+];
+// ---------------------------------------------------------------------------
+// `activation: always` block
+// ---------------------------------------------------------------------------
+/** Combined ceiling for all always-on skill bodies in the system prompt, UTF-8 bytes. */
+export const ALWAYS_SKILLS_MAX_BYTES = 12_000;
+// ---------------------------------------------------------------------------
+// Disk / parsing limits
+// ---------------------------------------------------------------------------
+/** Largest SKILL.md the scanner will read, UTF-8 bytes. */
+export const SKILL_MD_MAX_BYTES = 512 * 1024;
+/** Frontmatter block hard limits (§4.3 rule 8) — defence against malformed files. */
+export const FRONTMATTER_MAX_BYTES = 8 * 1024;
+export const FRONTMATTER_MAX_LINES = 200;
+/** Directories scanned per root before the scanner gives up (§6.2 step 6). */
+export const SKILL_SCAN_MAX_DIRS = 500;
+/** Soft wall-clock ceiling for one full discovery pass, milliseconds. */
+export const SKILL_SCAN_SOFT_TIMEOUT_MS = 1500;
+/** Staging leftovers older than this are reclaimed on the next discover() (P2-10). */
+export const STAGING_TTL_MS = 24 * 60 * 60 * 1000;
+// ---------------------------------------------------------------------------
+// Frontmatter field limits (§4.2)
+// ---------------------------------------------------------------------------
+/** `name` must be kebab-case ASCII. Also the dynamic slash-command name. */
+export const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+export const SKILL_NAME_MAX = 64;
+export const SKILL_DESC_MAX = 1024;
+export const SKILL_META_MAX = 256;
+export const SKILL_KEYWORDS_MAX = 16;
+export const SKILL_KEYWORD_LEN_MAX = 32;
+export const SKILL_ALLOWED_TOOLS_MAX = 32;
+// ---------------------------------------------------------------------------
+// Staged-install validation limits (§8.3 step 2) — enforced by validateStagedSkill
+// ---------------------------------------------------------------------------
+export const STAGED_MAX_FILE_BYTES = 5 * 1024 * 1024;
+export const STAGED_MAX_TOTAL_BYTES = 20 * 1024 * 1024;
+export const STAGED_MAX_FILES = 200;
+export const STAGED_MAX_DEPTH = 5;
+/** `skill_create` inline file limits (§8.4). */
+export const CREATE_MAX_FILE_BYTES = 1024 * 1024;
+export const CREATE_MAX_FILES = 20;
+/** Windows device names that can never be used as a path segment. */
+export const WINDOWS_RESERVED_NAMES = new Set([
+    'con',
+    'prn',
+    'aux',
+    'nul',
+    'com1',
+    'com2',
+    'com3',
+    'com4',
+    'com5',
+    'com6',
+    'com7',
+    'com8',
+    'com9',
+    'lpt1',
+    'lpt2',
+    'lpt3',
+    'lpt4',
+    'lpt5',
+    'lpt6',
+    'lpt7',
+    'lpt8',
+    'lpt9',
+]);

package/dist/skills/disclosure.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Progressive disclosure rendering (spec §5) — the exact text the model sees.
+ *
+ * Three levels:
+ *   L1 `renderSkillCatalog()`  → `<available_skills>` in the SYSTEM PROMPT.
+ *   L2 `renderSkillBody()`     → the `skill` tool RESULT (never the prompt, D2).
+ *   L3 nothing — bundled files are read on demand with `read_file` / `bash`.
+ *
+ * TWO INVARIANTS THAT ARE EASY TO BREAK AND EXPENSIVE TO LOSE:
+ *
+ *   1. Every byte of third-party text is passed through
+ *      `sanitizeForPromptBlock()` before it is concatenated into a tagged
+ *      block. "Wrap it in <skill> and tell the model it is reference material"
+ *      (§9.1 R1) only works if the content CANNOT close the tag. See D18.
+ *
+ *   2. Every budget is counted in UTF-8 BYTES, never `String.length` (D19).
+ *      `ToolExecutor` truncates at 100 000 bytes and would eat the closing tag.
+ */
+import type { SkillBodyOptions, SkillCatalogOptions, SkillFindOptions, SkillInvocationOptions, SkillPlatform, SkillRecord, SkillUsageMap } from './types.js';
+export declare function byteLength(text: string): number;
+/** Cut to at most `maxBytes` UTF-8 bytes without splitting a code point. */
+export declare function truncateToBytes(text: string, maxBytes: number): string;
+/**
+ * Neutralize a span of untrusted text so it can be embedded inside a tagged
+ * prompt block (§9.5). Idempotent, total, and never throws.
+ *
+ * Angle brackets become their FULL-WIDTH twins rather than HTML entities:
+ * `&lt;` reads as literal noise inside Markdown, whereas `＜` keeps the text
+ * legible to a human and semantically obvious to the model while being
+ * structurally incapable of closing `</skill>` or `</available_skills>`.
+ * Q6 accepts the cost for HTML/JSX-themed skills — that content belongs in
+ * `reference/` where `read_file` returns it verbatim, unsanitized.
+ */
+export declare function sanitizeForPromptBlock(text: string, opts?: {
+    collapseNewlines?: boolean;
+}): string;
+/** Records eligible for the Level 1 catalog, in the canonical order. */
+export declare function catalogRecords(records: SkillRecord[]): SkillRecord[];
+/**
+ * Catalog order with usage folded in — the thing that decides what SURVIVES
+ * truncation (§5.2). Filtering stays in `catalogRecords()` so there is exactly
+ * one definition of "eligible".
+ *
+ * INVARIANT I-A1: with no usage data every recency/frequency bucket is 0, the
+ * score collapses to the scope term alone, and the output is element-for-element
+ * identical to `catalogRecords()`. That is what lets the pre-existing catalog
+ * snapshots keep passing unchanged, and it is the reason this feature can be
+ * reverted by simply not passing `usage`.
+ */
+export declare function rankCatalogRecords(records: SkillRecord[], opts?: {
+    usage?: SkillUsageMap;
+    now?: number;
+}): SkillRecord[];
+/** Public helper for D14: the single catalog line for a freshly installed skill. */
+export declare function renderCatalogLine(record: SkillRecord, descLineMax?: number): string;
+/**
+ * Render the `<available_skills>` block, or `''` when nothing is eligible.
+ *
+ * `''` is load-bearing: it is what keeps `buildSystemPrompt()` byte-identical
+ * to its pre-Skills output on the `--no-skills` / zero-skill / all-manual paths
+ * (invariant I-S1, AC-10).
+ */
+export declare function renderSkillCatalog(records: SkillRecord[], opts?: SkillCatalogOptions): string;
+/**
+ * The empty-result text is load-bearing, not politeness (RA3).
+ *
+ * "No skill matched" is the exact moment a model is most tempted to go find one
+ * on the internet and install it — which would turn agent self-installation from
+ * a convenience the user authorised into an autonomous supply-chain decision
+ * (D-A4). The refusal has to be stated here, in the same breath as the miss,
+ * and it is deliberately worded like `skill_install`'s own description.
+ */
+export declare function renderSkillFindNoMatch(query: string, suggestions?: string[]): string;
+/**
+ * Render the `skill_find` payload. Same two invariants as the catalog: every
+ * span of third-party text is sanitized (D18) and the budget is counted in
+ * UTF-8 bytes (D19).
+ */
+export declare function renderSkillFindResults(query: string, matched: SkillRecord[], opts?: SkillFindOptions): string;
+/**
+ * Is this bundled file something you RUN or something you READ (§8.2)?
+ *
+ * A heuristic on purpose (QG6): a `scripts:` frontmatter key would answer this
+ * exactly, at the cost of forking the format contract with Claude Code for one
+ * line of guidance. The prefix + extension test covers the existing ecosystem.
+ */
+export declare function classifyBundledFile(path: string): 'script' | 'reference';
+/**
+ * Render the Level 2 payload returned by the `skill` tool.
+ *
+ * `mode: 'digest'` drops the body and points at the earlier copy instead (§7.2).
+ * Repeating 30 KB of identical text is not merely expensive — a verbatim
+ * duplicate in the history is the input shape most likely to send a model into
+ * repetition, and the note that already accompanied it said "you do not need to
+ * re-read this" while handing over a second copy.
+ */
+export declare function renderSkillBody(record: SkillRecord, opts?: SkillBodyOptions): string;
+/**
+ * Render always-on skills for the system prompt, or `''` when there are none.
+ *
+ * The overflow notice hangs off THIS block's own tail rather than the catalog's
+ * (P2-11): `renderSkillCatalog()` has no way to know what was dropped here, and
+ * a cross-function dependency for one advisory line is not worth the coupling.
+ *
+ * `platform` IS FORWARDED; `policy` IS NOT — and the absence of a `policy` field
+ * on these options is the enforcement, not a convention (P0-2 / D-G18). D-G9
+ * exempts always-on skills from the ceiling, so a policy line here would tell the
+ * model, on EVERY turn, that only certain tools are permitted — an invented
+ * restriction, applied for the whole session, traceable to nothing the user can
+ * see. `platform` is a fact about the host and is true regardless.
+ */
+export declare function renderAlwaysSkills(records: SkillRecord[], opts?: {
+    maxBytes?: number;
+    bodyMaxBytes?: number;
+    platform?: SkillPlatform;
+}): string;
+/** Split an argument string into shell-style words, honouring quotes. */
+export declare function splitArguments(args: string): string[];
+/**
+ * Substitute `$ARGUMENTS` / `$1..$9` in a skill body; `$$` is a literal `$`.
+ *
+ * When no placeholder appears at all and arguments were supplied, they are
+ * appended under an `## Arguments` heading so a skill that was written without
+ * placeholders still receives what the user typed.
+ */
+export declare function applySkillArguments(body: string, args: string): {
+    text: string;
+    substituted: boolean;
+};
+/**
+ * Build the user message a `/<skill-name>` command submits on the user's behalf.
+ *
+ * THIS PATH HAS A BUDGET NOW (FG3 / W2). It used to have none at all, while the
+ * scanner happily accepts a 512 KB `SKILL.md` — so `/big-skill` submitted half a
+ * megabyte as one user message, and `skills.bodyMaxBytes` was silently inert on
+ * the one delivery path a human triggers by hand. The user-visible symptom was
+ * "this skill errors every time I use it", with the provider's 400 as the only
+ * clue.
+ *
+ * STEP ORDER MATTERS: substitute arguments BEFORE truncating. The other way
+ * round, the bytes that get cut can be exactly where `$ARGUMENTS` was going to
+ * land, and the user sees their arguments quietly ignored.
+ */
+export declare function renderSkillInvocation(record: SkillRecord, args: string, opts?: SkillInvocationOptions): string;
+/** Nearest skill names for an unknown lookup: prefix matches first, then edits ≤ 2. */
+export declare function suggestSkillNames(query: string, names: string[], limit?: number): string[];