@sammorrowdrums/mcpi-ext 0.2.0 → 1.0.0

package/dist/routing/facilities.d.ts

@@ -0,0 +1,109 @@
+import type { BridgeInfo } from "@sammorrowdrums/tool-cli/client";
+/**
+ * The model-facing execution facilities mcpi-ext puts in front of an agent.
+ *
+ * An agent has to decide, per task, which surface actually does the work. This
+ * module is the single source of truth for how those surfaces are described:
+ * `buildExecutionFacilities` turns observed session state into a stable ordered
+ * list of descriptors, and every consumer — the prompt fallback and the future
+ * host registration seam — renders from that same list.
+ *
+ * Two rules govern everything here:
+ *
+ * 1. **Task shape, not precedence.** Each facility is described by the kind of
+ *    work it suits. No facility outranks another and none is a default. The
+ *    list is ordered alphabetically by id purely so the emitted bytes are
+ *    stable across turns; the order carries no ranking.
+ * 2. **Availability is always stated.** A facility is never silently dropped.
+ *    An unavailable facility is still listed together with the reason, so the
+ *    agent neither attempts it nor invents output it never produced.
+ */
+/** Stable machine identifiers for the four facilities. */
+export type FacilityId = "bash" | "code_mode" | "skills" | "tool_cli";
+/**
+ * Facility order. Alphabetical by id so the rendered section is byte-stable.
+ * This is deliberately not a preference order.
+ */
+export declare const FACILITY_ORDER: readonly FacilityId[];
+/**
+ * Three states, because "we could not tell" is a real answer and is not the
+ * same as "it is not there". Claiming either would be untruthful.
+ */
+export type AvailabilityState = "available" | "unavailable" | "unknown";
+export interface FacilityAvailability {
+    state: AvailabilityState;
+    /** Always populated. The reason for the state, never an empty string. */
+    detail: string;
+}
+export interface ExecutionFacility {
+    id: FacilityId;
+    /** Heading shown to the model. */
+    title: string;
+    /** Intent-first sentence. Always begins with "Use when". */
+    useWhen: string;
+    /** What the facility actually does. */
+    provides: string[];
+    /** What it deliberately cannot do, so the agent does not mis-route to it. */
+    doesNotProvide: string[];
+    availability: FacilityAvailability;
+}
+/** Skills discovered this session, plus the status of the draft extension. */
+export interface SkillsState {
+    count: number;
+    /** Whether the DRAFT, unratified SEP-2640 skills extension is enabled. */
+    draftExtensionEnabled: boolean;
+}
+/**
+ * tool-cli is only advertised after its local bridge completes an authenticated
+ * compatible handshake. Failures remain explicit so the prompt has a next step.
+ */
+export type ToolCliState = {
+    kind: "verified";
+    port: number;
+    bridgeInfo: BridgeInfo;
+} | {
+    kind: "not_started";
+    reason: string;
+} | {
+    kind: "failed";
+    reason: string;
+} | {
+    kind: "incompatible";
+    reason: string;
+} | {
+    kind: "no_bash";
+    reason: string;
+};
+/** Whether the host currently exposes a shell tool, when that is discoverable at all. */
+export type BashState = {
+    kind: "registered";
+    toolName: string;
+} | {
+    kind: "absent";
+} | {
+    kind: "undiscoverable";
+    reason: string;
+};
+export interface ExecutionRoutingState {
+    skills: SkillsState;
+    codeMode: CodeModeState;
+    toolCli: ToolCliState;
+    bash: BashState;
+}
+/**
+ * Code mode needs the optional `isolated-vm` native addon. When that addon is
+ * absent the facility is genuinely unavailable, and `reason` carries the
+ * specific cause so the prompt can say *why* rather than just that it failed.
+ */
+export interface CodeModeState {
+    active: boolean;
+    /** Why code mode is inactive. Ignored when `active` is true. */
+    reason?: string;
+}
+/**
+ * Build the ordered facility descriptors for the current session.
+ *
+ * Pure and deterministic: equal input always yields an equal list in
+ * `FACILITY_ORDER`, so the rendered prompt section is byte-stable.
+ */
+export declare function buildExecutionFacilities(state: ExecutionRoutingState): ExecutionFacility[];

