@juno-ai/bind 10.0.0 → 12.0.0

package/skills/sha256.d.ts

@@ -0,0 +1,38 @@
+/**
+ * SHA-256 over a UTF-8 string, in plain TypeScript.
+ *
+ * **Why the package carries an implementation instead of taking a port**, when
+ * `run/receipts.ts` deliberately does the opposite. Two differences decide it.
+ *
+ * The first is *when* the digest is needed. A receipt's hash is taken inside an
+ * already-async tool dispatch, so `crypto.subtle.digest` — which is async
+ * everywhere, and is the only digest workerd has — fits without changing any
+ * signature. A skill's `contentSha` is computed at **registration**, which is
+ * the synchronous act of a module declaring what it contributes. Taking an
+ * async digest there forces either an async `register()` (so a plugin's
+ * registration becomes something a host must await and order) or a lazily
+ * resolved hash on every read path that wants one. Both cost more than this
+ * file.
+ *
+ * The second is *what the value means*. A receipt hash is persisted by the host
+ * forever and compared against rows written by earlier versions, so the host
+ * must own the algorithm choice — and its input is tool arguments, routinely
+ * user data, which is why that doc argues preimage resistance. A `contentSha`
+ * identifies build content within one deployment: it is derived from source the
+ * deployment already ships, and nothing reads it that did not just compute it.
+ *
+ * A host with a native digest can still supply one — {@link Sha256Hex} is a
+ * parameter everywhere this is used — but it must be synchronous and it must be
+ * SHA-256, or the hashes two hosts compute for the same skill diverge.
+ *
+ * The implementation is the FIPS 180-4 reference algorithm with no shortcuts.
+ * `__tests__/sha256.test.ts` pins it against the published vectors, plus a
+ * multi-block and a multi-byte-UTF-8 case, because a hash that is subtly wrong
+ * fails silently: every value still looks like a hash.
+ */
+/** A synchronous SHA-256 that returns lowercase hex. */
+export type Sha256Hex = (text: string) => string;
+/** SHA-256 (lowercase hex) of a UTF-8 string. */
+export declare const sha256Hex: Sha256Hex;
+/** Byte length of a string in UTF-8 — what a resource listing reports. */
+export declare function utf8ByteLength(text: string): number;

package/skills/sha256.js

@@ -0,0 +1,122 @@
+/**
+ * SHA-256 over a UTF-8 string, in plain TypeScript.
+ *
+ * **Why the package carries an implementation instead of taking a port**, when
+ * `run/receipts.ts` deliberately does the opposite. Two differences decide it.
+ *
+ * The first is *when* the digest is needed. A receipt's hash is taken inside an
+ * already-async tool dispatch, so `crypto.subtle.digest` — which is async
+ * everywhere, and is the only digest workerd has — fits without changing any
+ * signature. A skill's `contentSha` is computed at **registration**, which is
+ * the synchronous act of a module declaring what it contributes. Taking an
+ * async digest there forces either an async `register()` (so a plugin's
+ * registration becomes something a host must await and order) or a lazily
+ * resolved hash on every read path that wants one. Both cost more than this
+ * file.
+ *
+ * The second is *what the value means*. A receipt hash is persisted by the host
+ * forever and compared against rows written by earlier versions, so the host
+ * must own the algorithm choice — and its input is tool arguments, routinely
+ * user data, which is why that doc argues preimage resistance. A `contentSha`
+ * identifies build content within one deployment: it is derived from source the
+ * deployment already ships, and nothing reads it that did not just compute it.
+ *
+ * A host with a native digest can still supply one — {@link Sha256Hex} is a
+ * parameter everywhere this is used — but it must be synchronous and it must be
+ * SHA-256, or the hashes two hosts compute for the same skill diverge.
+ *
+ * The implementation is the FIPS 180-4 reference algorithm with no shortcuts.
+ * `__tests__/sha256.test.ts` pins it against the published vectors, plus a
+ * multi-block and a multi-byte-UTF-8 case, because a hash that is subtly wrong
+ * fails silently: every value still looks like a hash.
+ */
+/** Round constants: the first 32 bits of the fractional parts of the cube roots of the first 64 primes. */
+// prettier-ignore
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function rotr(x, n) {
+    return (x >>> n) | (x << (32 - n));
+}
+const encoder = new TextEncoder();
+/** SHA-256 (lowercase hex) of a UTF-8 string. */
+export const sha256Hex = (text) => {
+    const data = encoder.encode(text);
+    // Pad to a whole number of 512-bit blocks: the 0x80 terminator, zeroes, then
+    // the message length in bits as a 64-bit big-endian integer.
+    const total = (((data.length + 9 + 63) / 64) | 0) * 64;
+    const buf = new Uint8Array(total);
+    buf.set(data);
+    buf[data.length] = 0x80;
+    const view = new DataView(buf.buffer);
+    // The bit length can exceed 32 bits for inputs over 512 MiB. Split it rather
+    // than relying on a single `setUint32`, which would silently truncate.
+    const bitLength = data.length * 8;
+    view.setUint32(total - 8, Math.floor(bitLength / 0x1_0000_0000));
+    view.setUint32(total - 4, bitLength >>> 0);
+    // Initial hash values: the first 32 bits of the fractional parts of the
+    // square roots of the first eight primes.
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+        0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < total; offset += 64) {
+        for (let i = 0; i < 16; i += 1)
+            w[i] = view.getUint32(offset + i * 4);
+        for (let i = 16; i < 64; i += 1) {
+            const x = w[i - 15];
+            const y = w[i - 2];
+            const s0 = rotr(x, 7) ^ rotr(x, 18) ^ (x >>> 3);
+            const s1 = rotr(y, 17) ^ rotr(y, 19) ^ (y >>> 10);
+            w[i] = w[i - 16] + s0 + w[i - 7] + s1;
+        }
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let hh = h[7];
+        for (let i = 0; i < 64; i += 1) {
+            const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const t1 = (hh + s1 + ch + K[i] + w[i]) | 0;
+            const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (s0 + maj) | 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        h[0] += a;
+        h[1] += b;
+        h[2] += c;
+        h[3] += d;
+        h[4] += e;
+        h[5] += f;
+        h[6] += g;
+        h[7] += hh;
+    }
+    let hex = "";
+    for (let i = 0; i < 8; i += 1)
+        hex += h[i].toString(16).padStart(8, "0");
+    return hex;
+};
+/** Byte length of a string in UTF-8 — what a resource listing reports. */
+export function utf8ByteLength(text) {
+    return encoder.encode(text).length;
+}

