@arnilo/prism 0.4.0 → 0.5.0

package/dist/agent-session/session/persist.js

@@ -0,0 +1,166 @@
+/** Finalize/persist phase of runInternal (plan 059). */
+import { boundedLoopSnapshot, initialAgentRunState, publicState, saveAgentRunState } from "../../agent-run-state.js";
+import { AgentRunStateError } from "../../contracts.js";
+import { redactRunLedgerRecord } from "../../redaction.js";
+import { isFlushableRunLedger } from "../../run-ledger.js";
+import { snapshotLoadedSkillBodies } from "../../skill-load.js";
+import { randomId } from "../helpers.js";
+export async function persistDurable(session, state) {
+    const durable = session.activeDurable;
+    if (!durable)
+        throw new AgentRunStateError("Durable run state is not configured");
+    const persisted = durable.options.persistSessionState
+        ? {
+            ...state,
+            sessionState: {
+                loadedSkillNames: session.loadedSkills.list(),
+                ...(session.activatedTools.list().length ? { activatedToolNames: session.activatedTools.list() } : {}),
+                ...(durable.options.includeSkillBodies
+                    ? {
+                        loadedSkillBodies: snapshotLoadedSkillBodies(session.activeRunSkills, session.loadedSkills, session.restoredSkillBodies.length
+                            ? new Map(session.restoredSkillBodies.map((e) => [e.name, e.instructions]))
+                            : undefined),
+                    }
+                    : {}),
+            },
+        }
+        : state;
+    const saved = await saveAgentRunState({
+        checkpoints: durable.options.checkpoints,
+        state: persisted,
+        expectedVersion: durable.version,
+        ownership: session.activeOwnership,
+        fencingToken: durable.options.fencingToken,
+        redactor: session.activeRedactor,
+        maxStateBytes: durable.options.maxStateBytes,
+    });
+    durable.state = saved.state;
+    durable.version = saved.record.version;
+    return publicState(saved.state);
+}
+export async function suspendDurable(session, input) {
+    const durable = session.activeDurable;
+    if (!durable)
+        throw new AgentRunStateError("Durable interruption is not configured");
+    const loop = session.activeLoop;
+    const loopState = loop?.snapshot ? boundedLoopSnapshot(loop.name, loop.revision ?? "1", loop.snapshot()) : undefined;
+    const state = durable.state ??
+        initialAgentRunState({
+            agent: session.agent,
+            options: durable.options,
+            runId: input.runId,
+            sessionId: session.id,
+            leafId: session.currentLeafId,
+            model: input.model,
+            counters: input.limits.snapshot(),
+            deadlineAt: input.limits.deadlineAt,
+            status: "suspended",
+            interruption: input.interruption,
+            messages: input.messages,
+            pending: input.pending,
+            pendingCalls: input.pendingCalls,
+            interruptBeforeTool: durable.options.interruptBeforeTool,
+        });
+    return persistDurable(session, {
+        ...state,
+        leafId: session.currentLeafId,
+        status: "suspended",
+        interruption: input.interruption,
+        ...(input.messages ? { input: input.messages } : {}),
+        ...(input.pending ? { pending: input.pending } : {}),
+        ...(input.pendingCalls ? { pendingCalls: input.pendingCalls } : {}),
+        nestedRuns: input.nestedRuns ?? state.nestedRuns,
+        ...(loopState ? { loopState } : {}),
+        counters: input.limits.snapshot(),
+    });
+}
+export async function persistSucceeded(ctx, loopUsage) {
+    const { session, runId, runUsage } = ctx;
+    const usage = runUsage.value() ?? loopUsage;
+    if (usage && session.activeLedger) {
+        const usageRecord = {
+            id: randomId("usage"),
+            sessionId: session.id,
+            runId,
+            scope: "run_total",
+            usage,
+            recordedAt: new Date().toISOString(),
+            ...session.activeOwnership,
+        };
+        await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
+    }
+    await session.drainLedger();
+    const runState = session.activeDurable?.state
+        ? await persistDurable(session, {
+            ...session.activeDurable.state,
+            status: "succeeded",
+            pending: undefined,
+            pendingCalls: undefined,
+            nestedRuns: undefined,
+            stickyDecisions: undefined,
+            interruption: undefined,
+            loopState: undefined,
+        })
+        : undefined;
+    session.emit({
+        type: "agent_finished",
+        sessionId: session.id,
+        runId,
+        usage,
+        ...(ctx.loopCtx.finishReason ? { finishReason: ctx.loopCtx.finishReason } : {}),
+    });
+    return session.buildRunResult({ runId, status: "succeeded", usage, runState });
+}
+export async function cleanupRun(input) {
+    const { session, controller, cleanupSignal, runId, model, startedAt, runStatus, runError } = input;
+    if (session.activeRun === controller)
+        session.activeRun = undefined;
+    session.activeRunId = undefined;
+    session.activeLoop = undefined;
+    session.activeGatedRound = undefined;
+    session.activeProviderTurnAbort = undefined;
+    session.pendingSoftInterrupt = false;
+    session.pendingSteers = [];
+    session.pendingSteerBytes = 0;
+    try {
+        await session.drainLedger();
+        if (session.activeLedger) {
+            const finishRecord = {
+                id: runId,
+                sessionId: session.id,
+                branchId: session.currentLeafId,
+                model,
+                provider: model.provider,
+                idempotencyKey: session.activeIdempotencyKey,
+                status: runStatus,
+                startedAt,
+                finishedAt: new Date().toISOString(),
+                abortReason: controller.signal.aborted ? String(controller.signal.reason) : undefined,
+                error: runError,
+                ...(session.activePromptVersion ? { promptVersion: session.activePromptVersion } : {}),
+                ...session.activeOwnership,
+            };
+            await session.activeLedger.appendRun(redactRunLedgerRecord(finishRecord, session.activeRedactor));
+            if (isFlushableRunLedger(session.activeLedger) && session.activeLedger.durability === "flush_on_terminal")
+                await session.activeLedger.flush();
+        }
+    }
+    finally {
+        session.activeLedger = undefined;
+        session.activeEffectStore = undefined;
+        session.activeOwnership = undefined;
+        session.activeIdentity = undefined;
+        session.activeIdempotencyKey = undefined;
+        session.activeGuardrails = undefined;
+        session.activeMetadata = undefined;
+        session.activePromptVersion = undefined;
+        session.activeLimits?.dispose();
+        session.activeLimits = undefined;
+        session.activeLimitOutputBuffer = false;
+        session.activeRedactor = undefined;
+        session.activeProvider = undefined;
+        cleanupSignal();
+        session.closeSubscribers();
+    }
+}
+//# sourceMappingURL=persist.js.map

