@qvac/harness 0.1.0 → 0.1.2

package/dist-lib/lib/helpers/thinking.d.ts

@@ -0,0 +1,8 @@
+export interface TextEvent {
+    type: 'thinking' | 'content';
+    text: string;
+}
+export interface SplitThinkingOptions {
+    startInThink?: boolean;
+}
+export declare function splitThinking(tokens: AsyncIterable<string>, opts?: SplitThinkingOptions): AsyncGenerator<TextEvent, string | null>;

package/dist-lib/lib/helpers/thinking.js

@@ -0,0 +1,95 @@
+import { firstMarker } from 'asenion/guards';
+import { holdback } from 'asenion/scan';
+import { STOP_MARKERS } from "./control-tokens.js";
+import { createJoinGuard } from "./join-guard.js";
+const OPEN_TAGS = ['<think>', '<thinking>'];
+const CLOSE_TAGS = ['</think>', '</thinking>'];
+const ALL_TAGS = [...OPEN_TAGS, ...CLOSE_TAGS];
+const NEVER_ASSEMBLE = [...ALL_TAGS, ...STOP_MARKERS];
+function findEarliest(buffer, tags) {
+    const found = firstMarker(buffer, tags);
+    return found === null ? null : { idx: found.index, len: found.marker.length };
+}
+export async function* splitThinking(tokens, opts) {
+    let buffer = '';
+    let inThink = opts?.startInThink === true;
+    let unproven = inThink ? '' : null;
+    const guards = {
+        thinking: createJoinGuard(NEVER_ASSEMBLE),
+        content: createJoinGuard(NEVER_ASSEMBLE)
+    };
+    const emit = (type, text) => {
+        const shown = guards[type].push(text);
+        if (!shown)
+            return null;
+        if (type === 'thinking' && unproven !== null)
+            unproven += shown;
+        return { type, text: shown };
+    };
+    for await (const token of tokens) {
+        buffer += token;
+        while (true) {
+            if (inThink) {
+                const open = findEarliest(buffer, OPEN_TAGS);
+                const close = findEarliest(buffer, CLOSE_TAGS);
+                if (open && (!close || open.idx < close.idx)) {
+                    const event = emit('thinking', buffer.slice(0, open.idx));
+                    if (event)
+                        yield event;
+                    guards.thinking.cut();
+                    buffer = buffer.slice(open.idx + open.len);
+                    continue;
+                }
+                if (!close)
+                    break;
+                const event = emit('thinking', buffer.slice(0, close.idx));
+                if (event)
+                    yield event;
+                guards.thinking.cut();
+                buffer = buffer.slice(close.idx + close.len);
+                inThink = false;
+                unproven = null;
+                continue;
+            }
+            const open = findEarliest(buffer, OPEN_TAGS);
+            const close = findEarliest(buffer, CLOSE_TAGS);
+            if (close && (!open || close.idx < open.idx)) {
+                const event = emit('content', buffer.slice(0, close.idx));
+                if (event)
+                    yield event;
+                guards.content.cut();
+                buffer = buffer.slice(close.idx + close.len);
+                continue;
+            }
+            if (open) {
+                const event = emit('content', buffer.slice(0, open.idx));
+                if (event)
+                    yield event;
+                guards.content.cut();
+                buffer = buffer.slice(open.idx + open.len);
+                inThink = true;
+                continue;
+            }
+            break;
+        }
+        const held = holdback(buffer, inThink ? CLOSE_TAGS : ALL_TAGS);
+        if (buffer.length > held) {
+            const event = emit(inThink ? 'thinking' : 'content', buffer.slice(0, buffer.length - held));
+            if (event)
+                yield event;
+            buffer = buffer.slice(buffer.length - held);
+        }
+    }
+    const last = emit(inThink ? 'thinking' : 'content', buffer);
+    if (last)
+        yield last;
+    for (const type of ['thinking', 'content']) {
+        const rest = guards[type].flush();
+        if (!rest)
+            continue;
+        if (type === 'thinking' && unproven !== null)
+            unproven += rest;
+        yield { type, text: rest };
+    }
+    return unproven;
+}

package/dist-lib/lib/helpers/tool-call-markup.d.ts

