@arnilo/prism 0.0.96 → 0.1.1

package/dist/testing/session-store-conformance.js

@@ -5,7 +5,7 @@
 // stores already satisfy. Mirrors the assertion shape already repeated across
 // src/__tests__/session-stores.test.ts and node-session-store-jsonl.test.ts so
 // adapter authors do not re-derive them. Throws plain Error; no test runner.
-import { isSessionAppendConflict } from "../contracts.js";
+import { HARD_MAX_SESSION_SEARCH_LIMIT, HARD_MAX_SESSION_SEARCH_QUERY_BYTES, isSessionAppendConflict, resolveSessionSearchQuery, } from "../contracts.js";
 /**
  * Assert that a `SessionStore` implementation satisfies the core adapter
  * contract: round-trip append/list, duplicate-entry-id rejection,
@@ -63,6 +63,9 @@ export async function assertSessionStoreConforms(store, options = {}) {
             throw new Error(`readBranchPath must return the ancestor chain root→leaf in order; got ${JSON.stringify(ids)}`);
         }
     }
+    if (options.exerciseSearchSessions && typeof store.searchSessions === "function") {
+        await assertSessionStoreSearchSessions(store);
+    }
     await assertSessionStoreBranchIsolation(store, options);
     if (options.exerciseConcurrentParentAppend) {
         await assertConcurrentParentAppendAllowed(store, sessionId, now, make);
@@ -104,6 +107,38 @@ export async function runSessionStoreConformance(factory, options = {}) {
         label: "dup",
     }, { idempotencyKey: "reopen-idem", expectedParentId: parent?.id }), (error) => isSessionAppendConflict(error) && error.conflict.idempotencyDuplicate === true, "Restarted store must still deduplicate an exact idempotency retry");
 }
+async function assertSessionStoreSearchSessions(store) {
+    const search = store.searchSessions;
+    await reject(() => search({ limit: 0 }), (error) => error instanceof TypeError, "searchSessions must reject non-positive limit");
+    await reject(() => search({ limit: Number.NaN }), (error) => error instanceof TypeError, "searchSessions must reject NaN limit");
+    await reject(() => search({ limit: HARD_MAX_SESSION_SEARCH_LIMIT + 1 }), (error) => error instanceof TypeError, "searchSessions must reject oversize limit");
+    await reject(() => search({ query: "x".repeat(HARD_MAX_SESSION_SEARCH_QUERY_BYTES + 1) }), (error) => error instanceof TypeError, "searchSessions must reject oversize query string");
+    const empty = await search(resolveSessionSearchQuery({
+        workspaceRoot: "__prism_conformance_empty__",
+        limit: 5,
+    }));
+    if (!Array.isArray(empty.items)) {
+        throw new Error("searchSessions must return a PersistencePage with an items array");
+    }
+    const resolved = resolveSessionSearchQuery({ limit: 1 });
+    const page = await search(resolved);
+    if (page.items.length > resolved.limit) {
+        throw new Error(`searchSessions must honor limit; got ${page.items.length} items for limit ${resolved.limit}`);
+    }
+    for (const hit of page.items) {
+        if (typeof hit.sessionId !== "string" || !hit.sessionId) {
+            throw new Error("searchSessions hits must include a non-empty sessionId");
+        }
+        if ("credential" in hit || "apiKey" in hit || "password" in hit) {
+            throw new Error("searchSessions hits must not include credential fields");
+        }
+    }
+    const unscoped = await search({ limit: 100 });
+    const owned = await search({ tenantId: "__missing_tenant__", limit: 100 });
+    if (owned.items.length > unscoped.items.length) {
+        throw new Error("searchSessions ownership filter must not return more hits than an unscoped search");
+    }
+}
 async function assertSessionStoreBranchIsolation(store, options) {
     const sessionId = options.sessionId ?? "conformance";
     const otherSessionId = options.otherSessionId ?? `${sessionId}-other`;
@@ -120,7 +155,7 @@ async function assertSessionStoreBranchIsolation(store, options) {
         throw new Error("SessionStore leaked entries across session ids");
     }
 }
-async function assertConcurrentParentAppendAllowed(store, sessionId, now, make) {
+async function assertConcurrentParentAppendAllowed(store, sessionId, _now, make) {
     const forkRoot = make("fork-root");
     await store.append(forkRoot);
     const childA = make("fork-a", forkRoot.id);

package/dist/testing/tool-conformance.js

@@ -26,15 +26,38 @@ export async function assertToolDispatchConforms(registry, options) {
     // 1. unknown tool → blocked "unknown_tool".
     await assertToolBlocked({ call: call("does-not-exist", {}), context: baseContext, ...shared, ...pickPolicy(options) }, "unknown_tool");
     // 2. denied tool (filter) → blocked "tool_denied".
-    await assertToolBlocked({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options), filter: { deny: [options.tool.name] } }, "tool_denied");
+    await assertToolBlocked({
+        call: call(options.tool.name, options.validArgs),
+        context: baseContext,
+        ...shared,
+        ...pickPolicy(options),
+        filter: { deny: [options.tool.name] },
+    }, "tool_denied");
     // 3. invalid (non-object) arguments → blocked "invalid_arguments".
     await assertToolBlocked({ call: call(options.tool.name, "not-an-object"), context: baseContext, ...shared, ...pickPolicy(options) }, "invalid_arguments");
     // 4. permission denial → blocked "permission_denied".
-    await assertToolBlocked({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options), permission: denyAllPermission }, "permission_denied");
+    await assertToolBlocked({
+        call: call(options.tool.name, options.validArgs),
+        context: baseContext,
+        ...shared,
+        ...pickPolicy(options),
+        permission: denyAllPermission,
+    }, "permission_denied");
     // 5. validator failure → blocked "validation_failed".
-    await assertToolBlocked({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options), validate: alwaysInvalidValidator }, "validation_failed");
+    await assertToolBlocked({
+        call: call(options.tool.name, options.validArgs),
+        context: baseContext,
+        ...shared,
+        ...pickPolicy(options),
+        validate: alwaysInvalidValidator,
+    }, "validation_failed");
     // 6. valid call → executes (tool_execution_started), no error, no blocked event.
-    const probe = await dispatchAndCollect({ call: call(options.tool.name, options.validArgs), context: baseContext, ...shared, ...pickPolicy(options) });
+    const probe = await dispatchAndCollect({
+        call: call(options.tool.name, options.validArgs),
+        context: baseContext,
+        ...shared,
+        ...pickPolicy(options),
+    });
     if (probe.result.error)
         throw new Error(`Valid tool call was not executed: ${probe.result.error.message}`);
     if (!probe.events.some((event) => event.type === "tool_execution_started")) {
@@ -69,7 +92,9 @@ export async function dispatchAndCollect(probe) {
         permission: probe.permission,
         validate: probe.validate,
         secrets: probe.secrets,
-        emit: (event) => { events.push(event); },
+        emit: (event) => {
+            events.push(event);
+        },
     });
     return { result, events };
 }

package/dist/testing/tool-effect-store-conformance.d.ts

@@ -0,0 +1,9 @@
+import type { AgentIdentity, ToolEffectKey, ToolEffectStore } from "../contracts.js";
+export interface ToolEffectStoreConformanceOptions {
+    readonly identity?: AgentIdentity;
+    readonly ownership?: ToolEffectKey["ownership"];
+    readonly key?: string;
+}
+/** Assert core claim/CAS, duplicate, reconciliation, and cleanup semantics without a test framework. */
+export declare function assertToolEffectStoreConforms(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;
+export declare function runToolEffectStoreConformance(factory: () => ToolEffectStore | Promise<ToolEffectStore>, options?: ToolEffectStoreConformanceOptions): Promise<void>;

package/dist/testing/tool-effect-store-conformance.js

@@ -0,0 +1,85 @@
+/** Assert core claim/CAS, duplicate, reconciliation, and cleanup semantics without a test framework. */
+export async function assertToolEffectStoreConforms(factory, options = {}) {
+    const store = await factory();
+    const identity = options.identity ?? testIdentity();
+    const ownership = options.ownership ?? { tenantId: identity.tenantId };
+    const base = key(identity, ownership, options.key ?? "prism:tool-effect:v1:conformance");
+    const first = await store.begin(base);
+    if (first.outcome !== "acquired" || first.record.status !== "pending" || !first.record.claimToken) {
+        throw new Error("store must acquire an absent tool effect as pending with a claim token");
+    }
+    const duplicate = await store.begin(base);
+    if (duplicate.outcome !== "existing" || duplicate.record.status !== "pending") {
+        throw new Error("store must return existing pending effects without a second claim");
+    }
+    const dispatched = await store.markDispatched(transition(base, first.record));
+    if (dispatched.status !== "dispatched" || dispatched.version !== first.record.version + 1) {
+        throw new Error("store must transition a claimed pending effect to dispatched");
+    }
+    const result = { toolCallId: base.toolCallId, name: base.toolName, value: { ok: true } };
+    const completed = await store.complete({ ...transition(base, dispatched), result });
+    if (completed.status !== "completed" || completed.result?.toolCallId !== base.toolCallId) {
+        throw new Error("store must retain a completed bounded result");
+    }
+    const replay = await store.begin(base);
+    if (replay.outcome !== "existing" || replay.record.status !== "completed") {
+        throw new Error("store must preserve completed duplicate state");
+    }
+    await expectReject(() => store.markDispatched(transition(base, dispatched)), "store must reject stale claim/version transitions");
+    const unknownKey = key(identity, ownership, `${base.key}:unknown`, "call-unknown");
+    const unknownPending = await store.begin(unknownKey);
+    const unknownDispatched = await store.markDispatched(transition(unknownKey, unknownPending.record));
+    const unknown = await store.markUnknown({ ...transition(unknownKey, unknownDispatched), failure: { code: "test" } });
+    if (unknown.status !== "unknown")
+        throw new Error("store must mark dispatched effects unknown");
+    const resolved = await store.resolveUnknown({
+        ...unknownKey,
+        expectedVersion: unknown.version,
+        status: "failed_terminal",
+        failure: { code: "test" },
+    });
+    if (resolved.status !== "failed_terminal")
+        throw new Error("store must CAS-resolve unknown effects");
+    const cleanup = await store.cleanup({ ownership, before: new Date(Date.now() + 60_000).toISOString(), limit: 100 });
+    if (cleanup.deleted < 1)
+        throw new Error("store cleanup must remove terminal effects");
+}
+export async function runToolEffectStoreConformance(factory, options = {}) {
+    await assertToolEffectStoreConforms(factory, options);
+}
+function key(identity, ownership, value, toolCallId = "call") {
+    return {
+        identity,
+        ownership,
+        key: value,
+        sessionId: "session",
+        runId: "run",
+        toolCallId,
+        toolName: "effect.tool",
+        argumentsHash: "a".repeat(64),
+    };
+}
+function transition(base, record) {
+    if (!record.claimToken)
+        throw new Error("store transition record lacks claim token");
+    return { ...base, claimToken: record.claimToken, expectedVersion: record.version };
+}
+async function expectReject(run, message) {
+    try {
+        await run();
+    }
+    catch {
+        return;
+    }
+    throw new Error(message);
+}
+function testIdentity() {
+    return {
+        tenantId: "tenant",
+        principal: { kind: "service", id: "conformance" },
+        scopes: ["tools:execute"],
+        issuedAt: "2026-01-01T00:00:00.000Z",
+        verified: true,
+    };
+}
+//# sourceMappingURL=tool-effect-store-conformance.js.map

package/dist/thinking.js

@@ -47,7 +47,10 @@ export function applyThinkingLevel(options, level, family = "reasoning_effort")
     if (!normalized || family === "noop")
         return options ?? {};
     const patch = thinkingCompatFor(family, normalized);
-    if (family === "openai_reasoning" && options?.compat?.reasoning && typeof options.compat.reasoning === "object" && !Array.isArray(options.compat.reasoning)) {
+    if (family === "openai_reasoning" &&
+        options?.compat?.reasoning &&
+        typeof options.compat.reasoning === "object" &&
+        !Array.isArray(options.compat.reasoning)) {
         return mergeProviderRequestOptions(options, {
             compat: {
                 reasoning: {

package/dist/tool-effects.d.ts

@@ -0,0 +1,15 @@
+import type { JsonObject, ToolEffectKey, ToolEffectStore } from "./contracts.js";
+export type ToolEffectErrorCode = "ERR_PRISM_TOOL_EFFECT_REQUIRED" | "ERR_PRISM_TOOL_EFFECT_CONFLICT" | "ERR_PRISM_TOOL_EFFECT_UNKNOWN" | "ERR_PRISM_TOOL_EFFECT_COMPLETED" | "ERR_PRISM_TOOL_EFFECT_LIMIT";
+export declare class ToolEffectError extends Error {
+    readonly code: ToolEffectErrorCode;
+    constructor(code: ToolEffectErrorCode, message: string);
+}
+/** Stable JSON representation for an already-validated tool arguments object. */
+export declare function canonicalToolEffectJson(value: unknown): string;
+export declare function toolEffectArgumentsHash(argumentsValue: JsonObject): string;
+/** Derives the only core-authoritative key. Callers never supply this from model input. */
+export declare function deriveToolEffectKey(input: Omit<ToolEffectKey, "key" | "signal">): string;
+/** In-process reference. Use a durable adapter for cross-replica claims. */
+export declare function createMemoryToolEffectStore(options?: {
+    readonly now?: () => number;
+}): ToolEffectStore;

package/dist/tool-effects.js

@@ -0,0 +1,352 @@
+import { createHash, randomUUID } from "node:crypto";
+import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.js";
+export class ToolEffectError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "ToolEffectError";
+    }
+}
+const DEFAULT_CLAIM_TTL_MS = 15 * 60_000;
+const HARD_CLAIM_TTL_MS = 60 * 60_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const HARD_MAX_ATTEMPTS = 10;
+const DEFAULT_CLEANUP_LIMIT = 100;
+const HARD_CLEANUP_LIMIT = 500;
+const MAX_EFFECT_KEY_BYTES = 96;
+const MAX_TOOL_NAME_BYTES = 512;
+const MAX_IDENTIFIER_BYTES = 512;
+const MAX_RESULT_BYTES = 64 * 1024;
+const MAX_REFERENCE_BYTES = 1024;
+const MAX_RECORD_BYTES = 128 * 1024;
+/** Stable JSON representation for an already-validated tool arguments object. */
+export function canonicalToolEffectJson(value) {
+    return JSON.stringify(canonical(value));
+}
+export function toolEffectArgumentsHash(argumentsValue) {
+    return createHash("sha256").update(canonicalToolEffectJson(argumentsValue)).digest("hex");
+}
+/** Derives the only core-authoritative key. Callers never supply this from model input. */
+export function deriveToolEffectKey(input) {
+    const value = canonicalToolEffectJson({
+        tenantId: input.ownership.tenantId,
+        accountId: input.ownership.accountId ?? null,
+        userId: input.ownership.userId ?? null,
+        principalId: input.identity.principal.id,
+        sessionId: input.sessionId,
+        runId: input.runId,
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        argumentsHash: input.argumentsHash,
+    });
+    return `prism:tool-effect:v1:${createHash("sha256").update(value).digest("hex")}`;
+}
+/** In-process reference. Use a durable adapter for cross-replica claims. */
+export function createMemoryToolEffectStore(options = {}) {
+    const records = new Map();
+    const now = options.now ?? Date.now;
+    function current(input) {
+        throwIfAborted(input.signal);
+        validateKey(input);
+        const found = records.get(recordKey(input));
+        if (!found)
+            return undefined;
+        assertMatches(found, input);
+        const expired = expire(found, now());
+        if (expired !== found)
+            records.set(recordKey(input), expired);
+        return expired;
+    }
+    function save(record, identity) {
+        const frozen = freezeRecord(record);
+        assertRecordSize(frozen);
+        records.set(recordKey({ identity, key: frozen.key }), frozen);
+        return frozen;
+    }
+    return {
+        async get(input) {
+            return current(input);
+        },
+        async begin(input) {
+            const existing = current(input);
+            const timestamp = now();
+            const ttl = claimTtl(input.claimTtlMs);
+            const attempts = maxAttempts(input.maxAttempts);
+            if (!existing)
+                return {
+                    outcome: "acquired",
+                    record: save(claim(input, 1, timestamp, ttl), input.identity),
+                };
+            if (existing.status === "failed_retryable" && existing.attempt < attempts) {
+                return {
+                    outcome: "acquired",
+                    record: save(claim(input, existing.attempt + 1, timestamp, ttl, existing), input.identity),
+                };
+            }
+            return { outcome: "existing", record: existing };
+        },
+        async markDispatched(input) {
+            const record = requireClaim(current(input), input, ["pending"]);
+            return save({
+                ...record,
+                status: "dispatched",
+                version: record.version + 1,
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async complete(input) {
+            const record = requireClaim(current(input), input, ["dispatched"]);
+            const result = input.result === undefined ? undefined : validateResult(input.result, input);
+            const resultRef = input.resultRef === undefined ? undefined : validateReference(input.resultRef);
+            return save({
+                ...withoutClaim(record),
+                status: "completed",
+                version: record.version + 1,
+                ...(result === undefined ? {} : { result }),
+                ...(resultRef === undefined ? {} : { resultRef }),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async fail(input) {
+            const record = requireClaim(current(input), input, ["pending", "dispatched"]);
+            return save({
+                ...withoutClaim(record),
+                status: input.status,
+                version: record.version + 1,
+                failure: validateFailure(input.failure),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async markUnknown(input) {
+            const record = requireClaim(current(input), input, ["dispatched"]);
+            return save({
+                ...withoutClaim(record),
+                status: "unknown",
+                version: record.version + 1,
+                ...(input.failure === undefined ? {} : { failure: validateFailure(input.failure) }),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async resolveUnknown(input) {
+            const record = current(input);
+            if (!record || record.status !== "unknown" || record.version !== input.expectedVersion)
+                throw conflict();
+            const result = input.result === undefined ? undefined : validateResult(input.result, input);
+            const resultRef = input.resultRef === undefined ? undefined : validateReference(input.resultRef);
+            return save({
+                ...record,
+                status: input.status,
+                version: record.version + 1,
+                ...(result === undefined ? {} : { result }),
+                ...(resultRef === undefined ? {} : { resultRef }),
+                ...(input.failure === undefined ? {} : { failure: validateFailure(input.failure) }),
+                updatedAt: timestamp(now()),
+            }, input.identity);
+        },
+        async cleanup(input) {
+            throwIfAborted(input.signal);
+            const before = Date.parse(input.before);
+            if (!Number.isFinite(before))
+                throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "cleanup boundary is invalid");
+            validateOwnership(input.ownership);
+            const limit = cleanupLimit(input.limit);
+            let deleted = 0;
+            for (const [id, record] of records) {
+                throwIfAborted(input.signal);
+                if (deleted >= limit)
+                    break;
+                if (!sameOwnership(record, input.ownership) || !isTerminal(record.status) || Date.parse(record.updatedAt) >= before)
+                    continue;
+                records.delete(id);
+                deleted += 1;
+            }
+            return { deleted };
+        },
+    };
+}
+function canonical(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype) {
+        const out = {};
+        for (const key of Object.keys(value).sort())
+            out[key] = canonical(value[key]);
+        return out;
+    }
+    throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "tool effect values must be JSON");
+}
+function claim(input, attempt, currentTime, ttl, previous) {
+    return {
+        ...owner(input.ownership),
+        key: input.key,
+        sessionId: input.sessionId,
+        runId: input.runId,
+        toolCallId: input.toolCallId,
+        toolName: input.toolName,
+        argumentsHash: input.argumentsHash,
+        status: "pending",
+        attempt,
+        version: (previous?.version ?? 0) + 1,
+        claimToken: randomUUID(),
+        createdAt: previous?.createdAt ?? timestamp(currentTime),
+        updatedAt: timestamp(currentTime),
+        expiresAt: timestamp(currentTime + ttl),
+    };
+}
+function expire(record, currentTime) {
+    if ((record.status !== "pending" && record.status !== "dispatched") || !record.expiresAt || Date.parse(record.expiresAt) > currentTime)
+        return record;
+    const status = record.status === "pending" ? "failed_retryable" : "unknown";
+    return freezeRecord({
+        ...withoutClaim(record),
+        status,
+        version: record.version + 1,
+        failure: { code: "ERR_PRISM_TOOL_EFFECT_EXPIRED" },
+        updatedAt: timestamp(currentTime),
+    });
+}
+function requireClaim(record, input, statuses) {
+    if (!record || !statuses.includes(record.status) || record.version !== input.expectedVersion || record.claimToken !== input.claimToken)
+        throw conflict();
+    return record;
+}
+function withoutClaim(record) {
+    const { claimToken: _claimToken, expiresAt: _expiresAt, ...rest } = record;
+    return rest;
+}
+function validateKey(input) {
+    assertIdentityActive(input.identity);
+    validateOwnership(input.ownership);
+    assertIdentityMatchesOwnership(input.identity, input.ownership);
+    if (input.ownership.tenantId !== input.identity.tenantId ||
+        input.ownership.accountId !== input.identity.accountId ||
+        input.ownership.userId !== input.identity.userId)
+        throw conflict();
+    validateText(input.key, MAX_EFFECT_KEY_BYTES, "effect key");
+    validateText(input.sessionId, MAX_IDENTIFIER_BYTES, "session id");
+    validateText(input.runId, MAX_IDENTIFIER_BYTES, "run id");
+    validateText(input.toolCallId, MAX_IDENTIFIER_BYTES, "tool call id");
+    validateText(input.toolName, MAX_TOOL_NAME_BYTES, "tool name");
+    if (!/^[a-f0-9]{64}$/.test(input.argumentsHash))
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "arguments hash is invalid");
+}
+function validateOwnership(ownership) {
+    if (!ownership.tenantId?.trim())
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "tool effect ownership is required");
+    for (const value of [ownership.tenantId, ownership.accountId, ownership.userId]) {
+        if (value !== undefined)
+            validateText(value, MAX_IDENTIFIER_BYTES, "ownership");
+    }
+}
+function assertMatches(record, input) {
+    if (record.key !== input.key ||
+        record.sessionId !== input.sessionId ||
+        record.runId !== input.runId ||
+        record.toolCallId !== input.toolCallId ||
+        record.toolName !== input.toolName ||
+        record.argumentsHash !== input.argumentsHash ||
+        !sameOwnership(record, input.ownership)) {
+        throw conflict();
+    }
+}
+function validateResult(result, input) {
+    if (result.toolCallId !== input.toolCallId || result.name !== input.toolName)
+        throw conflict();
+    return jsonSnapshot(result, MAX_RESULT_BYTES, "tool result");
+}
+function validateReference(reference) {
+    validateText(reference, MAX_REFERENCE_BYTES, "effect reference");
+    return reference;
+}
+function validateFailure(failure) {
+    validateText(failure.code, 128, "effect failure code");
+    return Object.freeze({
+        ...failure,
+        ...(failure.reference === undefined ? {} : { reference: validateReference(failure.reference) }),
+    });
+}
+function assertRecordSize(record) {
+    void jsonSnapshot(record, MAX_RECORD_BYTES, "tool effect record");
+}
+function jsonSnapshot(value, maxBytes, label) {
+    let text;
+    try {
+        text = JSON.stringify(value);
+    }
+    catch {
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", `${label} must be JSON serializable`);
+    }
+    if (text === undefined || Buffer.byteLength(text) > maxBytes)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", `${label} exceeds limits`);
+    return JSON.parse(text);
+}
+function freezeRecord(record) {
+    return freezeJson(jsonSnapshot(record, MAX_RECORD_BYTES, "tool effect record"));
+}
+function freezeJson(value) {
+    if (!value || typeof value !== "object")
+        return value;
+    for (const child of Object.values(value))
+        freezeJson(child);
+    return Object.freeze(value);
+}
+function owner(ownership) {
+    return {
+        tenantId: ownership.tenantId,
+        ...(ownership.accountId === undefined ? {} : { accountId: ownership.accountId }),
+        ...(ownership.userId === undefined ? {} : { userId: ownership.userId }),
+    };
+}
+function sameOwnership(left, right) {
+    return left.tenantId === right.tenantId && left.accountId === right.accountId && left.userId === right.userId;
+}
+function recordKey(input) {
+    return JSON.stringify([
+        input.identity.tenantId,
+        input.identity.accountId ?? "",
+        input.identity.userId ?? "",
+        input.identity.principal.id,
+        input.key,
+    ]);
+}
+function isTerminal(status) {
+    return status === "completed" || status === "failed_terminal";
+}
+function timestamp(value) {
+    return new Date(value).toISOString();
+}
+function claimTtl(value) {
+    const ttl = value ?? DEFAULT_CLAIM_TTL_MS;
+    if (!Number.isSafeInteger(ttl) || ttl < 1 || ttl > HARD_CLAIM_TTL_MS)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "claim TTL exceeds limits");
+    return ttl;
+}
+function maxAttempts(value) {
+    const attempts = value ?? DEFAULT_MAX_ATTEMPTS;
+    if (!Number.isSafeInteger(attempts) || attempts < 1 || attempts > HARD_MAX_ATTEMPTS)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "effect attempts exceed limits");
+    return attempts;
+}
+function cleanupLimit(value) {
+    const limit = value ?? DEFAULT_CLEANUP_LIMIT;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > HARD_CLEANUP_LIMIT)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "cleanup limit exceeds limits");
+    return limit;
+}
+function validateText(value, maxBytes, label) {
+    if (typeof value !== "string" || !value.trim() || Buffer.byteLength(value) > maxBytes)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", `${label} is required and bounded`);
+}
+function conflict() {
+    return new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "tool effect transition conflict");
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+//# sourceMappingURL=tool-effects.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;