@juno-ai/bind 9.0.0 → 11.0.0

package/plugins/dispatch.js

@@ -0,0 +1,241 @@
+/**
+ * Authoring and dispatching a tool: the mechanical half of writing one, which
+ * every host had been reimplementing.
+ *
+ * A `ToolPlugin` is a bundle whose `execute` dispatches by tool name, because
+ * that is the shape a plugin with shared setup wants. It is not the shape a
+ * *single* tool wants, and a host with a flat list of tools ends up writing the
+ * same four steps for each: switch on the name, parse the arguments, map a
+ * parse failure onto a result the model can read, and encode the result as a
+ * `role:"tool"` message. All four are mechanical, all four are easy to get
+ * subtly wrong (the usual bug is a parse failure thrown rather than returned,
+ * which turns a recoverable "you passed the wrong argument" into a dead run),
+ * and none of them are where a host's judgement belongs.
+ *
+ * {@link defineTool} and {@link pluginFromTools} do those steps. They are a
+ * convenience over the vocabulary in `./tool`, not a replacement for it: a
+ * plugin that needs shared setup across its tools, or whose dispatch is genuinely
+ * one decision, still writes `ToolPlugin` by hand and loses nothing.
+ */
+import { z } from "zod";
+import { sanitizeToolSchema } from "../tools/sanitize-schema.js";
+import { stripControlChars } from "../tools/control-chars.js";
+/**
+ * Define one tool from its schema and implementation.
+ *
+ * The returned value is an ordinary {@link ToolDef} with an `execute` attached,
+ * so it drops into anything that already consumes `ToolDef` — a catalog
+ * renderer, a schema regression test — without an adapter.
+ */
+export function defineTool(spec) {
+    // Hoisted so the closures below narrow it once; reading `spec.normalizeArgs`
+    // inside each would re-widen it to possibly-undefined on every call.
+    const normalize = spec.normalizeArgs;
+    return {
+        name: spec.name,
+        description: spec.description,
+        parameters: spec.schema,
+        ...(spec.annotations === undefined ? {} : { annotations: spec.annotations }),
+        ...(spec.hidden === undefined ? {} : { hidden: spec.hidden }),
+        ...(spec.supportsProgress === undefined
+            ? {}
+            : { supportsProgress: spec.supportsProgress }),
+        ...(spec.rawJsonSchema === undefined
+            ? {}
+            : { rawJsonSchema: spec.rawJsonSchema }),
+        ...(normalize === undefined
+            ? {}
+            : {
+                // Handed straight through, NOT re-parsed. `ToolDef.normalizeArgs` is
+                // documented as post-parse canonicalization and every dispatcher
+                // calls it that way, so re-parsing here was pure harm: it ran the
+                // schema a second time, and on any input the schema could not
+                // re-accept it silently returned the *un-normalized* value — which
+                // is the idempotency hash, so two equivalent calls stopped agreeing
+                // exactly when canonicalization mattered most.
+                //
+                // The cast is confined to this line. It is safe by the same contract:
+                // the value is post-parse, so it is a `z.output<TSchema>`.
+                normalizeArgs: normalize,
+            }),
+        ...(spec.summarizeActivity === undefined
+            ? {}
+            : { summarizeActivity: spec.summarizeActivity }),
+        // Parses, and deliberately does NOT normalize.
+        //
+        // Normalization is the dispatcher's step — it has to happen before the
+        // idempotency hash, which the harness never sees — and a dispatcher that
+        // applies `normalizeArgs` and then calls this would otherwise apply it
+        // twice. Once is a no-op for an idempotent canonicalizer and wrong for
+        // anything else (`n => n + 1` reached `execute` as `n + 2`).
+        //
+        // The parse stays because this is also the entry point for a host with no
+        // dispatcher of its own, and re-parsing an already-parsed value is a
+        // no-op for any schema that can legally be a tool schema — `.transform()`
+        // cannot (`z.toJSONSchema` rejects it, so the tool could never be
+        // advertised), and `.default()` / `z.coerce` are both parse-idempotent.
+        // A tool that supplies `rawJsonSchema` to bypass that conversion owns the
+        // requirement itself; see `ToolSpec.rawJsonSchema`.
+        execute: (args, ctx) => {
+            const parsed = spec.schema.safeParse(args);
+            if (!parsed.success) {
+                return validationFailure(spec.name, args, parsed.error);
+            }
+            return spec.execute(parsed.data, ctx);
+        },
+    };
+}
+/**
+ * Cap on the issues quoted back. A tool taking an array validates every
+ * element, so one malformed argument can produce thousands — and the result
+ * message is not transient: it is appended to the transcript and re-sent to
+ * the provider on every remaining turn of the run. Ten is enough for a model
+ * to act on; the rest are counted, not quoted.
+ */
+const MAX_QUOTED_ISSUES = 10;
+/**
+ * Quote model-supplied text back at it safely. A zod issue path can contain
+ * input *keys* (via `z.record`), and this string reaches a host's logs and, in
+ * Monad, a member-visible activity row — so control characters are replaced
+ * with a space rather than deleted, keeping adjacent words apart, and the
+ * result is bounded.
+ */
+function safeQuote(text) {
+    // `Array.from` iterates code points, so the bound cannot slice an astral
+    // character in half and put a lone surrogate in the transcript.
+    return Array.from(stripControlChars(text, " ")).slice(0, 200).join("");
+}
+/** How a tool's arguments failed to parse, phrased for the model. */
+function validationFailure(toolName, args, error) {
+    const quoted = error.issues.slice(0, MAX_QUOTED_ISSUES).map((issue) => {
+        const path = issue.path.map((segment) => String(segment)).join(".");
+        const where = path ? safeQuote(path) : "(top level)";
+        // zod renders an omitted key as "expected string, received undefined",
+        // which reads as a *type* error — and a model that reads it that way
+        // retries with the literal string "undefined" instead of supplying the
+        // field. Resolving the path against the input is what tells the two apart.
+        const omitted = issue.code === "invalid_type" && pathIsAbsent(args, issue.path);
+        return `- ${where}: ${omitted ? "required, but missing" : safeQuote(issue.message)}`;
+    });
+    const hidden = error.issues.length - quoted.length;
+    return {
+        success: false,
+        kind: "validation",
+        // Leads with the outcome, itemizes what to change, and ends with the
+        // action — the shape `ABORTED_TOOL_CALL_MESSAGE` established. A message
+        // that only diagnoses leaves the model to guess whether to retry.
+        error: `Invalid arguments for ${toolName} — the call did not run and nothing changed.\n` +
+            quoted.join("\n") +
+            (hidden > 0 ? `\n- (and ${hidden} more problems)` : "") +
+            `\nFix these fields and call ${toolName} again with the same intent. ` +
+            `Do not resend the same arguments.`,
+    };
+}
+/**
+ * Is the key a zod issue points at genuinely absent?
+ *
+ * Checked with `in` rather than by comparing the value to `undefined`, so a
+ * field explicitly present as `undefined` is reported as the wrong type rather
+ * than as missing. `JSON.parse` never produces `undefined`, so this only
+ * matters for a host dispatching pre-parsed arguments — which is exactly the
+ * caller `defineTool` supports.
+ */
+function pathIsAbsent(value, path) {
+    let current = value;
+    for (const segment of path) {
+        if (current === null || typeof current !== "object")
+            return true;
+        if (!(segment in current))
+            return true;
+        current = current[segment];
+    }
+    return false;
+}
+/**
+ * Bundle self-contained tools into a {@link ToolPlugin}.
+ *
+ * The generated `execute` is only a name resolver — each tool already validates
+ * its own arguments (see {@link DefinedTool}). An unknown name is a *returned*
+ * `not_found` failure rather than a throw: it happens whenever a resumed
+ * session's history references a tool that has since been retired, and a run
+ * should survive that.
+ */
+export function pluginFromTools(spec) {
+    const byName = new Map();
+    for (const tool of spec.tools) {
+        if (byName.has(tool.name)) {
+            // Thrown, not returned: two tools sharing a name is an authoring mistake
+            // that makes one of them permanently unreachable, and it should fail at
+            // construction rather than at whichever call happens to resolve first.
+            throw new Error(`pluginFromTools: plugin "${spec.name}" declares two tools named "${tool.name}".`);
+        }
+        byName.set(tool.name, tool);
+    }
+    return {
+        name: spec.name,
+        description: spec.description,
+        ...(spec.systemMessage === undefined
+            ? {}
+            : { systemMessage: spec.systemMessage }),
+        ...(spec.icon === undefined ? {} : { icon: spec.icon }),
+        ...(spec.isAvailable === undefined
+            ? {}
+            : { isAvailable: spec.isAvailable }),
+        tools: [...spec.tools],
+        async execute(toolName, args, ctx) {
+            const tool = byName.get(toolName);
+            if (!tool) {
+                return {
+                    success: false,
+                    kind: "not_found",
+                    // Leads with the outcome and ends with an action. A bare "unknown
+                    // tool" is indistinguishable from a transient miss, and a model
+                    // reading it that way re-issues the same call every iteration until
+                    // the budget runs out — which is exactly the state this arm exists
+                    // to survive (a resumed session referencing a retired tool).
+                    error: `No tool named "${safeQuote(toolName)}" exists on plugin "${spec.name}" — ` +
+                        `nothing ran and nothing changed, and calling it again will fail the ` +
+                        `same way. Use one of the tools currently listed for "${spec.name}", ` +
+                        `or finish the task without it.`,
+                };
+            }
+            return await tool.execute(args, ctx);
+        },
+    };
+}
+/**
+ * Convert a tool to the wire definition a provider is shown.
+ *
+ * `rawJsonSchema` wins when present (an MCP tool forwards its server's schema
+ * verbatim); otherwise the zod schema is converted. Either way the result goes
+ * through {@link sanitizeToolSchema}, because a strict validator rejects the
+ * *entire* request on the first unsupported construct — one bad tool takes
+ * every other tool down with it.
+ *
+ * `wireName` exists because tool naming is host policy: Monad encodes
+ * `plugin__tool` so it can route a call back to its plugin, and a host with a
+ * flat namespace does not need to. Defaults to the tool's own name.
+ *
+ * Returns the narrow `ChatCompletionFunctionTool` rather than the
+ * `ChatCompletionTool` union — a tool built from a parameter schema is always
+ * the function variant, and returning the union would make every caller narrow
+ * past a `custom` case that cannot occur. It still assigns to the union.
+ *
+ * Converts whatever it is handed. **Skip `hidden` tools in the caller's catalog
+ * loop** — a hidden tool stays runnable so a resumed session's history still
+ * resolves, but advertising it puts a retired tool back in front of the model.
+ */
+export function toolWireDefinition(tool, wireName = tool.name) {
+    const jsonSchema = tool.rawJsonSchema ??
+        // zod's converter is typed as its own JSON Schema shape; the wire wants a
+        // plain object, which is what it structurally is.
+        z.toJSONSchema(tool.parameters);
+    return {
+        type: "function",
+        function: {
+            name: wireName,
+            description: tool.description,
+            parameters: sanitizeToolSchema(jsonSchema),
+        },
+    };
+}

