@arnilo/prism 0.0.18 → 0.0.20

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## [0.0.20] - 2026-07-31
+
+### Added
+- Progressive skill disclosure: `skillsDisclosure` (`"progressive"` default, `"eager"` opt-in), session `LoadedSkillSet`, `createLoadSkillTool` / `resolveSkillLoad` (`load_skill`), catalog/body byte caps.
+- Runtime `activateAllSkills` migration opt-in when `AgentConfig.skills` is a `SkillRegistry` without per-run activation.
+- Context budget: `ContextBlock.priority` ordering; skill body demotion (`skill_body` omission) before full drop.
+- Optional `toolResultFold` host-gated projection for aged large tool results (session store untouched).
+
+### Changed
+- Default runtime `SkillRegistry` activation is **empty** when neither `RunOptions.activeSkills` nor `RunOptions.skills` is set (was `SkillRegistry.list()`).
+- Default skill prompt assembly is catalog-only (`name` + `description`); full `instructions` require eager mode or successful `load_skill`.
+
+### Breaking (minor, pre-1.0)
+- Hosts relying on implicit activate-all registry behavior must pass `activateAllSkills: true` or set `activeSkills` / `skills` explicitly.
+- Hosts expecting full skill bodies every turn must set `skillsDisclosure: "eager"` or register and use `load_skill`.
+
+See [docs/migration.md](docs/migration.md) for the full 0.0.19 → 0.0.20 notes.
+
+## [0.0.19] - 2026-07-30
+
+### Added
+- `@arnilo/prism-compaction-observational-memory`: `createObservationalMemory()` + `attach()` lifecycle, four-layer provider context (recent exact messages, observation log, reflections, raw-source retrieval), `recallObservationalMemoryBranchPage()`, `wrapResumeRun` / `wrapResumeStream`, nested settings with legacy flat-key mapping.
+
+### Changed
+- Observational memory: separate observer/reflector/dropper workers, domain-neutral observer default, dual coverage/eligibility fixes, full-ledger reflection recall, hard fold/render byte caps, post-run `compactAfterTokens` compaction when attached.
+
+See [docs/migration.md](docs/migration.md) for the full 0.0.18 → 0.0.19 observational memory notes.
+
 ## [0.0.18] - 2026-07-30
 
 ### Changed

package/dist/agents.js

@@ -15,6 +15,8 @@ import { isFlushableRunLedger } from "./run-ledger.js";
 import { RunLimitError, RunLimitTracker, resolveRunLimits } from "./run-limits.js";
 import { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, rebuildSessionContext, } from "./session-stores.js";
 import { resolveActiveSkills } from "./skills.js";