package/dist/routing/facilities.js

@@ -0,0 +1,175 @@
+/**
+ * Facility order. Alphabetical by id so the rendered section is byte-stable.
+ * This is deliberately not a preference order.
+ */
+export const FACILITY_ORDER = ["bash", "code_mode", "skills", "tool_cli"];
+function skillsAvailability(skills) {
+    const draft = skills.draftExtensionEnabled
+        ? "Draft SEP-2640 skills extension: enabled (unratified draft)."
+        : "Draft SEP-2640 skills extension: disabled.";
+    if (skills.count === 0) {
+        return {
+            state: "unavailable",
+            detail: `No MCP skills were discovered this session. ${draft} There is nothing for load_skill to load, so route the task to another facility.`,
+        };
+    }
+    return {
+        state: "available",
+        detail: `${skills.count} MCP skill(s) discovered and loadable by name. ${draft}`,
+    };
+}
+function codeModeAvailability(codeMode) {
+    if (!codeMode.active) {
+        const cause = codeMode.reason?.trim();
+        return {
+            state: "unavailable",
+            detail: cause
+                ? `Code mode is unavailable because ${cause}. code_execute and code_search cannot run; sandboxed execution is never downgraded to an in-process fallback. Route exact computation to bash or tool-cli instead.`
+                : "Code mode did not initialise this session, so code_execute and code_search cannot run.",
+        };
+    }
+    return {
+        state: "available",
+        detail: "Available with zero MCP servers connected — pure computation needs no server, and code_execute is registered whenever mcpi-ext loads.",
+    };
+}
+function toolCliAvailability(toolCli, bash) {
+    if (toolCli.kind === "incompatible") {
+        return {
+            state: "unavailable",
+            detail: `The authenticated tool-cli bridge handshake found an incompatible bridge/client contract: ${toolCli.reason}. TOOL_CLI_PORT and TOOL_CLI_TOKEN were not exposed. Install matching tool-cli and mcpi-ext major versions before retrying.`,
+        };
+    }
+    if (toolCli.kind === "failed") {
+        return {
+            state: "unavailable",
+            detail: `The local tool-cli bridge failed startup or its authenticated handshake: ${toolCli.reason}. MCP tools cannot be reached from the shell this session — use another available facility and report this failure rather than retrying tool-cli blindly.`,
+        };
+    }
+    if (toolCli.kind === "no_bash") {
+        return {
+            state: "unavailable",
+            detail: `The tool-cli bridge was not started because bash availability is required and was not confirmed: ${toolCli.reason}. No bridge credentials were exposed.`,
+        };
+    }
+    if (toolCli.kind === "not_started") {
+        return {
+            state: "unavailable",
+            detail: `The local tool-cli RPC server was not started: ${toolCli.reason}.`,
+        };
+    }
+    const verified = `The local tool-cli bridge started on port ${toolCli.port}, completed an authenticated ` +
+        `${toolCli.bridgeInfo.bridgeProtocol.name} v${toolCli.bridgeInfo.bridgeProtocol.version} handshake, ` +
+        `and reported ${toolCli.bridgeInfo.serverImplementation.name}@${toolCli.bridgeInfo.serverImplementation.version}.`;
+    // tool-cli is reached through the shell, so a missing shell tool makes a
+    // healthy RPC server unusable. Saying "available" here would be a lie.
+    if (bash.kind === "absent") {
+        return {
+            state: "unavailable",
+            detail: `${verified} However, no host bash tool is active now, so its credentials are not usable through the required invocation path.`,
+        };
+    }
+    if (bash.kind === "undiscoverable") {
+        return {
+            state: "unavailable",
+            detail: `${verified} However, current bash availability is unconfirmed (${bash.reason}), so tool-cli is not advertised as invocable.`,
+        };
+    }
+    return {
+        state: "available",
+        detail: `${verified} TOOL_CLI_PORT and TOOL_CLI_TOKEN are set for commands run with the "${bash.toolName}" tool.`,
+    };
+}
+function bashAvailability(bash) {
+    switch (bash.kind) {
+        case "registered":
+            return {
+                state: "available",
+                detail: `The host "${bash.toolName}" tool is active this session.`,
+            };
+        case "absent":
+            return {
+                state: "unavailable",
+                detail: "No host shell tool is active this session, so shell commands, external programs, and tool-cli cannot run.",
+            };
+        case "undiscoverable":
+            return {
+                state: "unknown",
+                detail: `The host tool registry could not be read (${bash.reason}), so shell availability is unconfirmed. Try the command you need and treat a failure as absence rather than assuming either way.`,
+            };
+    }
+}
+/**
+ * Build the ordered facility descriptors for the current session.
+ *
+ * Pure and deterministic: equal input always yields an equal list in
+ * `FACILITY_ORDER`, so the rendered prompt section is byte-stable.
+ */
+export function buildExecutionFacilities(state) {
+    return [
+        {
+            id: "bash",
+            title: "bash and external programs",
+            useWhen: "Use when the task touches the real machine: reading or writing files, running git, package managers, compilers, formatters or test runners, moving data between programs, or producing an artifact that has to exist on disk afterwards.",
+            provides: [
+                "The host bash tool, which runs real shell commands with filesystem, network, and process access.",
+                "Every external program installed on the host, composed with pipes, redirection, loops, globs, and exit codes.",
+                "The substrate the other facilities lack: this is the only facility that can create, modify, or inspect files and artifacts.",
+            ],
+            doesNotProvide: [
+                "MCP tool access on its own — reaching an MCP tool from the shell is the tool-cli facility, itself run as a bash command.",
+                "A sandbox. Commands run with the host's real permissions and their effects persist.",
+            ],
+            availability: bashAvailability(state.bash),
+        },
+        {
+            id: "code_mode",
+            title: "Code mode (code_execute, code_search)",
+            useWhen: "Use when the task needs exact computation or control flow: arithmetic, date maths, parsing, filtering, aggregation, pagination loops, or joining results — anywhere an approximated answer would simply be wrong.",
+            provides: [
+                "code_execute, which runs vanilla JavaScript in a sandboxed V8 isolate and returns the value you return.",
+                "code_search, which queries the MCP tool catalogue so you can find dispatchable tools before writing code.",
+                "Read-only MCP tools dispatched from inside the sandbox through the codemode namespace, so one execution can loop over many calls.",
+            ],
+            doesNotProvide: [
+                "Filesystem access. There is no fs, no file read or write, and no path the isolate can reach.",
+                "Network access. There is no fetch, no sockets, and no outbound request of any kind.",
+                "Process access. There is no process, no require, no import, and no child process.",
+                "Non-read-only MCP tools, which are refused inside the sandbox rather than prompted for.",
+            ],
+            availability: codeModeAvailability(state.codeMode),
+        },
+        {
+            id: "skills",
+            title: "Skills (load_skill)",
+            useWhen: "Use when the task is a domain workflow an MCP server has already documented — a named procedure with its own sequencing, conventions, and curated tool set, such as a triage runbook or a release checklist.",
+            provides: [
+                "Workflow guidance authored by the server: the skill body, loaded on demand by name with load_skill.",
+                "The specific tools that skill declares, enabled only after you approve the grant.",
+            ],
+            doesNotProvide: [
+                "Computation, filesystem access, or shell access.",
+                "Authority over tools the skill did not declare; loading a skill never widens access beyond its approved list.",
+                "Anything at all before approval — a declined or unavailable approval leaves every gated tool locked.",
+            ],
+            availability: skillsAvailability(state.skills),
+        },
+        {
+            id: "tool_cli",
+            title: "tool-cli (MCP-to-shell on-ramp)",
+            useWhen: "Use when you need to reach a specific MCP tool directly and no documented skill covers the task, or when you want to discover which servers and tools exist before committing to an approach.",
+            provides: [
+                "An authenticated command-line on-ramp to the same MCP tools the host already authorises, invoked through the host bash tool as `tool-cli ...`.",
+                "Progressive discovery: servers, then a server's tools, then one tool's schema, so you read only what you need.",
+                "Policy-authorized MCP resource listing, templates, and reads, including binary output written with `--out`.",
+                "Plain text and JSON on stdout, so results compose with jq, grep, pipes, and loops inside the same bash command.",
+            ],
+            doesNotProvide: [
+                "A tool of its own. tool-cli is a program you run with the bash tool, never something you call directly.",
+                "Any authority the host has not already granted — every call is re-authorised before it reaches a server.",
+                "Access to `skill://` resources, which remain isolated behind skill discovery and load_skill.",
+            ],
+            availability: toolCliAvailability(state.toolCli, state.bash),
+        },
+    ];
+}

