@arnilo/prism 0.0.96 → 0.1.0

package/dist/session-stores.js

@@ -1,4 +1,4 @@
-import { SESSION_APPEND_CONFLICT_CODE, SessionAppendConflictError } from "./contracts.js";
+import { DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES, DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES, resolveSessionSearchQuery, SESSION_APPEND_CONFLICT_CODE, SESSION_SEARCH_WORKSPACE_METADATA_KEY, SessionAppendConflictError, SessionSearchUnsupportedError, } from "./contracts.js";
 import { createId } from "./ids.js";
 export function createSessionEntry(options) {
     const { createId, now, ...entry } = options;
@@ -13,7 +13,9 @@ export function createSessionEntry(options) {
 // this if a legitimate branch exceeds it.
 const MAX_BRANCH_PAGES = 64;
 export function getSessionBranchEntries(input, options = {}) {
-    return typeof input === "function" ? readBranchFromReader(input, options) : getSessionBranchEntriesCore(input, options);
+    return typeof input === "function"
+        ? readBranchFromReader(input, options)
+        : getSessionBranchEntriesCore(input, options);
 }
 async function readBranchFromReader(reader, query) {
     const items = [];
@@ -29,8 +31,7 @@ async function readBranchFromReader(reader, query) {
     // indexEntries + the parentId walk order it and still reject missing parents / dupes.
     return getSessionBranchEntriesCore(items, { leafId: query.leafId });
 }
-function getSessionBranchEntriesCore(entries, options = {}) {
-    const index = indexEntries(entries);
+function getSessionBranchEntriesCore(entries, options = {}, index = indexEntries(entries)) {
     const leafId = options.leafId ?? entries.at(-1)?.id;
     if (!leafId)
         return [];
@@ -50,7 +51,7 @@ export function listSessionBranches(entries) {
     const index = indexEntries(entries);
     return entries
         .filter((entry) => !index.parentIds.has(entry.id))
-        .map((entry) => ({ leafId: entry.id, entries: getSessionBranchEntries(entries, { leafId: entry.id }) }));
+        .map((entry) => ({ leafId: entry.id, entries: getSessionBranchEntriesCore(entries, { leafId: entry.id }, index) }));
 }
 export function rebuildSessionContext(input, options = {}) {
     if (typeof input === "function") {
@@ -66,13 +67,15 @@ async function rebuildSessionContextFromReader(reader, query) {
 }
 function rebuildSessionContextCore(entries, options = {}) {
     const branch = getSessionBranchEntriesCore(entries, options);
-    const compaction = [...branch].reverse().find((entry) => entry.kind === "compaction" && entry.summary && isCompactionEntryData(entry.data));
+    const compaction = [...branch]
+        .reverse()
+        .find((entry) => entry.kind === "compaction" && entry.summary && isCompactionEntryData(entry.data));
     if (!compaction || !isCompactionEntryData(compaction.data)) {
         return {
             leafId: branch.at(-1)?.id,
             entries: branch,
-            messages: branch.flatMap((entry) => entry.kind === "message" && entry.message ? [entry.message] : []),
-            summaries: branch.flatMap((entry) => entry.kind === "summary" && entry.summary ? [entry.summary] : []),
+            messages: branch.flatMap((entry) => (entry.kind === "message" && entry.message ? [entry.message] : [])),
+            summaries: branch.flatMap((entry) => (entry.kind === "summary" && entry.summary ? [entry.summary] : [])),
         };
     }
     const keepIds = new Set(compaction.data.keepEntryIds ?? []);
@@ -93,16 +96,17 @@ function rebuildSessionContextCore(entries, options = {}) {
     }
     return { leafId: branch.at(-1)?.id, entries: branch, messages, summaries };
 }
-export function createMemorySessionStore(initialEntries = []) {
+export function createMemorySessionStore(initialEntries = [], options = {}) {
     const byId = new Map();
     const bySession = new Map();
     const leafBySession = new Map();
     const idempotencySeen = new Set();
+    const mode = options.sessionSearchMode ?? "linear";
     for (const entry of initialEntries)
         add(entry);
     return {
-        async append(entry, options) {
-            add(entry, options);
+        async append(entry, appendOptions) {
+            add(entry, appendOptions);
         },
         async list(sessionId) {
             return (bySession.get(sessionId) ?? []).map(cloneEntry);
@@ -111,6 +115,11 @@ export function createMemorySessionStore(initialEntries = []) {
             const entry = byId.get(id);
             return entry ? cloneEntry(entry) : undefined;
         },
+        async searchSessions(query) {
+            if (mode === "unsupported")
+                throw new SessionSearchUnsupportedError();
+            return searchMemorySessionsLinear(bySession, leafBySession, query);
+        },
     };
     function add(entry, options) {
         // ponytail: idempotency dedup keyed on (session, key, expectedParentId) so a
@@ -123,17 +132,22 @@ export function createMemorySessionStore(initialEntries = []) {
         if (dedupKey !== undefined && idempotencySeen.has(dedupKey)) {
             throw new SessionAppendConflictError({ code: SESSION_APPEND_CONFLICT_CODE, idempotencyDuplicate: true });
         }
-        // expectedParentId is existence validation (the parent must already be in the
-        // store or be undefined for a root). Tip-CAS is intentionally NOT used: prism
+        // expectedParentId is same-session existence validation (the parent must already
+        // be in the store for THIS session, or be undefined for a root). A parent from
+        // another session is rejected: the write would be unreadable, since every branch
+        // walk is per-session. Tip-CAS is intentionally NOT used: prism
         // allows branching from any existing leaf (checkout + append), so a stale-but-
         // existing parent is a valid branch, not a conflict. DB adapters may layer
         // stricter tip-CAS via unique constraints for linear-only sessions.
-        if (options?.expectedParentId !== undefined && !byId.has(options.expectedParentId)) {
-            throw new SessionAppendConflictError({
-                code: SESSION_APPEND_CONFLICT_CODE,
-                expectedParentId: options.expectedParentId,
-                currentLeafId: leafBySession.get(entry.sessionId),
-            });
+        if (options?.expectedParentId !== undefined) {
+            const parent = byId.get(options.expectedParentId);
+            if (!parent || parent.sessionId !== entry.sessionId) {
+                throw new SessionAppendConflictError({
+                    code: SESSION_APPEND_CONFLICT_CODE,
+                    expectedParentId: options.expectedParentId,
+                    currentLeafId: leafBySession.get(entry.sessionId),
+                });
+            }
         }
         if (byId.has(entry.id))
             throw new Error(`Duplicate session entry id: ${entry.id}`);
@@ -146,6 +160,166 @@ export function createMemorySessionStore(initialEntries = []) {
         leafBySession.set(entry.sessionId, entry.id);
     }
 }
+function searchMemorySessionsLinear(bySession, leafBySession, query) {
+    const q = resolveSessionSearchQuery(query);
+    q.signal?.throwIfAborted();
+    let sessionsScanned = 0;
+    let entriesScanned = 0;
+    let bytesScanned = 0;
+    const matches = [];
+    for (const [sessionId, entries] of bySession) {
+        if (sessionsScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_SESSIONS)
+            break;
+        if (entriesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES)
+            break;
+        if (bytesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES)
+            break;
+        q.signal?.throwIfAborted();
+        sessionsScanned += 1;
+        let updatedAt = "";
+        let label;
+        let summary;
+        let workspaceRoot;
+        let tenantId;
+        let accountId;
+        let userId;
+        let matchedLabel = false;
+        let matchedSummary = false;
+        let matchedQuery = false;
+        let matchedProvider = false;
+        let matchedModel = false;
+        let snippetSource;
+        for (const entry of entries) {
+            if (entriesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_ENTRIES)
+                break;
+            if (bytesScanned >= DEFAULT_MAX_SESSION_SEARCH_LINEAR_BYTES)
+                break;
+            entriesScanned += 1;
+            const text = entrySearchText(entry);
+            bytesScanned += utf8Bytes(text) + utf8Bytes(entry.label) + utf8Bytes(entry.summary);
+            if (entry.timestamp > updatedAt)
+                updatedAt = entry.timestamp;
+            if (entry.label)
+                label = entry.label;
+            if (entry.summary)
+                summary = entry.summary;
+            const meta = entry.metadata;
+            if (meta) {
+                if (typeof meta[SESSION_SEARCH_WORKSPACE_METADATA_KEY] === "string") {
+                    workspaceRoot = meta[SESSION_SEARCH_WORKSPACE_METADATA_KEY];
+                }
+                if (typeof meta.tenantId === "string")
+                    tenantId = meta.tenantId;
+                if (typeof meta.accountId === "string")
+                    accountId = meta.accountId;
+                if (typeof meta.userId === "string")
+                    userId = meta.userId;
+            }
+            if (q.label && entry.label?.includes(q.label))
+                matchedLabel = true;
+            if (q.summary && entry.summary?.includes(q.summary))
+                matchedSummary = true;
+            if (q.query) {
+                const hay = `${entry.label ?? ""}\n${entry.summary ?? ""}\n${text}`;
+                if (hay.includes(q.query)) {
+                    matchedQuery = true;
+                    snippetSource ??= entry.label ?? entry.summary ?? text;
+                }
+            }
+            if (q.provider && (entry.model?.provider === q.provider || metaProvider(entry) === q.provider))
+                matchedProvider = true;
+            if (q.model && entry.model?.model === q.model)
+                matchedModel = true;
+        }
+        if (q.workspaceRoot && workspaceRoot !== q.workspaceRoot)
+            continue;
+        if (q.tenantId && tenantId !== q.tenantId)
+            continue;
+        if (q.accountId && accountId !== q.accountId)
+            continue;
+        if (q.userId && userId !== q.userId)
+            continue;
+        if (q.label && !matchedLabel)
+            continue;
+        if (q.summary && !matchedSummary)
+            continue;
+        if (q.query && !matchedQuery)
+            continue;
+        if (q.provider && !matchedProvider)
+            continue;
+        if (q.model && !matchedModel)
+            continue;
+        if (q.fromUpdatedAt && updatedAt < q.fromUpdatedAt)
+            continue;
+        if (q.toUpdatedAt && updatedAt > q.toUpdatedAt)
+            continue;
+        matches.push({
+            sessionId,
+            leafId: leafBySession.get(sessionId),
+            updatedAt: updatedAt || undefined,
+            label,
+            summary,
+            snippet: clipSnippet(snippetSource ?? label ?? summary),
+            metadata: workspaceRoot !== undefined ? { [SESSION_SEARCH_WORKSPACE_METADATA_KEY]: workspaceRoot } : undefined,
+        });
+    }
+    matches.sort((a, b) => compareSearchHit(a, b, q.order));
+    const afterCursor = q.cursor ? decodeSearchCursor(q.cursor) : undefined;
+    const filtered = afterCursor ? matches.filter((hit) => isAfterSearchCursor(hit, afterCursor, q.order)) : matches;
+    const page = filtered.slice(0, q.limit);
+    const last = page.at(-1);
+    return {
+        items: page,
+        nextCursor: filtered.length > q.limit && last?.updatedAt ? encodeSearchCursor(last.updatedAt, last.sessionId) : undefined,
+    };
+}
+function entrySearchText(entry) {
+    if (!entry.message?.content)
+        return "";
+    const parts = [];
+    for (const block of entry.message.content) {
+        if (block.type === "text" && typeof block.text === "string")
+            parts.push(block.text);
+    }
+    return parts.join("\n");
+}
+function metaProvider(entry) {
+    const value = entry.metadata?.provider;
+    return typeof value === "string" ? value : undefined;
+}
+function utf8Bytes(value) {
+    return value ? new TextEncoder().encode(value).byteLength : 0;
+}
+function clipSnippet(value) {
+    if (!value)
+        return undefined;
+    const encoded = new TextEncoder().encode(value);
+    if (encoded.byteLength <= DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES)
+        return value;
+    return new TextDecoder().decode(encoded.slice(0, DEFAULT_MAX_SESSION_SEARCH_SNIPPET_BYTES));
+}
+function encodeSearchCursor(updatedAt, sessionId) {
+    return `${updatedAt}\t${sessionId}`;
+}
+function decodeSearchCursor(cursor) {
+    const tab = cursor.indexOf("\t");
+    if (tab <= 0 || tab === cursor.length - 1)
+        throw new TypeError("SessionSearchQuery.cursor is invalid");
+    return { updatedAt: cursor.slice(0, tab), sessionId: cursor.slice(tab + 1) };
+}
+function compareSearchHit(a, b, order) {
+    const aAt = a.updatedAt ?? "";
+    const bAt = b.updatedAt ?? "";
+    const cmp = aAt < bAt ? -1 : aAt > bAt ? 1 : a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0;
+    return order === "asc" ? cmp : -cmp;
+}
+function isAfterSearchCursor(hit, cursor, order) {
+    const at = hit.updatedAt ?? "";
+    if (order === "asc") {
+        return at > cursor.updatedAt || (at === cursor.updatedAt && hit.sessionId > cursor.sessionId);
+    }
+    return at < cursor.updatedAt || (at === cursor.updatedAt && hit.sessionId < cursor.sessionId);
+}
 function cloneEntry(entry) {
     return structuredClone(entry);
 }
@@ -153,8 +327,8 @@ function isCompactionEntryData(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         return false;
     const data = value;
-    return (data.throughEntryId === undefined || typeof data.throughEntryId === "string")
-        && (data.keepEntryIds === undefined || (Array.isArray(data.keepEntryIds) && data.keepEntryIds.every((item) => typeof item === "string")));
+    return ((data.throughEntryId === undefined || typeof data.throughEntryId === "string") &&
+        (data.keepEntryIds === undefined || (Array.isArray(data.keepEntryIds) && data.keepEntryIds.every((item) => typeof item === "string"))));
 }
 function indexEntries(entries) {
     const byId = new Map();

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;

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/structured-output.d.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig, ModelCapabilities, ModelConfig, ProviderRequestOptions, RunOptions, StructuredOutputOptions } from "./contracts.js";
+import type { AgentConfig, ModelCapabilities, ModelConfig, ProviderRequest, ProviderRequestOptions, RunOptions, StructuredOutputOptions } from "./contracts.js";
 export declare const DEFAULT_MAX_STRUCTURED_OUTPUT_SCHEMA_BYTES = 65536;
 export declare const DEFAULT_MAX_STRUCTURED_OUTPUT_NAME_LENGTH = 128;
 export declare class StructuredOutputError extends Error {
@@ -9,3 +9,7 @@ export declare function modelSupportsStructuredOutput(capabilities?: ModelCapabi
 export declare function validateStructuredOutputOptions(options: StructuredOutputOptions): StructuredOutputOptions;
 export declare function assertStructuredOutputRequestSupported(model: ModelConfig, options?: ProviderRequestOptions): void;
 export declare function resolveRunProviderOptions(runOptions: Pick<RunOptions, "providerOptions" | "loop">, config: Pick<AgentConfig, "providerOptions" | "loop">): ProviderRequestOptions | undefined;
+/** Strip native schema so a tool-eligible turn can call tools freely. */
+export declare function withoutStructuredOutput(request: ProviderRequest): ProviderRequest;
+/** Artifact/revision turn: keep/restore schema and withdraw tools. */
+export declare function artifactStructuredOutputRequest(request: ProviderRequest, schema?: StructuredOutputOptions): ProviderRequest;

package/dist/structured-output.js

@@ -38,8 +38,8 @@ export function assertStructuredOutputRequestSupported(model, options) {
         return;
     validateStructuredOutputOptions(options.structuredOutput);
     if (!modelSupportsStructuredOutput(model.capabilities)) {
-        throw new StructuredOutputError("unsupported_model", `Model ${model.provider}/${model.model} does not declare structuredOutput capability; `
-            + `set loop.structuredOutputMode to "artifact-loop" or choose a capable model`);
+        throw new StructuredOutputError("unsupported_model", `Model ${model.provider}/${model.model} does not declare structuredOutput capability; ` +
+            `set loop.structuredOutputMode to "artifact-loop" or choose a capable model`);
     }
 }
 function isGenerateValidateReviseLoopOptions(loop) {
@@ -56,4 +56,22 @@ export function resolveRunProviderOptions(runOptions, config) {
         structuredOutput: validateStructuredOutputOptions(loop.structuredOutput),
     });
 }
+/** Strip native schema so a tool-eligible turn can call tools freely. */
+export function withoutStructuredOutput(request) {
+    if (!request.options?.structuredOutput)
+        return request;
+    const { structuredOutput: _drop, ...options } = request.options;
+    return { ...request, options: Object.keys(options).length > 0 ? options : undefined };
+}
+/** Artifact/revision turn: keep/restore schema and withdraw tools. */
+export function artifactStructuredOutputRequest(request, schema) {
+    const structuredOutput = schema ?? request.options?.structuredOutput;
+    if (!structuredOutput)
+        return { ...request, tools: undefined };
+    return {
+        ...request,
+        tools: undefined,
+        options: { ...request.options, structuredOutput },
+    };
+}
 //# sourceMappingURL=structured-output.js.map

package/dist/system-prompts.js

@@ -1,7 +1,12 @@
 // ponytail: Phase 31 — `source: "user"` is the global base layer; `source: "app"` sits above package.
 // Behavioral change from Phase 14: `source: "user"` is now the global base (rank 0), not a high-priority caller override.
 // Unknown custom sources sort after package but before app/run so they cannot override host/run layers.
-const sourceRank = new Map([["user", 0], ["package", 1], ["app", 2], ["run", 3]]);
+const sourceRank = new Map([
+    ["user", 0],
+    ["package", 1],
+    ["app", 2],
+    ["run", 3],
+]);
 const unknownSourceRank = 1.5;
 export function composeSystemPrompt(contributions = [], options = {}) {
     const parts = baseParts(options.base);
@@ -40,7 +45,7 @@ function isContributionArray(value) {
     return Array.isArray(value);
 }
 function baseParts(base) {
-    return (typeof base === "string" ? [base] : base ?? []).filter((text) => text.length > 0);
+    return (typeof base === "string" ? [base] : (base ?? [])).filter((text) => text.length > 0);
 }
 function rank(layer) {
     return sourceRank.get(layer.source ?? "") ?? unknownSourceRank;

package/dist/testing/agent-event-source-conformance.d.ts

@@ -0,0 +1,4 @@
+import type { AgentEventSource } from "../contracts.js";
+export type AgentEventSourceConformanceFactory = () => AgentEventSource | Promise<AgentEventSource>;
+/** Assert durable append/page/replay ownership and cursor behavior without a database dependency. */
+export declare function assertAgentEventSourceConforms(factory: AgentEventSourceConformanceFactory): Promise<void>;