@arnilo/prism 0.0.23 → 0.0.24

package/dist/tool-effects.js

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

@@ -1,4 +1,4 @@
-import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, ToolRegistry, ToolResult } from "./contracts.js";
+import type { AgentEvent, ErrorInfo, Guardrails, JsonObject, OwnershipScope, RunLedger, ToolCallContent, ToolDefinition, ToolExecutionContext, 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";
@@ -42,6 +42,8 @@ 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;

package/dist/tools.js

@@ -1,10 +1,11 @@
 import { isJsonObject } from "./config.js";
 import { GuardrailError, runGuardrails } from "./guardrails.js";
-import { assertIdentityActive, assertIdentityMatchesOwnership } from "./identity.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";
@@ -89,8 +90,9 @@ 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) => {
@@ -135,17 +137,37 @@ 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");
+        if (isSuspended(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({
@@ -166,16 +188,43 @@ 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;
+        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);
@@ -194,6 +243,152 @@ export async function dispatchToolCall(options) {
         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,
+        },
+    };
+}
+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";
+}
 async function checkCall(call, options, startedAt) {
     const context = options.context;
     const tool = options.registry.get(call.name);

package/docs/0.1.0-readiness.md

@@ -1,12 +1,12 @@
 # 0.1.0 / 1.0 Readiness Gates
 
-Status: **0.0.23** is the current release line (Phase 6 production enterprise PostgreSQL state adapters); **1.0** readiness remains operator-gated, not automatic.
+Status: **0.0.24** is the current release line (Phase 7 distributed events and recoverable tool effects); **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
 (Phase 11, Node v24.18.0, Linux x86_64). Treat it as historical floor evidence,
 not the current release tag. Re-run each gate on the target release tree before
-cutting 0.0.23 / 1.0. The decision to cut 1.0 stays with the operator after
+cutting 0.0.24 / 1.0. The decision to cut 1.0 stays with the operator after
 operator-gated legs run in a protected environment and Phase 12 demand evidence
 exists.
 
@@ -14,15 +14,15 @@ 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.23)
+## Current line (0.0.24)
 
 | Item | Status |
 |---|---|
-| Published graph | **47** publishable manifests at **0.0.23** (`docs/release-and-install.md`) |
-| Phase 6 enterprise state | `@arnilo/prism-enterprise-postgres`: policy/evaluation/work-idempotency/router state, checksummed migration, explicit cleanup |
-| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.22 → 0.0.23 production enterprise state adapters` documents idempotency and async-router changes |
-| Protected database evidence | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; benchmark evidence fixes 10 scenarios, 14 index plans, and 50/100 ms p95 ceilings |
-| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.23 database evidence is recorded separately |
+| Published graph | **47** publishable manifests at **0.0.24** (`docs/release-and-install.md`) |
+| Phase 7 distributed events/effects | `AgentEventSource`, `ToolEffectStore`, AG-UI MCP/A2A fronting; enterprise `toolEffects`; schema v6/v7 + enterprise migration 002 |
+| Docs tripwires | `node --test dist/__tests__/docs.test.js` — migration section `0.0.23 → 0.0.24 distributed events and recoverable tool effects` |
+| Protected database evidence | `PRISM_TEST_POSTGRES_URL="$DATABASE_URL" npm run test:postgres`; `benchmark-0.0.24.json` under Task 0 ceilings |
+| Readiness table below | **0.0.16 measured values** remain historical network-free baseline; 0.0.24 database evidence is recorded separately |
 
 ## Gate table
 
@@ -80,7 +80,7 @@ Deterministic budgets (CI gate, `scripts/budget-gate.test.mjs`):
 | Root unpacked bytes | 2,043,402 | +5% | 2.1 MB (within) |
 | Root file count | 270 | +5% | 270 |
 | Cold-startup import | 38 ms | ceiling 250 ms | ~38 ms |
-| Aggregate packed (47 manifests, reference only) | 1,217,694 | +10% | remeasure for the 0.0.23 graph before release |
+| Aggregate packed (47 manifests, reference only) | 1,217,694 | +10% | remeasure for the 0.0.24 graph before release |
 
 Benchmark medians (on-demand evidence, `scripts/benchmark-0.0.16.mjs`, ±25%):