package/dist/routing/format.d.ts

@@ -0,0 +1,24 @@
+import { type ExecutionFacility, type ExecutionRoutingState } from "./facilities.js";
+/**
+ * Tag for the routing section. Named `execution_routing` rather than anything
+ * that reads like an invocable surface, so the model never mistakes the section
+ * itself for something it can call.
+ */
+export declare const EXECUTION_ROUTING_TAG = "execution_routing";
+/**
+ * Render an already-built facility list.
+ *
+ * Kept separate from {@link formatExecutionRouting} so the future host seam and
+ * the prompt fallback can render byte-identical text from one descriptor list.
+ */
+export declare function formatExecutionFacilities(facilities: readonly ExecutionFacility[]): string;
+/**
+ * Render the execution routing section for the current session.
+ *
+ * Emitted whenever mcpi-ext loads, including with zero MCP servers connected —
+ * an agent still needs to know that exact computation and the shell are on the
+ * table, and why the MCP-backed facilities are not.
+ *
+ * Deterministic: equal state always produces byte-identical output.
+ */
+export declare function formatExecutionRouting(state: ExecutionRoutingState): string;

package/dist/routing/format.js

@@ -0,0 +1,64 @@
+import { buildExecutionFacilities, } from "./facilities.js";
+/**
+ * Tag for the routing section. Named `execution_routing` rather than anything
+ * that reads like an invocable surface, so the model never mistakes the section
+ * itself for something it can call.
+ */
+export const EXECUTION_ROUTING_TAG = "execution_routing";
+const PREAMBLE = [
+    "This session exposes four execution facilities. They differ by the *shape* of the work, not by",
+    "rank: none of them is a default, none outranks another, and there is no sequence to try them in.",
+    "Match the facility to what the task actually requires.",
+    "",
+    "Every facility below states its own availability. Treat an unavailable facility as absent for",
+    "this session: do not invoke it, and never describe or summarise output it did not produce.",
+];
+const COMPOSITION = [
+    "### Composing facilities",
+    "",
+    "One task may need more than one facility. tool-cli and bash compose especially closely: tool-cli",
+    "*is* a program you run with the bash tool, so fetching MCP data and then filtering, joining, or",
+    "writing it to disk with ordinary shell programs is a single bash command rather than two rival",
+    "approaches. Code mode composes by handing you an exact value you then act on elsewhere, and a",
+    "skill composes by telling you which tools its workflow expects you to use.",
+];
+function formatFacility(facility) {
+    const lines = [`### ${facility.title}`, "", facility.useWhen, "", "Provides:"];
+    for (const item of facility.provides) {
+        lines.push(`- ${item}`);
+    }
+    lines.push("", "Does not provide:");
+    for (const item of facility.doesNotProvide) {
+        lines.push(`- ${item}`);
+    }
+    lines.push("", `Availability: ${facility.availability.state} — ${facility.availability.detail}`);
+    return lines;
+}
+/**
+ * Render an already-built facility list.
+ *
+ * Kept separate from {@link formatExecutionRouting} so the future host seam and
+ * the prompt fallback can render byte-identical text from one descriptor list.
+ */
+export function formatExecutionFacilities(facilities) {
+    const lines = ["", "", `<${EXECUTION_ROUTING_TAG}>`, "## Execution routing", ""];
+    lines.push(...PREAMBLE, "");
+    for (const facility of facilities) {
+        lines.push(...formatFacility(facility), "");
+    }
+    lines.push(...COMPOSITION);
+    lines.push(`</${EXECUTION_ROUTING_TAG}>`);
+    return lines.join("\n");
+}
+/**
+ * Render the execution routing section for the current session.
+ *
+ * Emitted whenever mcpi-ext loads, including with zero MCP servers connected —
+ * an agent still needs to know that exact computation and the shell are on the
+ * table, and why the MCP-backed facilities are not.
+ *
+ * Deterministic: equal state always produces byte-identical output.
+ */
+export function formatExecutionRouting(state) {
+    return formatExecutionFacilities(buildExecutionFacilities(state));
+}