package/plugins/index.d.ts

@@ -1,3 +1,5 @@
 export { hasContentParts, type ToolAnnotations, type ToolDef, type ToolFailureKind, type ToolPlugin, type ToolResult, type RegistrablePlugin, type SuspendDirective, } from "./tool.js";
+export { defineTool, pluginFromTools, toolWireDefinition, type DefinedTool, type ToolSpec, type PluginSpec, } from "./dispatch.js";
+export { toolResultMessage } from "./tool-message.js";
 export { createToolRegistry, type PluginSummary, type ToolRegistry, type ToolRegistryOptions, } from "./registry.js";
 export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, type ActivationDropReason, type CatalogPartition, type DroppedActivation, type RehydrateOptions, type RehydrateResult, } from "./activation.js";

package/plugins/index.js

@@ -1,3 +1,5 @@
 export { hasContentParts, } from "./tool.js";
+export { defineTool, pluginFromTools, toolWireDefinition, } from "./dispatch.js";
+export { toolResultMessage } from "./tool-message.js";
 export { createToolRegistry, } from "./registry.js";
 export { rehydrateActivation, initialActivePlugins, partitionPluginCatalog, } from "./activation.js";

package/plugins/tool-message.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Encoding a tool result as the message that answers its call.
+ *
+ * Deliberately its own module with **type-only** imports: the tool loop uses
+ * this encoder, and `./dispatch` imports zod at runtime for schema conversion.
+ * Folding the two together would pull zod into the module graph of every host
+ * that imports only `@juno-ai/bind/loop`, which today needs none of it.
+ */
+import type OpenAI from "openai";
+import type { ToolResult } from "./tool.js";
+/**
+ * Encode a {@link ToolResult} as the `role:"tool"` message that answers a call.
+ *
+ * This is the encoding the loop itself synthesizes for a failed or refused
+ * call, exported so a host's own results are shaped identically — a model that
+ * sees `{"success":false,"kind":…,"error":…}` from the harness and something
+ * else from the host has to learn two error formats in one transcript.
+ *
+ * `contentParts` and `suspend` are deliberately omitted: both are control
+ * signals for the host, not text for the model. A host relaying multimodal
+ * parts attaches them alongside this message.
+ */
+export declare function toolResultMessage(toolCallId: string, result: ToolResult<unknown>): OpenAI.ChatCompletionToolMessageParam;