package/skills/skill-md.d.ts

@@ -0,0 +1,73 @@
+/**
+ * `SKILL.md` — the interchange format.
+ *
+ * A deployment's canonical storage is its own (a database row, a directory of
+ * files), but the portable form is the de-facto `SKILL.md` bundle: a `---`
+ * fenced YAML frontmatter block followed by a markdown body, as used by
+ * Anthropic's skills and agentskills.io. It is how a skill authored in one
+ * place is read in another, which makes both directions of this file a
+ * compatibility surface rather than an internal convenience.
+ *
+ * **Import is deliberately lenient and export is deliberately strict.** The
+ * input is a document a person wrote, often in another tool, and the two
+ * outcomes are not symmetric: refusing a skill over a cosmetic frontmatter
+ * mistake loses knowledge the author already wrote down, while accepting a
+ * malformed one costs a warning. So parsing repairs what it can, warns about
+ * what it repaired, and fails on exactly two things — frontmatter that is not
+ * YAML at all, and a missing `description`, which is the one field with no
+ * sensible default because it is the entire Tier-1 catalog line.
+ *
+ * **YAML arrives as a port.** The package takes peer dependencies only, and a
+ * YAML implementation is neither a peer the harness can assume nor something
+ * it should bundle. Every host that reads `SKILL.md` already has one — the
+ * seam is two functions wide.
+ */
+/**
+ * The host's YAML implementation. `js-yaml`'s `load`/`dump` and the `yaml`
+ * package's `parse`/`stringify` both satisfy it directly.
+ *
+ * `parse` must **throw** on invalid YAML rather than returning a sentinel: the
+ * repair pass below is driven by the throw, so a parser that returns
+ * `undefined` instead would skip the repair and reject documents this module
+ * is meant to accept.
+ */
+export interface SkillYamlCodec {
+    parse: (text: string) => unknown;
+    /** Must emit block-style YAML and must not wrap long lines. */
+    stringify: (value: Record<string, unknown>) => string;
+}
+export interface ParsedSkillMd {
+    /** `null` when frontmatter omits it — the caller supplies a fallback (usually the filename). */
+    name: string | null;
+    description: string;
+    whenToUse: string | null;
+    body: string;
+    /** Unknown frontmatter keys, preserved for round-trip and read-only display. */
+    metadata: Record<string, unknown> | null;
+}
+export type SkillMdParseResult = {
+    ok: true;
+    skill: ParsedSkillMd;
+    warnings: string[];
+} | {
+    ok: false;
+    error: string;
+    warnings: string[];
+};
+/** Parse a raw `SKILL.md` (frontmatter + body) into importable fields. */
+export declare function parseSkillMarkdown(raw: string, yaml: SkillYamlCodec): SkillMdParseResult;
+/**
+ * Serialize a stored skill back to canonical `SKILL.md` text.
+ *
+ * Preserved unknown keys are written first and the canonical keys last, so a
+ * stray `name` / `description` / `when_to_use` that ended up inside `metadata`
+ * — which an earlier lenient import makes possible — cannot clobber the real
+ * value on the way out.
+ */
+export declare function serializeSkillMarkdown(skill: {
+    name: string;
+    description: string;
+    whenToUse: string | null;
+    body: string;
+    metadata: Record<string, unknown> | null;
+}, yaml: SkillYamlCodec): string;

