@hydraharness/harness-tool-skill 0.0.0-stage → 0.1.1-rc.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# @hydraharness/harness-tool-skill
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bounded automatic skill routing, model-facing discovery, exact instruction loading, and deterministic user invocation.
+
+Requires `ctx.agents`, `ctx.tools`, and `ctx.skills` (`inject: ['agents', 'tools', 'skills']`). The plugin does not inject a session-wide skill catalog. It may inject one strongly matched skill body for a direct user task.
+
+## Tool: `skill_search`
+
+| Arg | Type | Notes |
+|---|---|---|
+| `query` | string (required) | Concise task keywords. Greetings, thanks, acknowledgements, casual chat, meta questions, and vague requests should not be searched. |
+
+The tool snapshots the calling agent's cwd-sensitive registry view, keeps only model-invocable summaries, and ranks lexical matches across `name`, `description`, and `whenToUse`. Exact whole-name phrases rank first, then matched terms and metadata fields. Equal scores prefer an alias, then lexical name order. Each canonical definition contributes only its best-ranked name before count and byte limits apply. It does not call `ctx.skills.get()` and therefore never loads instruction bodies while searching.
+
+One result returns at most `searchMaxResults` candidates (default `5`), caps each description or routing hint at `searchDescriptionMaxLength` characters (default `500`), and caps the complete rendered UTF-8 result at `searchMaxResultBytes` bytes (default `8192`). All limits are positive integers; the description limit has minimum `3`, and the byte limit must fit the fixed empty-result framing. `truncated: true` says matching candidates were omitted by a count or byte bound. `complete: false` says provider discovery was unstable or partially unavailable, so an empty result is not authoritative.
+
+The rendered result is:
+
+```markdown
+<skill_candidates complete="true" truncated="false">
+- `<name>`: <normalized-and-capped-description>
+  Use when: <normalized-and-capped-routing-hint>
+</skill_candidates>
+Choose zero or one candidate. Call `skill` only for the best match; load another only when the task clearly requires an independent skill.
+```
+
+An empty complete search renders `(none)` and means no skill should be loaded. This two-step contract keeps model-visible discovery cost bounded even when the registry contains many skills.
+
+## Automatic invocation
+
+Before an accepted step reaches the model, direct-user text is ranked with the same lexical metadata scores as `skill_search`. The host loads exactly one skill only when the registry snapshot is complete and the best model-invocable candidate is unambiguous before lexical name tie-breaking. An exact whole name is strong only when the skill name has multiple terms. Other matches require at least two distinct name terms including the leading name term. Greetings, generic test requests, description-only matches, ties, and non-user text load nothing; `skill_search` remains the fallback.
+
+An explicit `/name` gesture suppresses automatic routing for that step. Automatic discovery and loading fail open on stale, invalid, incomplete, or failing providers, while cancellation still stops the step. A successful injection uses durable `skill-invocation` source metadata with `trigger: 'automatic'`; direct gestures use `trigger: 'user'`.
+
+English and Vietnamese negation or avoidance cues, including `not`, `don't`, `without`, `avoid`, `không`, and `đừng`, suppress automatic loading for the whole request. This conservative check leaves selection to the model-facing tools even if the negation concerns another part of the task. Explicit slash gestures retain their direct invocation behavior.
+
+## Tool: `skill`
+
+| Arg | Type | Notes |
+|---|---|---|
+| `name` | string (required) | Exact kebab-case name returned by `skill_search` or explicitly named by the user. |
+
+Execution uses the calling agent's `session.header.cwd`, validates the name, rejects non-model-invocable skills before loading, then rechecks policy on the loaded definition. A successful call returns canonical `{ name, provider, resourceBase?, content }`; its Native renderer produces one text result containing `<skill_content name="...">`, `<skill_resources>`, and `<skill_instructions>`.
+
+Resource guidance resolves only paths or URLs explicitly referenced by the instructions against `resourceBase`. Scripts, references, and assets load on demand; the result does not enumerate a skill directory. An unresolved name reports that the skill is unknown or no longer available. Invalid names and model-disabled skills have distinct errors.
+
+## User-explicit invocation
+
+A whitespace-bounded `/name` token in a claimed direct-user message deterministically loads a user-invocable skill and appends its full `<skill_content>` rendering after the other injections for that step. Tokens from non-user sources cannot forge the gesture; unknown or user-disabled names stay ordinary prose. This is the model-independent path for `disable-model-invocation` skills, takes precedence over automatic routing, and does not call `skill_search` or `skill`.
+
+## Model Experience
+
+### Tool schemas
+
+#### What the model sees
+
+The model sees the generated [`skill_search` and `skill` schemas](../../../docs/tool-catalog.md#hydraharness-tool-skill). No data-dependent skill roster is added to the request prefix.
+
+#### Token effect
+
+Fixed schema cost on each request where the tools are visible.
+
+#### KV Cache effect
+
+Prefix-stable while definitions and visibility remain unchanged.
+
+### Search result
+
+#### What the model sees
+
+A search adds only the bounded candidate result above.
+
+#### Token effect
+
+At most the configured rendered UTF-8 byte limit, retained in later requests until compaction.
+
+#### KV Cache effect
+
+Append-only after the reusable request prefix.
+
+### Loaded result
+
+#### What the model sees
+
+The selected provider's `<skill_content>`, resource guidance, and complete instructions. The tool does not add a duplicate injected copy.
+
+#### Token effect
+
+Data-dependent body tokens are resent on later steps until compaction.
+
+#### KV Cache effect
+
+Append-only after the reusable request prefix.
+
+### Tool errors
+
+#### What the model sees
+
+Invalid or stale selections return `Error: invalid skill name "<name>"`, `Error: skill "<name>" is unknown or no longer available`, or `Error: skill "<name>" is not available for model invocation`. Provider lookup failures use the same `Error: <message>` wrapper.
+
+#### Token effect
+
+Only a failing tool call adds the short retained error text.
+
+#### KV Cache effect
+
+Append-only after the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+- Automatic routing and search use lexical metadata matching, not semantic retrieval. Add a semantic index only after measured routing misses justify its dependency and operational cost.
+- The automatic-routing veto recognizes common English/Vietnamese cues; it is not a general intent classifier and does not cover every language or phrasing.
+- Loaded instruction bodies have no size cap; a provider can return a body that consumes substantial next-step context.
+- Resources are guidance, not attachments; the tools neither enumerate nor fetch referenced files.
+- Loading is one-shot text; there is no partial, streaming, or cached-content handle.
+- Body-only edits do not notify the model. A later exact load reads current content while earlier tool results remain historical facts.

package/lib/index.js

@@ -0,0 +1,439 @@
+import { Buffer } from "node:buffer";
+import z from "@hydraharness/schemastery";
+import { defineTool } from "@hydraharness/harness-tools";
+import { createUserMessage } from "@hydraharness/harness-llm";
+import { escapeText, isModelInvocable, isSkillName, isUserInvocable, renderSkillContent } from "@hydraharness/harness-skill";
+//#region lib/types/index.js
+/**
+* Bounded skill routing, model-facing search, and exact loading.
+*
+* @module @hydraharness/harness-tool-skill
+*/
+const name = "tool-skill";
+const inject = [
+	"agents",
+	"tools",
+	"skills"
+];
+const DEFAULT_SEARCH_MAX_RESULTS = 5;
+const DEFAULT_SEARCH_DESCRIPTION_MAX_LENGTH = 500;
+const DEFAULT_SEARCH_MAX_RESULT_BYTES = 8192;
+/** Validate and default the model-facing skill search configuration. */
+const Config = z.object({
+	searchMaxResults: z.number().default(DEFAULT_SEARCH_MAX_RESULTS),
+	searchDescriptionMaxLength: z.number().default(DEFAULT_SEARCH_DESCRIPTION_MAX_LENGTH),
+	searchMaxResultBytes: z.number().default(DEFAULT_SEARCH_MAX_RESULT_BYTES)
+});
+/**
+* Register bounded automatic routing, model-facing search, exact loading, and direct user invocation.
+*/
+function apply(ctx, config = {}) {
+	const searchMaxResults = config.searchMaxResults ?? DEFAULT_SEARCH_MAX_RESULTS;
+	const searchDescriptionMaxLength = config.searchDescriptionMaxLength ?? DEFAULT_SEARCH_DESCRIPTION_MAX_LENGTH;
+	const searchMaxResultBytes = config.searchMaxResultBytes ?? DEFAULT_SEARCH_MAX_RESULT_BYTES;
+	assertPositiveInteger("searchMaxResults", searchMaxResults);
+	assertPositiveInteger("searchDescriptionMaxLength", searchDescriptionMaxLength, 3);
+	assertPositiveInteger("searchMaxResultBytes", searchMaxResultBytes, minimumSearchResultBytes());
+	const skillTool = defineTool({
+		name: "skill",
+		description: "Load the full instructions for exactly one skill. Use only an exact name returned by `skill_search` for the current task or explicitly named by the user; do not guess names or reload an inline <skill_content> block.",
+		parameters: { name: {
+			type: "string",
+			required: true,
+			description: "The exact skill name returned by `skill_search` or explicitly named by the user."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					name: {
+						type: "string",
+						required: true
+					},
+					provider: {
+						type: "string",
+						required: true
+					},
+					resourceBase: { oneOf: [
+						{
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								kind: {
+									type: "string",
+									required: true,
+									const: "directory"
+								},
+								path: {
+									type: "string",
+									required: true
+								}
+							}
+						},
+						{
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								kind: {
+									type: "string",
+									required: true,
+									const: "url"
+								},
+								url: {
+									type: "string",
+									required: true
+								}
+							}
+						},
+						{
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								kind: {
+									type: "string",
+									required: true,
+									const: "opaque"
+								},
+								description: {
+									type: "string",
+									required: true
+								}
+							}
+						}
+					] },
+					content: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderSkillContent(value)
+			}]
+		},
+		async execute(args, exec) {
+			if (!isSkillName(args.name)) throw new Error(`invalid skill name "${args.name}"`);
+			const lookup = {
+				cwd: exec.agent?.session.header.cwd,
+				signal: exec.signal,
+				scope: exec.agent
+			};
+			const summary = (await ctx.skills.list(lookup)).find((skill) => skill.name === args.name);
+			if (!summary) throw new Error(`skill "${args.name}" is unknown or no longer available`);
+			if (!isModelInvocable(summary)) throw new Error(`skill "${args.name}" is not available for model invocation`);
+			const skill = await ctx.skills.get(args.name, lookup);
+			if (!skill) throw new Error(`skill "${args.name}" is unknown or no longer available`);
+			if (!isModelInvocable(skill)) throw new Error(`skill "${args.name}" is not available for model invocation`);
+			return {
+				name: skill.name,
+				provider: skill.provider,
+				...skill.resourceBase !== void 0 ? { resourceBase: { ...skill.resourceBase } } : {},
+				content: skill.content
+			};
+		},
+		presentCall(args) {
+			return {
+				card: "generic",
+				title: `Load skill ${args.name}`,
+				kind: "read",
+				rawInput: args.name
+			};
+		}
+	});
+	ctx.tools.register(skillTool);
+	const skillSearchTool = defineTool({
+		name: "skill_search",
+		description: "Find a bounded shortlist of skills for a substantive user task before loading one. Search with concise task keywords; do not call this for greetings, thanks, acknowledgements, casual chat, meta questions, or vague requests. An empty result means load no skill.",
+		parameters: { query: {
+			type: "string",
+			required: true,
+			description: "Concise keywords describing the user task, not a greeting or conversational filler."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					complete: {
+						type: "boolean",
+						required: true
+					},
+					truncated: {
+						type: "boolean",
+						required: true
+					},
+					matches: {
+						type: "array",
+						required: true,
+						items: {
+							type: "object",
+							additionalProperties: false,
+							properties: {
+								name: {
+									type: "string",
+									required: true
+								},
+								description: {
+									type: "string",
+									required: true
+								},
+								whenToUse: { type: "string" }
+							}
+						}
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderSkillSearchResult(value)
+			}]
+		},
+		async execute(args, exec) {
+			const snapshot = await ctx.skills.snapshot({
+				cwd: exec.agent?.session.header.cwd,
+				signal: exec.signal,
+				scope: exec.agent
+			});
+			exec.signal.throwIfAborted();
+			return boundedSearchResult(rankSkills(snapshot.skills.filter(isModelInvocable), args.query).map((entry) => entry.skill), snapshot.complete, searchMaxResults, searchDescriptionMaxLength, searchMaxResultBytes);
+		},
+		presentCall(args) {
+			return {
+				card: "generic",
+				title: "Search skills",
+				kind: "read",
+				rawInput: args.query
+			};
+		}
+	});
+	ctx.tools.register(skillSearchTool);
+	ctx.on("agent/pre-step", async ({ agent, messages, signal }, next) => {
+		const decision = await next();
+		if (decision.kind === "reject") return decision;
+		const names = invokedSkillNames(messages);
+		const task = directUserText(messages);
+		if (names.length === 0 && task === "") return decision;
+		signal.throwIfAborted();
+		const lookup = {
+			cwd: agent.session.header.cwd,
+			signal,
+			scope: agent
+		};
+		const injections = [];
+		if (names.length === 0) {
+			if (vetoesAutomaticSkill(task)) return decision;
+			try {
+				const snapshot = await ctx.skills.snapshot(lookup);
+				signal.throwIfAborted();
+				if (!snapshot.complete) return decision;
+				const selected = automaticallySelectedSkill(rankSkills(snapshot.skills.filter(isModelInvocable), task));
+				if (selected === void 0) return decision;
+				const skill = await ctx.skills.get(selected.name, lookup);
+				signal.throwIfAborted();
+				if (skill === void 0 || !isModelInvocable(skill)) return decision;
+				const source = {
+					kind: "skill-invocation",
+					name: skill.name,
+					trigger: "automatic",
+					form: "instructions"
+				};
+				injections.push(createUserMessage({
+					content: [{
+						type: "text",
+						text: renderSkillContent(skill)
+					}],
+					source
+				}));
+			} catch (error) {
+				signal.throwIfAborted();
+				ctx.logger.warn(`tool-skill: automatic routing failed: ${String(error)}`);
+				return decision;
+			}
+		}
+		for (const name of names) {
+			const skill = await ctx.skills.get(name, lookup);
+			signal.throwIfAborted();
+			if (skill === void 0 || !isUserInvocable(skill)) continue;
+			const source = {
+				kind: "skill-invocation",
+				name,
+				trigger: "user",
+				form: "instructions"
+			};
+			injections.push(createUserMessage({
+				content: [{
+					type: "text",
+					text: renderSkillContent(skill)
+				}],
+				source
+			}));
+		}
+		if (injections.length === 0) return decision;
+		return {
+			kind: "enter",
+			messages: [...decision.messages, ...injections]
+		};
+	});
+}
+const ROUTING_TERM = /[\p{L}\p{N}]+/gu;
+/**
+* Rank model-invocable skill summaries against task keywords without loading any body.
+* @param skills - candidate summaries visible to the calling agent.
+* @param query - task text or concise model-authored keywords.
+* @returns matching summaries and scores in deterministic relevance order.
+*/
+function rankSkills(skills, query) {
+	const queryPhrase = routingPhrase(query);
+	const queryTerms = new Set(queryPhrase.split(" ").filter(Boolean));
+	if (queryTerms.size === 0) return [];
+	const ranked = [];
+	for (const skill of skills) {
+		const namePhrase = routingPhrase(skill.name);
+		const nameTermList = namePhrase.split(" ");
+		const nameTerms = new Set(nameTermList);
+		const descriptionTerms = routingTerms(skill.description);
+		const whenToUseTerms = routingTerms(skill.whenToUse ?? "");
+		const matchedTerms = countMatches(queryTerms, new Set([
+			...nameTerms,
+			...descriptionTerms,
+			...whenToUseTerms
+		]));
+		const exactName = ` ${queryPhrase} `.includes(` ${namePhrase} `);
+		if (!exactName && matchedTerms === 0) continue;
+		ranked.push({
+			skill,
+			exactName,
+			matchedTerms,
+			nameMatches: countMatches(queryTerms, nameTerms),
+			nameTermCount: nameTerms.size,
+			leadingNameMatch: queryTerms.has(nameTermList[0]),
+			whenToUseMatches: countMatches(queryTerms, whenToUseTerms),
+			descriptionMatches: countMatches(queryTerms, descriptionTerms)
+		});
+	}
+	ranked.sort((left, right) => Number(right.exactName) - Number(left.exactName) || right.matchedTerms - left.matchedTerms || right.nameMatches - left.nameMatches || right.whenToUseMatches - left.whenToUseMatches || right.descriptionMatches - left.descriptionMatches || Number(right.skill.aliasFor !== void 0) - Number(left.skill.aliasFor !== void 0) || compareText(left.skill.name, right.skill.name));
+	const seen = /* @__PURE__ */ new Set();
+	return ranked.filter(({ skill }) => {
+		const canonical = skill.aliasFor ?? skill.name;
+		if (seen.has(canonical)) return false;
+		seen.add(canonical);
+		return true;
+	});
+}
+function vetoesAutomaticSkill(task) {
+	const text = task.normalize("NFKC");
+	return /(?:^|[^\p{L}\p{N}])(?:no|not|never|without|avoid|skip|stop|cannot|\p{L}+n['’]t)(?=$|[^\p{L}\p{N}])/iu.test(text) || /(?:^|[^\p{L}\p{N}])(?:không|đừng|chớ|ngừng|khong|dung)(?=$|[^\p{L}\p{N}])/iu.test(text);
+}
+function automaticallySelectedSkill(ranked) {
+	const best = ranked.find(isStrongAutomaticMatch);
+	if (best === void 0) return void 0;
+	const next = ranked.slice(ranked.indexOf(best) + 1).find(isStrongAutomaticMatch);
+	if (next !== void 0 && next.exactName === best.exactName && next.matchedTerms === best.matchedTerms && next.nameMatches === best.nameMatches && next.whenToUseMatches === best.whenToUseMatches && next.descriptionMatches === best.descriptionMatches) return void 0;
+	return best.skill;
+}
+function isStrongAutomaticMatch(candidate) {
+	return candidate.exactName ? candidate.nameTermCount >= 2 : candidate.matchedTerms >= 2 && candidate.nameMatches >= 2 && candidate.leadingNameMatch;
+}
+function boundedSearchResult(ranked, complete, maxResults, descriptionMaxLength, maxResultBytes) {
+	const candidates = ranked.slice(0, maxResults).map((skill) => {
+		const whenToUse = skill.whenToUse === void 0 ? void 0 : boundSearchText(skill.whenToUse, descriptionMaxLength);
+		return {
+			name: skill.name,
+			description: boundSearchText(skill.description, descriptionMaxLength),
+			...whenToUse === void 0 || whenToUse === "" ? {} : { whenToUse }
+		};
+	});
+	const matches = [];
+	for (const candidate of candidates) {
+		const nextMatches = [...matches, candidate];
+		if (resultBytes({
+			complete,
+			truncated: nextMatches.length < ranked.length,
+			matches: nextMatches
+		}) > maxResultBytes) break;
+		matches.push(candidate);
+	}
+	return {
+		complete,
+		truncated: matches.length < ranked.length,
+		matches
+	};
+}
+function renderSkillSearchResult(result) {
+	const candidates = result.matches.length === 0 ? ["(none)"] : result.matches.flatMap((match) => [`- \`${match.name}\`: ${escapeText(match.description)}`, ...match.whenToUse === void 0 ? [] : [`  Use when: ${escapeText(match.whenToUse)}`]]);
+	return [
+		`<skill_candidates complete="${result.complete}" truncated="${result.truncated}">`,
+		...candidates,
+		"</skill_candidates>",
+		...result.complete ? [] : ["Discovery was incomplete; an empty result does not prove that no matching skill exists."],
+		"Choose zero or one candidate. Call `skill` only for the best match; load another only when the task clearly requires an independent skill."
+	].join("\n");
+}
+function minimumSearchResultBytes() {
+	return Math.max(...[true, false].flatMap((complete) => [true, false].map((truncated) => resultBytes({
+		complete,
+		truncated,
+		matches: []
+	}))));
+}
+function resultBytes(result) {
+	return Buffer.byteLength(renderSkillSearchResult(result), "utf8");
+}
+function routingPhrase(value) {
+	return (value.normalize("NFKD").replaceAll(/\p{M}/gu, "").toLowerCase().match(ROUTING_TERM) ?? []).join(" ");
+}
+function routingTerms(value) {
+	return new Set(routingPhrase(value).split(" ").filter(Boolean));
+}
+function countMatches(left, right) {
+	let count = 0;
+	for (const value of left) if (right.has(value)) count += 1;
+	return count;
+}
+function directUserText(messages) {
+	return messages.flatMap((message) => message.source.kind === "user" ? message.content.flatMap((block) => block.type === "text" ? [block.text] : []) : []).join("\n").trim();
+}
+function compareText(left, right) {
+	return Number(left > right) - Number(left < right);
+}
+/** Normalize and length-bound one model-visible summary field. */
+function boundSearchText(value, maxLength) {
+	const normalized = value.replaceAll(/\s+/g, " ").trim();
+	return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3)}...`;
+}
+function assertPositiveInteger(name, value, minimum = 1) {
+	if (!Number.isInteger(value) || value < minimum) throw new Error(`tool-skill: ${name} must be an integer greater than or equal to ${minimum}`);
+}
+/**
+* A whitespace-bounded `/name` token (the public skill-name grammar) anywhere
+* in the text — the same word-boundary shape the transcript chip decoration
+* uses, so a gesture reads as one wherever it sits in the sentence. A second
+* `/` or any non-boundary character breaks the match, which keeps file paths
+* (`/usr/bin`) and fractions (`5/8`) out.
+*/
+const SKILL_GESTURE = /(^|\s)\/([a-z0-9]+(?:-[a-z0-9]+)*)(?=\s|$)/g;
+/**
+* `/name` gesture tokens from the claimed user messages, deduplicated in
+* first-seen order. Every text block of direct user input is scanned; no
+* other source can forge a gesture.
+* @param messages - the step's claimed batch.
+* @returns candidate skill names, unvalidated against the registry.
+*/
+function invokedSkillNames(messages) {
+	const names = [];
+	for (const message of messages) {
+		if (message.source.kind !== "user") continue;
+		for (const block of message.content) {
+			if (block.type !== "text") continue;
+			for (const match of block.text.matchAll(SKILL_GESTURE)) {
+				const name = match[2];
+				if (name !== void 0 && !names.includes(name)) names.push(name);
+			}
+		}
+	}
+	return names;
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-tool-skill`.
+* @module @hydraharness/harness-tool-skill/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-tool-skill";
+/** Cordis companion plugin name. */
+const name = "tool-skill-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+* relations are owned by the capability seam it calls.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Bounded skill routing, model-facing search, and exact loading.
+ *
+ * @module @hydraharness/harness-tool-skill
+ */
+import type { Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+export declare const name = "tool-skill";
+export declare const inject: string[];
+/** Model-facing skill search configuration. */
+export interface Config {
+    /** Maximum candidates returned by one search; minimum 1. */
+    searchMaxResults?: number;
+    /** Maximum normalized description or routing-hint length per candidate; minimum 3. */
+    searchDescriptionMaxLength?: number;
+    /** Maximum UTF-8 bytes in one rendered search result. */
+    searchMaxResultBytes?: number;
+}
+/** Validate and default the model-facing skill search configuration. */
+export declare const Config: z<Config>;
+/**
+ * Register bounded automatic routing, model-facing search, exact loading, and direct user invocation.
+ */
+export declare function apply(ctx: Context, config?: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-tool-skill`.
+ * @module @hydraharness/harness-tool-skill/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-skill-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "@hydraharness/harness-tool-skill",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Bounded automatic skill routing, model-facing search, and exact loading for Hydra harness",
+  "hydra": {
+    "plugin": {
+      "application": "Let the agent search for relevant skills and load their full instructions."
+    }
+  },
+  "version": "0.1.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/skill/tool-skill"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-skill": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@hydraharness/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/harness-agent": "^0.1.1-rc.6",
+    "@hydraharness/harness-llm": "^0.1.1-rc.6",
+    "@hydraharness/harness-session": "^0.1.1-rc.6",
+    "@hydraharness/harness-scope": "^0.1.1-rc.6",
+    "@hydraharness/harness-skill": "^0.1.1-rc.6",
+    "@hydraharness/harness-skill-filesystem": "^0.1.1-rc.6",
+    "@hydraharness/harness-tools": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  }
 }