package/dist/routing/index.d.ts

@@ -0,0 +1,4 @@
+export { buildExecutionFacilities, FACILITY_ORDER, type AvailabilityState, type BashState, type CodeModeState, type ExecutionFacility, type ExecutionRoutingState, type FacilityAvailability, type FacilityId, type SkillsState, type ToolCliState, } from "./facilities.js";
+export { EXECUTION_ROUTING_TAG, formatExecutionFacilities, formatExecutionRouting, } from "./format.js";
+export { publishExecutionFacilities, supportsExecutionFacilityRegistration, type ExecutionFacilityRegistrar, } from "./seam.js";
+export { detectToolCliTripwires, type AssistantTurn, type ObservedToolCall, type TripwireCode, type TripwireFinding, type TripwireOptions, } from "./tripwire.js";

package/dist/routing/index.js

@@ -0,0 +1,4 @@
+export { buildExecutionFacilities, FACILITY_ORDER, } from "./facilities.js";
+export { EXECUTION_ROUTING_TAG, formatExecutionFacilities, formatExecutionRouting, } from "./format.js";
+export { publishExecutionFacilities, supportsExecutionFacilityRegistration, } from "./seam.js";
+export { detectToolCliTripwires, } from "./tripwire.js";

package/dist/routing/seam.d.ts