package/dist/agent-session/session/provider-round.d.ts

@@ -0,0 +1,6 @@
+/** Provider-round phase of runInternal (plan 059). */
+import type { ProviderRequest, ProviderTurnResult, RunOptions, Usage } from "../../contracts.js";
+import type { RoundContext, SessionHost } from "./types.js";
+export declare function recordProviderUsage(ctx: RoundContext, turnUsage: Usage | undefined, turn: number, attempt: number): Promise<void>;
+export declare function generateWithRetry(session: SessionHost, request: ProviderRequest, runId: string, options: RunOptions, signal: AbortSignal, requestSecrets?: readonly (string | undefined)[], turn?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>): Promise<ProviderTurnResult>;
+export declare function generateProviderTurn(session: SessionHost, request: ProviderRequest, runId: string, signal: AbortSignal, secrets?: readonly (string | undefined)[], turn?: number, attempt?: number, recordUsage?: (usage: Usage | undefined, turn: number, attempt: number) => Promise<void>): Promise<ProviderTurnResult>;

package/dist/agent-session/session/provider-round.js

@@ -0,0 +1,231 @@
+/** Provider-round phase of runInternal (plan 059). */
+import { assertGuardrailsAllowed, GuardrailError, runGuardrails } from "../../guardrails.js";
+import { createProviderTurnMetadata, readProviderHttpStatus } from "../../observability.js";
+import { providerToolCallDeltaContent } from "../../provider-events.js";
+import { errorToErrorInfo, redactRunLedgerRecord, redactSecrets } from "../../redaction.js";
+import { createDefaultRetryPolicy, waitForRetry } from "../../retry.js";
+import { bridgeAbort, errorFromInfo, isSteerSoftInterrupt, jsonBytes, mergeRetry, ProviderTurnFailure, providerContent, randomId, reconstructMissingToolCalls, SteerSoftInterrupt, throwIfAborted, } from "../helpers.js";
+/**
+ * Plan 062: price usage through the host's {@link CostCatalog} when the provider
+ * did not report a cost itself. Stale/unknown quotes, catalog failures, or
+ * non-`per_million_tokens` units degrade to usage-only (cost untouched).
+ */
+async function withCatalogCost(catalog, model, usage, signal) {
+    if (!catalog || usage.cost !== undefined)
+        return usage;
+    try {
+        const quote = await catalog.get(model.model, { signal });
+        if (!quote || (quote.unit !== undefined && quote.unit !== "per_million_tokens"))
+            return usage;
+        const cost = ((usage.inputTokens ?? 0) * (quote.input ?? 0) +
+            (usage.outputTokens ?? 0) * (quote.output ?? 0) +
+            (usage.cacheReadTokens ?? 0) * (quote.cacheRead ?? 0) +
+            (usage.cacheWriteTokens ?? 0) * (quote.cacheWrite ?? 0)) /
+            1_000_000;
+        if (!Number.isFinite(cost) || cost <= 0)
+            return usage;
+        return { ...usage, cost, ...(quote.currency !== undefined ? { currency: quote.currency } : {}) };
+    }
+    catch {
+        return usage; // catalog failure degrades to usage-only
+    }
+}
+export async function recordProviderUsage(ctx, turnUsage, turn, attempt) {
+    const { session, limits, runUsage, runId } = ctx;
+    const usage = turnUsage
+        ? await withCatalogCost(session.agent.config.costCatalog, ctx.model, turnUsage, ctx.controller.signal)
+        : undefined;
+    limits.recordUsage(usage);
+    if (!usage)
+        return;
+    runUsage.add(usage);
+    if (!session.activeLedger)
+        return;
+    const usageRecord = {
+        id: randomId("usage"),
+        sessionId: session.id,
+        runId,
+        scope: "provider_turn",
+        turn,
+        attempt,
+        usage,
+        recordedAt: new Date().toISOString(),
+        ...session.activeOwnership,
+    };
+    await session.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, session.activeRedactor));
+}
+export async function generateWithRetry(session, request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage) {
+    const retry = mergeRetry(session.agent.config.retry, options.retry);
+    const secrets = [...requestSecrets, ...(retry?.secrets ?? [])];
+    const policy = retry?.policy ?? (retry ? createDefaultRetryPolicy(retry) : undefined);
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return await generateProviderTurn(session, request, runId, signal, secrets, turn, attempt, recordUsage);
+        }
+        catch (error) {
+            if (error instanceof GuardrailError || isSteerSoftInterrupt(error))
+                throw error;
+            const failure = error instanceof ProviderTurnFailure ? error : undefined;
+            const info = failure ? redactSecrets(failure.info, secrets) : errorToErrorInfo(error, secrets);
+            if (!policy || failure?.observable)
+                throw errorFromInfo(info);
+            const context = { sessionId: session.id, runId, attempt, error: info, metadata: retry?.metadata, signal };
+            let decision = await policy.decide(context);
+            const payload = (await session.agent.config.middleware?.run("retry", { context, decision })) ?? {
+                context,
+                decision,
+            };
+            decision = payload.decision;
+            if (!decision.retry)
+                throw errorFromInfo(info);
+            const delayMs = decision.delayMs ?? 0;
+            session.emit({ type: "retry_scheduled", sessionId: session.id, runId, attempt, delayMs, error: info });
+            await waitForRetry(decision, signal);
+        }
+    }
+}
+export async function generateProviderTurn(session, request, runId, signal, secrets = [], turn = 1, attempt = 1, recordUsage) {
+    session.activeLimits.charge("maxProviderAttempts");
+    session.activeLimits.charge("maxRequestBytes", jsonBytes(request));
+    const startedAt = performance.now();
+    const providerId = session.activeProvider?.id ?? request.model.provider;
+    const buildMetadata = (extra = {}) => createProviderTurnMetadata(request, providerId, { attempt, ...extra });
+    session.emit({
+        type: "provider_turn_started",
+        sessionId: session.id,
+        runId,
+        turn,
+        metadata: buildMetadata(),
+    });
+    const content = [];
+    const calls = [];
+    const toolDeltas = [];
+    let messageId;
+    let started = false;
+    let usage;
+    let usageRecorded = false;
+    const bufferedOutput = [];
+    const bufferOutput = Boolean(session.activeGuardrails?.output?.length || session.activeLimitOutputBuffer);
+    const emitOutput = (event) => {
+        if (bufferOutput)
+            bufferedOutput.push(event);
+        else
+            session.emit(event);
+    };
+    const recordTurnUsage = async () => {
+        if (usageRecorded)
+            return;
+        usageRecorded = true;
+        await recordUsage?.(usage, turn, attempt);
+    };
+    const turnAbort = new AbortController();
+    const cleanupTurn = bridgeAbort(signal, turnAbort);
+    session.activeProviderTurnAbort = turnAbort;
+    if (session.pendingSoftInterrupt) {
+        session.pendingSoftInterrupt = false;
+        turnAbort.abort(new SteerSoftInterrupt());
+    }
+    const turnRequest = { ...request, signal: turnAbort.signal };
+    try {
+        throwIfAborted(turnAbort.signal);
+        for await (const event of session.activeProvider.generate(turnRequest)) {
+            throwIfAborted(turnAbort.signal);
+            session.activeLimits.charge("maxResponseBytes", jsonBytes(event));
+            if (event.type === "error")
+                throw new ProviderTurnFailure(event.error, started);
+            if (event.type === "usage")
+                usage = event.usage;
+            if (event.type === "done") {
+                usage = event.usage ?? usage;
+                break;
+            }
+            if (event.type === "message_start") {
+                started = true;
+                messageId = event.messageId;
+                emitOutput({ type: "message_started", sessionId: session.id, runId, message: { id: messageId, role: "assistant", content: [] } });
+                continue;
+            }
+            if (event.type === "content_delta" || event.type === "tool_call" || event.type === "tool_call_delta") {
+                if (!started) {
+                    started = true;
+                    emitOutput({ type: "message_started", sessionId: session.id, runId, message: { role: "assistant", content: [] } });
+                }
+                if (event.type === "tool_call_delta") {
+                    toolDeltas.push(event);
+                    emitOutput({ type: "message_delta", sessionId: session.id, runId, content: providerToolCallDeltaContent(event) });
+                    continue;
+                }
+                const block = providerContent(event);
+                content.push(block);
+                if (block.type === "tool_call")
+                    calls.push(block);
+                emitOutput({ type: "message_delta", sessionId: session.id, runId, content: block });
+            }
+        }
+        for (const call of reconstructMissingToolCalls(toolDeltas, calls)) {
+            content.push(call);
+            calls.push(call);
+            emitOutput({ type: "message_delta", sessionId: session.id, runId, content: call });
+        }
+        await recordTurnUsage();
+        if (session.activeGuardrails?.output?.length) {
+            assertGuardrailsAllowed(await runGuardrails({
+                stage: "output",
+                guardrails: session.activeGuardrails,
+                value: { content, calls, messageId, started, usage },
+                context: { sessionId: session.id, runId, metadata: session.activeMetadata ?? {}, signal: turnAbort.signal },
+                redactor: session.activeRedactor,
+                emit: (event) => session.emit(event),
+            }));
+        }
+        if (bufferOutput)
+            for (const event of bufferedOutput)
+                session.emit(event);
+        const latencyMs = Math.round(performance.now() - startedAt);
+        session.emit({
+            type: "provider_turn_finished",
+            sessionId: session.id,
+            runId,
+            turn,
+            metadata: buildMetadata({ latencyMs }),
+            usage,
+        });
+        return { content, calls, messageId, started, usage };
+    }
+    catch (error) {
+        if (isSteerSoftInterrupt(error) || isSteerSoftInterrupt(turnAbort.signal.reason)) {
+            await recordTurnUsage();
+            const latencyMs = Math.round(performance.now() - startedAt);
+            session.emit({
+                type: "provider_turn_finished",
+                sessionId: session.id,
+                runId,
+                turn,
+                metadata: buildMetadata({ latencyMs }),
+                usage,
+            });
+            throw new SteerSoftInterrupt();
+        }
+        const latencyMs = Math.round(performance.now() - startedAt);
+        const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : errorToErrorInfo(error, secrets);
+        await recordTurnUsage();
+        session.emit({
+            type: "provider_turn_finished",
+            sessionId: session.id,
+            runId,
+            turn,
+            metadata: buildMetadata({ latencyMs, httpStatus: readProviderHttpStatus(info) }),
+            usage,
+            error: info,
+        });
+        if (error instanceof GuardrailError || error instanceof ProviderTurnFailure)
+            throw error;
+        throw new ProviderTurnFailure(info, started);
+    }
+    finally {
+        cleanupTurn();
+        if (session.activeProviderTurnAbort === turnAbort)
+            session.activeProviderTurnAbort = undefined;
+    }
+}
+//# sourceMappingURL=provider-round.js.map

