@arnilo/prism 0.0.96 → 0.1.0

package/dist/tool-result-fold.js

@@ -0,0 +1,176 @@
+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/dist/tools.d.ts

@@ -1,15 +1,15 @@
-import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
-import type { RunLimitTracker } from "./run-limits.js";
+import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolEffectDeclaration, ToolEffectStore, ToolRegistry, ToolResult } from "./contracts.js";
 import type { MiddlewareRegistry } from "./middleware.js";
 import { type SecretRedactor } from "./redaction.js";
 import { type DuplicateRegistrationOptions } from "./registry-options.js";
+import type { RunLimitTracker } from "./run-limits.js";
 import { type PermissionPolicy, type TrustPolicy } from "./security.js";
 export interface ToolFilter {
     readonly allow?: readonly string[];
     readonly deny?: readonly string[];
 }
 export type ToolFilterInput = ToolFilter | readonly ToolFilter[];
-export type ToolValidator = (tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext) => void | string | ErrorInfo | Promise<void | string | ErrorInfo>;
+export type ToolValidator = (tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext) => undefined | string | ErrorInfo | Promise<undefined | string | ErrorInfo>;
 export interface ToolArgumentValidationError {
     readonly path?: string;
     readonly message: string;
@@ -42,7 +42,11 @@ export interface DispatchToolCallOptions {
     readonly trust?: TrustPolicy;
     readonly redactor?: SecretRedactor;
     readonly ledger?: RunLedger;
+    /** Optional shared recovery store. Only declared optional/required effects use it. */
+    readonly effectStore?: ToolEffectStore;
     readonly ownership?: OwnershipScope;
+    /** Host-verified identity; asserted active before tool side effects when present. */
+    readonly identity?: import("./identity.js").AgentIdentity;
     /** Tool stages run after middleware normalization and before side effects/exposure. */
     readonly guardrails?: Guardrails;
     /** Shared run tracker; direct hosts may supply one for their call scope. */
@@ -53,3 +57,4 @@ export interface ToolRegistryOptions extends DuplicateRegistrationOptions {
 export declare function createToolRegistry(tools?: readonly ToolDefinition[], options?: ToolRegistryOptions): ToolRegistry;
 export declare function filterTools(tools: readonly ToolDefinition[], filter?: ToolFilterInput): readonly ToolDefinition[];
 export declare function dispatchToolCall(options: DispatchToolCallOptions): Promise<ToolResult>;
+export declare function resolveToolEffectDeclaration(tool: ToolDefinition, args: JsonObject, context: ToolExecutionContext): ToolEffectDeclaration | undefined;

package/dist/tools.js

@@ -1,9 +1,11 @@
 import { isJsonObject } from "./config.js";
-import { createId } from "./ids.js";
 import { GuardrailError, runGuardrails } from "./guardrails.js";
+import { assertIdentityActive, assertIdentityMatchesOwnership, ownershipFromIdentity } from "./identity.js";
+import { createId } from "./ids.js";
 import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "./redaction.js";
 import { assertCanRegister } from "./registry-options.js";
 import { assertPermission, assertTrusted } from "./security.js";
+import { deriveToolEffectKey, toolEffectArgumentsHash, ToolEffectError } from "./tool-effects.js";
 /** Wrap a schema adapter as the existing `ToolValidator` seam used by dispatch and the agent runtime. */
 export function createToolParameterValidator(validator, options = {}) {
     const missingSchema = options.missingSchema ?? "allow";
@@ -51,7 +53,9 @@ export function createToolRegistry(tools = [], options = {}) {
 export function filterTools(tools, filter) {
     const filters = Array.isArray(filter) ? filter : filter ? [filter] : [];
     const denied = new Set(filters.flatMap((item) => item.deny ?? []));
-    const allows = filters.map((item) => item.allow?.length ? new Set(item.allow) : undefined).filter((item) => Boolean(item));
+    const allows = filters
+        .map((item) => (item.allow?.length ? new Set(item.allow) : undefined))
+        .filter((item) => Boolean(item));
     return tools.filter((tool) => !denied.has(tool.name) && allows.every((allow) => allow.has(tool.name)));
 }
 function toolExecutionMetadata(startedAt, status) {
@@ -86,9 +90,11 @@ export async function dispatchToolCall(options) {
     const postcheck = await checkCall(mediatedCall, options, startedAt);
     if (postcheck)
         return postcheck;
-    const context = {
-        ...options.context,
+    const { idempotencyKey: _untrustedKey, ...baseContext } = options.context;
+    let context = {
+        ...baseContext,
         toolCallId: mediatedCall.id,
+        identity: options.identity ?? options.context.identity,
         progress: async (progress, metadata) => {
             await options.context.progress?.(progress, metadata);
             await options.emit?.({
@@ -108,8 +114,22 @@ export async function dispatchToolCall(options) {
         },
     };
     try {
-        await assertTrusted(options.trust, { kind: "tool", target: mediatedCall.name, capability: "execute", metadata: options.context.metadata });
-        await assertPermission(options.permission, { kind: "tool", action: "execute", target: mediatedCall.name, metadata: options.context.metadata });
+        if (context.identity) {
+            assertIdentityActive(context.identity);
+            assertIdentityMatchesOwnership(context.identity, options.ownership);
+        }
+        await assertTrusted(options.trust, {
+            kind: "tool",
+            target: mediatedCall.name,
+            capability: "execute",
+            metadata: options.context.metadata,
+        });
+        await assertPermission(options.permission, {
+            kind: "tool",
+            action: "execute",
+            target: mediatedCall.name,
+            metadata: options.context.metadata,
+        });
     }
     catch (error) {
         return blocked(mediatedCall, context, "permission_denied", errorToErrorInfo(error, secrets), options, startedAt);
@@ -117,17 +137,38 @@ export async function dispatchToolCall(options) {
     const validation = await options.validate?.(tool, mediatedCall.arguments, context);
     if (validation)
         return blocked(mediatedCall, context, "validation_failed", toErrorInfo(validation, secrets), options, startedAt);
+    let effect;
+    try {
+        const prepared = await prepareToolEffect(tool, mediatedCall, context, options);
+        if (prepared.result)
+            return prepared.result;
+        context = prepared.context;
+        effect = prepared.effect;
+    }
+    catch (error) {
+        return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
+    }
     try {
         await options.beforeExecute?.(mediatedCall, tool, context);
     }
     catch (error) {
-        if (error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED")
+        await failBeforeEffect(effect, isSuspended(error) ? "failed_retryable" : "failed_terminal");
+        // Loop-state contract errors (snapshot capture) are terminal run errors, not tool errors.
+        if (isSuspended(error) || isLoopStateError(error) || isDelegationSuspended(error))
             throw error;
         return blocked(mediatedCall, context, "execution_denied", errorToErrorInfo(error, secrets), options, startedAt);
     }
-    await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
-    await appendToolCallRecord(options, "started", mediatedCall, startedAt, {});
+    let completedResult;
+    let dispatchAttempted = false;
     try {
+        await options.emit?.({ type: "tool_execution_started", sessionId: context.sessionId, runId: context.runId, call: mediatedCall });
+        await appendToolCallRecord(options, "started", mediatedCall, startedAt, {});
+        if (effect) {
+            dispatchAttempted = true;
+            const record = await effect.store.markDispatched(transition(effect));
+            effect.expectedVersion = record.version;
+            effect.dispatched = true;
+        }
         const raw = await tool.execute(mediatedCall.arguments, context);
         const mediatedResult = await (options.middleware?.run("tool_result", raw) ?? raw);
         const outputGuards = await runGuardrails({
@@ -148,27 +189,221 @@ export async function dispatchToolCall(options) {
         if (outputGuards.terminal) {
             if (outputGuards.terminal.action !== "block")
                 throw new GuardrailError(outputGuards.terminal);
+            if (effect)
+                return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
             return blocked(mediatedCall, context, "guardrail_blocked", { message: "Tool result blocked by guardrail" }, options, startedAt);
         }
+        if (effect && mediatedResult.error)
+            return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
         const result = options.redactor?.redact(mediatedResult) ?? mediatedResult;
+        if (effect) {
+            try {
+                const record = await effect.store.complete({ ...transition(effect), result });
+                effect.expectedVersion = record.version;
+                effect.completed = true;
+                completedResult = record.result ?? result;
+            }
+            catch {
+                return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
+            }
+        }
+        completedResult ??= result;
         const finishedAt = new Date().toISOString();
         const metadata = toolExecutionMetadata(startedAt, "finished");
-        await options.emit?.({ type: "tool_execution_finished", sessionId: context.sessionId, runId: context.runId, result, metadata });
-        await appendToolCallRecord(options, "finished", mediatedCall, startedAt, { finishedAt, result });
-        return result;
+        await options.emit?.({
+            type: "tool_execution_finished",
+            sessionId: context.sessionId,
+            runId: context.runId,
+            result: completedResult,
+            metadata,
+        });
+        await appendToolCallRecord(options, "finished", mediatedCall, startedAt, { finishedAt, result: completedResult });
+        return completedResult;
     }
     catch (error) {
+        if (completedResult)
+            return completedResult;
+        // Nested-run suspensions must propagate to the run loop, never become tool errors.
+        if (isDelegationSuspended(error)) {
+            if (effect && (effect.dispatched || dispatchAttempted))
+                await unknownEffectResult(effect, mediatedCall);
+            else
+                await failBeforeEffect(effect, "failed_retryable");
+            throw error;
+        }
+        if (effect && (effect.dispatched || dispatchAttempted))
+            return finishUnknownEffect(effect, mediatedCall, context, options, startedAt);
+        await failBeforeEffect(effect, "failed_terminal");
         if (error instanceof GuardrailError)
             throw error;
         const info = errorToErrorInfo(error, secrets);
         const result = { toolCallId: mediatedCall.id, name: mediatedCall.name, error: info };
         const finishedAt = new Date().toISOString();
         const metadata = toolExecutionMetadata(startedAt, "error");
-        await options.emit?.({ type: "tool_execution_error", sessionId: context.sessionId, runId: context.runId, call: mediatedCall, error: info, metadata });
+        await options.emit?.({
+            type: "tool_execution_error",
+            sessionId: context.sessionId,
+            runId: context.runId,
+            call: mediatedCall,
+            error: info,
+            metadata,
+        });
         await appendToolCallRecord(options, "error", mediatedCall, startedAt, { finishedAt, result });
         return result;
     }
 }
+async function prepareToolEffect(tool, call, context, options) {
+    const identity = context.identity;
+    const declaration = resolveToolEffectDeclaration(tool, call.arguments, context);
+    if (!declaration || declaration.kind === "none" || declaration.idempotency === "none")
+        return { context };
+    if (!identity && declaration.idempotency === "unsupported")
+        return { context };
+    if (!identity)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "verified identity is required for a durable tool effect");
+    const ownership = ownershipFromIdentity(identity);
+    const argumentsHash = toolEffectArgumentsHash(call.arguments);
+    const base = {
+        identity,
+        ownership,
+        sessionId: context.sessionId,
+        runId: context.runId,
+        toolCallId: call.id,
+        toolName: call.name,
+        argumentsHash,
+    };
+    const key = { ...base, key: deriveToolEffectKey(base), signal: context.signal };
+    const keyedContext = { ...context, idempotencyKey: key.key };
+    if (declaration.idempotency === "tool_managed" || declaration.idempotency === "unsupported")
+        return { context: keyedContext };
+    const store = options.effectStore;
+    if (!store) {
+        if (declaration.idempotency === "required")
+            throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_REQUIRED", "durable tool effect store is required");
+        return { context: keyedContext };
+    }
+    let begun;
+    try {
+        begun = await store.begin(key);
+    }
+    catch (error) {
+        if (error instanceof ToolEffectError)
+            throw error;
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect claim outcome is unknown");
+    }
+    if (begun.outcome === "existing")
+        return { context: keyedContext, result: replayEffectResult(begun.record) };
+    if (!begun.record.claimToken)
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect claim outcome is unknown");
+    return {
+        context: keyedContext,
+        effect: {
+            store,
+            key,
+            claimToken: begun.record.claimToken,
+            expectedVersion: begun.record.version,
+            dispatched: false,
+            completed: false,
+        },
+    };
+}
+export function resolveToolEffectDeclaration(tool, args, context) {
+    const classifierContext = Object.freeze({
+        sessionId: context.sessionId,
+        runId: context.runId,
+        toolCallId: context.toolCallId,
+        signal: context.signal,
+        metadata: context.metadata,
+    });
+    const declaration = typeof tool.effect === "function" ? tool.effect(args, classifierContext) : tool.effect;
+    if (!declaration)
+        return undefined;
+    if (!["none", "local_mutation", "external_mutation"].includes(declaration.kind) ||
+        !["none", "optional", "required", "tool_managed", "unsupported"].includes(declaration.idempotency) ||
+        (declaration.kind === "none" && declaration.idempotency !== "none")) {
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_LIMIT", "tool effect declaration is invalid");
+    }
+    return declaration;
+}
+function replayEffectResult(record) {
+    if (record.status === "completed") {
+        if (record.result)
+            return record.result;
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_COMPLETED", "tool effect already completed without replayable result");
+    }
+    if (record.status === "dispatched" || record.status === "unknown") {
+        throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect outcome requires reconciliation");
+    }
+    throw new ToolEffectError("ERR_PRISM_TOOL_EFFECT_CONFLICT", "tool effect is not dispatchable");
+}
+function transition(effect) {
+    return { ...effect.key, claimToken: effect.claimToken, expectedVersion: effect.expectedVersion };
+}
+async function failBeforeEffect(effect, status) {
+    if (!effect || effect.dispatched || effect.completed)
+        return;
+    try {
+        await effect.store.fail({
+            ...transition(effect),
+            status,
+            failure: { code: "ERR_PRISM_TOOL_EFFECT_PRE_DISPATCH" },
+        });
+    }
+    catch {
+        // No effect was invoked. A stale/failed pre-dispatch transition only delays a later safe retry.
+    }
+}
+async function unknownEffectResult(effect, call) {
+    try {
+        let claim = effect.dispatched
+            ? { claimToken: effect.claimToken, version: effect.expectedVersion }
+            : undefined;
+        if (!claim) {
+            const current = await effect.store.get(effect.key);
+            if (current?.status === "dispatched" && current.claimToken)
+                claim = { claimToken: current.claimToken, version: current.version };
+        }
+        if (claim) {
+            await effect.store.markUnknown({
+                ...effect.key,
+                claimToken: claim.claimToken,
+                expectedVersion: claim.version,
+                failure: { code: "ERR_PRISM_TOOL_EFFECT_UNKNOWN" },
+            });
+        }
+    }
+    catch {
+        // A post-dispatch persistence error is itself ambiguous; never expose or retry it.
+    }
+    return effectErrorResult(call, "ERR_PRISM_TOOL_EFFECT_UNKNOWN", "tool effect outcome requires reconciliation");
+}
+async function finishUnknownEffect(effect, call, context, options, startedAt) {
+    const result = await unknownEffectResult(effect, call);
+    const error = result.error;
+    const finishedAt = new Date().toISOString();
+    const metadata = toolExecutionMetadata(startedAt, "error");
+    try {
+        await options.emit?.({ type: "tool_execution_error", sessionId: context.sessionId, runId: context.runId, call, error, metadata });
+        await appendToolCallRecord(options, "error", call, startedAt, { finishedAt, result });
+    }
+    catch {
+        // The effect is already ambiguous; exposure/ledger failures cannot make it safe to retry.
+    }
+    return result;
+}
+function effectErrorResult(call, code, message) {
+    const error = new ToolEffectError(code, message);
+    return { toolCallId: call.id, name: call.name, error: errorToErrorInfo(error) };
+}
+function isSuspended(error) {
+    return error?.code === "ERR_PRISM_AGENT_RUN_SUSPENDED";
+}
+function isLoopStateError(error) {
+    return typeof error?.code === "string" && error.code.startsWith("ERR_PRISM_LOOP_");
+}
+function isDelegationSuspended(error) {
+    return error?.code === "ERR_PRISM_DELEGATION_SUSPENDED";
+}
 async function checkCall(call, options, startedAt) {
     const context = options.context;
     const tool = options.registry.get(call.name);