package/plugins/tool-message.js

@@ -0,0 +1,31 @@
+/**
+ * Encode a {@link ToolResult} as the `role:"tool"` message that answers a call.
+ *
+ * This is the encoding the loop itself synthesizes for a failed or refused
+ * call, exported so a host's own results are shaped identically — a model that
+ * sees `{"success":false,"kind":…,"error":…}` from the harness and something
+ * else from the host has to learn two error formats in one transcript.
+ *
+ * `contentParts` and `suspend` are deliberately omitted: both are control
+ * signals for the host, not text for the model. A host relaying multimodal
+ * parts attaches them alongside this message.
+ */
+export function toolResultMessage(toolCallId, result) {
+    const body = result.success
+        ? { success: true, data: result.data }
+        : {
+            success: false,
+            // `success` and `kind` lead so a model skimming a batch of results
+            // reads the verdict before the prose, and the order is fixed —
+            // `success`, `kind`, `error`, then `data` when present — so the same
+            // result always serializes to the same bytes.
+            ...(result.kind === undefined ? {} : { kind: result.kind }),
+            error: result.error,
+            ...(result.data === undefined ? {} : { data: result.data }),
+        };
+    return {
+        role: "tool",
+        tool_call_id: toolCallId,
+        content: JSON.stringify(body),
+    };
+}