package/dist/agent-session/session/tool-round.d.ts

@@ -0,0 +1,31 @@
+/** Tool-round phase of runInternal (plan 059). */
+import type { AgentRunRef, LoopContext, NestedRunRef, PendingDecision, ResumeNestedRun, StickyDecision, ToolCallContent, ToolRegistry, ToolResult, Usage } from "../../contracts.js";
+import { AgentDelegationSuspendedError } from "../../contracts.js";
+import type { RoundContext, SessionHost } from "./types.js";
+export declare function matchNestedSticky(session: SessionHost, decision: PendingDecision): StickyDecision | undefined;
+export declare function matchStickyDecision(session: SessionHost, call: ToolCallContent, registry: ToolRegistry): StickyDecision | undefined;
+export declare function buildPendingDecision(session: SessionHost, call: ToolCallContent, approvalId: string, registry: ToolRegistry, runId: string, metadata: Readonly<Record<string, unknown>>, signal: AbortSignal): PendingDecision;
+export declare function applyNestedRun(session: SessionHost, input: {
+    ref: AgentRunRef;
+    toolCall: ToolCallContent;
+    path: readonly string[];
+    pending: readonly PendingDecision[];
+    hook?: ResumeNestedRun;
+}): Promise<{
+    toolResult: ToolResult;
+} | {
+    entry: NestedRunRef;
+    pending: PendingDecision[];
+}>;
+export declare function suspendGatedRound(ctx: RoundContext): Promise<void>;
+export declare function suspendNested(ctx: RoundContext, nested: {
+    entry: NestedRunRef;
+    toolCall: ToolCallContent;
+    pending: PendingDecision[];
+}): Promise<never>;
+export declare function replayToolResult(ctx: RoundContext, result: ToolResult): Promise<void>;
+export declare function handleNestedSignal(ctx: RoundContext, error: AgentDelegationSuspendedError): Promise<void>;
+export declare function bindChargeToolRound(ctx: RoundContext): LoopContext["chargeToolRound"];
+export declare function bindDispatchToolCall(ctx: RoundContext): LoopContext["dispatchToolCall"];
+export declare function replayDurableNestedAndPending(ctx: RoundContext): Promise<void>;
+export declare function runLoopUntilSettled(ctx: RoundContext): Promise<Usage | undefined>;