@arnilo/prism 0.0.19 → 0.0.20

package/dist/skill-load.js

@@ -0,0 +1,112 @@
+import { estimateTextBytes } from "./context-budget.js";
+import { HARD_MAX_SKILL_INSTRUCTION_BYTES } from "./skill-disclosure.js";
+export const DEFAULT_LOAD_SKILL_TOOL_NAME = "load_skill";
+export const SKILL_LOAD_ERROR_CODE = "skill_load_failed";
+export const MAX_LOAD_SKILL_RESULT_BYTES = 512;
+export class SkillLoadError extends Error {
+    code = SKILL_LOAD_ERROR_CODE;
+    constructor(message) {
+        super(message);
+        this.name = "SkillLoadError";
+    }
+}
+export function isSkillLoadError(error) {
+    return error instanceof Error && error.code === SKILL_LOAD_ERROR_CODE;
+}
+export function resolveSkillLoad(options) {
+    const name = options.name.trim();
+    if (!name)
+        throw new SkillLoadError("Skill name is required");
+    let skill;
+    try {
+        skill = options.registry.resolve(name);
+    }
+    catch {
+        throw new SkillLoadError(`Unknown skill: ${name}`);
+    }
+    if (options.activeSkillNames && !options.activeSkillNames.includes(skill.name)) {
+        throw new SkillLoadError(`Skill ${skill.name} is not active for this run`);
+    }
+    const toolNames = new Set((options.tools ?? []).map((tool) => tool.name));
+    const missingTool = skill.toolNames?.find((toolName) => !toolNames.has(toolName));
+    if (missingTool)
+        throw new SkillLoadError(`Skill ${skill.name} requires inactive tool: ${missingTool}`);
+    if (!skill.instructions?.trim())
+        throw new SkillLoadError(`Skill ${skill.name} has no instructions to load`);
+    const bytes = estimateTextBytes(skill.instructions);
+    if (bytes > HARD_MAX_SKILL_INSTRUCTION_BYTES) {
+        throw new SkillLoadError(`Skill ${skill.name} instructions exceed hard cap (${HARD_MAX_SKILL_INSTRUCTION_BYTES} bytes)`);
+    }
+    if (options.loaded?.has(skill.name))
+        throw new SkillLoadError(`Skill ${skill.name} is already loaded`);
+    return skill;
+}
+function skillLoadMetadata(context) {
+    const metadata = context.metadata;
+    if (!metadata || typeof metadata !== "object")
+        return undefined;
+    return metadata;
+}
+function capLoadSkillText(text) {
+    const bytes = estimateTextBytes(text);
+    if (bytes <= MAX_LOAD_SKILL_RESULT_BYTES)
+        return text;
+    const suffix = "…";
+    let end = MAX_LOAD_SKILL_RESULT_BYTES - new TextEncoder().encode(suffix).length;
+    const encoded = new TextEncoder().encode(text);
+    while (end > 0 && (encoded[end] & 0xc0) === 0x80)
+        end--;
+    return new TextDecoder().decode(encoded.slice(0, end)) + suffix;
+}
+export function createLoadSkillTool(options) {
+    const toolName = options.name ?? DEFAULT_LOAD_SKILL_TOOL_NAME;
+    return {
+        name: toolName,
+        description: "Load the full instructions for an active skill by exact name.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "Exact skill name from the catalog." },
+            },
+            required: ["name"],
+        },
+        execute(args, context) {
+            const fail = (reason, text) => {
+                const bounded = capLoadSkillText(text);
+                return {
+                    toolCallId: context.toolCallId,
+                    name: toolName,
+                    value: { ok: false, reason, text: bounded },
+                    content: [{ type: "text", text: bounded }],
+                };
+            };
+            const name = typeof args.name === "string" ? args.name : "";
+            const metadata = skillLoadMetadata(context);
+            const loaded = metadata?.loadedSkills ?? options.loaded;
+            if (!loaded)
+                return fail("no_loaded_set", "Skill load state is unavailable for this session.");
+            try {
+                const skill = resolveSkillLoad({
+                    registry: options.registry,
+                    name,
+                    tools: metadata?.activeTools ?? options.tools,
+                    loaded,
+                    activeSkillNames: metadata?.activeSkillNames,
+                });
+                loaded.add(skill.name);
+                const text = capLoadSkillText(`Loaded skill ${skill.name} for this session.`);
+                return {
+                    toolCallId: context.toolCallId,
+                    name: toolName,
+                    value: { ok: true, name: skill.name, text },
+                    content: [{ type: "text", text }],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Skill load failed";
+                return fail("skill_load_failed", message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=skill-load.js.map

package/dist/tool-result-fold.d.ts

@@ -0,0 +1,40 @@
+import type { Message, ToolResult } from "./contracts.js";
+export declare const DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS = 2;
+export declare const DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES = 4096;
+export declare const DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 512;
+export declare const HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 4096;
+export declare const TOOL_RESULT_FOLD_TURN_METADATA_KEY: "prismToolResultTurn";
+export interface ToolResultFoldInput {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly text: string;
+}
+export interface ToolResultFoldOptions {
+    readonly minAgeTurns?: number;
+    readonly minBytes?: number;
+    readonly maxSummaryBytes?: number;
+    readonly summarize: (input: ToolResultFoldInput) => Promise<string> | string;
+}
+export interface ResolvedToolResultFoldOptions {
+    readonly minAgeTurns: number;
+    readonly minBytes: number;
+    readonly maxSummaryBytes: number;
+    readonly summarize: (input: ToolResultFoldInput) => Promise<string> | string;
+}
+export interface FoldToolResultsContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly signal?: AbortSignal;
+}
+/** Run overrides agent; disabled when neither supplies `summarize`. */
+export declare function resolveToolResultFold(run?: ToolResultFoldOptions, agent?: ToolResultFoldOptions): ResolvedToolResultFoldOptions | undefined;
+/** Projection-only fold for history tool messages; does not mutate the input array. */
+export declare function foldToolResultHistory(history: readonly Message[], options: ResolvedToolResultFoldOptions, context: FoldToolResultsContext): Promise<readonly Message[]>;
+/** Projection-only fold for in-flight tool results before message conversion. */
+export declare function foldToolResults(results: readonly ToolResult[], options: ResolvedToolResultFoldOptions, context: FoldToolResultsContext): Promise<readonly ToolResult[]>;
+export declare function formatFoldedToolResult(summary: string): string;
+export declare function foldedToolResultHeader(toolName: string, toolCallId: string, summary: string): string;

package/dist/tool-result-fold.js

@@ -0,0 +1,164 @@
+import { estimateTextBytes } from "./context-budget.js";
+export const DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS = 2;
+export const DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES = 4_096;
+export const DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 512;
+export const HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES = 4_096;
+export const TOOL_RESULT_FOLD_TURN_METADATA_KEY = "prismToolResultTurn";
+/** Run overrides agent; disabled when neither supplies `summarize`. */
+export function resolveToolResultFold(run, agent) {
+    const options = run ?? agent;
+    if (!options?.summarize)
+        return undefined;
+    const minAgeTurns = options.minAgeTurns ?? DEFAULT_TOOL_RESULT_FOLD_MIN_AGE_TURNS;
+    const minBytes = options.minBytes ?? DEFAULT_TOOL_RESULT_FOLD_MIN_BYTES;
+    const maxSummaryBytes = options.maxSummaryBytes ?? DEFAULT_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES;
+    assertPositiveInt(minAgeTurns, "minAgeTurns", 1, 1_024);
+    assertPositiveInt(minBytes, "minBytes", 1, 32 * 1024 * 1024);
+    assertPositiveInt(maxSummaryBytes, "maxSummaryBytes", 1, HARD_TOOL_RESULT_FOLD_MAX_SUMMARY_BYTES);
+    return { minAgeTurns, minBytes, maxSummaryBytes, summarize: options.summarize };
+}
+/** Projection-only fold for history tool messages; does not mutate the input array. */
+export async function foldToolResultHistory(history, options, context) {
+    if (history.length === 0)
+        return history;
+    const turns = inferToolResultTurns(history);
+    const out = [];
+    for (let index = 0; index < history.length; index += 1) {
+        const message = history[index];
+        const folded = await foldToolResultMessage(message, options, {
+            ...context,
+            toolResultTurn: turns[index] ?? context.turn,
+        });
+        out.push(folded);
+    }
+    return out;
+}
+/** Projection-only fold for in-flight tool results before message conversion. */
+export async function foldToolResults(results, options, context) {
+    if (results.length === 0)
+        return results;
+    const out = [];
+    for (const result of results) {
+        const folded = await foldToolResultValue(result, options, { ...context, toolResultTurn: context.turn });
+        out.push(folded);
+    }
+    return out;
+}
+async function foldToolResultMessage(message, options, context) {
+    if (message.role !== "tool")
+        return message;
+    const block = message.content.find((part) => part.type === "tool_result");
+    if (!block || block.type !== "tool_result")
+        return message;
+    const text = toolResultText(block.result, block.error, message.content);
+    const folded = await maybeFold({
+        options,
+        context,
+        toolCallId: block.toolCallId,
+        toolName: block.name,
+        text,
+        apply: (summary) => ({
+            ...message,
+            content: message.content.map((part) => part.type === "tool_result"
+                ? { ...part, result: foldedToolResultHeader(block.name, block.toolCallId, summary), error: undefined }
+                : part),
+            metadata: { ...message.metadata, prismFolded: true },
+        }),
+    });
+    return folded ?? message;
+}
+async function foldToolResultValue(result, options, context) {
+    const text = toolResultText(result.value, result.error, result.content);
+    const folded = await maybeFold({
+        options,
+        context,
+        toolCallId: result.toolCallId,
+        toolName: result.name,
+        text,
+        apply: (summary) => ({
+            ...result,
+            value: foldedToolResultHeader(result.name, result.toolCallId, summary),
+            error: undefined,
+            metadata: { ...result.metadata, prismFolded: true },
+        }),
+    });
+    return folded ?? result;
+}
+async function maybeFold(input) {
+    const age = input.context.turn - input.context.toolResultTurn;
+    if (age < input.options.minAgeTurns)
+        return undefined;
+    if (estimateTextBytes(input.text) < input.options.minBytes)
+        return undefined;
+    throwIfAborted(input.context.signal);
+    try {
+        const summary = await input.options.summarize({
+            sessionId: input.context.sessionId,
+            runId: input.context.runId,
+            turn: input.context.toolResultTurn,
+            toolCallId: input.toolCallId,
+            toolName: input.toolName,
+            text: input.text,
+        });
+        return input.apply(capSummaryBytes(String(summary), input.options.maxSummaryBytes));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function formatFoldedToolResult(summary) {
+    return summary;
+}
+export function foldedToolResultHeader(toolName, toolCallId, summary) {
+    return `Tool result ${toolName} [${toolCallId}]: ${summary}`;
+}
+function toolResultText(result, error, extra) {
+    const parts = [JSON.stringify(error ?? result ?? null)];
+    for (const block of extra ?? []) {
+        if (block.type === "text" && "text" in block && typeof block.text === "string")
+            parts.push(block.text);
+    }
+    return parts.join("\n");
+}
+function capSummaryBytes(summary, maxBytes) {
+    const bytes = estimateTextBytes(summary);
+    if (bytes <= maxBytes)
+        return summary;
+    const encoded = new TextEncoder().encode(summary);
+    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)) + "…";
+}
+function inferToolResultTurns(history) {
+    const turns = new Array(history.length).fill(1);
+    let providerTurn = 0;
+    let toolTurn = 1;
+    for (let index = 0; index < history.length; index += 1) {
+        const message = history[index];
+        const stamped = readToolResultTurn(message.metadata);
+        if (message.role === "assistant") {
+            providerTurn += 1;
+            toolTurn = providerTurn;
+        }
+        if (message.role === "tool") {
+            turns[index] = stamped ?? toolTurn;
+        }
+    }
+    return turns;
+}
+function readToolResultTurn(metadata) {
+    const value = metadata?.[TOOL_RESULT_FOLD_TURN_METADATA_KEY];
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+function assertPositiveInt(value, name, min, max) {
+    if (!Number.isSafeInteger(value) || value < min || value > max) {
+        throw new TypeError(`toolResultFold.${name} must be a safe integer from ${min} to ${max}`);
+    }
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason instanceof Error ? signal.reason : new Error("Tool result fold aborted");
+}
+//# sourceMappingURL=tool-result-fold.js.map

package/docs/0.1.0-readiness.md

@@ -1,6 +1,6 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.0.19** is the current release line (Phase 2 observational memory lifecycle); **1.0** readiness remains operator-gated, not automatic.
+Status: **0.0.20** is the current release line (Phase 3 skills progressive disclosure); **1.0** readiness remains operator-gated, not automatic.
 
 This page distills runnable readiness gates into one command-per-gate table. The
 **Last evidence** column records the 2026-07-26 **0.0.16** baseline snapshot
@@ -14,13 +14,13 @@ Evidence trail: [`docs/review-coverage-2026-07-26-phase-11.md`](./review-coverag
 (addenda 0–9), [`docs/release-and-install.md`](./release-and-install.md),
 [`docs/migration.md`](./migration.md), [`docs/performance.md`](./performance.md).
 
-## Current line (0.0.19)
+## Current line (0.0.20)
 
 | Item | Status |
 |---|---|
-| Published graph | **44** publishable manifests at **0.0.19** (`docs/release-and-install.md`) |
-| Phase 2 observational memory | `createObservationalMemory().attach()`, four-layer context, nested settings, recall paging, hard fold/render caps |
-| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.18 → 0.0.19 observational memory lifecycle` documents intentional breaks |
+| Published graph | **44** publishable manifests at **0.0.20** (`docs/release-and-install.md`) |
+| Phase 3 progressive disclosure | `skillsDisclosure`, `load_skill`, empty registry default + `activateAllSkills`, priority budget demotion, optional `toolResultFold` |
+| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.19 → 0.0.20 skills and context progressive disclosure` documents intentional breaks |
 | Readiness table below | **0.0.16 measured values** — refresh evidence columns when 1.0 RC gates are recorded |
 
 ## Gate table

package/docs/agent-session-runtime.md

@@ -51,6 +51,8 @@ string | Message | readonly Message[]
 
 `RunOptions.model` can override the request model for a run. Model overrides append a `model_change` entry. `AgentConfig.inputLayout` selects the default input assembly layout (`"cache_aware"` by default, or opt-in `"legacy"`); `RunOptions.inputLayout` wins for one run. `AgentConfig.providerOptions`/`RunOptions.providerOptions` supply generic provider request options; `timeoutMs`, `maxRetries`, and `maxRetryDelayMs` are deprecated inert provider-level hints in first-party providers. Use `RunOptions.signal`/host abort controllers for timeouts and `AgentConfig.retry`/`RunOptions.retry` for retry. `AgentConfig.providerRequestPolicies`/`RunOptions.providerRequestPolicies` run before `AIProvider.generate()` and before `provider_request` middleware. `AgentConfig.systemPrompt` and `RunOptions.systemPrompt` add explicit layered system prompt contributions; `RunOptions.systemPrompt: false` disables configured prompt layers for that run while keeping `AgentConfig.instructions` as the base path. `RunOptions.compaction` can enable auto-compaction for that run or use `false` to disable configured auto-compaction. `RunOptions.retry` can enable provider-turn retry for that run or use `false` to disable configured retry. `RunOptions.metadata` is merged with agent/session metadata for assembly, provider requests, and tool contexts. Deprecated `RunOptions.maxToolRounds` narrows `limits.maxToolRounds`. `RunOptions.signal` is bridged into the per-run abort signal passed to assembly, providers, tools, auto-compaction, and retry backoff.
 
+`RunOptions.activeSkills` selects named skills from a configured `SkillRegistry`; `RunOptions.skills` replaces a plain `Skill[]` config for one run. When `AgentConfig.skills` is a registry and neither is set, **no skills activate** unless `activateAllSkills: true` (run or agent). `skillsDisclosure` (`"progressive"` default, `"eager"` opt-in; run wins) controls catalog vs full instruction bodies; the session-owned `LoadedSkillSet` is populated by `load_skill` when the host registers `createLoadSkillTool`. `toolResultFold` (off unless the host supplies `summarize`) optionally folds aged large tool results in provider input only. See [Context and skills](context-and-skills.md).
+
 ## Outputs / response / events
 
 `session.run()` / `session.prompt()` resolve to an `AgentRunResult` with `sessionId`, `runId`, `status`, `text`, `content`, optional `message`/`usage`/`leafId`, and terminal `error`/`abortReason` when applicable. Callers may ignore the return value. Failed and aborted runs still emit their terminal events, then reject with `AgentRunError` whose `.result` carries the same shape.

package/docs/context-and-skills.md

@@ -6,7 +6,7 @@
 
 ## When to use it
 
-Use context resolution when a host wants project/session/context blocks resolved before prompt composition. Use the skill registry when a host wants explicit progressive skill disclosure. Declarative `AgentDefinition.skills` are inactive unless listed; omitted skills means none unless the host uses the migration-only `activateAllCapabilities: true` option.
+Use context resolution when a host wants project/session/context blocks resolved before prompt composition. Use the skill registry when a host wants explicit progressive skill disclosure: catalog `name` + `description` every turn by default, full `instructions` only after `load_skill` or when the host opts into eager mode. Declarative `AgentDefinition.skills` are inactive unless listed; omitted skills means none unless the host uses the migration-only `activateAllCapabilities: true` option.
 
 Do not use these helpers as an agent loop, package discovery mechanism, context cache, token budgeter, retrier, credential resolver, semantic skill ranker, tool activator, or permission system.
 
@@ -107,7 +107,8 @@ The agent/session runtime resolves skills per run and wires each active skill's
 | Surface | Config shape | Run override | Active skills |
 | --- | --- | --- | --- |
 | Runtime agent | `AgentConfig.skills: SkillRegistry` | `RunOptions.activeSkills: ["brief"]` | Named skills only, resolved with `resolveActiveSkills({ registry, names, tools })`. |
-| Runtime agent | `AgentConfig.skills: SkillRegistry` | no `activeSkills` / no `skills` | All registry skills (`SkillRegistry.list()`). |
+| Runtime agent | `AgentConfig.skills: SkillRegistry` | no `activeSkills` / no `skills` / no `activateAllSkills` | No skills active (fail-closed default). |
+| Runtime agent | `AgentConfig.skills: SkillRegistry` | `activateAllSkills: true` (run or agent) | All registry skills (`SkillRegistry.list()`), migration opt-in. |
 | Runtime agent | `AgentConfig.skills: Skill[]` | `RunOptions.skills: [...]` | Override array only. |
 | Runtime agent | `AgentConfig.skills: Skill[]` | no `RunOptions.skills` | All configured array skills. |
 | Declarative definition | `AgentDefinition.skills: ["brief"]` | later runtime `activeSkills` optional | Listed names only. |
@@ -118,13 +119,13 @@ Runtime selection precedence mirrors the other `RunOptions` overrides (`redactor
 
 1. `AgentConfig.skills` is a `SkillRegistry` and `RunOptions.activeSkills: readonly string[]` (names) is set → the runtime calls `resolveActiveSkills({ registry, names, tools })`.
 2. `RunOptions.skills: readonly Skill[]` is set → that array replaces `AgentConfig.skills` for the run. This override exists for the case where `AgentConfig.skills` is a plain `Skill[]` (no registry), so name resolution is impossible.
-3. Neither set → all configured runtime skills are active (current behavior; `SkillRegistry.list()` or the plain array as-is). This is not the declarative default.
+3. Neither set → no skills active when `AgentConfig.skills` is a `SkillRegistry` (fail-closed). Use `activateAllSkills: true` on the run or agent to restore prior list-all behavior (`SkillRegistry.list()`). Plain `Skill[]` configs still activate every configured array skill. This is not the declarative default.
 
 names win when a registry exists. `RunOptions.activeSkills` cannot be used against a plain-array `AgentConfig.skills` — use `RunOptions.skills` instead. Use `RunOptions.skills: []` for an explicit no-skills runtime run.
 
-Each active skill contributes two things the runtime now wires together:
+Each active skill contributes two things the runtime wires together:
 
-- `Skill.instructions` → rendered as system messages by `skillMessages()` (active set only).
+- `Skill` prompt text → rendered as system messages by `skillMessages()` / `skillPromptText()` (active set only). Default `skillsDisclosure: "progressive"` sends `Skill <name>: <description>`; full `instructions` appear only when the skill is in the session `LoadedSkillSet` or disclosure is `"eager"`.
 - `Skill.context: ContextProvider[]` → collected across active skills (`activeSkills.flatMap(s => s.context ?? [])`), resolved through the existing `resolveContextProviders(...)`, and merged into the request's `context` **after** host `AgentConfig.context` blocks. Inactive skills contribute neither instructions nor context.
 
 `toolNames` enforcement is live: because selection routes through `resolveActiveSkills()`, a skill demanding a host-inactive tool throws with `Skill ${name} requires inactive tool: ${missing}` **before the first provider turn** — no provider call, no store write, no partial side effect. This is the fail-fast contract the docs already claimed; the runtime now honors it.
@@ -153,7 +154,69 @@ await session.run(input, { skills: [{ name: "verbose", instructions: "Be verbose
 await session.run(input, { skills: [] }); // explicit no skills for this run
 ```
 
-Skill selection grants no tool access and cannot bypass permissions — a skill's `toolNames` can only *require* host-active tools, never activate or grant them. Declarative skills also do not activate themselves by presence in a registry; list names on `AgentDefinition.skills` (or pass runtime `activeSkills`) when wanted. Per-skill token budgeting is deferred; the merge order (host context, then skill context) is the only priority knob today.
+Skill selection grants no tool access and cannot bypass permissions — a skill's `toolNames` can only *require* host-active tools, never activate or grant them. Declarative skills also do not activate themselves by presence in a registry; list names on `AgentDefinition.skills` (or pass runtime `activeSkills`) when wanted.
+
+### Progressive skill disclosure
+
+`skillsDisclosure` on `AgentConfig` / `RunOptions` (`"progressive"` default, `"eager"` opt-in; run wins) controls how active skills render in provider input:
+
+| Mode | Provider view per active skill |
+| --- | --- |
+| `"progressive"` (default) | `Skill <name>: <description>` (or `(no description)` when empty) |
+| `"eager"` | `Skill <name>:\n<instructions>` every turn (pre-0.0.20 behavior) |
+
+Catalog caps: **64** entries default / **256** hard; descriptions **512 B** default / **4 KiB** hard; instruction bodies **32 KiB** default / **256 KiB** hard on load/eager render. Oversize catalog/description/instruction payloads fail closed (`SkillDisclosureError` / `SkillLoadError`).
+
+```ts
+import { assembleProviderInput, createLoadedSkillSet } from "@arnilo/prism";
+
+const loaded = createLoadedSkillSet(); // session-owned; not checkpoint-persisted in 0.0.20
+const request = await assembleProviderInput({
+  model,
+  input: "Hi",
+  skills: active,
+  skillsDisclosure: "progressive",
+  loadedSkills: loaded,
+});
+```
+
+### On-demand skill load (`load_skill`)
+
+Hosts opt in by registering `createLoadSkillTool({ registry, loaded })` on the active tool set. The model calls `load_skill { name }` with an exact registry name; success adds the name to the session `LoadedSkillSet` so later turns include `instructions` under progressive mode. The tool does **not** activate tools, widen permissions, or load skills that were not active for the run.
+
+Fail-closed cases: unknown name, inactive skill for the run, inactive required `toolNames`, oversize body, duplicate load, missing session loaded-set wiring. Tool output and errors are size-capped; skill text is untrusted host/extension data.
+
+```ts
+import { createAgent, createLoadSkillTool, createSkillRegistry } from "@arnilo/prism";
+
+const registry = createSkillRegistry([ponytail, brief]);
+const loadSkill = createLoadSkillTool({ registry }); // session injects loadedSkills at dispatch
+const agent = createAgent({ model, provider, skills: registry, tools: [loadSkill, /* host */] });
+await agent.createSession().run("…", { activeSkills: ["ponytail"] });
+// Turn 1: catalog only. After load_skill({ name: "ponytail" }), later turns include instructions.
+```
+
+Pure validation without the tool: `resolveSkillLoad({ registry, name, tools, loaded, activeSkillNames })`.
+
+### Context budget priority and skill demotion
+
+When `assembleProviderInput` runs with `contextBudget`, `applyContextBudget` evicts droppable sections in layout order. Within `context` blocks and skills, victims sort by ascending `ContextBlock.priority` (missing = **0**), then LIFO within the same priority.
+
+Under pressure on a skill with a loaded body, eviction may demote to catalog-only first (`ContextBudgetOmissionKind: "skill_body"`), then remove the skill entirely (`"skills"`). Demoted bodies render as description-only even when the name remains in `LoadedSkillSet`. See [Input and prompt assembly](input-and-prompt-assembly.md).
+
+### Optional tool-result fold
+
+`toolResultFold` on `AgentConfig` / `RunOptions` (run wins) is **off** unless the host supplies a `summarize` callback. When enabled, aged large tool-result messages in the **provider view** become a one-line header plus bounded summary text; session store entries stay raw. Defaults: `minAgeTurns` **2**, `minBytes` **4096**, `maxSummaryBytes` **512** (hard **4096**). Summarizer failure keeps the raw tool result (fail closed). Not a second memory system — use observational memory / compaction for durable recall.
+
+```ts
+await session.run("…", {
+  toolResultFold: {
+    minAgeTurns: 2,
+    minBytes: 4_096,
+    summarize: async ({ toolCallId, text }) => `ref:${toolCallId} ${text.slice(0, 80)}`,
+  },
+});
+```
 
 ### Migration note
 
@@ -164,12 +227,25 @@ For declarative agents, old configs that omitted `skills` should now add explici
 resolveAgentDefinition({ name: "doc", model, skills: ["brief"] }, context);
 ```
 
-Use `activateAllCapabilities: true` only as a temporary all-skills/all-tools compatibility opt-in during migration. Runtime `RunOptions.activeSkills` remains the per-run narrowing tool after an agent has a skill registry configured.
+Runtime hosts that relied on `SkillRegistry.list()` when `activeSkills` was omitted must opt in explicitly:
+
+```ts
+// Restore pre-0.0.20 list-all activation (still subject to progressive disclosure):
+await session.run("Hi", { activateAllSkills: true });
+
+// Or restore full instruction bodies every turn:
+const agent = createAgent({ model, provider, skills: registry, skillsDisclosure: "eager" });
+```
+
+Use `activateAllCapabilities: true` only as a temporary all-skills/all-tools compatibility opt-in during migration for **declarative** definitions. Runtime `RunOptions.activeSkills` remains the per-run narrowing tool after an agent has a skill registry configured.
 
 ## Security and performance notes
 
 - Context providers run sequentially and deterministically in caller order.
 - Skill registry lookup is `Map`-backed, and selection is linear in requested skills plus active tools. Strict duplicate mode adds one O(1) `Map.has()` check during registration only.
+- Progressive catalog render is O(active skills) with byte/count caps; `load_skill` lookup is O(1). Budget eviction over context/skills is O(n log n) worst case.
+- `load_skill` cannot grant tools; loaded instructions are untrusted text bounded by hard caps. `toolResultFold` summarizer output is untrusted and capped; failures keep raw tool results.
+- Loaded-skill names are session-scoped in memory only in 0.0.20 — not checkpoint-persisted; new sessions start catalog-only until reload.
 - These helpers perform no provider calls, tool execution, resource loading, package discovery, filesystem/network access, retries, timers, or watchers by themselves.
 - Context and skill output is host/extension data. Do not include secrets unless the host explicitly accepts that prompt exposure.
 - Active tools remain host-supplied; skills and middleware do not activate tools or grant permissions. Use `duplicate: "error"` when loading third-party skills to prevent silent name shadowing.

package/docs/index.md

@@ -34,7 +34,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Database persistence](database-persistence.md): production persistence contracts, shared checksummed migration/full-shape catalog primitives (`@arnilo/prism/testing/persistence-schema`), conditional append, indexes, `readBranchPath`, reference relational schema, retention/legal-hold/quota lifecycle (`lifecycle`), and NoSQL mapping.
 - [SQLite persistence](sqlite-persistence.md): optional `better-sqlite3` adapter with session/run storage, checkpoints/leases, feedback, FTS `searchSessions` (migration-v4), and transactionally verified/backfilled migration metadata.
 - [PostgreSQL persistence](postgres-persistence.md): optional pooled `pg` adapter with session/run/checkpoint/lease/feedback storage, FTS `searchSessions` (migration-v4), advisory-locked checksummed/full-shape migrations, and opt-in live conformance.
-- [Migration guide](migration.md): **0.0.15** OpenAI hosted tools/continuation/Realtime, exact AI SDK v4 matrix, RAG lifecycle/reranking/trust/status, and memory export/rebuild; **0.0.14** conversations, memory consent/lifecycle, artifact co-work review, AG-UI co-work events, scoped M365/GWS OAuth connectors, browser checkpoints, device contracts, and Alibaba/Ollama providers; plus prior release migrations.
+- [Migration guide](migration.md): **0.0.20** progressive skill disclosure, empty registry default, `load_skill`, priority budget demotion, optional tool-result fold; **0.0.19** observational memory lifecycle; **0.0.15** OpenAI hosted tools/continuation/Realtime, exact AI SDK v4 matrix, RAG lifecycle/reranking/trust/status, and memory export/rebuild; **0.0.14** conversations, memory consent/lifecycle, artifact co-work review, AG-UI co-work events, scoped M365/GWS OAuth connectors, browser checkpoints, device contracts, and Alibaba/Ollama providers; plus prior release migrations.
 - [Node JSONL session store](node-jsonl-session-store.md): development-only JSONL file adapter for single-process Node hosts; no cross-process safety; `searchSessions` throws `SessionSearchUnsupportedError`.
 - [Persistence, credentials, and multimodality primitives](persistence-credentials-multimodality-primitives.md): Plan 056 inventory — session/run-ledger/persistence contracts, credential/OAuth seams, content/resource/model capabilities, package dependency matrix, conformance matrix, and threat model for production adapters.
 
@@ -58,7 +58,7 @@ Prism is a TypeScript/Node.js agent harness. Host apps and extension packages ow
 - [Multimodal content](multimodal-content.md): complete-request media resolution and aggregate bounds, DNS-classified/address-pinned URLs, SSRF/MIME policy, `ModelCapabilities.input` tags, and first-party content-type mapping.
 - [System prompts](system-prompts.md): compose explicit user/package/app/run system prompt layers, auto-load the standard `AGENTS.md` (workspace) / `SYSTEM.md` prompt files via the Node `loadSystemPromptFiles` loader (trust-gated for `AGENTS.md`), and append `SYSTEM.md` → per-agent `AGENT.md` body → repo `AGENTS.md` layers from a discovered agent bundle via `resolveAgentBundle`.
 - [Instruction injection](instruction-injection.md): register package injectors that layer redacted instructions/context blocks without granting tools, permissions, or resource escapes.
-- [Context and skills](context-and-skills.md): resolve ordered context providers and keep context/skill selection host-owned; omitted declarative skills stay inactive by default, `toolNames` fail closed before provider turns, and strict skill registries prevent silent shadowing.
+- [Context and skills](context-and-skills.md): resolve ordered context providers; progressive skill catalog (`skillsDisclosure`, default catalog-only), `load_skill` on-demand bodies, fail-closed registry activation (`activateAllSkills` migration opt-in), `toolNames` fail closed before provider turns, priority-aware budget demotion, and optional `toolResultFold`.
 - [Retrieval-augmented generation](rag.md): optional bounded source lifecycle, document adapters, host reranking, ingestion status, attributable citations, and inert context injection.
 
 ## Tools

package/docs/migration.md

@@ -1,5 +1,27 @@
 # Migration guide
 
+## 0.0.19 → 0.0.20 skills and context progressive disclosure (small intentional breaks)
+
+Release **0.0.20** completes Phase 3 progressive skill disclosure in core `@arnilo/prism`:
+
+1. **Default skill prompt is catalog-only.** Active skills render `Skill <name>: <description>` every turn (`skillsDisclosure: "progressive"` default). Full `instructions` appear only after a successful `load_skill` for that session or when the host sets `skillsDisclosure: "eager"`.
+2. **Runtime `SkillRegistry` without activation is empty.** When `AgentConfig.skills` is a `SkillRegistry` and neither `RunOptions.activeSkills` nor `RunOptions.skills` is set, **zero** skills activate (was `SkillRegistry.list()`). Migration: `activateAllSkills: true` on the run or agent restores list-all activation (still subject to disclosure rules). Plain `Skill[]` configs are unchanged.
+3. **`load_skill` is host-opt-in.** Export `createLoadSkillTool({ registry, loaded })` from `@arnilo/prism`; register on the active tool set. Unknown names, inactive required tools, oversize bodies, and duplicate loads fail closed; load cannot widen tools or permissions.
+4. **Context budget honors `ContextBlock.priority`.** Within `context` and `skills` victims, lower priority drops first (missing = 0), then LIFO. Skills with loaded bodies may demote to description-only (`skill_body` omission) before full removal.
+5. **Optional `toolResultFold`.** Off by default; host `summarize` + thresholds fold aged large tool results in provider view only (session store untouched). Summarizer failure keeps raw results.
+
+Example: `node examples/skills-progressive-disclosure.ts` (network-free).
+
+```ts
+// Migration for hosts that relied on activate-all registry behavior:
+await session.run("Hi", { activateAllSkills: true });
+
+// Migration for hosts that want full bodies every turn without load_skill:
+const agent = createAgent({ model, provider, skills: registry, skillsDisclosure: "eager" });
+```
+
+Declarative `activateAllCapabilities: true` is unchanged and does **not** set runtime `activateAllSkills`.
+
 ## 0.0.18 → 0.0.19 observational memory lifecycle (small intentional breaks)
 
 Release **0.0.19** completes Phase 2 observational memory in `@arnilo/prism-compaction-observational-memory` only; core `@arnilo/prism` runtime behavior is unchanged.