@@ -0,0 +1,35 @@
+import type { ExecutionFacility } from "./facilities.js";
+/**
+ * Narrow feature-detection seam for a future mcpi core capability.
+ *
+ * If mcpi core ever grows `registerExecutionFacility`, the host owns rendering
+ * and ordering of execution-facility guidance and mcpi-ext should hand over
+ * structured descriptors instead of appending its own prompt section. Until
+ * then — and mcpi core does not expose this today — the fallback in
+ * `before_agent_start` renders the same descriptors itself.
+ *
+ * The two paths are mutually exclusive by construction, so a host that gains
+ * the API cannot end up with the section twice.
+ *
+ * This file deliberately contains no type assertions: the guard narrows with
+ * `in` plus a `typeof` check, so a host that merely happens to carry a
+ * non-function property of the same name is correctly rejected.
+ */
+export interface ExecutionFacilityRegistrar {
+    registerExecutionFacility(facility: ExecutionFacility): void;
+}
+/**
+ * True when the host implements the (not-yet-existing) registration API.
+ *
+ * Narrowing without a cast: `in` refines the object type, and the `typeof`
+ * check proves the member is callable before we treat it as such.
+ */
+export declare function supportsExecutionFacilityRegistration<T extends object>(host: T): host is T & ExecutionFacilityRegistrar;
+/**
+ * Hand the facility descriptors to the host if it can take them.
+ *
+ * Returns `true` when the host consumed them — in which case the caller must
+ * not also emit the fallback prompt section. Returns `false` when the API is
+ * absent, which is the current state of every shipped mcpi core.
+ */
+export declare function publishExecutionFacilities(host: object, facilities: readonly ExecutionFacility[]): boolean;