@@ -0,0 +1,20 @@
+export interface RecoveredToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    raw?: string;
+}
+export declare const MAX_RAW_CALL_CHARS = 4096;
+export declare function clipRawCall(raw: string): string;
+export declare function recoverMarkupToolCalls(text: string, knownTools: ReadonlyArray<{
+    name: string;
+}>): RecoveredToolCall[];
+export declare function stripToolCallMarkup(text: string): string;
+export declare function stripToolResponseBlocks(text: string): string;
+export declare function toolCallMarkup(calls: ReadonlyArray<{
+    name: string;
+    arguments?: Record<string, unknown>;
+}>): string;
+export declare function normalizeToolArgs(args: Record<string, unknown>, declaredKeys: ReadonlyArray<string>): Record<string, unknown>;
+export declare function recoverSkillNamedCall(text: string, skillNames: ReadonlyArray<string>, skillToolName: string): RecoveredToolCall[];
+export declare function recoverPrintedSkillLoad(text: string, skillToolName: string): RecoveredToolCall[];

package/dist-lib/lib/helpers/tool-call-markup.js

@@ -0,0 +1,201 @@
+const FUNCTION_OPEN = '<function=';
+const FUNCTION_CLOSE = '</function>';
+const RESPONSE_OPEN = '<tool_response>';
+const RESPONSE_CLOSE = '</tool_response>';
+const PARAMETER_OPEN = '<parameter=';
+const PARAMETER_CLOSE = '</parameter>';
+const MAX_NAME_LENGTH = 64;
+function* markupBlocks(text, open, close) {
+    let cursor = 0;
+    for (;;) {
+        const start = text.indexOf(open, cursor);
+        if (start === -1)
+            return;
+        const nameStart = start + open.length;
+        cursor = nameStart;
+        const name = nameOf(text, nameStart);
+        if (name === null)
+            continue;
+        const bodyStart = nameStart + name.length + 1;
+        const bodyEnd = text.indexOf(close, bodyStart);
+        if (bodyEnd === -1)
+            return;
+        yield {
+            name: name.trim(),
+            body: text.slice(bodyStart, bodyEnd),
+            start,
+            end: bodyEnd + close.length
+        };
+        cursor = bodyEnd + close.length;
+    }
+}
+function nameOf(text, nameStart) {
+    const window = text.slice(nameStart, nameStart + MAX_NAME_LENGTH + 1);
+    const nameEnd = window.indexOf('>');
+    if (nameEnd === -1)
+        return null;
+    const name = window.slice(0, nameEnd);
+    return name.includes('\n') ? null : name;
+}
+export const MAX_RAW_CALL_CHARS = 4096;
+export function clipRawCall(raw) {
+    return raw.length > MAX_RAW_CALL_CHARS ? raw.slice(0, MAX_RAW_CALL_CHARS) : raw;
+}
+export function recoverMarkupToolCalls(text, knownTools) {
+    const known = new Set(knownTools.map((tool) => tool.name));
+    const calls = [];
+    for (const block of markupBlocks(text, FUNCTION_OPEN, FUNCTION_CLOSE)) {
+        if (!block.name || !known.has(block.name))
+            continue;
+        calls.push({
+            id: `recovered-markup-${calls.length}`,
+            name: block.name,
+            arguments: decodeArguments(block.body),
+            raw: clipRawCall(text.slice(block.start, block.end))
+        });
+    }
+    return calls;
+}
+export function stripToolCallMarkup(text) {
+    let out = '';
+    let cursor = 0;
+    for (const block of markupBlocks(text, FUNCTION_OPEN, FUNCTION_CLOSE)) {
+        out += text.slice(cursor, block.start);
+        cursor = block.end;
+    }
+    out += text.slice(cursor);
+    const dangling = danglingIndex(out);
+    const withoutCalls = dangling === -1 ? out : out.slice(0, dangling);
+    return stripToolResponseBlocks(withoutCalls)
+        .replace(/<\/?(tool_call|tool_response)>/gi, '')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function stripToolResponseBlocks(text) {
+    let out = '';
+    let cursor = 0;
+    for (;;) {
+        const start = text.indexOf(RESPONSE_OPEN, cursor);
+        if (start === -1)
+            break;
+        out += text.slice(cursor, start);
+        const end = text.indexOf(RESPONSE_CLOSE, start + RESPONSE_OPEN.length);
+        if (end === -1)
+            return out;
+        cursor = end + RESPONSE_CLOSE.length;
+    }
+    return out + text.slice(cursor);
+}
+function danglingIndex(text) {
+    let cursor = 0;
+    for (;;) {
+        const start = text.indexOf(FUNCTION_OPEN, cursor);
+        if (start === -1)
+            return -1;
+        const nameStart = start + FUNCTION_OPEN.length;
+        if (nameOf(text, nameStart) !== null)
+            return start;
+        cursor = nameStart;
+    }
+}
+export function toolCallMarkup(calls) {
+    return calls.map(markupForCall).join('\n');
+}
+function markupForCall(call) {
+    const params = Object.entries(call.arguments ?? {})
+        .map(([key, value]) => `<parameter=${key}>${encodeMarkupValue(value)}</parameter>`)
+        .join('');
+    return `<function=${call.name}>${params}</function>`;
+}
+function encodeMarkupValue(value) {
+    return JSON.stringify(value ?? null).replace(/</g, '\\u003c');
+}
+const ARG_WRAPPER_KEYS = new Set(['parameters', 'arguments', 'args', 'input', 'params']);
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function normalizeToolArgs(args, declaredKeys) {
+    const keys = Object.keys(args);
+    if (keys.length !== 1)
+        return args;
+    const only = keys[0];
+    if (!ARG_WRAPPER_KEYS.has(only) || declaredKeys.includes(only))
+        return args;
+    const inner = args[only];
+    if (isRecord(inner))
+        return inner;
+    if (typeof inner === 'string') {
+        try {
+            const parsed = JSON.parse(inner);
+            if (isRecord(parsed))
+                return parsed;
+        }
+        catch {
+            return args;
+        }
+    }
+    return args;
+}
+function decodeArguments(block) {
+    const args = {};
+    for (const param of markupBlocks(block, PARAMETER_OPEN, PARAMETER_CLOSE)) {
+        if (!param.name)
+            continue;
+        const raw = param.body.trim();
+        try {
+            args[param.name] = JSON.parse(raw);
+        }
+        catch {
+            args[param.name] = raw;
+        }
+    }
+    return args;
+}
+export function recoverSkillNamedCall(text, skillNames, skillToolName) {
+    const known = new Set(skillNames);
+    for (const block of markupBlocks(text, FUNCTION_OPEN, FUNCTION_CLOSE)) {
+        if (!known.has(block.name))
+            continue;
+        return [
+            {
+                id: 'recovered-skill-named-call',
+                name: skillToolName,
+                arguments: { name: block.name },
+                raw: clipRawCall(text.slice(block.start, block.end))
+            }
+        ];
+    }
+    return [];
+}
+const SKILL_LOAD_KEYS = new Set(['name', 'skill', 'skill_name', 'file', 'path', 'filename']);
+export function recoverPrintedSkillLoad(text, skillToolName) {
+    for (const match of text.matchAll(/\{[^{}]*\}/g)) {
+        let candidate;
+        try {
+            candidate = JSON.parse(match[0]);
+        }
+        catch {
+            continue;
+        }
+        if (!isRecord(candidate))
+            continue;
+        const keys = Object.keys(candidate);
+        if (keys.length === 0 || !keys.every((key) => SKILL_LOAD_KEYS.has(key)))
+            continue;
+        const name = candidate.name ?? candidate.skill ?? candidate.skill_name;
+        const file = candidate.file ?? candidate.path ?? candidate.filename;
+        if (typeof name !== 'string' || typeof file !== 'string')
+            continue;
+        if (!/\.(md|py)\s*$/i.test(file.replaceAll('"', '').trim()))
+            continue;
+        return [
+            {
+                id: 'recovered-printed-skill-load',
+                name: skillToolName,
+                arguments: { name, file },
+                raw: clipRawCall(match[0])
+            }
+        ];
+    }
+    return [];
+}

package/dist-lib/lib/helpers/tool-intent.d.ts

@@ -0,0 +1,7 @@
+export declare const INTENT_PARAM = "intent";
+export declare const INTENT_PARAM_DESCRIPTION: string;
+export declare function sanitizeToolIntent(value: unknown): string | undefined;
+export declare function takeToolIntent(args: Record<string, unknown>): {
+    args: Record<string, unknown>;
+    intent?: string;
+};

package/dist-lib/lib/helpers/tool-intent.js

@@ -0,0 +1,21 @@
+import { stripControlTokens } from "./control-tokens.js";
+export const INTENT_PARAM = 'intent';
+export const INTENT_PARAM_DESCRIPTION = 'One short sentence, addressed to the user, saying plainly what this call will ' +
+    'do for them — the outcome, never the code. It is the only thing the approval ' +
+    'prompt shows them.';
+const MAX_INTENT_LENGTH = 160;
+export function sanitizeToolIntent(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const collapsed = stripControlTokens(value).replace(/\s+/g, ' ').trim();
+    if (!collapsed)
+        return undefined;
+    return collapsed.length > MAX_INTENT_LENGTH ? collapsed.slice(0, MAX_INTENT_LENGTH) : collapsed;
+}
+export function takeToolIntent(args) {
+    if (!(INTENT_PARAM in args))
+        return { args };
+    const { [INTENT_PARAM]: raw, ...rest } = args;
+    const intent = sanitizeToolIntent(raw);
+    return intent === undefined ? { args: rest } : { args: rest, intent };
+}

package/dist-lib/lib/helpers/tool-label.d.ts

@@ -0,0 +1,8 @@
+import type { ResponseFormat } from '../capabilities/completion.ts';
+import type { ToolCallDisplay } from '../tool-call-display.ts';
+export declare const TOOL_LABEL_SCHEMA: ResponseFormat;
+export declare function buildToolLabelPrompt(name: string, args: Record<string, unknown>): string;
+export declare function skillCallLabel(args: Record<string, unknown>): string;
+export declare function isSkillTool(name: string): boolean;
+export declare function parseToolLabelResponse(raw: string): ToolCallDisplay | null;
+export declare function fallbackToolLabel(name: string, args?: Record<string, unknown>): string;

package/dist-lib/lib/helpers/tool-label.js

@@ -0,0 +1,131 @@
+import { unwrap } from 'asenion';
+import { SKILL_TOOL_NAME } from "../capabilities/tool-names.js";
+import { unquoteArg } from "../tools/model-args.js";
+import { stripControlTokens } from "./control-tokens.js";
+const MAX_LABEL_WORDS = 6;
+const MAX_LABEL_LENGTH = 60;
+const MAX_DESCRIPTION_LENGTH = 200;
+const MAX_ARGS_JSON = 1500;
+const LABEL_INSTRUCTION = 'Write a 3 to 6 word label a person watching the run would read, and one sentence describing ' +
+    'what the call does and to what, for a person deciding whether to approve it. ' +
+    'Do not mention tools, code, JSON, or these instructions. ' +
+    'Examples: Load apple-notes; Search today’s space news; Read example.com/docs.';
+const ECHOED_INSTRUCTION = /3 to 6 words?|name the action|do not mention tools|person watching|tool call in|describe the outcome|not the code|run outcome description|^(skill )?tool call$/i;
+export const TOOL_LABEL_SCHEMA = {
+    type: 'json_schema',
+    json_schema: {
+        name: 'tool_label',
+        schema: {
+            type: 'object',
+            properties: { label: { type: 'string' }, description: { type: 'string' } },
+            required: ['label', 'description'],
+            additionalProperties: false
+        }
+    }
+};
+export function buildToolLabelPrompt(name, args) {
+    const json = JSON.stringify(args);
+    const clipped = json.length > MAX_ARGS_JSON ? json.slice(0, MAX_ARGS_JSON) : json;
+    return `${LABEL_INSTRUCTION}\nTool: ${name}\nArguments:\n${clipped}`;
+}
+function normalizeModelLabel(raw) {
+    const firstLine = stripControlTokens(raw)
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .find(Boolean);
+    if (!firstLine)
+        return null;
+    const unlabeled = firstLine.replace(/^label\s*[:\-–]\s*/i, '');
+    const unquoted = unwrap(unlabeled)
+        .replace(/^["'`]+|["'`]+$/g, '')
+        .trim();
+    const words = unquoted.split(/\s+/).filter(Boolean).slice(0, MAX_LABEL_WORDS);
+    if (words.length === 0)
+        return null;
+    const label = words
+        .join(' ')
+        .replace(/[.,;:!?]+$/, '')
+        .trim()
+        .slice(0, MAX_LABEL_LENGTH)
+        .trim();
+    if (!label || ECHOED_INSTRUCTION.test(label))
+        return null;
+    return label;
+}
+export function skillCallLabel(args) {
+    const name = stringArg(args, 'name') || stringArg(args, 'skill_name') || stringArg(args, 'skill');
+    if (!name)
+        return 'Load skill instructions';
+    const title = titleSkillName(name);
+    const file = stringArg(args, 'file');
+    return file ? `Read ${title}/${fileName(file)}` : `Load ${title}`;
+}
+export function isSkillTool(name) {
+    return name === SKILL_TOOL_NAME;
+}
+function stringArg(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string')
+        return '';
+    return unquoteArg(value).trim();
+}
+function fileName(path) {
+    const parts = path.split(/[/\\]/);
+    return parts.at(-1) || path;
+}
+function titleSkillName(name) {
+    return name
+        .split(/[-_\s]+/)
+        .filter(Boolean)
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+function normalizeModelDescription(raw) {
+    const text = stripControlTokens(raw).replace(/\s+/g, ' ').trim();
+    if (!text || ECHOED_INSTRUCTION.test(text))
+        return undefined;
+    return text.length > MAX_DESCRIPTION_LENGTH
+        ? `${text.slice(0, MAX_DESCRIPTION_LENGTH).trimEnd()}…`
+        : text;
+}
+export function parseToolLabelResponse(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('{')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            const label = typeof parsed.label === 'string' ? normalizeModelLabel(parsed.label) : null;
+            if (!label)
+                return null;
+            const description = typeof parsed.description === 'string'
+                ? normalizeModelDescription(parsed.description)
+                : undefined;
+            return description ? { label, description } : { label };
+        }
+        catch {
+        }
+    }
+    const label = normalizeModelLabel(trimmed);
+    return label ? { label } : null;
+}
+export function fallbackToolLabel(name, args = {}) {
+    if (isSkillTool(name))
+        return skillCallLabel(args);
+    const query = stringArg(args, 'query');
+    if (query)
+        return `Search ${query}`.slice(0, MAX_LABEL_LENGTH).trim();
+    const url = stringArg(args, 'url');
+    if (url) {
+        const method = stringArg(args, 'method').toUpperCase();
+        const target = displayUrl(url);
+        return `${method ? `${method} ` : 'Read '}${target}`.slice(0, MAX_LABEL_LENGTH).trim();
+    }
+    const words = name.replace(/[_-]+/g, ' ').trim();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function displayUrl(url) {
+    const trimmed = url
+        .trim()
+        .replace(/^https?:\/\//, '')
+        .replace(/\/$/, '');
+    return trimmed || url;
+}

package/dist-lib/lib/hooks/built-in/arg-repair.d.ts

@@ -0,0 +1,5 @@
+import type { HarnessHook, HookContext, HookResult } from '../types.ts';
+export declare class ArgRepairHook implements HarnessHook {
+    readonly phase: "preToolCall";
+    run(ctx: HookContext): HookResult;
+}

package/dist-lib/lib/hooks/built-in/arg-repair.js

@@ -0,0 +1,88 @@
+import { jsonrepair } from 'jsonrepair';
+import { hlog } from "../../log.js";
+const STRUCTURED_TYPES = new Set(['object', 'array']);
+export class ArgRepairHook {
+    phase = 'preToolCall';
+    run(ctx) {
+        if (ctx.phase !== 'preToolCall' || !ctx.parameters)
+            return;
+        let args = ctx.args;
+        for (const [key, schema] of Object.entries(ctx.parameters.properties)) {
+            const value = args[key];
+            if (typeof value !== 'string')
+                continue;
+            const types = structuredTypes(schema);
+            if (types.size === 0)
+                continue;
+            const parsed = parseStructured(value, types);
+            if (parsed === null) {
+                hlog('arg repair declined', { tool: ctx.toolName, param: key, length: value.length });
+                continue;
+            }
+            args = { ...args, [key]: parsed };
+        }
+        if (args !== ctx.args)
+            return { args };
+    }
+}
+function parseStructured(value, types) {
+    const text = value.trim();
+    const parsed = read(text);
+    if (typeof parsed === 'string') {
+        const inner = parsed.trim();
+        if (inner !== text && (inner[0] === '{' || inner[0] === '[' || inner[0] === '"')) {
+            return parseStructured(parsed, types);
+        }
+        return null;
+    }
+    const accepted = accept(parsed, types);
+    if (accepted !== null)
+        return accepted;
+    if (Array.isArray(parsed) &&
+        types.has('object') &&
+        isRecord(parsed[0]) &&
+        typeof parsed.at(-1) === 'string') {
+        return parsed[0];
+    }
+    if (text[0] === '"' && types.has('object'))
+        return accept(read(`{${text}}`), types);
+    return null;
+}
+function read(text) {
+    try {
+        return JSON.parse(jsonrepair(text));
+    }
+    catch {
+        return null;
+    }
+}
+function accept(value, types) {
+    if (isRecord(value) && types.has('object'))
+        return value;
+    if (Array.isArray(value) && types.has('array'))
+        return value;
+    return null;
+}
+function structuredTypes(schema) {
+    const found = new Set();
+    if (!isRecord(schema))
+        return found;
+    const declared = Array.isArray(schema.type) ? schema.type : [schema.type];
+    for (const type of declared) {
+        if (typeof type === 'string' && STRUCTURED_TYPES.has(type))
+            found.add(type);
+    }
+    for (const key of ['oneOf', 'anyOf']) {
+        const branches = schema[key];
+        if (!Array.isArray(branches))
+            continue;
+        for (const branch of branches) {
+            for (const type of structuredTypes(branch))
+                found.add(type);
+        }
+    }
+    return found;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist-lib/lib/hooks/built-in/egress.d.ts

@@ -0,0 +1,5 @@
+import type { HarnessHook, HookContext, HookResult } from '../types.ts';
+export declare class EgressGuardHook implements HarnessHook {
+    readonly phase: "preToolCall";
+    run(ctx: HookContext): HookResult;
+}

package/dist-lib/lib/hooks/built-in/egress.js

@@ -0,0 +1,29 @@
+import { mcpTargetUrl } from "../../tools/mcp-call.js";
+import { checkOutboundHost } from "../../tools/url-guard.js";
+export class EgressGuardHook {
+    phase = 'preToolCall';
+    run(ctx) {
+        if (ctx.phase !== 'preToolCall')
+            return;
+        let target;
+        if (ctx.toolName === 'http_request' || ctx.toolName === 'web_fetch') {
+            target = typeof ctx.args.url === 'string' ? ctx.args.url : '';
+        }
+        else if (ctx.toolName === 'mcp_call') {
+            target = mcpTargetUrl(ctx.args);
+        }
+        else {
+            return;
+        }
+        let url;
+        try {
+            url = new URL(target);
+        }
+        catch {
+            return;
+        }
+        const blocked = checkOutboundHost(url);
+        if (blocked)
+            return { error: blocked, guidance: true };
+    }
+}

package/dist-lib/lib/hooks/built-in/index.d.ts

@@ -0,0 +1,3 @@
+export { ArgRepairHook } from './arg-repair.ts';
+export { EgressGuardHook } from './egress.ts';
+export { SkillCatalogGuardHook } from './skill-catalog.ts';

package/dist-lib/lib/hooks/built-in/index.js

@@ -0,0 +1,3 @@
+export { ArgRepairHook } from "./arg-repair.js";
+export { EgressGuardHook } from "./egress.js";
+export { SkillCatalogGuardHook } from "./skill-catalog.js";

package/dist-lib/lib/hooks/built-in/skill-catalog.d.ts

@@ -0,0 +1,10 @@
+import type { SkillCatalogEntry } from '../../tools/skills/catalog.ts';
+import type { HarnessHook, HookContext, HookResult } from '../types.ts';
+type SkillCatalogInput = readonly SkillCatalogEntry[] | (() => readonly SkillCatalogEntry[] | readonly string[]);
+export declare class SkillCatalogGuardHook implements HarnessHook {
+    readonly phase: "preToolCall";
+    private readonly _catalog;
+    constructor(catalog?: SkillCatalogInput);
+    run(ctx: HookContext): HookResult;
+}
+export {};

package/dist-lib/lib/hooks/built-in/skill-catalog.js

@@ -0,0 +1,17 @@
+export class SkillCatalogGuardHook {
+    phase = 'preToolCall';
+    _catalog;
+    constructor(catalog = []) {
+        this._catalog = catalog;
+    }
+    run(ctx) {
+        if (ctx.phase !== 'preToolCall' || ctx.toolName !== 'skill')
+            return;
+        const entries = ctx.skillNames ?? (typeof this._catalog === 'function' ? this._catalog() : this._catalog);
+        const known = new Set(entries.map((entry) => (typeof entry === 'string' ? entry : entry.name)));
+        const raw = ctx.args.name ?? ctx.args.skill_name ?? ctx.args.skill;
+        const name = typeof raw === 'string' ? raw : '';
+        if (!known.has(name))
+            return { error: `skill not found: ${name}`, guidance: true };
+    }
+}