@juno-ai/bind 10.0.0 → 11.0.0

package/skills/discovery.js

@@ -0,0 +1,91 @@
+import { serializeSkillMarkdown } from "./skill-md.js";
+import { sha256Hex as defaultSha256Hex } from "./sha256.js";
+/**
+ * The Agent Skills **discovery index** — how a deployment advertises skills to
+ * agents that are not its own.
+ *
+ * Per the Agent Skills Discovery RFC v0.2.0
+ * (https://github.com/cloudflare/agent-skills-discovery-rfc,
+ * https://agentskills.io/), an external agent fetches
+ * `/.well-known/agent-skills/index.json`, reads the `skills[]` catalogue, pulls
+ * each `SKILL.md` from its advertised `url`, and verifies the bytes against the
+ * published `digest`. Both documents are generated from the same registry here,
+ * so the digest a reader sees always matches the bytes served.
+ *
+ * **What to publish is a product decision and stays with the host** — hence the
+ * explicit `include` allowlist rather than "every platform skill". The
+ * criterion that matters is whether a skill helps an outside agent drive
+ * *something the deployment actually exposes externally*. A skill about the
+ * host's internal agent runtime cannot help an external client and does not
+ * belong in a public document; a plugin-contributed skill is tied to tools that
+ * are not on the external surface; a workspace's own skills are private data.
+ * Making the list an argument also means dropping a new file into a skills
+ * folder never publishes it by accident.
+ */
+/** The RFC v0.2.0 schema URL advertised in the index's `$schema` field. */
+export const AGENT_SKILLS_DISCOVERY_SCHEMA_URL = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+/** Root of the well-known discovery namespace (host-relative per RFC 3986). */
+export const AGENT_SKILLS_WELL_KNOWN_BASE = "/.well-known/agent-skills";
+/** Host-relative URL of the `SKILL.md` artifact for a skill name. */
+export function skillMarkdownUrl(name, base = AGENT_SKILLS_WELL_KNOWN_BASE) {
+    return `${base}/${name}/SKILL.md`;
+}
+/**
+ * Canonical `SKILL.md` bytes for a published skill — exactly the text served at
+ * its `url` and hashed for its `digest`.
+ *
+ * `metadata` is null because a code skill has none to preserve: it is
+ * registered from name, description, hint and body, so anything else in the
+ * document it was authored from was already dropped at registration. Emitting
+ * it here would put bytes in the artifact that the digest of a re-registered
+ * skill could not reproduce.
+ */
+function skillMarkdownFor(skill, yaml) {
+    return serializeSkillMarkdown({
+        name: skill.def.name,
+        description: skill.def.description,
+        whenToUse: skill.def.whenToUse ?? null,
+        body: skill.def.render(),
+        metadata: null,
+    }, yaml);
+}
+/** Only `platform`-origin skills are publishable; a name that is not one is not published. */
+function publishable(name, registry) {
+    const skill = registry.get(name);
+    return skill && skill.origin === "platform" ? skill : null;
+}
+/** The allowlist as a set — de-duplicated, and O(1) to test. */
+function allowlist(include) {
+    return include instanceof Set ? include : new Set(include);
+}
+/** Build the discovery index from the allowlisted, registered platform skills. */
+export function buildAgentSkillsDiscoveryIndex(options) {
+    const sha256Hex = options.sha256Hex ?? defaultSha256Hex;
+    const skills = [...allowlist(options.include)]
+        .map((name) => publishable(name, options.registry))
+        .filter((skill) => skill !== null)
+        .sort((a, b) => a.def.name.localeCompare(b.def.name))
+        .map((skill) => ({
+        name: skill.def.name,
+        type: "skill-md",
+        description: skill.def.description,
+        url: skillMarkdownUrl(skill.def.name, options.baseUrl),
+        digest: `sha256:${sha256Hex(skillMarkdownFor(skill, options.yaml))}`,
+    }));
+    return { $schema: AGENT_SKILLS_DISCOVERY_SCHEMA_URL, skills };
+}
+/**
+ * The published `SKILL.md` text for a name, or `null` when it is not published.
+ *
+ * One return value for "not on the allowlist", "not registered", and
+ * "registered but not a platform skill": the caller serves a 404 for all three,
+ * and distinguishing them would tell an anonymous reader which internal skills
+ * exist.
+ */
+export function getPublishedSkillMarkdown(name, options) {
+    // Allowlist first: an unknown name short-circuits without touching the registry.
+    if (!allowlist(options.include).has(name))
+        return null;
+    const skill = publishable(name, options.registry);
+    return skill ? skillMarkdownFor(skill, options.yaml) : null;
+}