package/dist/routing/seam.js

@@ -0,0 +1,28 @@
+/**
+ * True when the host implements the (not-yet-existing) registration API.
+ *
+ * Narrowing without a cast: `in` refines the object type, and the `typeof`
+ * check proves the member is callable before we treat it as such.
+ */
+export function supportsExecutionFacilityRegistration(host) {
+    if (!("registerExecutionFacility" in host)) {
+        return false;
+    }
+    return typeof host.registerExecutionFacility === "function";
+}
+/**
+ * Hand the facility descriptors to the host if it can take them.
+ *
+ * Returns `true` when the host consumed them — in which case the caller must
+ * not also emit the fallback prompt section. Returns `false` when the API is
+ * absent, which is the current state of every shipped mcpi core.
+ */
+export function publishExecutionFacilities(host, facilities) {
+    if (!supportsExecutionFacilityRegistration(host)) {
+        return false;
+    }
+    for (const facility of facilities) {
+        host.registerExecutionFacility(facility);
+    }
+    return true;
+}

package/dist/routing/tripwire.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Anti-hallucination tripwire for tool-cli.
+ *
+ * tool-cli is a program, not a callable tool. The failure mode this guards
+ * against is an agent that "invokes" it by writing markup or a shell transcript
+ * into its own message and then narrates output that no process ever produced.
+ * Both halves are wrong, and both are cheap to detect: a real invocation always
+ * leaves a bash tool call whose command mentions `tool-cli`.
+ *
+ * The detector is deliberately strict. Mentioning the `<tool_cli_usage_docs>`
+ * tag in prose without a real call trips it, because that is exactly the
+ * confusion — treating the documentation tag as an invocation syntax — the
+ * routing prompt is written to prevent.
+ */
+/** A tool call as observed on an assistant turn. */
+export interface ObservedToolCall {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/** The assistant output under inspection. */
+export interface AssistantTurn {
+    text: string;
+    toolCalls?: readonly ObservedToolCall[];
+}
+export type TripwireCode = "tool_cli_pseudo_call" | "tool_cli_narrated_without_bash";
+export interface TripwireFinding {
+    code: TripwireCode;
+    /** The offending excerpt, so a failure message can point at it. */
+    evidence: string;
+    message: string;
+}
+export interface TripwireOptions {
+    /** Host tool names that actually execute shell commands. */
+    bashToolNames?: readonly string[];
+}
+/**
+ * Inspect one assistant turn for fabricated tool-cli usage.
+ *
+ * Returns every finding rather than the first, so a regression test can assert
+ * on the specific failure mode instead of just "something was wrong".
+ */
+export declare function detectToolCliTripwires(turn: AssistantTurn, options?: TripwireOptions): TripwireFinding[];

package/dist/routing/tripwire.js

@@ -0,0 +1,80 @@
+/**
+ * Anti-hallucination tripwire for tool-cli.
+ *
+ * tool-cli is a program, not a callable tool. The failure mode this guards
+ * against is an agent that "invokes" it by writing markup or a shell transcript
+ * into its own message and then narrates output that no process ever produced.
+ * Both halves are wrong, and both are cheap to detect: a real invocation always
+ * leaves a bash tool call whose command mentions `tool-cli`.
+ *
+ * The detector is deliberately strict. Mentioning the `<tool_cli_usage_docs>`
+ * tag in prose without a real call trips it, because that is exactly the
+ * confusion — treating the documentation tag as an invocation syntax — the
+ * routing prompt is written to prevent.
+ */
+const DEFAULT_BASH_TOOL_NAMES = ["bash"];
+/** `<tool_cli`, `</tool-cli`, `< tool_cli_usage_docs`, and friends. */
+const PSEUDO_CALL_PATTERN = /<\s*\/?\s*tool[_-]cli[\w-]*/i;
+/**
+ * Lines that read like a shell transcript rather than prose.
+ *
+ * Two shapes qualify, and both are deliberately narrow so ordinary sentences
+ * such as "tool-cli is available this session." are not mistaken for commands:
+ * a line carrying an explicit shell prompt, or a line that opens with the
+ * program and goes on to use recognisably CLI syntax — a flag, a quoted
+ * argument, or a JSON brace.
+ */
+const NARRATED_INVOCATION_PATTERNS = [
+    /^[ \t]*[$>][ \t]*tool-cli[ \t]+\S/m,
+    /^[ \t]*tool-cli[ \t]+\S.*(?:--?[A-Za-z]|['"{}])/m,
+];
+function commandOf(call) {
+    const command = call.arguments?.command;
+    return typeof command === "string" ? command : "";
+}
+function hasRealToolCliCall(turn, bashToolNames) {
+    return (turn.toolCalls ?? []).some((call) => bashToolNames.includes(call.name) && commandOf(call).includes("tool-cli"));
+}
+function excerpt(text, pattern) {
+    const match = pattern.exec(text);
+    if (!match) {
+        return "";
+    }
+    const start = Math.max(0, match.index - 20);
+    return text.slice(start, match.index + match[0].length + 60).trim();
+}
+/** The first narration pattern that matches, or undefined when none do. */
+function narratedInvocation(text) {
+    return NARRATED_INVOCATION_PATTERNS.find((pattern) => pattern.test(text));
+}
+/**
+ * Inspect one assistant turn for fabricated tool-cli usage.
+ *
+ * Returns every finding rather than the first, so a regression test can assert
+ * on the specific failure mode instead of just "something was wrong".
+ */
+export function detectToolCliTripwires(turn, options = {}) {
+    const bashToolNames = options.bashToolNames ?? DEFAULT_BASH_TOOL_NAMES;
+    // A genuine invocation clears both tripwires: the agent really did run it, so
+    // whatever it wrote about the command is grounded in a real result.
+    if (hasRealToolCliCall(turn, bashToolNames)) {
+        return [];
+    }
+    const findings = [];
+    if (PSEUDO_CALL_PATTERN.test(turn.text)) {
+        findings.push({
+            code: "tool_cli_pseudo_call",
+            evidence: excerpt(turn.text, PSEUDO_CALL_PATTERN),
+            message: "Assistant text contains tool-cli markup but no bash tool call ran tool-cli. tool-cli is invoked by calling the bash tool with a `tool-cli ...` command, never by emitting XML or text that imitates a call.",
+        });
+    }
+    const narrated = narratedInvocation(turn.text);
+    if (narrated) {
+        findings.push({
+            code: "tool_cli_narrated_without_bash",
+            evidence: excerpt(turn.text, narrated),
+            message: "Assistant text narrates a tool-cli invocation but no bash tool call ran tool-cli, so any output shown was fabricated rather than observed.",
+        });
+    }
+    return findings;
+}

package/dist/skills/discover.d.ts

@@ -0,0 +1,12 @@
+import type { McpPolicy } from "../mcp/policy.js";
+import type { McpSkillMetadata } from "./skill-registry.js";
+/**
+ * Discover skills from a connected MCP server by reading its resources.
+ *
+ * Looks for resources with `skill://` URIs ending in `/SKILL.md`,
+ * reads each one, and parses YAML frontmatter for skill metadata.
+ *
+ * All resource I/O goes through the shared policy boundary, so a server can
+ * only ever surface its own skill resources.
+ */
+export declare function discoverSkillsFromServer(policy: McpPolicy, serverName: string, log?: (msg: string) => void, signal?: AbortSignal): Promise<McpSkillMetadata[]>;