melchizedek-agents 0.16.2 → 0.18.0

package/dist/lib/tools/openapiTools.js

@@ -0,0 +1,225 @@
+/**
+ * lib/tools/openapiTools.ts — any HTTP API with an OpenAPI spec becomes an
+ * agent's tools, from YAML.
+ *
+ * WHY: "Bring your own API" was a code task: write a `defineTool` per
+ * endpoint, register it, name it in YAML. ADK 2.2 ships `OpenAPIToolset`,
+ * which turns an OpenAPI 3 spec into one tool per operation (parameters and
+ * request body as the tool's schema, the operation's summary as its
+ * description). An agent's `openapi:` list hands it a spec file:
+ *
+ *   openapi:
+ *     - spec: "specs/weather.yaml"          # beside this YAML file
+ *       operations: [getForecast]           # omitted: the GET operations only
+ *       auth: { api_key: { env: "WEATHER_KEY", in: "header", name: "X-Api-Key" } }
+ *
+ * WHAT THE ENGINE ADDS to ADK's toolset, all of it exposure discipline:
+ *   - READ-ONLY BY DEFAULT. Without `operations`, only GET operations become
+ *     tools; anything that writes is exposed only by naming it, and a named
+ *     operation can be listed under `require_approval` like a registry tool
+ *     (ADR 0028), so a POST or a DELETE can wait for a person.
+ *   - SECRETS FROM THE ENVIRONMENT. `auth` names an environment variable,
+ *     never a value; a variable that is not set fails the compile, so an
+ *     agent never runs half-authenticated. A YAML (possibly registry-stored)
+ *     chooses both the variable and the host, so it may never name one of
+ *     the framework's own secrets (credentialEnvProblem): the database URL,
+ *     a provider key or an A2A secret cannot be sent to an API.
+ *     OPENAPI_CREDENTIAL_ENVS, when the operator sets it, is the exact list
+ *     of variables an `auth` may name.
+ *   - THE SSRF GUARD. Every server URL the tools will call must be http(s)
+ *     and pass lib/net/addressGuard.ts: its literal rules at compile time
+ *     (offline), and the full check with DNS before each call (a name can
+ *     re-resolve between calls). ALLOW_PRIVATE_OPENAPI=true permits
+ *     private hosts for local development, as ALLOW_PRIVATE_MCP does for MCP.
+ *     The model chooses arguments, never the host: path parameters are
+ *     URL-encoded by ADK and dot segments refused.
+ *   - REDIRECTS HELD TO THE SAME GUARD. ADK calls globalThis.fetch, which
+ *     follows redirects; a call runs under lib/net/redirects.ts instead, so
+ *     each hop is checked before it is fetched. A hop on the same origin
+ *     gets the server's own check; a hop to another origin must pass the
+ *     full guard even with ALLOW_PRIVATE_OPENAPI (that permits the server
+ *     you configured, not wherever it points), and loses every header but
+ *     content negotiation, credentials included.
+ *   - BOUNDED RESULTS. A response larger than MAX_RESULT_CHARS is cut and
+ *     says so; a network failure comes back as `{ error }`, never a throw.
+ *
+ * Spec files only, never URLs: a spec fetched at compile time would be a
+ * second outbound surface, and a spec that changes under a running agent
+ * changes its tools. Save the spec beside the YAML and review it like code.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+import { OpenAPIToolset, tokenToSchemeCredential } from '@google/adk';
+import { blockedHostReason, checkHost } from '../net/addressGuard.js';
+import { withRedirectGuard } from '../net/redirects.js';
+/** Characters a single API result may carry into the conversation. */
+export const MAX_RESULT_CHARS = 20_000;
+/** Marks a tool built here, so require_approval may gate it (lib/compile.ts). */
+export const OPENAPI_TOOL = Symbol.for('melchizedek.openapiTool');
+/** snake_case, the way ADK names a tool from an operationId. */
+export function toSnake(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[^A-Za-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase();
+}
+/** True when a configured operation name (an operationId or a tool name) names this tool. */
+export function namesTool(configured, tool) {
+    return configured === tool.name || configured === tool.operation?.operationId || toSnake(configured) === tool.name;
+}
+/**
+ * Why a server may not be called, or null. At compile time only the literal
+ * rules apply (no connection is made, and a build must not need DNS); before
+ * each call the name is resolved too, which guards the connection itself.
+ */
+async function hostProblem(baseUrl, resolve) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch {
+        return `'${baseUrl}' is not a URL`;
+    }
+    if (!/^https?:$/.test(url.protocol))
+        return `'${baseUrl}' must be http(s)`;
+    if (process.env.ALLOW_PRIVATE_OPENAPI === 'true')
+        return null;
+    const reason = resolve ? await checkHost(url.hostname) : blockedHostReason(url.hostname);
+    return reason ? `refusing ${url.hostname}: ${reason} (set ALLOW_PRIVATE_OPENAPI=true for local development)` : null;
+}
+/** Prefixes and names of variables the framework itself reads: never an API credential. */
+const FRAMEWORK_ENV_PREFIXES = [
+    'A2A_', 'SUPABASE_', 'DATABASE_', 'MCP_', 'MODEL_', 'MEMORY_', 'OTEL_', 'TELEMETRY_', 'MELCHIZEDEK_',
+    'GOOGLE_', 'GEMINI_', 'ANTHROPIC_', 'OPENAI_', 'AZURE_', 'AWS_', 'XAI_', 'MOONSHOT_', 'OLLAMA_', 'WIKI_',
+    'ALLOW_', 'OPENAPI_',
+];
+const FRAMEWORK_ENV_NAMES = new Set(['PUBLIC_URL', 'HOST', 'PORT', 'PATH', 'HOME', 'NODE_OPTIONS', 'WEB_EXTRACT_CHAR_LIMIT']);
+/**
+ * Why an `auth` may not read this variable, or null. With
+ * OPENAPI_CREDENTIAL_ENVS set, only the names it lists are allowed; without
+ * it, anything but the framework's own variables is.
+ */
+export function credentialEnvProblem(name, env = process.env) {
+    const allow = env.OPENAPI_CREDENTIAL_ENVS?.split(',').map((s) => s.trim()).filter(Boolean);
+    if (allow?.length) {
+        return allow.includes(name) ? null : `${name} is not in OPENAPI_CREDENTIAL_ENVS (${allow.join(', ')})`;
+    }
+    if (FRAMEWORK_ENV_NAMES.has(name) || FRAMEWORK_ENV_PREFIXES.some((p) => name.startsWith(p))) {
+        return `${name} is one of the framework's own settings and may not be sent to an API; give the API its own variable (or list it in OPENAPI_CREDENTIAL_ENVS)`;
+    }
+    return null;
+}
+function credentialFor(auth, spec) {
+    if (!auth)
+        return {};
+    const read = (env) => {
+        const refused = credentialEnvProblem(env);
+        if (refused)
+            throw new Error(`openapi ${spec}: ${refused}`);
+        const value = process.env[env]?.trim();
+        if (!value)
+            throw new Error(`openapi ${spec}: ${env} is not set (auth reads it from the environment)`);
+        return value;
+    };
+    if (auth.bearer_env) {
+        const [authScheme, authCredential] = tokenToSchemeCredential('oauth2Token', undefined, undefined, read(auth.bearer_env));
+        return { authScheme, authCredential };
+    }
+    if (auth.api_key) {
+        const [authScheme, authCredential] = tokenToSchemeCredential('apikey', auth.api_key.in, auth.api_key.name, read(auth.api_key.env));
+        return { authScheme, authCredential };
+    }
+    return {};
+}
+/**
+ * Where an API call may be redirected: the server's own rule on its origin,
+ * the full guard (no development exception) anywhere else.
+ */
+const REDIRECTS = {
+    async hopProblem(url, crossOrigin) {
+        if (!/^https?:$/.test(url.protocol))
+            return `${url.protocol} is not http(s)`;
+        if (!crossOrigin)
+            return hostProblem(url.href, true);
+        const reason = await checkHost(url.hostname);
+        return reason ? `refusing ${url.hostname}: ${reason}` : null;
+    },
+};
+/** Cut an API result to MAX_RESULT_CHARS, saying so. */
+export function boundResult(result) {
+    const text = typeof result === 'string' ? result : JSON.stringify(result ?? null);
+    if (text.length <= MAX_RESULT_CHARS)
+        return result;
+    return { truncated: true, text: `${text.slice(0, MAX_RESULT_CHARS)}… [cut at ${MAX_RESULT_CHARS} characters]` };
+}
+/**
+ * The tools one `openapi:` entry gives an agent. Throws (failing the compile)
+ * on a missing spec, an unset auth variable, an operation the spec does not
+ * have, or a server the guard refuses.
+ */
+export async function buildOpenApiTools(entry, baseDir = process.cwd()) {
+    const specPath = resolve(baseDir, entry.spec);
+    if (!existsSync(specPath))
+        throw new Error(`openapi: spec not found: ${entry.spec}`);
+    const ext = extname(specPath).toLowerCase();
+    if (!['.yaml', '.yml', '.json'].includes(ext))
+        throw new Error(`openapi ${entry.spec}: a spec is .yaml, .yml or .json`);
+    const toolset = new OpenAPIToolset({
+        specStr: readFileSync(specPath, 'utf-8'),
+        specType: ext === '.json' ? 'json' : 'yaml',
+        ...(entry.prefix ? { prefix: entry.prefix } : {}),
+        ...credentialFor(entry.auth, entry.spec),
+    });
+    const all = (await toolset.getTools());
+    let chosen;
+    if (entry.operations?.length) {
+        const unknown = entry.operations.filter((op) => !all.some((t) => namesTool(op, t) || namesTool(op, { name: t.name.replace(`${entry.prefix}_`, ''), operation: t.operation })));
+        if (unknown.length) {
+            throw new Error(`openapi ${entry.spec}: no operation ${unknown.map((u) => `'${u}'`).join(', ')} (the spec has ${all.map((t) => t.operation?.operationId ?? t.name).join(', ')})`);
+        }
+        chosen = all.filter((t) => entry.operations.some((op) => namesTool(op, t) || namesTool(op, { name: t.name.replace(`${entry.prefix}_`, ''), operation: t.operation })));
+    }
+    else {
+        chosen = all.filter((t) => t.endpoint.method.toLowerCase() === 'get');
+    }
+    if (entry.base_url)
+        for (const t of chosen)
+            t.endpoint.baseUrl = entry.base_url;
+    for (const baseUrl of new Set(chosen.map((t) => t.endpoint.baseUrl))) {
+        if (!baseUrl)
+            throw new Error(`openapi ${entry.spec}: the spec names no server; set base_url`);
+        const problem = await hostProblem(baseUrl, false);
+        if (problem)
+            throw new Error(`openapi ${entry.spec}: ${problem}`);
+    }
+    return chosen.map(guarded);
+}
+/**
+ * A copy of a generated tool whose call re-checks its host, follows
+ * redirects only where the guard allows, catches a network failure, and
+ * bounds the result. The original is untouched.
+ */
+function guarded(tool) {
+    const copy = Object.create(tool);
+    const original = tool.runAsync.bind(tool);
+    Object.defineProperty(copy, OPENAPI_TOOL, { value: true });
+    Object.defineProperty(copy, 'runAsync', {
+        value: async (request) => {
+            const problem = await hostProblem(tool.endpoint.baseUrl, true);
+            if (problem)
+                return { error: `${tool.name} was not called: ${problem}` };
+            try {
+                return boundResult(await withRedirectGuard(REDIRECTS, () => original(request)));
+            }
+            catch (err) {
+                return { error: `${tool.name} failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+        },
+    });
+    return copy;
+}
+/** True for a tool built from an `openapi:` entry. */
+export function isOpenApiTool(tool) {
+    return !!tool && typeof tool === 'object' && tool[OPENAPI_TOOL] === true;
+}

package/dist/lib/tools/skillToolset.d.ts

@@ -0,0 +1,135 @@
+/**
+ * lib/tools/skillToolset.ts — Agent Skills for a syndicate agent, the way a
+ * coding harness holds them.
+ *
+ * WHY this file exists:
+ *   A coding harness (Claude Code, Codex, Gemini CLI) keeps every installed
+ *   skill's frontmatter in its system prompt, reads a SKILL.md in full only
+ *   when a request matches its description, opens the files a skill ships
+ *   only when the procedure reaches them, and runs the scripts a skill
+ *   ships. ADK 2.2 carries the mechanism (`SkillToolset`, `loadAllSkillsInDir`,
+ *   the open SKILL.md standard's layout: SKILL.md + references/, assets/,
+ *   scripts/). Three things it does not do, this file does:
+ *
+ *   1. INJECT THE INDEX. ADK's TypeScript port never calls the toolset's own
+ *      request hook, so `<available_skills>` would reach the model only
+ *      through a `list_skills` call. `skillsInstruction()` renders the index
+ *      once at compile time and lib/compile.ts appends it to the agent's
+ *      instruction: no round trip, always in view.
+ *   2. KEEP DISCLOSURE PROGRESSIVE. ADK's `load_skill` returns every
+ *      resource's full content with the instructions. `LeanLoadSkillTool`
+ *      returns the instructions and the resources' NAMES; `load_skill_resource`
+ *      reads one when the procedure asks.
+ *   3. GATE EVERY SCRIPT RUN. ADK's `run_skill_script` runs when called.
+ *      `GatedRunSkillScriptTool` asks for a person's approval first through
+ *      the same confirmation interrupt `require_approval` uses (ADR 0028),
+ *      so the turn pauses `input-required` and resumes on approve or reject.
+ *
+ *   `allowed-tools` in a skill's frontmatter is honoured through ADK's
+ *   activation mechanism: once the skill is loaded, the tools it names
+ *   become callable, provided the agent's YAML listed them under
+ *   `skills.tools`. Exposure stays two deliberate acts (the skill names the
+ *   tool, the YAML permits it); a skill cannot grant itself a tool the YAML
+ *   withheld.
+ *
+ * WHAT RUNS: only scripts shipped in a skill's `scripts/` directory, through
+ *   ADK's local executor (`skills.scripts: local`), after approval. The
+ *   model's own code never executes: the executor is handed to the toolset,
+ *   never to the agent, so ADK's code-block execution stays off. ADK's
+ *   container executor cannot stage a skill's files yet, so it is not offered.
+ *
+ * FAILURE CONTRACT: a missing skills directory fails the compile (an agent
+ *   running without the skills it was declared with would be a silent
+ *   defect). Inside a turn, the ADK tools return `{ error }` objects the
+ *   model can read, never throw.
+ */
+import type { FunctionDeclaration } from '@google/genai';
+import { BaseTool, RunSkillScriptTool, SkillToolset } from '@google/adk';
+import type { ReadonlyContext, RunAsyncToolRequest } from '@google/adk';
+/** What an agent's YAML `skills:` block may say. */
+export interface SkillsConfig {
+    /** A directory of skills, one subdirectory each holding a SKILL.md. Relative to the working directory. */
+    dir: string;
+    /** Whether a skill's `scripts/` may run. `local` runs them on this host, each after a person approves. */
+    scripts?: 'none' | 'local';
+    /** Registry tool names a skill may unlock through its `allowed-tools` frontmatter, once loaded. */
+    tools?: string[];
+}
+/** ADK's Skill, as this module reads it (the type is not exported from the package index). */
+export interface LoadedSkill {
+    frontmatter: {
+        name: string;
+        description: string;
+        allowedTools?: string;
+        metadata?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    instructions: string;
+    resources?: {
+        references?: Record<string, unknown>;
+        assets?: Record<string, unknown>;
+        scripts?: Record<string, unknown>;
+    };
+}
+/** Seconds a skill script may run before the local executor kills it. */
+export declare const SCRIPT_TIMEOUT_SECONDS = 120;
+/**
+ * Load every skill under `dir` (ADK's loader: a skill is a directory whose
+ * name equals its frontmatter `name`, holding a SKILL.md with a description;
+ * an invalid skill is skipped with ADK's warning). A directory that does
+ * not exist is an error: the YAML declared skills this agent cannot have.
+ */
+export declare function loadSkillSuite(dir: string): Promise<Record<string, LoadedSkill>>;
+/**
+ * Why a skill directory under `dir` was NOT loaded: ADK skips an invalid
+ * skill with a log line the operator may never see, so the compiler reports
+ * each one. A candidate is a subdirectory holding a SKILL.md.
+ */
+export declare function skillSuiteProblems(dir: string): Promise<string[]>;
+/**
+ * The block lib/compile.ts appends to an agent's instruction: the frontmatter
+ * index every request sees, and the names of the tools that read and run a
+ * skill. The ORDER of use (read before following, cite, when to run a
+ * script) is the YAML instruction's to state; this block only says what
+ * exists.
+ */
+export declare function skillsInstruction(skills: Record<string, LoadedSkill>, config: SkillsConfig): string;
+/**
+ * ADK's `load_skill`, minus the resource dump: the procedure in full, the
+ * frontmatter, and the names of the files the skill ships. Loading also
+ * activates the skill for the agent (ADK's state key), which is what unlocks
+ * its `allowed-tools`.
+ */
+export declare class LeanLoadSkillTool extends BaseTool {
+    private readonly toolset;
+    constructor(toolset: SkillToolset);
+    _getDeclaration(): FunctionDeclaration;
+    runAsync({ args, toolContext }: RunAsyncToolRequest): Promise<unknown>;
+}
+/**
+ * ADK's `run_skill_script` behind a person's approval: the first call raises
+ * the confirmation interrupt (the hint names the skill, the script and the
+ * arguments) and returns without running; the resumed call runs only when
+ * the answer confirmed it. Mirrors FunctionTool's own gate, so the turn
+ * runner and the A2A server treat it exactly as `require_approval` (ADR 0028).
+ */
+export declare class GatedRunSkillScriptTool extends RunSkillScriptTool {
+    runAsync(request: RunAsyncToolRequest): Promise<unknown>;
+}
+/**
+ * The toolset an agent with `skills:` carries. `list_skills` is left out
+ * (the index is in the instruction); `load_skill` is the lean one;
+ * `run_skill_script` is present, gated, only when scripts may run.
+ */
+export declare class HarnessSkillToolset extends SkillToolset {
+    private readonly harnessTools;
+    constructor(skills: Record<string, LoadedSkill>, config: SkillsConfig, additionalTools?: unknown[]);
+    getTools(context?: ReadonlyContext): Promise<BaseTool[]>;
+}
+/** Build the toolset and its instruction block for one agent. */
+export declare function buildSkillHarness(config: SkillsConfig, additionalTools: unknown[]): Promise<{
+    toolset: HarnessSkillToolset;
+    instruction: string;
+    skills: Record<string, LoadedSkill>;
+    problems: string[];
+}>;

package/dist/lib/tools/skillToolset.js

@@ -0,0 +1,247 @@
+/**
+ * lib/tools/skillToolset.ts — Agent Skills for a syndicate agent, the way a
+ * coding harness holds them.
+ *
+ * WHY this file exists:
+ *   A coding harness (Claude Code, Codex, Gemini CLI) keeps every installed
+ *   skill's frontmatter in its system prompt, reads a SKILL.md in full only
+ *   when a request matches its description, opens the files a skill ships
+ *   only when the procedure reaches them, and runs the scripts a skill
+ *   ships. ADK 2.2 carries the mechanism (`SkillToolset`, `loadAllSkillsInDir`,
+ *   the open SKILL.md standard's layout: SKILL.md + references/, assets/,
+ *   scripts/). Three things it does not do, this file does:
+ *
+ *   1. INJECT THE INDEX. ADK's TypeScript port never calls the toolset's own
+ *      request hook, so `<available_skills>` would reach the model only
+ *      through a `list_skills` call. `skillsInstruction()` renders the index
+ *      once at compile time and lib/compile.ts appends it to the agent's
+ *      instruction: no round trip, always in view.
+ *   2. KEEP DISCLOSURE PROGRESSIVE. ADK's `load_skill` returns every
+ *      resource's full content with the instructions. `LeanLoadSkillTool`
+ *      returns the instructions and the resources' NAMES; `load_skill_resource`
+ *      reads one when the procedure asks.
+ *   3. GATE EVERY SCRIPT RUN. ADK's `run_skill_script` runs when called.
+ *      `GatedRunSkillScriptTool` asks for a person's approval first through
+ *      the same confirmation interrupt `require_approval` uses (ADR 0028),
+ *      so the turn pauses `input-required` and resumes on approve or reject.
+ *
+ *   `allowed-tools` in a skill's frontmatter is honoured through ADK's
+ *   activation mechanism: once the skill is loaded, the tools it names
+ *   become callable, provided the agent's YAML listed them under
+ *   `skills.tools`. Exposure stays two deliberate acts (the skill names the
+ *   tool, the YAML permits it); a skill cannot grant itself a tool the YAML
+ *   withheld.
+ *
+ * WHAT RUNS: only scripts shipped in a skill's `scripts/` directory, through
+ *   ADK's local executor (`skills.scripts: local`), after approval. The
+ *   model's own code never executes: the executor is handed to the toolset,
+ *   never to the agent, so ADK's code-block execution stays off. ADK's
+ *   container executor cannot stage a skill's files yet, so it is not offered.
+ *
+ * FAILURE CONTRACT: a missing skills directory fails the compile (an agent
+ *   running without the skills it was declared with would be a silent
+ *   defect). Inside a turn, the ADK tools return `{ error }` objects the
+ *   model can read, never throw.
+ */
+import { readdirSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Type } from '@google/genai';
+import { BaseTool, LoadSkillResourceTool, RunSkillScriptTool, SkillToolset, UnsafeLocalCodeExecutor, loadAllSkillsInDir, validateSkillDir, } from '@google/adk';
+/** Seconds a skill script may run before the local executor kills it. */
+export const SCRIPT_TIMEOUT_SECONDS = 120;
+/**
+ * Load every skill under `dir` (ADK's loader: a skill is a directory whose
+ * name equals its frontmatter `name`, holding a SKILL.md with a description;
+ * an invalid skill is skipped with ADK's warning). A directory that does
+ * not exist is an error: the YAML declared skills this agent cannot have.
+ */
+export async function loadSkillSuite(dir) {
+    const abs = resolve(dir);
+    let real;
+    try {
+        real = realpathSync(abs);
+        readdirSync(real);
+    }
+    catch {
+        throw new Error(`skills: directory not found or unreadable: ${dir}`);
+    }
+    const skills = (await loadAllSkillsInDir(real));
+    for (const skill of Object.values(skills))
+        honourAllowedTools(skill);
+    return skills;
+}
+/**
+ * Why a skill directory under `dir` was NOT loaded: ADK skips an invalid
+ * skill with a log line the operator may never see, so the compiler reports
+ * each one. A candidate is a subdirectory holding a SKILL.md.
+ */
+export async function skillSuiteProblems(dir) {
+    const real = realpathSync(resolve(dir));
+    const out = [];
+    for (const entry of readdirSync(real, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillDir = resolve(real, entry.name);
+        if (!readdirSync(skillDir).some((f) => f.toLowerCase() === 'skill.md'))
+            continue;
+        for (const problem of await validateSkillDir(skillDir))
+            out.push(`${entry.name}: ${problem.split('\n')[0]}`);
+    }
+    return out;
+}
+/**
+ * The open standard's `allowed-tools` (a space- or comma-separated list of
+ * tool names) becomes ADK's `metadata.adk_additional_tools`, which is what
+ * the toolset reads when the skill is loaded. A skill that already set the
+ * ADK field keeps it.
+ */
+function honourAllowedTools(skill) {
+    const fm = skill.frontmatter;
+    const declared = typeof fm.allowedTools === 'string' ? fm.allowedTools : typeof fm['allowed-tools'] === 'string' ? fm['allowed-tools'] : '';
+    const names = declared.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+    if (names.length === 0)
+        return;
+    fm.metadata = { ...(fm.metadata ?? {}) };
+    if (!Array.isArray(fm.metadata.adk_additional_tools))
+        fm.metadata.adk_additional_tools = names;
+}
+function escapeXml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/**
+ * The block lib/compile.ts appends to an agent's instruction: the frontmatter
+ * index every request sees, and the names of the tools that read and run a
+ * skill. The ORDER of use (read before following, cite, when to run a
+ * script) is the YAML instruction's to state; this block only says what
+ * exists.
+ */
+export function skillsInstruction(skills, config) {
+    const entries = Object.values(skills).sort((a, b) => a.frontmatter.name.localeCompare(b.frontmatter.name));
+    const index = entries.length === 0
+        ? '<available_skills>\n</available_skills>'
+        : [
+            '<available_skills>',
+            ...entries.flatMap((s) => [
+                '  <skill>',
+                `    <name>${escapeXml(s.frontmatter.name)}</name>`,
+                `    <description>${escapeXml(s.frontmatter.description.trim())}</description>`,
+                '  </skill>',
+            ]),
+            '</available_skills>',
+        ].join('\n');
+    const scripts = config.scripts === 'local';
+    const lines = [
+        'Skills are installed procedures, one directory each: a SKILL.md with the procedure, and optionally references/, assets/ and scripts/. The index below lists every installed skill by name and description; it is complete, so never call a tool to list skills.',
+        'load_skill(name) returns a skill\'s full SKILL.md and the names of the files it ships. load_skill_resource(skill_name, path) returns one of those files ("references/x.md", "assets/x.yaml", "scripts/x.sh").',
+        scripts
+            ? 'run_skill_script(skill_name, script_path, args) runs a script from a skill\'s scripts/ directory on this machine. Every run waits for the user\'s approval before it executes; when a run is refused, say so and do not retry it.'
+            : 'Scripts in a skill\'s scripts/ directory cannot run here; when a procedure says to run one, give the user the exact command instead.',
+        index,
+    ];
+    return lines.join('\n\n');
+}
+function resourceNames(skill) {
+    const out = [];
+    for (const [dir, files] of Object.entries(skill.resources ?? {})) {
+        for (const name of Object.keys(files ?? {}))
+            out.push(`${dir}/${name}`);
+    }
+    return out.sort();
+}
+/**
+ * ADK's `load_skill`, minus the resource dump: the procedure in full, the
+ * frontmatter, and the names of the files the skill ships. Loading also
+ * activates the skill for the agent (ADK's state key), which is what unlocks
+ * its `allowed-tools`.
+ */
+export class LeanLoadSkillTool extends BaseTool {
+    toolset;
+    constructor(toolset) {
+        super({
+            name: 'load_skill',
+            description: 'Read one installed skill in full: its SKILL.md procedure, its frontmatter, and the names of the files it ships. Read a skill before you follow it.',
+        });
+        this.toolset = toolset;
+    }
+    _getDeclaration() {
+        return {
+            name: this.name,
+            description: this.description,
+            parameters: {
+                type: Type.OBJECT,
+                properties: { name: { type: Type.STRING, description: 'The skill\'s name, exactly as the index lists it.' } },
+                required: ['name'],
+            },
+        };
+    }
+    async runAsync({ args, toolContext }) {
+        const name = typeof args.name === 'string' ? args.name.trim() : '';
+        if (!name)
+            return { error: 'Skill name is required.', error_code: 'MISSING_SKILL_NAME' };
+        const skill = this.toolset.getSkill(name);
+        if (!skill) {
+            return { error: `Skill '${name}' not found. Installed: ${Object.keys(this.toolset.skills).sort().join(', ') || '(none)'}.`, error_code: 'SKILL_NOT_FOUND' };
+        }
+        // The same state key ADK's own load_skill sets: SkillToolset reads it to
+        // resolve the skill's additional tools on the next request.
+        const agentName = toolContext.invocationContext.agent?.name ?? toolContext.agentName;
+        const stateKey = `_adk_activated_skill_${agentName}`;
+        const activated = toolContext.state.get(stateKey) ?? [];
+        if (!activated.includes(name))
+            toolContext.state.set(stateKey, [...activated, name]);
+        return { skill_name: name, frontmatter: skill.frontmatter, instructions: skill.instructions, files: resourceNames(skill) };
+    }
+}
+/**
+ * ADK's `run_skill_script` behind a person's approval: the first call raises
+ * the confirmation interrupt (the hint names the skill, the script and the
+ * arguments) and returns without running; the resumed call runs only when
+ * the answer confirmed it. Mirrors FunctionTool's own gate, so the turn
+ * runner and the A2A server treat it exactly as `require_approval` (ADR 0028).
+ */
+export class GatedRunSkillScriptTool extends RunSkillScriptTool {
+    async runAsync(request) {
+        const { args, toolContext } = request;
+        const ctx = toolContext;
+        if (!ctx.toolConfirmation) {
+            const summary = `${String(args.skill_name ?? '?')}: ${String(args.script_path ?? '?')}${args.args ? ` ${JSON.stringify(args.args)}` : ''}`;
+            ctx.requestConfirmation({
+                hint: `Approval is required before a skill script runs on this machine. The agent asks to run ${summary}.`,
+                payload: { skill_name: args.skill_name, script_path: args.script_path, args: args.args ?? {} },
+            });
+            ctx.actions.skipSummarization = true;
+            return { error: 'This script run requires approval, please approve or reject.' };
+        }
+        if (!ctx.toolConfirmation.confirmed)
+            return { error: 'This script run was rejected.' };
+        return super.runAsync(request);
+    }
+}
+/**
+ * The toolset an agent with `skills:` carries. `list_skills` is left out
+ * (the index is in the instruction); `load_skill` is the lean one;
+ * `run_skill_script` is present, gated, only when scripts may run.
+ */
+export class HarnessSkillToolset extends SkillToolset {
+    harnessTools;
+    constructor(skills, config, additionalTools = []) {
+        const codeExecutor = config.scripts === 'local' ? new UnsafeLocalCodeExecutor({ timeoutSeconds: SCRIPT_TIMEOUT_SECONDS }) : undefined;
+        super(skills, { codeExecutor, additionalTools: additionalTools });
+        this.harnessTools = [new LeanLoadSkillTool(this), new LoadSkillResourceTool(this)];
+        if (codeExecutor)
+            this.harnessTools.push(new GatedRunSkillScriptTool(this));
+    }
+    async getTools(context) {
+        // The parent resolves the skills' additional tools from the activation
+        // state; its own fixed tools are replaced by the harness set.
+        const parentTools = await super.getTools(context);
+        const fixed = new Set(['list_skills', 'load_skill', 'load_skill_resource', 'run_skill_script', 'run_skill_inline_script', 'search_skills']);
+        return [...this.harnessTools, ...parentTools.filter((t) => !fixed.has(t.name))];
+    }
+}
+/** Build the toolset and its instruction block for one agent. */
+export async function buildSkillHarness(config, additionalTools) {
+    const skills = await loadSkillSuite(config.dir);
+    const toolset = new HarnessSkillToolset(skills, config, additionalTools);
+    return { toolset, instruction: skillsInstruction(skills, config), skills, problems: await skillSuiteProblems(config.dir) };
+}

package/dist/lib/tools/urlContextTool.d.ts

@@ -0,0 +1,29 @@
+/**
+ * lib/tools/urlContextTool.ts — `url_context`: the model reads the pages
+ * whose URLs appear in the conversation, server-side, on Gemini.
+ *
+ * WHY: ADK's URL_CONTEXT is Gemini's built-in URL reading, and it THROWS for
+ * any other model, which would fail a mixed-provider syndicate at request
+ * time. This is the same tool made safe to declare anywhere, the pattern
+ * web_search uses: on a Gemini model it adds `{ urlContext: {} }` to the
+ * request; on any other it does nothing, and `npm run doctor` reports it as
+ * dropped (lib/models/capabilities.ts). For reading a page on every
+ * provider, declare `web_extract` (client-side, SSRF-guarded).
+ *
+ * Exposure: Google fetches the URLs, not this host, so no address of this
+ * deployment's network is reachable through it. Page text arrives as model
+ * input; treat it as data, as any fetched page.
+ */
+import { BaseTool } from '@google/adk';
+import type { LlmRequest } from '@google/adk';
+export declare const URL_CONTEXT_TOOL_NAME = "url_context";
+export declare class UrlContextTool extends BaseTool {
+    constructor();
+    /** Never a client-side function tool. */
+    _getDeclaration(): undefined;
+    runAsync(): Promise<unknown>;
+    processLlmRequest({ llmRequest }: {
+        llmRequest: LlmRequest;
+    }): Promise<void>;
+}
+export declare const URL_CONTEXT: UrlContextTool;