package/skills/activation.d.ts

@@ -0,0 +1,64 @@
+import type { ResolvedSkillInstructions } from "./resolve.js";
+import type { SkillSummary, SkillWarn } from "./types.js";
+/**
+ * Progressive knowledge disclosure — the skill half of `plugins/activation.ts`.
+ *
+ * The controller does one thing and refuses to do a second: it adds refs to the
+ * run's active set, resolves the bodies, records the hash pin, and hands the
+ * full resolved set back. It **never touches the transcript**. The system
+ * message is a pure render of run state, so a host re-renders it from the
+ * instructions it is given rather than splicing a marker or mutating a string
+ * in place — the difference shows up the first time a run is resumed and the
+ * spliced text is already there twice.
+ */
+/**
+ * The skill read path, injectable. The other half of the source — the Tier-1
+ * catalog — is the `availableSkills` array, so a host customizes both
+ * independently: an in-memory store for a test, an isolated one-skill store for
+ * an always-on persona, the real registry plus its database for a live run.
+ */
+export interface SkillStore {
+    resolveActiveInstructions(activeRefs: string[]): Promise<ResolvedSkillInstructions>;
+}
+export interface SkillActivation {
+    /**
+     * Activate skills for this run: admit the refs that are in the catalog,
+     * resolve the bodies for the **whole** active set, pin their hashes, and hand
+     * the instructions to `applyInstructions`.
+     *
+     * Resolution covers the whole set rather than the delta because the caller
+     * re-renders one section from the result; a delta would make it the caller's
+     * job to concatenate in the right order, which is the ordering guarantee the
+     * resolver exists to own. A call that admits nothing new is a no-op.
+     */
+    activateSkills(refs: Iterable<string>): Promise<void>;
+}
+export interface SkillActivationParams {
+    /** This run's Tier-1 catalog — the set a ref must be in to be activatable. */
+    availableSkills: readonly SkillSummary[];
+    /**
+     * Caller-owned active-ref set, mutated in place.
+     *
+     * Owned by the caller because two other things read it: conversation assembly
+     * seeds it before the first turn (it is what the initial catalog renders as
+     * active), and the host persists it when the run ends.
+     */
+    activeSkills: Set<string>;
+    /**
+     * Caller-owned ref → `contentSha` pin, grown on each activation.
+     *
+     * Also caller-owned, and for a sharper reason: a host hoists it above the try
+     * block so the terminal-path catch can still persist what the run had loaded.
+     * A pin the controller owned would be lost on exactly the failed runs an eval
+     * most wants to reproduce.
+     */
+    loadedSkillShas: Record<string, string>;
+    store: SkillStore;
+    /**
+     * Called after each activation that changed the set, with the freshly
+     * resolved bodies for the full active set.
+     */
+    applyInstructions: (instructions: string[]) => void;
+    onWarn?: SkillWarn;
+}
+export declare function createSkillActivation(params: SkillActivationParams): SkillActivation;