package/skills/skill-md.js

@@ -0,0 +1,149 @@
+/**
+ * `SKILL.md` — the interchange format.
+ *
+ * A deployment's canonical storage is its own (a database row, a directory of
+ * files), but the portable form is the de-facto `SKILL.md` bundle: a `---`
+ * fenced YAML frontmatter block followed by a markdown body, as used by
+ * Anthropic's skills and agentskills.io. It is how a skill authored in one
+ * place is read in another, which makes both directions of this file a
+ * compatibility surface rather than an internal convenience.
+ *
+ * **Import is deliberately lenient and export is deliberately strict.** The
+ * input is a document a person wrote, often in another tool, and the two
+ * outcomes are not symmetric: refusing a skill over a cosmetic frontmatter
+ * mistake loses knowledge the author already wrote down, while accepting a
+ * malformed one costs a warning. So parsing repairs what it can, warns about
+ * what it repaired, and fails on exactly two things — frontmatter that is not
+ * YAML at all, and a missing `description`, which is the one field with no
+ * sensible default because it is the entire Tier-1 catalog line.
+ *
+ * **YAML arrives as a port.** The package takes peer dependencies only, and a
+ * YAML implementation is neither a peer the harness can assume nor something
+ * it should bundle. Every host that reads `SKILL.md` already has one — the
+ * seam is two functions wide.
+ */
+/**
+ * Frontmatter keys this module owns. Everything else is preserved verbatim in
+ * `metadata` — a host or another tool may put anything here, and dropping it
+ * would make an import/export round-trip lossy.
+ */
+const KNOWN_KEYS = new Set(["name", "description", "when_to_use", "whenToUse", "when-to-use"]);
+/** Lower-kebab, at most 64 characters — the shape a skill name must canonicalize to. */
+const NAME_PATTERN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const NAME_MAX = 64;
+function splitFrontmatter(raw) {
+    const text = raw.replace(/^/, ""); // a BOM before the fence is common from Windows editors
+    if (!text.startsWith("---"))
+        return null;
+    const rest = text.slice(3).replace(/^\r?\n/, "");
+    const endIndex = rest.search(/\r?\n---\s*(\r?\n|$)/);
+    if (endIndex === -1)
+        return null;
+    return {
+        frontmatter: rest.slice(0, endIndex),
+        body: rest.slice(endIndex).replace(/^\r?\n---\s*(\r?\n)?/, ""),
+    };
+}
+/**
+ * Repair the one frontmatter mistake that dominates real imports: an unquoted
+ * value containing a colon (`description: Use when X: do Y`), which YAML reads
+ * as a nested mapping and rejects. Quote any `key: value` whose value has an
+ * unquoted inner colon.
+ *
+ * A value opening with `[` or `{` is a flow collection — valid YAML where the
+ * colons are structural — and is skipped. Without that exception a single
+ * unrelated bad line, which forces this whole-block pass, would collateral-
+ * quote a legitimate inline array or object into a plain string.
+ */
+function repairUnquotedColons(frontmatter) {
+    return frontmatter
+        .split(/\r?\n/)
+        .map((line) => {
+        const match = line.match(/^(\s*[A-Za-z0-9_-]+:\s+)(.*)$/);
+        if (!match)
+            return line;
+        const value = match[2];
+        const trimmed = value.trim();
+        const structured = /^["'[{]/.test(trimmed) || trimmed.length === 0;
+        if (structured || !value.includes(":"))
+            return line;
+        return `${match[1]}"${value.replace(/"/g, '\\"')}"`;
+    })
+        .join("\n");
+}
+function loadYaml(frontmatter, yaml) {
+    const warnings = [];
+    let parsed;
+    try {
+        parsed = yaml.parse(frontmatter);
+    }
+    catch {
+        try {
+            parsed = yaml.parse(repairUnquotedColons(frontmatter));
+            warnings.push("Frontmatter had unquoted colon values; auto-quoted them on import.");
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return null;
+    return { object: parsed, warnings };
+}
+/** Parse a raw `SKILL.md` (frontmatter + body) into importable fields. */
+export function parseSkillMarkdown(raw, yaml) {
+    const split = splitFrontmatter(raw);
+    if (!split) {
+        return {
+            ok: false,
+            error: "Not a SKILL.md — expected a `---` YAML frontmatter block.",
+            warnings: [],
+        };
+    }
+    const loaded = loadYaml(split.frontmatter, yaml);
+    if (!loaded) {
+        return { ok: false, error: "Frontmatter is not valid YAML.", warnings: [] };
+    }
+    const { object, warnings } = loaded;
+    const description = typeof object.description === "string" ? object.description.trim() : "";
+    if (!description) {
+        return {
+            ok: false,
+            error: "SKILL.md is missing a required `description`.",
+            warnings,
+        };
+    }
+    const rawName = typeof object.name === "string" ? object.name.trim() : "";
+    const name = rawName.length > 0 ? rawName : null;
+    if (name && (name.length > NAME_MAX || !NAME_PATTERN.test(name))) {
+        warnings.push(`Frontmatter name "${name}" is not lower-kebab-case ≤ ${NAME_MAX} chars; it will be normalized.`);
+    }
+    // Three spellings, because all three appear in the wild.
+    const hintRaw = object.when_to_use ?? object.whenToUse ?? object["when-to-use"] ?? null;
+    const whenToUse = typeof hintRaw === "string" && hintRaw.trim() ? hintRaw.trim() : null;
+    const extra = Object.entries(object).filter(([key]) => !KNOWN_KEYS.has(key));
+    const metadata = extra.length > 0 ? Object.fromEntries(extra) : null;
+    return {
+        ok: true,
+        skill: { name, description, whenToUse, body: split.body.trim(), metadata },
+        warnings,
+    };
+}
+/**
+ * Serialize a stored skill back to canonical `SKILL.md` text.
+ *
+ * Preserved unknown keys are written first and the canonical keys last, so a
+ * stray `name` / `description` / `when_to_use` that ended up inside `metadata`
+ * — which an earlier lenient import makes possible — cannot clobber the real
+ * value on the way out.
+ */
+export function serializeSkillMarkdown(skill, yaml) {
+    const front = { ...(skill.metadata ?? {}) };
+    front.name = skill.name;
+    front.description = skill.description;
+    if (skill.whenToUse)
+        front.when_to_use = skill.whenToUse;
+    else
+        delete front.when_to_use;
+    return `---\n${yaml.stringify(front).trimEnd()}\n---\n\n${skill.body.trim()}\n`;
+}

package/skills/types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * The skill vocabulary — the *knowledge* sibling of `src/plugins/tool.ts`.
+ *
+ * A skill is a markdown-shaped procedure or reference module, disclosed to a
+ * model in three tiers: a one-line catalog entry it always sees (Tier 1), a
+ * body injected into the system prompt once loaded (Tier 2), and bundled
+ * resources it may read after loading (Tier 3). That progression is the whole
+ * point: a workspace's accumulated know-how does not fit in a context window,
+ * and a catalog line costs ~50 tokens where a body costs thousands.
+ *
+ * Two sources of skill exist and they differ in exactly one way — where the
+ * body comes from. A **code skill** is registered from the deployment's own
+ * source (see {@link SkillDef}) and its body is a build artifact; an
+ * **external skill** is data the host stores and can edit at runtime. The
+ * harness owns the first entirely and knows nothing about the second beyond
+ * the shape it resolves to, which is why {@link SkillSummary} is the only type
+ * both sides share.
+ */
+/**
+ * Where a resolved skill came from.
+ *
+ * - `platform` — code-registered and unowned: available to every agent.
+ * - `plugin` — code-registered and contributed by a tool plugin: available
+ *   only to an agent that can load that plugin, since a recipe for tools the
+ *   agent cannot call is noise.
+ * - `tenant` — authored in the **host's data store** rather than in code. The
+ *   name is Monad's (a tenant is its workspace unit) and is kept because it is
+ *   the value hosts already persist and render; read it as "host-managed".
+ *
+ * The order is also the precedence order — see `compareSkillSummaries`.
+ */
+export type SkillOrigin = "platform" | "plugin" | "tenant";
+/** `reference` = inline text the model reads; `asset` = an opaque blob, summarised rather than inlined. */
+export type SkillResourceKind = "reference" | "asset";
+/**
+ * A Tier-3 resource bundled with a code skill. Code-skill resources are static
+ * assets of the deploy artifact, so their text is a function rather than a
+ * handle: `render()` is called to hash the resource at registration and again
+ * to read it. Binary `asset` resources belong to host-stored skills, where
+ * there is somewhere to put the bytes.
+ */
+export interface SkillResourceDef {
+    /** Relative path, e.g. `references/spec.md`. Unique within the skill. */
+    path: string;
+    /** Always `reference` for a code skill — there is no blob store in a build artifact. */
+    kind: Extract<SkillResourceKind, "reference">;
+    /** MIME type, e.g. `text/markdown`. */
+    contentType: string;
+    /** The inline text body. Must be deterministic: it feeds the content hash. */
+    render: () => string;
+}
+/**
+ * A code-registered skill — what a plugin contributes or a standalone module
+ * registers. `render()` must be deterministic for a given build: its output is
+ * hashed into the skill's `contentSha`, which is what pins an eval or a replay
+ * to the exact instructions a run actually saw.
+ */
+export interface SkillDef {
+    /** Lower-kebab; unique across a registry. */
+    name: string;
+    /** Tier-1 catalog line: what the skill does. */
+    description: string;
+    /**
+     * Activation hint appended to the catalog line — when to reach for this.
+     * Required for a code skill: without it the catalog line says what the skill
+     * is but not when it applies, which is the half that decides routing.
+     */
+    whenToUse: string;
+    /**
+     * Set for a plugin-contributed skill. Filled by the registration path from
+     * the owning plugin's name rather than read from the def — see
+     * `createSkillRegistry`.
+     */
+    ownerPlugin?: string;
+    /** The Tier-2 markdown body. */
+    render: () => string;
+    /** Tier-3 bundled reference resources. */
+    resources?: SkillResourceDef[];
+}
+/**
+ * The Tier-1 projection every source resolves to — the analogue of
+ * `PluginSummary`. The catalog and the activation set are both built from
+ * these, so neither has to know whether a skill came from code or from the
+ * host's store.
+ */
+export interface SkillSummary {
+    /**
+     * The activation ref: what a host persists as the run's active-skill set.
+     * `platform:<name>` for a code skill (see `refs.ts`), the host's own opaque
+     * identifier for an external one. One namespaced form spans both sources
+     * without ambiguity; the catalog still renders the plain `name`.
+     */
+    ref: string;
+    /** Lower-kebab identifier, unique within the resolved catalog. */
+    name: string;
+    /** Tier-1 catalog line. */
+    description: string;
+    /** Optional activation hint, appended to the catalog line. */
+    whenToUse: string | null;
+    /** Set for a plugin-contributed skill (and for a host skill that shadows one). */
+    ownerPlugin: string | null;
+    /** Which of the three sources this came from. */
+    origin: SkillOrigin;
+}
+/** A registered code skill, as the registry hands it back. */
+export interface RegisteredSkill {
+    def: SkillDef;
+    /** `platform` (standalone) or `plugin` (contributed). Never `tenant`: code only. */
+    origin: Extract<SkillOrigin, "platform" | "plugin">;
+    /** The owning plugin's name for a `plugin` skill; null for `platform`. */
+    ownerPlugin: string | null;
+    /** Content hash over every version-defining input, computed at registration. */
+    contentSha: string;
+}
+/** A Tier-3 resource as the catalog and the wrapper see it — metadata, not bytes. */
+export interface SkillResourceRef {
+    path: string;
+    kind: SkillResourceKind;
+    /** Size in bytes. Rendered only for `asset`, which is never inlined. */
+    bytes: number;
+}
+/**
+ * A skill body resolved for injection, whatever its source. The host's
+ * external source returns these; the registry-backed code path produces them
+ * internally.
+ */
+export interface ResolvedSkillBody {
+    name: string;
+    ownerPlugin: string | null;
+    /**
+     * Monotonic revision for a host-stored skill, rendered into the wrapper so
+     * the model can cite what it read. `null` for a code skill, whose version
+     * history is the deployment's source control rather than a number.
+     */
+    version: number | null;
+    body: string;
+    /** The content hash pinned into the run's `loadedSkillShas`. */
+    contentSha: string;
+    resources: SkillResourceRef[];
+}
+/**
+ * Rough token budget for the Tier-1 catalog. Past it the catalog demotes its
+ * overflow to names only rather than dropping entries: a name the model can
+ * still pass to `load_skill` beats a skill it cannot discover at all.
+ */
+export declare const SKILL_CATALOG_TOKEN_BUDGET = 2500;
+/**
+ * Max skills one session may hold loaded at once. The count half of the active
+ * bound — cheap to check before anything is resolved.
+ */
+export declare const SKILL_MAX_ACTIVE_PER_SESSION = 12;
+/**
+ * Combined token budget for all loaded bodies. The other half of the active
+ * bound, and the one that actually protects the context window: twelve small
+ * skills are fine and three large ones are not, so a count cap alone does not
+ * bound the prompt.
+ */
+export declare const SKILL_MAX_ACTIVE_BODY_TOKENS = 40000;
+/**
+ * Characters per token, for every estimate in this module. Deliberately crude:
+ * these budgets choose between "render the line" and "render the name", and a
+ * real tokenizer would cost more than the decision is worth.
+ */
+export declare const SKILL_CHARS_PER_TOKEN = 4;
+/** The module's shared estimator. */
+export declare function estimateSkillTokens(text: string): number;
+/**
+ * Observe something the harness will otherwise carry on past — a name
+ * collision, a pinned body that has drifted, an activation of a skill that is
+ * not in the catalog. A port rather than a logger because the package has no
+ * opinion about where a host's warnings go, and because a test needs to see
+ * them without scraping stdout.
+ */
+export type SkillWarn = (message: string, fields: Record<string, unknown>) => void;

package/skills/types.js

@@ -0,0 +1,55 @@
+/**
+ * The skill vocabulary — the *knowledge* sibling of `src/plugins/tool.ts`.
+ *
+ * A skill is a markdown-shaped procedure or reference module, disclosed to a
+ * model in three tiers: a one-line catalog entry it always sees (Tier 1), a
+ * body injected into the system prompt once loaded (Tier 2), and bundled
+ * resources it may read after loading (Tier 3). That progression is the whole
+ * point: a workspace's accumulated know-how does not fit in a context window,
+ * and a catalog line costs ~50 tokens where a body costs thousands.
+ *
+ * Two sources of skill exist and they differ in exactly one way — where the
+ * body comes from. A **code skill** is registered from the deployment's own
+ * source (see {@link SkillDef}) and its body is a build artifact; an
+ * **external skill** is data the host stores and can edit at runtime. The
+ * harness owns the first entirely and knows nothing about the second beyond
+ * the shape it resolves to, which is why {@link SkillSummary} is the only type
+ * both sides share.
+ */
+// ---------------------------------------------------------------------------
+// Bounds
+//
+// Every one of these bounds the *prompt*, not a database. They are defaults: a
+// host passes its own where the call takes one. What they must not be is
+// absent — an unbounded catalog and an unbounded active set are the two ways a
+// skill library silently degrades every run in the deployment rather than
+// failing one of them.
+// ---------------------------------------------------------------------------
+/**
+ * Rough token budget for the Tier-1 catalog. Past it the catalog demotes its
+ * overflow to names only rather than dropping entries: a name the model can
+ * still pass to `load_skill` beats a skill it cannot discover at all.
+ */
+export const SKILL_CATALOG_TOKEN_BUDGET = 2500;
+/**
+ * Max skills one session may hold loaded at once. The count half of the active
+ * bound — cheap to check before anything is resolved.
+ */
+export const SKILL_MAX_ACTIVE_PER_SESSION = 12;
+/**
+ * Combined token budget for all loaded bodies. The other half of the active
+ * bound, and the one that actually protects the context window: twelve small
+ * skills are fine and three large ones are not, so a count cap alone does not
+ * bound the prompt.
+ */
+export const SKILL_MAX_ACTIVE_BODY_TOKENS = 40_000;
+/**
+ * Characters per token, for every estimate in this module. Deliberately crude:
+ * these budgets choose between "render the line" and "render the name", and a
+ * real tokenizer would cost more than the decision is worth.
+ */
+export const SKILL_CHARS_PER_TOKEN = 4;
+/** The module's shared estimator. */
+export function estimateSkillTokens(text) {
+    return Math.ceil(text.length / SKILL_CHARS_PER_TOKEN);
+}