package/skills/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@juno-ai/bind/skills` — progressive knowledge disclosure.
+ *
+ * The knowledge sibling of `@juno-ai/bind/plugins`: the same three-tier
+ * disclosure applied to instructions rather than tools. See `docs/skills.md`
+ * for the model and `docs/bind.md` for why each piece is on this side of the
+ * boundary.
+ */
+export { SKILL_CATALOG_TOKEN_BUDGET, SKILL_CHARS_PER_TOKEN, SKILL_MAX_ACTIVE_BODY_TOKENS, SKILL_MAX_ACTIVE_PER_SESSION, estimateSkillTokens, type RegisteredSkill, type ResolvedSkillBody, type SkillDef, type SkillOrigin, type SkillResourceDef, type SkillResourceKind, type SkillResourceRef, type SkillSummary, type SkillWarn, } from "./types.js";
+export { PLATFORM_SKILL_REF_PREFIX, codeSkillNameFromRef, codeSkillRef, isCodeSkillRef, } from "./refs.js";
+export { sha256Hex, utf8ByteLength, type Sha256Hex } from "./sha256.js";
+export { computeSkillContentSha, stableSkillJson, type SkillShaInput } from "./sha.js";
+export { parseSkillMarkdown, serializeSkillMarkdown, type ParsedSkillMd, type SkillMdParseResult, type SkillYamlCodec, } from "./skill-md.js";
+export { codeSkillResourceRefs, createSkillRegistry, toCodeSkillSummary, type SkillRegistry, type SkillRegistryOptions, } from "./registry.js";
+export { compareSkillSummaries, partitionSkillCatalog, type SkillCatalogDetail, type SkillCatalogEntry, type SkillCatalogOptions, type SkillCatalogPartition, } from "./catalog.js";
+export { resolveActiveSkillInstructions, wrapSkillContent, type ExternalSkillSource, type ResolveActiveSkillsParams, type ResolvedSkillInstructions, } from "./resolve.js";
+export { createSkillActivation, type SkillActivation, type SkillActivationParams, type SkillStore, } from "./activation.js";
+export { admitSkillLoad, estimateSkillBodyTokens, type SkillLoadBounds, type SkillLoadDecision, type SkillLoadRefusal, } from "./admission.js";
+export { AGENT_SKILLS_DISCOVERY_SCHEMA_URL, AGENT_SKILLS_WELL_KNOWN_BASE, buildAgentSkillsDiscoveryIndex, getPublishedSkillMarkdown, skillMarkdownUrl, type AgentSkillsDiscoveryIndex, type DiscoverySkillEntry, type SkillDiscoveryOptions, } from "./discovery.js";

package/skills/index.js

@@ -0,0 +1,19 @@
+/**
+ * `@juno-ai/bind/skills` — progressive knowledge disclosure.
+ *
+ * The knowledge sibling of `@juno-ai/bind/plugins`: the same three-tier
+ * disclosure applied to instructions rather than tools. See `docs/skills.md`
+ * for the model and `docs/bind.md` for why each piece is on this side of the
+ * boundary.
+ */
+export { SKILL_CATALOG_TOKEN_BUDGET, SKILL_CHARS_PER_TOKEN, SKILL_MAX_ACTIVE_BODY_TOKENS, SKILL_MAX_ACTIVE_PER_SESSION, estimateSkillTokens, } from "./types.js";
+export { PLATFORM_SKILL_REF_PREFIX, codeSkillNameFromRef, codeSkillRef, isCodeSkillRef, } from "./refs.js";
+export { sha256Hex, utf8ByteLength } from "./sha256.js";
+export { computeSkillContentSha, stableSkillJson } from "./sha.js";
+export { parseSkillMarkdown, serializeSkillMarkdown, } from "./skill-md.js";
+export { codeSkillResourceRefs, createSkillRegistry, toCodeSkillSummary, } from "./registry.js";
+export { compareSkillSummaries, partitionSkillCatalog, } from "./catalog.js";
+export { resolveActiveSkillInstructions, wrapSkillContent, } from "./resolve.js";
+export { createSkillActivation, } from "./activation.js";
+export { admitSkillLoad, estimateSkillBodyTokens, } from "./admission.js";
+export { AGENT_SKILLS_DISCOVERY_SCHEMA_URL, AGENT_SKILLS_WELL_KNOWN_BASE, buildAgentSkillsDiscoveryIndex, getPublishedSkillMarkdown, skillMarkdownUrl, } from "./discovery.js";

package/skills/refs.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Activation refs.
+ *
+ * A run persists which skills are loaded, and the set spans two sources whose
+ * identifiers cannot be told apart by shape — a code skill has a name, a
+ * host-stored skill has whatever id the host mints. Namespacing the code side
+ * makes the union unambiguous with one string comparison and no lookup, which
+ * matters because the resolver has to route every ref before it knows whether
+ * either source has it.
+ *
+ * The prefix is part of the persisted format. Changing it strands every stored
+ * active-skill set and every `loadedSkillShas` pin recorded against one.
+ */
+/** The namespace every code-registered skill's ref carries. */
+export declare const PLATFORM_SKILL_REF_PREFIX = "platform:";
+/** Build the activation ref for a code-registered skill name. */
+export declare function codeSkillRef(name: string): string;
+/** True if a ref points at a code-registered skill rather than a host-stored one. */
+export declare function isCodeSkillRef(ref: string): boolean;
+/** Extract the skill name from a code-skill ref (`platform:foo` → `foo`). */
+export declare function codeSkillNameFromRef(ref: string): string;

package/skills/refs.js

@@ -0,0 +1,27 @@
+/**
+ * Activation refs.
+ *
+ * A run persists which skills are loaded, and the set spans two sources whose
+ * identifiers cannot be told apart by shape — a code skill has a name, a
+ * host-stored skill has whatever id the host mints. Namespacing the code side
+ * makes the union unambiguous with one string comparison and no lookup, which
+ * matters because the resolver has to route every ref before it knows whether
+ * either source has it.
+ *
+ * The prefix is part of the persisted format. Changing it strands every stored
+ * active-skill set and every `loadedSkillShas` pin recorded against one.
+ */
+/** The namespace every code-registered skill's ref carries. */
+export const PLATFORM_SKILL_REF_PREFIX = "platform:";
+/** Build the activation ref for a code-registered skill name. */
+export function codeSkillRef(name) {
+    return `${PLATFORM_SKILL_REF_PREFIX}${name}`;
+}
+/** True if a ref points at a code-registered skill rather than a host-stored one. */
+export function isCodeSkillRef(ref) {
+    return ref.startsWith(PLATFORM_SKILL_REF_PREFIX);
+}
+/** Extract the skill name from a code-skill ref (`platform:foo` → `foo`). */
+export function codeSkillNameFromRef(ref) {
+    return ref.slice(PLATFORM_SKILL_REF_PREFIX.length);
+}

package/skills/registry.d.ts

@@ -0,0 +1,57 @@
+import { type Sha256Hex } from "./sha256.js";
+import type { RegisteredSkill, SkillDef, SkillResourceRef, SkillSummary, SkillWarn } from "./types.js";
+/**
+ * The code-skill registry — what a deployment's own source contributes, as
+ * against what its users author.
+ *
+ * **A factory, not a module singleton**, for the same two reasons the tool
+ * registry is one: module state in a workerd isolate has a lifetime the host
+ * does not control, and an implicit global makes every test share a registry
+ * with every other. A host that wants singleton ergonomics wraps one instance
+ * in a module of its own — that decision belongs to the host.
+ *
+ * The registry is deliberately **not** the whole skill library. It holds code
+ * skills, whose bodies are build artifacts and whose version history is source
+ * control. Host-stored skills never enter it; they meet code skills only in the
+ * resolved {@link SkillSummary} catalog, which is source-agnostic by design.
+ */
+export interface SkillRegistry {
+    /**
+     * Register a standalone skill with no owning plugin — available to every
+     * agent.
+     *
+     * `ownerPlugin` on the def is **ignored** and warned about. A platform skill
+     * is unowned by definition, and honouring a stray field here would make the
+     * loader auto-activate a plugin and mislabel the skill as that plugin's.
+     */
+    registerPlatform(def: SkillDef): void;
+    /**
+     * Register a skill contributed by a tool plugin. `ownerPlugin` is filled from
+     * `pluginName` rather than the def, so a recipe is only ever offered to an
+     * agent that can load the tools it describes.
+     */
+    registerPlugin(pluginName: string, def: SkillDef): void;
+    get(name: string): RegisteredSkill | undefined;
+    all(): RegisteredSkill[];
+    /** Tier-1 summaries, gated to the plugins available on this run. */
+    summaries(options?: {
+        availablePlugins?: Iterable<string>;
+    }): SkillSummary[];
+    /** Drop every registration. For a test that wants a controlled set. */
+    clear(): void;
+}
+export interface SkillRegistryOptions {
+    /**
+     * Observe a likely author bug: a name collision, or a platform registration
+     * carrying an owner. Both overwrite/ignore and continue — a bad skill must
+     * not take down agent startup — so this is the only signal they happened.
+     */
+    onWarn?: SkillWarn;
+    /** Override the content digest. Must be synchronous SHA-256 (see `sha256.ts`). */
+    sha256Hex?: Sha256Hex;
+}
+/** The Tier-3 listing for a code skill: metadata, with sizes measured in UTF-8 bytes. */
+export declare function codeSkillResourceRefs(def: SkillDef): SkillResourceRef[];
+/** Project a registered code skill into the source-agnostic Tier-1 summary. */
+export declare function toCodeSkillSummary(skill: RegisteredSkill): SkillSummary;
+export declare function createSkillRegistry(options?: SkillRegistryOptions): SkillRegistry;

package/skills/registry.js

@@ -0,0 +1,94 @@
+import { codeSkillRef } from "./refs.js";
+import { computeSkillContentSha } from "./sha.js";
+import { sha256Hex as defaultSha256Hex, utf8ByteLength } from "./sha256.js";
+/** The Tier-3 listing for a code skill: metadata, with sizes measured in UTF-8 bytes. */
+export function codeSkillResourceRefs(def) {
+    return (def.resources ?? []).map((resource) => ({
+        path: resource.path,
+        kind: resource.kind,
+        bytes: utf8ByteLength(resource.render()),
+    }));
+}
+/** Project a registered code skill into the source-agnostic Tier-1 summary. */
+export function toCodeSkillSummary(skill) {
+    return {
+        ref: codeSkillRef(skill.def.name),
+        name: skill.def.name,
+        description: skill.def.description,
+        whenToUse: skill.def.whenToUse ?? null,
+        ownerPlugin: skill.ownerPlugin,
+        origin: skill.origin,
+    };
+}
+export function createSkillRegistry(options = {}) {
+    const skills = new Map();
+    const sha256Hex = options.sha256Hex ?? defaultSha256Hex;
+    const warn = options.onWarn ?? (() => { });
+    const digestResources = (resources) => (resources ?? []).map((resource) => ({
+        path: resource.path,
+        contentType: resource.contentType,
+        contentHash: sha256Hex(resource.render()),
+    }));
+    const register = (def, origin, ownerPlugin) => {
+        const existing = skills.get(def.name);
+        // Re-registering the *same* def is ordinary — a module imported twice, a
+        // host that re-runs its bootstrap — and is silent. Two distinct defs under
+        // one name is a copy-paste or a cross-plugin clash: last wins, loudly.
+        if (existing && existing.def !== def) {
+            warn("code skill name collision — overwriting", {
+                name: def.name,
+                previousOrigin: existing.origin,
+                previousOwnerPlugin: existing.ownerPlugin,
+                newOrigin: origin,
+                newOwnerPlugin: ownerPlugin,
+            });
+        }
+        const contentSha = computeSkillContentSha({
+            name: def.name,
+            description: def.description,
+            whenToUse: def.whenToUse ?? null,
+            body: def.render(),
+            ownerPlugin,
+            metadata: null,
+            resources: digestResources(def.resources),
+        }, sha256Hex);
+        skills.set(def.name, { def, origin, ownerPlugin, contentSha });
+    };
+    return {
+        registerPlatform(def) {
+            if (def.ownerPlugin != null) {
+                warn("platform skill declared an ownerPlugin; ignoring it", {
+                    name: def.name,
+                    ignoredOwnerPlugin: def.ownerPlugin,
+                });
+            }
+            register(def, "platform", null);
+        },
+        registerPlugin(pluginName, def) {
+            register({ ...def, ownerPlugin: pluginName }, "plugin", pluginName);
+        },
+        get(name) {
+            return skills.get(name);
+        },
+        all() {
+            return [...skills.values()];
+        },
+        summaries(summaryOptions) {
+            const availablePlugins = summaryOptions?.availablePlugins === undefined
+                ? undefined
+                : new Set(summaryOptions.availablePlugins);
+            const out = [];
+            for (const skill of skills.values()) {
+                if (skill.origin === "plugin" && availablePlugins) {
+                    if (!skill.ownerPlugin || !availablePlugins.has(skill.ownerPlugin))
+                        continue;
+                }
+                out.push(toCodeSkillSummary(skill));
+            }
+            return out;
+        },
+        clear() {
+            skills.clear();
+        },
+    };
+}

package/skills/resolve.d.ts

@@ -0,0 +1,89 @@
+import type { RegisteredSkill, ResolvedSkillBody, SkillResourceRef, SkillSummary, SkillWarn } from "./types.js";
+/**
+ * Tier 2 — resolving the bodies of the skills a run has loaded.
+ *
+ * The bodies land in the **system prompt**, not the conversation tail, which is
+ * the decision the rest of this module follows from. It makes them immune to
+ * compaction (an agent cannot forget an instruction it was given the way it
+ * forgets a message), and it puts them inside the provider's cacheable prefix —
+ * so their order and their bytes have to be a pure function of the run's state,
+ * or every turn pays for a cache miss on everything below them.
+ */
+/**
+ * Resolve the bodies of the host's own skills — the ones the registry does not
+ * hold. Batched rather than per-ref because the natural implementation is a
+ * query, and a per-ref port turns one query into N.
+ *
+ * `pinnedShas` is a subset of the caller's pin map covering only these refs. A
+ * source that can reproduce a historical body should return it; one that cannot
+ * should return its current body and leave the drift for the caller to notice
+ * (the resolver records what it actually resolved, never what was asked for).
+ * Refs the source omits are dropped from the result, which is the right answer
+ * for a skill that was deleted mid-session.
+ */
+export type ExternalSkillSource = (refs: string[], pinnedShas: Record<string, string> | undefined) => Promise<ReadonlyMap<string, ResolvedSkillBody>>;
+export interface ResolveActiveSkillsParams {
+    /** The run's active refs, in whatever order the host stored them. */
+    activeRefs: readonly string[];
+    /** This run's Tier-1 catalog. A ref absent from it resolves to nothing. */
+    available: readonly SkillSummary[];
+    /** Where code refs (`platform:<name>`) resolve from. */
+    registry: {
+        get(name: string): RegisteredSkill | undefined;
+    };
+    /** Where every other ref resolves from. Omit for a code-only deployment. */
+    externalSource?: ExternalSkillSource;
+    /**
+     * Ref → `contentSha` recorded by a completed run. Present = **pinned mode**:
+     * reproduce what that run saw, for a replay, an eval, or an optimizer.
+     * Absent = live head, which is what an ordinary turn wants — a skill edited
+     * mid-session should take effect on the next turn.
+     */
+    pinnedShas?: Record<string, string>;
+    /**
+     * Skills resolvable by name that are **not** in the registry, consulted
+     * before it.
+     *
+     * This is the isolation seam. A host may want an always-on instruction module
+     * — an onboarding persona, a per-agent operating manual — that flows through
+     * this one resolver alongside the standard library but must never appear in
+     * any catalog and must never be loadable by name from a model's tool call.
+     * Registering it globally would do both. Passing it here does neither.
+     */
+    extraSkills?: ReadonlyMap<string, RegisteredSkill>;
+    onWarn?: SkillWarn;
+}
+export interface ResolvedSkillInstructions {
+    /** One wrapped body per resolved ref, in catalog order. */
+    instructions: string[];
+    /** Ref → the `contentSha` actually resolved. The run's pin. */
+    shas: Record<string, string>;
+}
+/**
+ * Wrap a resolved body for in-prompt identification.
+ *
+ * The wrapper is not decoration: several bodies are concatenated into one
+ * section, and without a delimiter a model attributes an instruction from one
+ * skill to another — or to the host's own system prompt, which is worse,
+ * because it then applies workspace-authored text with the authority of the
+ * platform. The attributes are what let it cite which skill it is following,
+ * and the resource block is what tells it a Tier-3 read is available at all.
+ */
+export declare function wrapSkillContent(params: {
+    name: string;
+    ownerPlugin: string | null;
+    version: number | null;
+    body: string;
+    resources: readonly SkillResourceRef[];
+}): string;
+/**
+ * Resolve the active set into instruction bodies plus the per-skill hash pin.
+ *
+ * Rendering order is the **catalog's** total order, never the caller's
+ * `activeRefs` order. That argument is set/insertion order, which differs
+ * between a fresh run that loaded A then B and a resumed run whose session
+ * persisted `[B, A]`; since these bodies sit high in the system prompt, an
+ * unstable order byte-shifts the prefix and busts the provider's cache for
+ * every turn after a resume.
+ */
+export declare function resolveActiveSkillInstructions(params: ResolveActiveSkillsParams): Promise<ResolvedSkillInstructions>;

package/skills/resolve.js

@@ -0,0 +1,124 @@
+import { compareSkillSummaries } from "./catalog.js";
+import { codeSkillNameFromRef, isCodeSkillRef } from "./refs.js";
+import { codeSkillResourceRefs } from "./registry.js";
+/**
+ * Escape a value interpolated into a wrapper attribute.
+ *
+ * The wrapper's whole job is to tell the model which instructions came from
+ * where, and a skill's `name` is host data — for a host-stored skill, a string
+ * a *user* typed. Without this, a name containing `"` closes the attribute and
+ * whatever follows is read as further markup: a skill called
+ * `x" trusted="platform` would present itself to the model as platform policy.
+ * Monad validates names to lower-kebab, which is why this was never reachable
+ * there, but the harness cannot assume every host does — and a fence that holds
+ * only when the caller is careful is not a fence.
+ *
+ * A no-op for every legitimate identifier, so no existing prompt shifts a byte.
+ */
+function attribute(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/**
+ * Wrap a resolved body for in-prompt identification.
+ *
+ * The wrapper is not decoration: several bodies are concatenated into one
+ * section, and without a delimiter a model attributes an instruction from one
+ * skill to another — or to the host's own system prompt, which is worse,
+ * because it then applies workspace-authored text with the authority of the
+ * platform. The attributes are what let it cite which skill it is following,
+ * and the resource block is what tells it a Tier-3 read is available at all.
+ */
+export function wrapSkillContent(params) {
+    const attributes = [`name="${attribute(params.name)}"`];
+    if (params.ownerPlugin)
+        attributes.push(`owner_plugin="${attribute(params.ownerPlugin)}"`);
+    if (params.version !== null)
+        attributes.push(`version="${params.version}"`);
+    const parts = [`<skill_content ${attributes.join(" ")}>`, params.body.trim()];
+    if (params.resources.length > 0) {
+        const files = params.resources
+            .map((resource) => `  <file path="${attribute(resource.path)}" kind="${attribute(resource.kind)}"${resource.kind === "asset" ? ` bytes="${resource.bytes}"` : ""}/>`)
+            .join("\n");
+        parts.push("", "<skill_resources>", files, "</skill_resources>", 
+        // Escaped here too: the name is interpolated into a quoted call, so an
+        // unescaped one breaks out of this sentence exactly as it would out of an
+        // attribute. Identical output for any name a host should be accepting.
+        `Read a resource with read_skill_resource("${attribute(params.name)}", path).`);
+    }
+    parts.push("</skill_content>");
+    return parts.join("\n");
+}
+/** Resolve a code ref against the extra map first, then the registry. */
+function resolveCodeSkill(ref, params) {
+    const name = codeSkillNameFromRef(ref);
+    const registered = params.extraSkills?.get(name) ?? params.registry.get(name);
+    if (!registered)
+        return null;
+    const pinned = params.pinnedShas?.[ref];
+    if (pinned && registered.contentSha !== pinned) {
+        // A code skill's history is the deployment's source control, and the
+        // running build has only its own copy — the body at the pinned hash is not
+        // recoverable here. Reproduce best-effort and flag it, so a consumer
+        // comparing runs can see that this one is not a faithful replay.
+        params.onWarn?.("pinned code skill drifted since the run; using current body", {
+            ref,
+            pinnedSha: pinned,
+            currentSha: registered.contentSha,
+        });
+    }
+    return {
+        name: registered.def.name,
+        ownerPlugin: registered.ownerPlugin,
+        version: null,
+        body: registered.def.render(),
+        contentSha: registered.contentSha,
+        resources: codeSkillResourceRefs(registered.def),
+    };
+}
+/**
+ * Resolve the active set into instruction bodies plus the per-skill hash pin.
+ *
+ * Rendering order is the **catalog's** total order, never the caller's
+ * `activeRefs` order. That argument is set/insertion order, which differs
+ * between a fresh run that loaded A then B and a resumed run whose session
+ * persisted `[B, A]`; since these bodies sit high in the system prompt, an
+ * unstable order byte-shifts the prefix and busts the provider's cache for
+ * every turn after a resume.
+ */
+export async function resolveActiveSkillInstructions(params) {
+    const byRef = new Map(params.available.map((summary) => [summary.ref, summary]));
+    const present = params.activeRefs
+        .map((ref) => byRef.get(ref))
+        .filter((summary) => summary !== undefined)
+        .sort(compareSkillSummaries)
+        .map((summary) => summary.ref);
+    const externalRefs = present.filter((ref) => !isCodeSkillRef(ref));
+    const external = externalRefs.length > 0 && params.externalSource
+        ? await params.externalSource(externalRefs, params.pinnedShas)
+        : new Map();
+    const instructions = [];
+    const shas = {};
+    for (const ref of present) {
+        const resolved = isCodeSkillRef(ref)
+            ? resolveCodeSkill(ref, params)
+            : (external.get(ref) ?? null);
+        // A ref that resolves to nothing is skipped rather than reported: it means
+        // the skill was deleted, renamed, or gated off since it was loaded, and a
+        // run should carry on without the instruction rather than fail on it.
+        if (!resolved)
+            continue;
+        instructions.push(wrapSkillContent({
+            name: resolved.name,
+            ownerPlugin: resolved.ownerPlugin,
+            version: resolved.version,
+            body: resolved.body,
+            resources: resolved.resources,
+        }));
+        shas[ref] = resolved.contentSha;
+    }
+    return { instructions, shas };
+}

package/skills/sha.d.ts

@@ -0,0 +1,53 @@
+import { sha256Hex as defaultSha256Hex, type Sha256Hex } from "./sha256.js";
+/**
+ * A skill's content hash — the value that makes a replay honest.
+ *
+ * A run records which skills it loaded, and an eval, a regression harness, or a
+ * GEPA-style optimizer later asks what the agent was actually told. The name is
+ * not enough: skills are edited. So a run pins a hash per loaded skill, and the
+ * hash must cover **every input that changes the model's instructions** — body,
+ * catalog line, activation hint, owner, preserved frontmatter, and each bundled
+ * resource. Anything left out is a way to change what the agent reads while the
+ * pin still claims the run is reproducible.
+ *
+ * Resources are hashed by digest rather than by content so a large reference
+ * costs one pass, and they are sorted by path so listing order — which is
+ * incidental, and differs between a directory scan and a hand-written array —
+ * never changes the result.
+ */
+export interface SkillShaInput {
+    name: string;
+    description: string;
+    whenToUse: string | null;
+    body: string;
+    ownerPlugin: string | null;
+    /** Preserved unknown frontmatter keys, or null. */
+    metadata: Record<string, unknown> | null;
+    /** One entry per resource; order-independent. */
+    resources: ReadonlyArray<{
+        path: string;
+        contentType: string;
+        contentHash: string;
+    }>;
+}
+/**
+ * Deterministic, compact JSON with object keys sorted recursively — the
+ * canonical form the content hash is taken over.
+ *
+ * Two details are load-bearing. Keys are sorted because a `metadata` object
+ * that arrived from a YAML parse, a JSON column, or a hand-written literal has
+ * no reliable key order, and unsorted output would rotate the hash for content
+ * nobody edited. A `Date` serializes to its ISO string because `typeof
+ * new Date() === "object"` with no own keys, so recursing into it would
+ * collapse every distinct timestamp to `{}` — and a YAML timestamp in
+ * frontmatter is exactly how one gets here.
+ */
+export declare function stableSkillJson(value: unknown): string;
+/**
+ * Compute a skill's content hash from its version-defining inputs.
+ *
+ * `sha256Hex` defaults to the package's own implementation; pass a host digest
+ * only if it is synchronous and genuinely SHA-256 (see `sha256.ts`).
+ */
+export declare function computeSkillContentSha(input: SkillShaInput, sha256Hex?: Sha256Hex): string;
+export { defaultSha256Hex as sha256Hex, type Sha256Hex };

package/skills/sha.js

@@ -0,0 +1,60 @@
+import { sha256Hex as defaultSha256Hex } from "./sha256.js";
+/**
+ * Deterministic, compact JSON with object keys sorted recursively — the
+ * canonical form the content hash is taken over.
+ *
+ * Two details are load-bearing. Keys are sorted because a `metadata` object
+ * that arrived from a YAML parse, a JSON column, or a hand-written literal has
+ * no reliable key order, and unsorted output would rotate the hash for content
+ * nobody edited. A `Date` serializes to its ISO string because `typeof
+ * new Date() === "object"` with no own keys, so recursing into it would
+ * collapse every distinct timestamp to `{}` — and a YAML timestamp in
+ * frontmatter is exactly how one gets here.
+ */
+export function stableSkillJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value && typeof value === "object") {
+        const source = value;
+        const sorted = {};
+        for (const key of Object.keys(source).sort())
+            sorted[key] = sortKeys(source[key]);
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Compute a skill's content hash from its version-defining inputs.
+ *
+ * `sha256Hex` defaults to the package's own implementation; pass a host digest
+ * only if it is synchronous and genuinely SHA-256 (see `sha256.ts`).
+ */
+export function computeSkillContentSha(input, sha256Hex = defaultSha256Hex) {
+    const canonical = {
+        name: input.name,
+        description: input.description,
+        whenToUse: input.whenToUse,
+        body: input.body,
+        ownerPlugin: input.ownerPlugin,
+        // Stringified rather than nested so a `metadata` key named `body` or
+        // `resources` cannot collide with a sibling of the canonical object.
+        metadata: stableSkillJson(input.metadata),
+        resources: [...input.resources]
+            .map((resource) => ({
+            path: resource.path,
+            contentType: resource.contentType,
+            contentHash: resource.contentHash,
+        }))
+            // `localeCompare`, not a code-unit comparison, because hosts already
+            // store hashes computed this way and any reordering rotates them —
+            // orphaning every version snapshot a pinned replay resolves against.
+            .sort((a, b) => a.path.localeCompare(b.path)),
+    };
+    return sha256Hex(stableSkillJson(canonical));
+}
+export { defaultSha256Hex as sha256Hex };