package/skills/activation.js

@@ -0,0 +1,39 @@
+export function createSkillActivation(params) {
+    const { activeSkills, loadedSkillShas, store, applyInstructions } = params;
+    const availableRefs = new Set(params.availableSkills.map((summary) => summary.ref));
+    return {
+        async activateSkills(refs) {
+            const admitted = [];
+            for (const ref of refs) {
+                // The catalog is the authorization boundary for reading a skill: it is
+                // already gated on the agent's plugins and the host's scope, so a ref
+                // outside it is refused here rather than resolved and then filtered.
+                if (!availableRefs.has(ref)) {
+                    params.onWarn?.("refusing to activate unavailable skill", { ref });
+                    continue;
+                }
+                if (!activeSkills.has(ref) && !admitted.includes(ref))
+                    admitted.push(ref);
+            }
+            if (admitted.length === 0)
+                return;
+            // Resolve against the *would-be* set, and commit only if that succeeds.
+            //
+            // Adding first is the obvious order and it is wrong. A store that throws
+            // — a database blip, an external source that times out — would leave the
+            // caller's set claiming the skill is active while `applyInstructions`
+            // never ran, so the body is not in the prompt. The retry then finds
+            // nothing new to admit and returns early, and the run finishes with a
+            // catalog that lists a skill as loaded whose instructions the model never
+            // saw. Failing cleanly is what makes a retry able to fix it.
+            const next = new Set(activeSkills);
+            for (const ref of admitted)
+                next.add(ref);
+            const { instructions, shas } = await store.resolveActiveInstructions([...next]);
+            for (const ref of admitted)
+                activeSkills.add(ref);
+            Object.assign(loadedSkillShas, shas);
+            applyInstructions(instructions);
+        },
+    };
+}

package/skills/admission.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Whether a run may load one more skill.
+ *
+ * Two bounds, and they are not redundant. The **count** is cheap and is checked
+ * before anything is resolved. The **token total** is the one that actually
+ * protects the context window: twelve short skills fit and three long ones do
+ * not, so a count cap alone bounds the wrong quantity. Without the second, a
+ * model in a loop loads its way to a context-limit error mid-run, which reads
+ * to a user as the agent breaking rather than as it over-reaching.
+ *
+ * Shaped like `admitChildRun` in `run/children.ts`, and for the same reason:
+ * **the host measures, the harness judges.** Estimating the token cost of the
+ * would-be active set means resolving bodies, which is I/O; comparing a number
+ * to a limit is not. So each bound arrives with the measurement it judges, and
+ * a bound whose number the host could not produce is simply omitted — a rule
+ * that silently never fires is worse than one that is visibly absent.
+ */
+export type SkillLoadRefusal = {
+    kind: "active_count";
+    active: number;
+    max: number;
+} | {
+    kind: "active_body_tokens";
+    tokens: number;
+    max: number;
+};
+export type SkillLoadDecision = {
+    admitted: true;
+} | {
+    admitted: false;
+    refusal: SkillLoadRefusal;
+    /**
+     * A noun phrase, carrying no identifiers. Hosts surface a refusal to the
+     * model as a tool error and sometimes to a person, so it must be safe to
+     * render in both places and must read after a host's own prefix.
+     */
+    reason: string;
+};
+export interface SkillLoadBounds {
+    /**
+     * Refs already active. Omit the pair to skip the count bound; a non-finite or
+     * negative count **refuses**, because a broken measurement is not evidence
+     * that there is room.
+     */
+    activeCount?: number;
+    maxActive?: number;
+    /**
+     * Estimated tokens of the instruction set the load would produce — the whole
+     * would-be active set, not the increment. Omit the pair to skip the bound.
+     */
+    projectedBodyTokens?: number;
+    maxBodyTokens?: number;
+}
+/**
+ * Judge a `load_skill` against the active-set bounds. A skill that is already
+ * active is never subject to either bound — reloading it adds nothing — so
+ * callers should short-circuit before calling.
+ */
+export declare function admitSkillLoad(bounds: SkillLoadBounds): SkillLoadDecision;
+/** Estimated token cost of a resolved instruction set — the input to the body bound. */
+export declare function estimateSkillBodyTokens(instructions: readonly string[]): number;