+import { createLoadedSkillSet, resolveSkillsDisclosure } from "./skill-disclosure.js";
+import { resolveToolResultFold } from "./tool-result-fold.js";
 import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "./structured-output.js";
 import { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 import { createToolRegistry, dispatchToolCall } from "./tools.js";
@@ -167,6 +169,7 @@ class RuntimeAgentSession {
     activeLimitOutputBuffer = false;
     activeDurable;
     activeLoopTurn = 1;
+    loadedSkills = createLoadedSkillSet();
     ledgerChain = Promise.resolve();
     ledgerFailure;
     snapshotGeneration = 0;
@@ -428,6 +431,9 @@ class RuntimeAgentSession {
                         promptBuilder: this.agent.config.promptBuilder,
                         contextProviders,
                         skills: activeSkills,
+                        skillsDisclosure: resolveSkillsDisclosure(options.skillsDisclosure, this.agent.config.skillsDisclosure),
+                        toolResultFold: resolveToolResultFold(options.toolResultFold, this.agent.config.toolResultFold),
+                        loadedSkills: this.loadedSkills,
                         tools,
                         resourceLoader: this.agent.config.resourceLoader,
                         permission: this.agent.config.permission,
@@ -472,7 +478,12 @@ class RuntimeAgentSession {
                         runId,
                         toolCallId: call.id,
                         signal: controller.signal,
-                        metadata,
+                        metadata: {
+                            ...metadata,
+                            loadedSkills: this.loadedSkills,
+                            activeTools: tools,
+                            activeSkillNames: activeSkills.map((skill) => skill.name),
+                        },
                         identity: this.activeIdentity,
                     },
                     middleware: this.agent.config.middleware,
@@ -815,7 +826,11 @@ class RuntimeAgentSession {
         if (configured && typeof configured === "object" && "list" in configured) {
             if (options.activeSkills)
                 return resolveActiveSkills({ registry: configured, names: options.activeSkills, tools });
-            return configured.list();
+            if (options.skills !== undefined)
+                return options.skills;
+            if (options.activateAllSkills ?? this.agent.config.activateAllSkills)
+                return configured.list();
+            return [];
         }
         const arr = options.skills ?? (Array.isArray(configured) ? configured : []);
         return arr;

package/dist/context-budget.d.ts

@@ -1,11 +1,12 @@
 import type { ContextBlock, InputAssemblyLayout, Message, ProviderRequest, Skill, ToolDefinition } from "./contracts.js";
+import { type LoadedSkillSet, type SkillsDisclosure } from "./skill-disclosure.js";
 /** Assembler-time input budget. At least one max required when present. */
 export interface ContextBudget {
     readonly maxInputTokens?: number;
     readonly maxInputBytes?: number;
     readonly reportOmissions?: boolean;
 }
-export type ContextBudgetOmissionKind = "skills" | "context" | "history" | "tool_results" | "summaries" | "attachments" | "tools";
+export type ContextBudgetOmissionKind = "skills" | "skill_body" | "context" | "history" | "tool_results" | "summaries" | "attachments" | "tools";
 export interface ContextBudgetOmission {
     readonly kind: ContextBudgetOmissionKind;
     readonly id?: string;
@@ -54,10 +55,13 @@ export declare function applyContextBudget(options: {
     readonly tools?: readonly ToolDefinition[];
     readonly budget: ContextBudget;
     readonly layout?: InputAssemblyLayout;
+    readonly skillsDisclosure?: SkillsDisclosure;
+    readonly loadedSkills?: LoadedSkillSet;
 }): {
     readonly groups: ContextBudgetMessageGroups;
     readonly context: readonly ContextBlock[];
     readonly skills: readonly Skill[];
     readonly tools: readonly ToolDefinition[] | undefined;
+    readonly demotedSkillBodies: readonly string[];
     readonly report: ContextBudgetReport;
 };

package/dist/context-budget.js

@@ -1,3 +1,4 @@
+import { capSkillCatalog, selectSkillsForPrompt, skillHasRenderableBody, skillPromptText, } from "./skill-disclosure.js";
 export const CONTEXT_BUDGET_REPORT_METADATA_KEY = "contextBudgetReport";
 export const HARD_MAX_CONTEXT_BUDGET_TOKENS = 2_000_000;
 export const HARD_MAX_CONTEXT_BUDGET_BYTES = 32 * 1024 * 1024;
@@ -58,14 +59,16 @@ export function applyContextBudget(options) {
         toolResults: [...options.groups.toolResults],
     };
     const context = [...(options.context ?? [])];
-    const skills = [...(options.skills ?? [])].filter((skill) => skill.instructions);
+    const skillContext = { disclosure: options.skillsDisclosure, loaded: options.loadedSkills };
+    const skills = [...capSkillCatalog(selectSkillsForPrompt(options.skills ?? [], skillContext))];
     const tools = options.tools ? [...options.tools] : undefined;
     const omitted = [];
+    const demotedBodies = new Set();
     // Measure once, then subtract each dropped item's own estimate (dropNext computes it
     // with the same estimators) — avoids an O(n²) re-scan of the full keep-set per drop.
-    const kept = measureAll(groups, context, skills, tools);
+    const kept = measureAll(groups, context, skills, tools, skillContext, demotedBodies);
     while (overBudget(kept, budget)) {
-        const drop = dropNext(groups, context, skills, layout);
+        const drop = dropNext(groups, context, skills, layout, skillContext, demotedBodies);
         if (!drop) {
             throw new ContextBudgetError();
         }
@@ -80,6 +83,7 @@ export function applyContextBudget(options) {
         context,
         skills,
         tools,
+        demotedSkillBodies: [...demotedBodies],
         report: {
             omitted: budget.reportOmissions ? reportOmissions : [],
             keptTokens: kept.tokens,
@@ -90,7 +94,7 @@ export function applyContextBudget(options) {
         },
     };
 }
-function dropNext(groups, context, skills, layout) {
+function dropNext(groups, context, skills, layout, skillContext, demotedBodies) {
     // ponytail: drop droppable groups in layout order; within history, drop oldest first (shift).
     // cache_aware keeps attachments longer so stable prefix stays intact while budget still allows it.
     const order = layout === "cache_aware"
@@ -114,7 +118,8 @@ function dropNext(groups, context, skills, layout) {
             return omission("attachments", message.id, message);
         }
         if (kind === "context" && context.length > 0) {
-            const block = context.pop();
+            const index = pickVictimIndex(context, (block) => block.priority ?? 0);
+            const block = context.splice(index, 1)[0];
             const text = `${block.title ? `${block.title}:\n` : "Context:\n"}${contextBlockText(block)}`;
             return {
                 kind: "context",
@@ -124,8 +129,23 @@ function dropNext(groups, context, skills, layout) {
             };
         }
         if (kind === "skills" && skills.length > 0) {
-            const skill = skills.pop();
-            const text = `Skill ${skill.name}:\n${skill.instructions ?? ""}`;
+            const renderContext = withDemoted(skillContext, demotedBodies);
+            const demoteIndex = findSkillBodyIndex(skills, renderContext);
+            if (demoteIndex !== undefined) {
+                const skill = skills[demoteIndex];
+                const beforeText = skillPromptText(skill, renderContext) ?? "";
+                demotedBodies.add(skill.name);
+                const afterText = skillPromptText(skill, withDemoted(skillContext, demotedBodies)) ?? "";
+                return {
+                    kind: "skill_body",
+                    id: skill.name,
+                    tokenEstimate: estimateTextTokens(beforeText) - estimateTextTokens(afterText),
+                    byteLength: estimateTextBytes(beforeText) - estimateTextBytes(afterText),
+                };
+            }
+            const index = pickVictimIndex(skills, () => 0);
+            const skill = skills.splice(index, 1)[0];
+            const text = skillPromptText(skill, withDemoted(skillContext, demotedBodies)) ?? "";
             return {
                 kind: "skills",
                 id: skill.name,
@@ -148,7 +168,8 @@ function toolResultId(message) {
     const block = message.content.find((part) => part.type === "tool_result");
     return block && block.type === "tool_result" ? block.toolCallId : undefined;
 }
-function measureAll(groups, context, skills, tools) {
+function measureAll(groups, context, skills, tools, skillContext, demotedBodies) {
+    const renderContext = withDemoted(skillContext, demotedBodies);
     let tokens = 0;
     let bytes = 0;
     const addMessage = (message) => {
@@ -173,7 +194,7 @@ function measureAll(groups, context, skills, tools) {
         bytes += estimateTextBytes(text);
     }
     for (const skill of skills) {
-        const text = `Skill ${skill.name}:\n${skill.instructions ?? ""}`;
+        const text = skillPromptText(skill, renderContext) ?? "";
         tokens += estimateTextTokens(text);
         bytes += estimateTextBytes(text);
     }
@@ -228,6 +249,31 @@ function messageText(message) {
     })
         .join("\n");
 }
+/** Lowest priority first; equal priority → LIFO (highest index). */
+function pickVictimIndex(items, priorityOf) {
+    let best = 0;
+    for (let i = 1; i < items.length; i++) {
+        const pi = priorityOf(items[i]);
+        const pb = priorityOf(items[best]);
+        if (pi < pb || (pi === pb && i > best))
+            best = i;
+    }
+    return best;
+}
+function withDemoted(context, demotedBodies) {
+    return demotedBodies.size > 0 ? { ...context, demotedBodies } : context;
+}
+/** Index of skill with renderable body to demote; LIFO among ties (all skills default priority 0). */
+function findSkillBodyIndex(skills, renderContext) {
+    let best;
+    for (let i = 0; i < skills.length; i++) {
+        if (!skillHasRenderableBody(skills[i], renderContext))
+            continue;
+        if (best === undefined || i > best)
+            best = i;
+    }
+    return best;
+}
 function contextBlockText(block) {
     if (typeof block.content === "string")
         return block.content;

package/dist/contracts.d.ts

@@ -372,6 +372,12 @@ export interface RunOptions {
     readonly validate?: ToolValidator;
     readonly activeSkills?: readonly string[];
     readonly skills?: readonly Skill[];
+    /** Migration opt-in: activate every skill in a configured `SkillRegistry` when `activeSkills` / `skills` are unset. */
+    readonly activateAllSkills?: true;
+    /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
+    readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
+    readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
     readonly instructionInjectors?: readonly InstructionInjector[];
     readonly inputLayout?: InputAssemblyLayout;
     readonly loop?: AgentLoopStrategy | AgentLoopOptions;
@@ -419,6 +425,12 @@ export interface AgentConfig {
     readonly tools?: ToolRegistry | readonly ToolDefinition[];
     readonly context?: readonly ContextProvider[];
     readonly skills?: SkillRegistry | readonly Skill[];
+    /** Migration opt-in: activate every registry skill by default when run options do not narrow activation. */
+    readonly activateAllSkills?: true;
+    /** Progressive: catalog (name+description) unless loaded; eager: full instructions every turn. Default progressive. */
+    readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    /** Opt-in projection-only fold for aged large tool results in provider view; store untouched. */
+    readonly toolResultFold?: import("./tool-result-fold.js").ToolResultFoldOptions;
     readonly inputBuilder?: InputBuilder;
     readonly promptBuilder?: PromptBuilder;
     readonly middleware?: MiddlewareRegistry;
@@ -946,6 +958,10 @@ export interface PromptBuildRequest {
     readonly messages: readonly Message[];
     readonly context?: readonly ContextBlock[];
     readonly skills?: readonly Skill[];
+    readonly skillsDisclosure?: import("./skill-disclosure.js").SkillsDisclosure;
+    readonly loadedSkills?: import("./skill-disclosure.js").LoadedSkillSet;
+    /** Skills demoted to catalog-only by context budget this turn. */
+    readonly demotedSkillBodies?: readonly string[];
     readonly tools?: readonly ToolDefinition[];
     /** Model being prompted; lets builders adapt composition to declared capabilities
      *  (e.g. the default builder omits the `Available tools:` text for tool-capable models). */

package/dist/index.d.ts

@@ -84,6 +84,12 @@ export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries,
 export { createChainedSettingsProvider, createStaticSettingsProvider } from "./settings.js";
 export type { ResolveActiveSkillsOptions, SkillRegistryOptions } from "./skills.js";
 export { createSkillRegistry, resolveActiveSkills } from "./skills.js";
+export { createLoadedSkillSet, DEFAULT_MAX_SKILL_CATALOG_ENTRIES, DEFAULT_MAX_SKILL_DESCRIPTION_BYTES, DEFAULT_MAX_SKILL_INSTRUCTION_BYTES, EMPTY_SKILL_DESCRIPTION, HARD_MAX_SKILL_CATALOG_ENTRIES, HARD_MAX_SKILL_DESCRIPTION_BYTES, HARD_MAX_SKILL_INSTRUCTION_BYTES, isSkillDisclosureError, resolveSkillsDisclosure, SkillDisclosureError, } from "./skill-disclosure.js";
+export type { LoadedSkillSet, SkillRenderContext, SkillsDisclosure } from "./skill-disclosure.js";
+export type { CreateLoadSkillToolOptions, ResolveSkillLoadOptions } from "./skill-load.js";
+export { createLoadSkillTool, DEFAULT_LOAD_SKILL_TOOL_NAME, isSkillLoadError, MAX_LOAD_SKILL_RESULT_BYTES, resolveSkillLoad, SKILL_LOAD_ERROR_CODE, SkillLoadError, } from "./skill-load.js";
+export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS, DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES, foldedToolResultHeader, foldToolResultHistory, foldToolResults, formatFoldedToolResult, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, resolveToolResultFold, TOOL_RESULT_FOLD_TURN_METADATA_KEY, } from "./tool-result-fold.js";
+export type { FoldToolResultsContext, ResolvedToolResultFoldOptions, ToolResultFoldInput, ToolResultFoldOptions, } from "./tool-result-fold.js";
 export { artifactStructuredOutputRequest, assertStructuredOutputRequestSupported, DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH, DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES, modelSupportsStructuredOutput, resolveRunProviderOptions, StructuredOutputError, validateStructuredOutputOptions, withoutStructuredOutput, } from "./structured-output.js";
 export type { ComposeSystemPromptOptions } from "./system-prompts.js";
 export { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
@@ -94,5 +100,5 @@ export { createToolParameterValidator, createToolRegistry, dispatchToolCall, fil
 export type { ResolvedUseCaseModel, ResolveUseCaseModelInput, UseCaseModelBinding, } from "./use-case-model.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export declare const name = "prism";
-export declare const version = "0.0.18";
+export declare const version = "0.0.20";
 export declare const description = "Agent harness for AI providers, agents, sessions, and tools.";

package/dist/index.js

@@ -45,12 +45,15 @@ export { assertPermission, assertTrusted, checkPermission, createStaticPermissio
 export { createMemorySessionStore, createSessionEntry, getSessionBranchEntries, listSessionBranches, rebuildSessionContext, } from "./session-stores.js";
 export { createChainedSettingsProvider, createStaticSettingsProvider } from "./settings.js";
 export { createSkillRegistry, resolveActiveSkills } from "./skills.js";
+export { createLoadedSkillSet, DEFAULT_MAX_SKILL_CATALOG_ENTRIES, DEFAULT_MAX_SKILL_DESCRIPTION_BYTES, DEFAULT_MAX_SKILL_INSTRUCTION_BYTES, EMPTY_SKILL_DESCRIPTION, HARD_MAX_SKILL_CATALOG_ENTRIES, HARD_MAX_SKILL_DESCRIPTION_BYTES, HARD_MAX_SKILL_INSTRUCTION_BYTES, isSkillDisclosureError, resolveSkillsDisclosure, SkillDisclosureError, } from "./skill-disclosure.js";
+export { createLoadSkillTool, DEFAULT_LOAD_SKILL_TOOL_NAME, isSkillLoadError, MAX_LOAD_SKILL_RESULT_BYTES, resolveSkillLoad, SKILL_LOAD_ERROR_CODE, SkillLoadError, } from "./skill-load.js";
+export { DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS, DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES, foldedToolResultHeader, foldToolResultHistory, foldToolResults, formatFoldedToolResult, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES, resolveToolResultFold, TOOL_RESULT_FOLD_TURN_METADATA_KEY, } from "./tool-result-fold.js";
 export { artifactStructuredOutputRequest, assertStructuredOutputRequestSupported, DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH, DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES, modelSupportsStructuredOutput, resolveRunProviderOptions, StructuredOutputError, validateStructuredOutputOptions, withoutStructuredOutput, } from "./structured-output.js";
 export { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 export { applyThinkingLevel, isThinkingLevel, normalizeThinkingLevel, THINKING_LEVELS, thinkingCompatFor, thinkingFamilyForModel, } from "./thinking.js";
 export { createToolParameterValidator, createToolRegistry, dispatchToolCall, filterTools } from "./tools.js";
 export { resolveUseCaseModel, resolveUseCaseModelBinding, useCaseCredentialProviderId, } from "./use-case-model.js";
 export const name = "prism";
-export const version = "0.0.18";
+export const version = "0.0.20";
 export const description = "Agent harness for AI providers, agents, sessions, and tools.";
 //# sourceMappingURL=index.js.map

package/dist/input.d.ts

@@ -2,6 +2,8 @@ import { type ContextBudget } from "./context-budget.js";
 import type { ContentBlock, ContextBlock, ContextProvider, ContextResolutionContext, InputBuildContext, InputBuilder, InstructionInjector, JsonObject, Message, ModelConfig, PromptBuilder, PromptBuildRequest, ProviderRequest, ProviderRequestOptions, ResourceLoader, Skill, ToolDefinition, ToolResult } from "./contracts.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import type { SecretRedactor } from "./redaction.js";
+import { type LoadedSkillSet, type SkillsDisclosure } from "./skill-disclosure.js";
+import { type ResolvedToolResultFoldOptions } from "./tool-result-fold.js";
 export type AgentInput = string | Message | readonly Message[];
 export interface PromptInstruction {
     readonly text: string;
@@ -53,10 +55,14 @@ export interface AssembleProviderInputOptions extends DefaultInputBuildContext {
     readonly contextProviders?: readonly ContextProvider[];
     readonly promptBuilder?: PromptBuilder;
     readonly skills?: readonly Skill[];
+    readonly skillsDisclosure?: SkillsDisclosure;
+    readonly loadedSkills?: LoadedSkillSet;
     readonly tools?: readonly ToolDefinition[];
     readonly providerOptions?: ProviderRequestOptions;
     /** Assembler-time eviction; does not delete session store history. */
     readonly contextBudget?: ContextBudget;
+    /** Resolved tool-result fold; projection-only, store untouched. */
+    readonly toolResultFold?: ResolvedToolResultFoldOptions;
 }
 export declare function createDefaultInputBuilder(): DefaultInputBuilder;
 export declare function resolveContextProviders(options: ResolveContextOptions): Promise<readonly ContextBlock[]>;

package/dist/input.js

@@ -3,6 +3,8 @@ import { applyContextBudget, CONTEXT_BUDGET_REPORT_METADATA_KEY } from "./contex
 import { runInstructionInjectors } from "./instruction-injection.js";
 import { redactMessage } from "./redaction.js";
 import { loadTextResource } from "./resources.js";
+import { skillMessages as buildSkillMessages } from "./skill-disclosure.js";
+import { foldToolResultHistory, foldToolResults } from "./tool-result-fold.js";
 import { composeSystemPrompt } from "./system-prompts.js";
 export function createDefaultInputBuilder() {
     return {
@@ -39,7 +41,16 @@ export function createDefaultPromptBuilder() {
             // Tool-capable models receive schemas via request.tools; the text list only serves
             // text-only (or unknown-capability) models — duplicating it doubles tool tokens per turn.
             const tools = request.model?.capabilities?.tools === true ? undefined : request.tools;
-            return [...contextMessages(request.context), ...skillMessages(request.skills), ...toolMessages(tools), ...request.messages];
+            return [
+                ...contextMessages(request.context),
+                ...buildSkillMessages(request.skills, {
+                    disclosure: request.skillsDisclosure,
+                    loaded: request.loadedSkills,
+                    demotedBodies: request.demotedSkillBodies?.length ? new Set(request.demotedSkillBodies) : undefined,
+                }),
+                ...toolMessages(tools),
+                ...request.messages,
+            ];
         },
     };
 }
@@ -64,6 +75,18 @@ export async function assembleProviderInput(options) {
     // filter against loop-local turn. Instructions layer via composeSystemPrompt (no parallel prompt
     // code); contextBlocks merge via resolveContextProviders (middleware still runs).
     const turn = options.turn ?? 1;
+    const foldContext = {
+        sessionId: options.sessionId ?? "",
+        runId: options.runId ?? "",
+        turn,
+        signal: options.signal,
+    };
+    const foldedHistory = options.toolResultFold
+        ? await foldToolResultHistory(options.history ?? [], options.toolResultFold, foldContext)
+        : (options.history ?? []);
+    const foldedToolResults = options.toolResultFold && options.toolResults?.length
+        ? await foldToolResults(options.toolResults, options.toolResultFold, foldContext)
+        : options.toolResults;
     const injectorContribs = options.instructionInjectors?.length
         ? runInstructionInjectors(options.instructionInjectors, {
             sessionId: options.sessionId ?? "",
@@ -71,7 +94,7 @@ export async function assembleProviderInput(options) {
             turn,
             // Runtime history is already redacted; input is redacted here before injector code sees it.
             input: inputMessages(options.input).map((message) => redactMessage(message, options.redactor)),
-            history: options.history ?? [],
+            history: foldedHistory,
             metadata: options.metadata ?? {},
             signal: options.signal ?? new AbortController().signal,
         })
@@ -79,12 +102,19 @@ export async function assembleProviderInput(options) {
     const systemInstructions = injectorContribs.instructions.length
         ? composeSystemPrompt(injectorContribs.instructions, { base: options.systemInstructions })
         : options.systemInstructions;
-    const buildContext = { ...options, ...baseContext, systemInstructions };
+    const buildContext = {
+        ...options,
+        ...baseContext,
+        systemInstructions,
+        history: foldedHistory,
+        toolResults: foldedToolResults,
+    };
     const layout = buildContext.inputLayout ?? "cache_aware";
     let messages;
     let context;
     let skills = options.skills;
     let tools = options.tools;
+    let demotedSkillBodies;
     let budgetReport;
     if (options.contextBudget) {
         // ponytail: budget path always uses default groups so eviction kinds stay deterministic;
@@ -104,6 +134,8 @@ export async function assembleProviderInput(options) {
             tools,
             budget: options.contextBudget,
             layout,
+            skillsDisclosure: options.skillsDisclosure,
+            loadedSkills: options.loadedSkills,
         });
         messages = flattenInputGroups(applied.groups, layout);
         if (buildContext.middleware)
@@ -111,6 +143,7 @@ export async function assembleProviderInput(options) {
         context = applied.context;
         skills = applied.skills;
         tools = applied.tools;
+        demotedSkillBodies = applied.demotedSkillBodies;
         if (options.contextBudget.reportOmissions)
             budgetReport = applied.report;
     }
@@ -134,6 +167,9 @@ export async function assembleProviderInput(options) {
             messages,
             context,
             skills,
+            skillsDisclosure: options.skillsDisclosure,
+            loadedSkills: options.loadedSkills,
+            demotedSkillBodies,
             tools,
             metadata: options.metadata,
             signal: options.signal,
@@ -142,6 +178,9 @@ export async function assembleProviderInput(options) {
             messages,
             context,
             skills,
+            skillsDisclosure: options.skillsDisclosure,
+            loadedSkills: options.loadedSkills,
+            demotedSkillBodies,
             tools,
             metadata: options.metadata,
             signal: options.signal,
@@ -274,11 +313,6 @@ function textMessage(role, text, metadata) {
 function contextMessages(context) {
     return (context ?? []).map((block) => textMessage("system", `${block.title ? `${block.title}:\n` : "Context:\n"}${blockText(block)}`, block.metadata));
 }
-function skillMessages(skills) {
-    return (skills ?? [])
-        .filter((skill) => skill.instructions)
-        .map((skill) => textMessage("system", `Skill ${skill.name}:\n${skill.instructions}`, skill.metadata));
-}
 function toolMessages(tools) {
     if (!tools?.length)
         return [];

package/dist/skill-disclosure.d.ts

@@ -0,0 +1,35 @@
+import type { Message, Skill } from "./contracts.js";
+export type SkillsDisclosure = "progressive" | "eager";
+export declare const EMPTY_SKILL_DESCRIPTION: "(no description)";
+export declare const DEFAULT_MAX_SKILL_CATALOG_ENTRIES = 64;
+export declare const HARD_MAX_SKILL_CATALOG_ENTRIES = 256;
+export declare const DEFAULT_MAX_SKILL_DESCRIPTION_BYTES = 512;
+export declare const HARD_MAX_SKILL_DESCRIPTION_BYTES = 4096;
+export declare const DEFAULT_MAX_SKILL_INSTRUCTION_BYTES = 32768;
+export declare const HARD_MAX_SKILL_INSTRUCTION_BYTES = 262144;
+export declare const SKILL_DISCLOSURE_ERROR_CODE: "skill_disclosure_exceeded";
+export declare class SkillDisclosureError extends Error {
+    readonly code: "skill_disclosure_exceeded";
+    constructor(message: string);
+}
+export declare function isSkillDisclosureError(error: unknown): error is SkillDisclosureError;
+export interface LoadedSkillSet {
+    has(name: string): boolean;
+    add(name: string): void;
+    list(): readonly string[];
+    clear(): void;
+}
+export declare function createLoadedSkillSet(): LoadedSkillSet;
+export interface SkillRenderContext {
+    readonly disclosure?: SkillsDisclosure;
+    readonly loaded?: LoadedSkillSet;
+    /** Budget demotion: render catalog-only even when eager/loaded. */
+    readonly demotedBodies?: ReadonlySet<string>;
+}
+export declare function resolveSkillsDisclosure(run?: SkillsDisclosure, agent?: SkillsDisclosure): SkillsDisclosure;
+export declare function capSkillCatalog(skills: readonly Skill[]): readonly Skill[];
+/** Skills that should appear in prompt assembly for the given disclosure mode. */
+export declare function selectSkillsForPrompt(skills: readonly Skill[], context?: SkillRenderContext): readonly Skill[];
+export declare function skillHasRenderableBody(skill: Skill, context?: SkillRenderContext): boolean;
+export declare function skillPromptText(skill: Skill, context?: SkillRenderContext): string | undefined;
+export declare function skillMessages(skills: readonly Skill[] | undefined, context?: SkillRenderContext): Message[];

package/dist/skill-disclosure.js

@@ -0,0 +1,101 @@
+import { estimateTextBytes } from "./context-budget.js";
+export const EMPTY_SKILL_DESCRIPTION = "(no description)";
+export const DEFAULT_MAX_SKILL_CATALOG_ENTRIES = 64;
+export const HARD_MAX_SKILL_CATALOG_ENTRIES = 256;
+export const DEFAULT_MAX_SKILL_DESCRIPTION_BYTES = 512;
+export const HARD_MAX_SKILL_DESCRIPTION_BYTES = 4_096;
+export const DEFAULT_MAX_SKILL_INSTRUCTION_BYTES = 32_768;
+export const HARD_MAX_SKILL_INSTRUCTION_BYTES = 262_144;
+export const SKILL_DISCLOSURE_ERROR_CODE = "skill_disclosure_exceeded";
+export class SkillDisclosureError extends Error {
+    code = SKILL_DISCLOSURE_ERROR_CODE;
+    constructor(message) {
+        super(message);
+        this.name = "SkillDisclosureError";
+    }
+}
+export function isSkillDisclosureError(error) {
+    return error instanceof Error && error.code === SKILL_DISCLOSURE_ERROR_CODE;
+}
+export function createLoadedSkillSet() {
+    const names = new Set();
+    return {
+        has(name) {
+            return names.has(name);
+        },
+        add(name) {
+            names.add(name);
+        },
+        list() {
+            return [...names];
+        },
+        clear() {
+            names.clear();
+        },
+    };
+}
+export function resolveSkillsDisclosure(run, agent) {
+    return run ?? agent ?? "progressive";
+}
+export function capSkillCatalog(skills) {
+    if (skills.length > HARD_MAX_SKILL_CATALOG_ENTRIES) {
+        throw new SkillDisclosureError(`Skill catalog exceeds hard cap (${HARD_MAX_SKILL_CATALOG_ENTRIES} entries)`);
+    }
+    return skills.slice(0, DEFAULT_MAX_SKILL_CATALOG_ENTRIES);
+}
+/** Skills that should appear in prompt assembly for the given disclosure mode. */
+export function selectSkillsForPrompt(skills, context = {}) {
+    const disclosure = context.disclosure ?? "progressive";
+    if (disclosure === "eager")
+        return skills.filter((skill) => skill.instructions);
+    return skills;
+}
+export function skillHasRenderableBody(skill, context = {}) {
+    const disclosure = context.disclosure ?? "progressive";
+    const loaded = context.loaded?.has(skill.name) ?? false;
+    const demoted = context.demotedBodies?.has(skill.name) ?? false;
+    return !demoted && (disclosure === "eager" || loaded) && !!skill.instructions;
+}
+export function skillPromptText(skill, context = {}) {
+    const includeBody = skillHasRenderableBody(skill, context);
+    if (includeBody) {
+        if (!skill.instructions)
+            return undefined;
+        const bytes = estimateTextBytes(skill.instructions);
+        if (bytes > HARD_MAX_SKILL_INSTRUCTION_BYTES) {
+            throw new SkillDisclosureError(`Skill ${skill.name} instructions exceed hard cap (${HARD_MAX_SKILL_INSTRUCTION_BYTES} bytes)`);
+        }
+        return `Skill ${skill.name}:\n${skill.instructions}`;
+    }
+    let description = skill.description?.trim() || EMPTY_SKILL_DESCRIPTION;
+    const bytes = estimateTextBytes(description);
+    if (bytes > HARD_MAX_SKILL_DESCRIPTION_BYTES) {
+        throw new SkillDisclosureError(`Skill ${skill.name} description exceeds hard cap (${HARD_MAX_SKILL_DESCRIPTION_BYTES} bytes)`);
+    }
+    if (bytes > DEFAULT_MAX_SKILL_DESCRIPTION_BYTES) {
+        description = truncateUtf8Bytes(description, DEFAULT_MAX_SKILL_DESCRIPTION_BYTES);
+    }
+    return `Skill ${skill.name}: ${description}`;
+}
+export function skillMessages(skills, context = {}) {
+    return capSkillCatalog(selectSkillsForPrompt(skills ?? [], context))
+        .map((skill) => {
+        const text = skillPromptText(skill, context);
+        return text ? textMessage("system", text, skill.metadata) : undefined;
+    })
+        .filter((message) => message !== undefined);
+}
+function textMessage(role, text, metadata) {
+    return { role, content: [{ type: "text", text }], metadata };
+}
+function truncateUtf8Bytes(text, maxBytes) {
+    const encoded = new TextEncoder().encode(text);
+    if (encoded.length <= maxBytes)
+        return text;
+    const suffix = new TextEncoder().encode("…");
+    let end = Math.max(0, maxBytes - suffix.length);
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return new TextDecoder().decode(encoded.slice(0, end)) + "…";
+}
+//# sourceMappingURL=skill-disclosure.js.map

package/dist/skill-load.d.ts

@@ -0,0 +1,25 @@
+import type { Skill, SkillRegistry, ToolDefinition } from "./contracts.js";
+import { type LoadedSkillSet } from "./skill-disclosure.js";
+export declare const DEFAULT_LOAD_SKILL_TOOL_NAME: "load_skill";
+export declare const SKILL_LOAD_ERROR_CODE: "skill_load_failed";
+export declare const MAX_LOAD_SKILL_RESULT_BYTES = 512;
+export declare class SkillLoadError extends Error {
+    readonly code: "skill_load_failed";
+    constructor(message: string);
+}
+export declare function isSkillLoadError(error: unknown): error is SkillLoadError;
+export interface ResolveSkillLoadOptions {
+    readonly registry: SkillRegistry;
+    readonly name: string;
+    readonly tools?: readonly ToolDefinition[];
+    readonly loaded?: LoadedSkillSet;
+    readonly activeSkillNames?: readonly string[];
+}
+export declare function resolveSkillLoad(options: ResolveSkillLoadOptions): Skill;
+export interface CreateLoadSkillToolOptions {
+    readonly registry: SkillRegistry;
+    readonly loaded?: LoadedSkillSet;
+    readonly tools?: readonly ToolDefinition[];
+    readonly name?: string;
+}
+export declare function createLoadSkillTool(options: CreateLoadSkillToolOptions): ToolDefinition;