package/skills/admission.js

@@ -0,0 +1,41 @@
+import { SKILL_MAX_ACTIVE_BODY_TOKENS, SKILL_MAX_ACTIVE_PER_SESSION, estimateSkillTokens, } from "./types.js";
+function bounded(measurement) {
+    return measurement !== undefined;
+}
+/**
+ * Judge a `load_skill` against the active-set bounds. A skill that is already
+ * active is never subject to either bound — reloading it adds nothing — so
+ * callers should short-circuit before calling.
+ */
+export function admitSkillLoad(bounds) {
+    const maxActive = bounds.maxActive ?? SKILL_MAX_ACTIVE_PER_SESSION;
+    if (bounded(bounds.activeCount)) {
+        const active = bounds.activeCount;
+        // `!(active < max)` rather than `active >= max`: every comparison is false
+        // against NaN, so the naive form admits on a broken count instead of
+        // refusing on one.
+        if (!(Number.isFinite(active) && active >= 0 && active < maxActive)) {
+            return {
+                admitted: false,
+                refusal: { kind: "active_count", active, max: maxActive },
+                reason: `active-skill limit reached (${maxActive} loaded). Work from the skills already loaded rather than loading more.`,
+            };
+        }
+    }
+    const maxBodyTokens = bounds.maxBodyTokens ?? SKILL_MAX_ACTIVE_BODY_TOKENS;
+    if (bounded(bounds.projectedBodyTokens)) {
+        const tokens = bounds.projectedBodyTokens;
+        if (!(Number.isFinite(tokens) && tokens >= 0 && tokens <= maxBodyTokens)) {
+            return {
+                admitted: false,
+                refusal: { kind: "active_body_tokens", tokens, max: maxBodyTokens },
+                reason: `loading this skill would take the loaded instructions to about ${tokens} tokens, over the ${maxBodyTokens}-token budget. Work from the skills already loaded instead of loading more.`,
+            };
+        }
+    }
+    return { admitted: true };
+}
+/** Estimated token cost of a resolved instruction set — the input to the body bound. */
+export function estimateSkillBodyTokens(instructions) {
+    return instructions.reduce((total, body) => total + estimateSkillTokens(body), 0);
+}

package/skills/catalog.d.ts

@@ -0,0 +1,54 @@
+import { type SkillSummary } from "./types.js";
+/**
+ * Total order over summaries: origin, then name, then ref.
+ *
+ * A **total** order, not just a stable one: `ref` is the unique tiebreak so two
+ * skills that collide on name still sort deterministically. Both the catalog
+ * and the injected instruction bodies use this comparator, which is what keeps
+ * the system prompt byte-stable across a fresh run and a resumed one — the
+ * active set is persisted in load order, and rendering in *that* order would
+ * shift the prefix on every resume.
+ */
+export declare function compareSkillSummaries(a: SkillSummary, b: SkillSummary): number;
+/** How much of a skill's catalog entry survived the budget. */
+export type SkillCatalogDetail = "full" | "name_only";
+export interface SkillCatalogEntry {
+    summary: SkillSummary;
+    detail: SkillCatalogDetail;
+}
+export interface SkillCatalogPartition {
+    /** Already loaded. Always rendered in full — the body's cost is already paid. */
+    active: SkillSummary[];
+    /** Loadable, each marked with the detail the budget allows. */
+    loadable: SkillCatalogEntry[];
+    /** How many loadable entries were demoted to `name_only`. */
+    truncated: number;
+}
+export interface SkillCatalogOptions {
+    /** Defaults to {@link SKILL_CATALOG_TOKEN_BUDGET}. */
+    tokenBudget?: number;
+    /**
+     * Cost of one entry at a given detail, in tokens. Defaults to an estimate of
+     * `- name: description — whenToUse`.
+     *
+     * A host that renders a different line should pass its own: the budget is
+     * only as honest as its measurement, and a default that under-counts a
+     * verbose format silently overruns the prefix it was meant to protect.
+     */
+    cost?: (summary: SkillSummary, detail: SkillCatalogDetail) => number;
+}
+/**
+ * Split the catalog into active and loadable, demoting the loadable tail to
+ * names only once the budget is spent.
+ *
+ * **Demote, never drop.** A skill the model cannot see is a skill it cannot
+ * ask for, and a workspace's library grows past any budget worth setting. A
+ * bare name still routes: it is enough for the model to call `load_skill` and
+ * read the real description. The host is expected to say so in the line it
+ * renders for the truncated tail — `truncated` is there to let it.
+ *
+ * The active set is charged against the budget but never demoted: those bodies
+ * are already in the prompt, so shortening their catalog lines would save
+ * nothing that matters while hiding what the agent is currently working from.
+ */
+export declare function partitionSkillCatalog(activeSkills: ReadonlySet<string>, available: readonly SkillSummary[], options?: SkillCatalogOptions): SkillCatalogPartition;

package/skills/catalog.js

@@ -0,0 +1,77 @@
+import { SKILL_CATALOG_TOKEN_BUDGET, estimateSkillTokens, } from "./types.js";
+/**
+ * The Tier-1 catalog — what the model sees for every skill on every turn,
+ * whether or not it ever loads one.
+ *
+ * This module returns **data, not prose**, exactly as `partitionPluginCatalog`
+ * does and for the same two reasons: catalog wording is a product surface with
+ * the host's voice, and it sits in the cacheable system prefix, where the host
+ * needs byte-identical output for unchanged inputs or it loses the provider's
+ * prompt cache for everything below it. What is genuinely shared is the
+ * *ordering* and the *budget*, and both are here.
+ */
+/**
+ * Origin precedence. Deployment-owned knowledge is described before
+ * plugin-specific recipes, and both before what the workspace wrote — so the
+ * general instruction is read before the specialization, and so the tail that
+ * a budget demotes is the tail that grows without bound.
+ */
+const ORIGIN_RANK = {
+    platform: 0,
+    plugin: 1,
+    tenant: 2,
+};
+/**
+ * Total order over summaries: origin, then name, then ref.
+ *
+ * A **total** order, not just a stable one: `ref` is the unique tiebreak so two
+ * skills that collide on name still sort deterministically. Both the catalog
+ * and the injected instruction bodies use this comparator, which is what keeps
+ * the system prompt byte-stable across a fresh run and a resumed one — the
+ * active set is persisted in load order, and rendering in *that* order would
+ * shift the prefix on every resume.
+ */
+export function compareSkillSummaries(a, b) {
+    return (ORIGIN_RANK[a.origin] - ORIGIN_RANK[b.origin] ||
+        a.name.localeCompare(b.name) ||
+        a.ref.localeCompare(b.ref));
+}
+function defaultCost(summary, detail) {
+    if (detail === "name_only")
+        return estimateSkillTokens(`- ${summary.name}`);
+    const hint = summary.whenToUse ? ` — ${summary.whenToUse}` : "";
+    return estimateSkillTokens(`- ${summary.name}: ${summary.description}${hint}`);
+}
+/**
+ * Split the catalog into active and loadable, demoting the loadable tail to
+ * names only once the budget is spent.
+ *
+ * **Demote, never drop.** A skill the model cannot see is a skill it cannot
+ * ask for, and a workspace's library grows past any budget worth setting. A
+ * bare name still routes: it is enough for the model to call `load_skill` and
+ * read the real description. The host is expected to say so in the line it
+ * renders for the truncated tail — `truncated` is there to let it.
+ *
+ * The active set is charged against the budget but never demoted: those bodies
+ * are already in the prompt, so shortening their catalog lines would save
+ * nothing that matters while hiding what the agent is currently working from.
+ */
+export function partitionSkillCatalog(activeSkills, available, options = {}) {
+    const budget = options.tokenBudget ?? SKILL_CATALOG_TOKEN_BUDGET;
+    const cost = options.cost ?? defaultCost;
+    const ordered = [...available].sort(compareSkillSummaries);
+    const active = ordered.filter((summary) => activeSkills.has(summary.ref));
+    const loadableSummaries = ordered.filter((summary) => !activeSkills.has(summary.ref));
+    let spent = active.reduce((total, summary) => total + cost(summary, "full"), 0);
+    let truncated = 0;
+    const loadable = loadableSummaries.map((summary) => {
+        const full = cost(summary, "full");
+        if (spent + full <= budget) {
+            spent += full;
+            return { summary, detail: "full" };
+        }
+        truncated += 1;
+        return { summary, detail: "name_only" };
+    });
+    return { active, loadable, truncated };
+}