@arnilo/prism 0.0.3 → 0.0.5

package/dist/agents.js

@@ -1,8 +1,11 @@
-import { resolveLoop } from "./agent-loops.js";
+import { AgentRunError } from "./contracts.js";
+import { resolveLoop, resolveToolConcurrency } from "./agent-loops.js";
+import { createProviderTurnMetadata, readProviderHttpStatus } from "./observability.js";
 import { createDefaultCompactionStrategy, isCompactionEntryData } from "./compaction.js";
 import { assembleProviderInput } from "./input.js";
 import { providerToolCallDeltaContent, reconstructToolCallDeltas } from "./provider-events.js";
-import { createProviderRequestPolicyChain, mergeProviderRequestOptions, normalizeProviderRequestPolicyResult } from "./provider-request-policy.js";
+import { createProviderRequestPolicyChain, normalizeProviderRequestPolicyResult } from "./provider-request-policy.js";
+import { assertStructuredOutputRequestSupported, resolveRunProviderOptions } from "./structured-output.js";
 import { errorToErrorInfo, redactAgentEvent, redactProviderRequest, redactRunLedgerRecord, redactSecrets, redactSessionEntry } from "./redaction.js";
 import { composeSystemPrompt, mergeSystemPromptConfig } from "./system-prompts.js";
 import { createDefaultRetryPolicy, waitForRetry } from "./retry.js";
@@ -34,7 +37,9 @@ class RuntimeAgentSession {
     activeLedger;
     activeOwnership;
     activeIdempotencyKey;
-    ledgerPromises = [];
+    activeLoopTurn = 1;
+    ledgerChain = Promise.resolve();
+    ledgerFailure;
     constructor(config) {
         this.id = config.id ?? randomId("session");
         this.agent = config.agent;
@@ -67,6 +72,8 @@ class RuntimeAgentSession {
         const model = options.model ?? this.agent.config.model;
         const startedAt = new Date().toISOString();
         let runError;
+        const runUsage = createUsageAccumulator();
+        let usage;
         try {
             this.resolveRunProvider(options);
             throwIfAborted(controller.signal);
@@ -101,12 +108,32 @@ class RuntimeAgentSession {
                 // ponytail: skill context after host context; no per-skill token budget yet.
                 ...activeSkills.flatMap((skill) => skill.context ?? []),
             ];
-            const providerOptions = mergeProviderRequestOptions(this.agent.config.providerOptions, options.providerOptions);
+            const providerOptions = resolveRunProviderOptions(options, this.agent.config);
+            assertStructuredOutputRequestSupported(options.model ?? this.agent.config.model, providerOptions);
             const validate = options.validate ?? this.agent.config.validator;
             // ponytail: RunOptions.instructionInjectors overrides AgentConfig.instructionInjectors (mirrors validate/loop).
             const instructionInjectors = options.instructionInjectors ?? this.agent.config.instructionInjectors ?? [];
             const inputLayout = options.inputLayout ?? this.agent.config.inputLayout;
             const loop = resolveLoop(options, this.agent.config);
+            const toolConcurrency = resolveToolConcurrency(options, this.agent.config);
+            this.activeLoopTurn = 1;
+            const recordProviderUsage = async (turnUsage, turn, attempt) => {
+                runUsage.add(turnUsage);
+                if (!this.activeLedger)
+                    return;
+                const usageRecord = {
+                    id: randomId("usage"),
+                    sessionId: this.id,
+                    runId,
+                    scope: "provider_turn",
+                    turn,
+                    attempt,
+                    usage: turnUsage,
+                    recordedAt: new Date().toISOString(),
+                    ...this.activeOwnership,
+                };
+                await this.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, this.activeRedactor));
+            };
             // ponytail: LoopContext binds existing private helpers; loop orchestrates only.
             const ctx = {
                 sessionId: this.id,
@@ -117,6 +144,7 @@ class RuntimeAgentSession {
                 input,
                 inputMessages,
                 maxToolRounds,
+                toolConcurrency,
                 assemble: async (nextInput, toolResults, turn) => assembleProviderInput({
                     model: options.model ?? this.agent.config.model,
                     input: nextInput,
@@ -144,8 +172,9 @@ class RuntimeAgentSession {
                 generate: async (request) => {
                     const policyResult = await this.applyProviderRequestPolicies(request, runId, options, metadata, controller.signal);
                     const middlewareRequest = await this.agent.config.middleware?.run("provider_request", policyResult.request) ?? policyResult.request;
-                    return this.generateWithRetry(this.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets);
+                    return this.generateWithRetry(this.redactProviderRequest(middlewareRequest), runId, options, controller.signal, policyResult.secrets, this.activeLoopTurn, recordProviderUsage);
                 },
+                isToolCallExclusive: (call) => registry.get(call.name)?.exclusive === true,
                 dispatchToolCall: (call) => dispatchToolCall({
                     call,
                     registry,
@@ -160,14 +189,20 @@ class RuntimeAgentSession {
                     validate,
                 }),
                 appendMessage: (message) => this.appendMessage(message, runId),
-                emit: (event) => this.emit(event),
+                emit: (event) => {
+                    if (event.type === "turn_started")
+                        this.activeLoopTurn = event.turn;
+                    this.emit(event);
+                },
             };
-            const usage = await loop.run(ctx);
+            const loopUsage = await loop.run(ctx);
+            usage = runUsage.value() ?? loopUsage;
             if (usage && this.activeLedger) {
                 const usageRecord = {
                     id: randomId("usage"),
                     sessionId: this.id,
                     runId,
+                    scope: "run_total",
                     usage,
                     recordedAt: new Date().toISOString(),
                     ...this.activeOwnership,
@@ -176,11 +211,23 @@ class RuntimeAgentSession {
             }
             await this.drainLedger();
             this.emit({ type: "agent_finished", sessionId: this.id, runId, usage });
+            return this.buildRunResult({
+                runId,
+                status: "succeeded",
+                usage,
+            });
         }
         catch (error) {
             runError = errorToErrorInfo(error);
             this.emit({ type: "error", sessionId: this.id, runId, error: runError });
-            throw error;
+            const result = this.buildRunResult({
+                runId,
+                status: controller.signal.aborted ? "aborted" : "failed",
+                usage: runUsage.value() ?? usage,
+                error: runError,
+                abortReason: controller.signal.aborted ? String(controller.signal.reason) : undefined,
+            });
+            throw new AgentRunError(result, { cause: error });
         }
         finally {
             if (this.activeRun === controller)
@@ -220,6 +267,48 @@ class RuntimeAgentSession {
     prompt(input, options) {
         return this.run(input, options);
     }
+    async *stream(input, options = {}) {
+        const { maxQueuedEvents, overflow, ...runOptions } = options;
+        const subscription = this.subscribe({ maxQueuedEvents, overflow });
+        let runOwnedId;
+        let settled = false;
+        const runPromise = this.run(input, runOptions).finally(() => {
+            settled = true;
+        });
+        try {
+            for await (const event of subscription) {
+                if ("runId" in event && typeof event.runId === "string") {
+                    if (runOwnedId === undefined && event.type === "agent_started")
+                        runOwnedId = event.runId;
+                    if (runOwnedId !== undefined && event.runId !== runOwnedId)
+                        continue;
+                }
+                yield event;
+            }
+            await runPromise;
+        }
+        finally {
+            if (!settled) {
+                this.abort(new Error("stream consumer closed"));
+                await runPromise.catch(() => undefined);
+            }
+        }
+    }
+    buildRunResult(input) {
+        const final = finalAssistantMessage(this.history);
+        return {
+            sessionId: this.id,
+            runId: input.runId,
+            status: input.status,
+            leafId: this.currentLeafId,
+            text: final.text,
+            content: final.content,
+            message: final.message,
+            usage: input.usage,
+            error: input.error,
+            abortReason: input.abortReason,
+        };
+    }
     async compact(options = {}) {
         if (this.activeRun)
             throw new Error("Agent session already has an active run");
@@ -301,7 +390,17 @@ class RuntimeAgentSession {
                 redacted: Boolean(this.activeRedactor),
                 ...this.activeOwnership,
             };
-            this.ledgerPromises.push(this.activeLedger.appendEvent(redactRunLedgerRecord(record, this.activeRedactor)));
+            const ledger = this.activeLedger;
+            this.ledgerChain = this.ledgerChain.then(async () => {
+                if (this.ledgerFailure)
+                    return;
+                try {
+                    await ledger.appendEvent(redactRunLedgerRecord(record, this.activeRedactor));
+                }
+                catch (error) {
+                    this.ledgerFailure = error;
+                }
+            });
         }
     }
     closeSubscribers() {
@@ -310,19 +409,20 @@ class RuntimeAgentSession {
         this.subscribers.clear();
     }
     async drainLedger() {
-        if (this.ledgerPromises.length === 0)
-            return;
-        const pending = this.ledgerPromises;
-        this.ledgerPromises = [];
-        await Promise.all(pending);
-    }
-    async generateWithRetry(request, runId, options, signal, requestSecrets = []) {
+        await this.ledgerChain;
+        const failure = this.ledgerFailure;
+        this.ledgerChain = Promise.resolve();
+        this.ledgerFailure = undefined;
+        if (failure)
+            throw failure;
+    }
+    async generateWithRetry(request, runId, options, signal, requestSecrets = [], turn = 1, recordUsage) {
         const retry = mergeRetry(this.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 this.generateProviderTurn(request, runId, signal, secrets);
+                return await this.generateProviderTurn(request, runId, signal, secrets, turn, attempt, recordUsage);
             }
             catch (error) {
                 const failure = error instanceof ProviderTurnFailure ? error : undefined;
@@ -341,32 +441,37 @@ class RuntimeAgentSession {
             }
         }
     }
-    async generateProviderTurn(request, runId, signal, secrets = []) {
+    async generateProviderTurn(request, runId, signal, secrets = [], turn = 1, attempt = 1, recordUsage) {
+        const startedAt = performance.now();
+        const providerId = this.activeProvider?.id ?? request.model.provider;
+        const buildMetadata = (extra = {}) => createProviderTurnMetadata(request, providerId, { attempt, ...extra });
+        this.emit({
+            type: "provider_turn_started",
+            sessionId: this.id,
+            runId,
+            turn,
+            metadata: buildMetadata(),
+        });
         const content = [];
         const calls = [];
         const toolDeltas = [];
         let messageId;
         let started = false;
         let usage;
+        let usageRecorded = false;
+        const recordTurnUsage = async () => {
+            if (!usage || usageRecorded)
+                return;
+            usageRecorded = true;
+            await recordUsage?.(usage, turn, attempt);
+        };
         try {
             for await (const event of this.activeProvider.generate(request)) {
                 throwIfAborted(signal);
                 if (event.type === "error")
                     throw new ProviderTurnFailure(event.error, started);
-                if (event.type === "usage") {
+                if (event.type === "usage")
                     usage = event.usage;
-                    if (this.activeLedger) {
-                        const usageRecord = {
-                            id: randomId("usage"),
-                            sessionId: this.id,
-                            runId,
-                            usage: event.usage,
-                            recordedAt: new Date().toISOString(),
-                            ...this.activeOwnership,
-                        };
-                        await this.activeLedger.appendUsage(redactRunLedgerRecord(usageRecord, this.activeRedactor));
-                    }
-                }
                 if (event.type === "done") {
                     usage = event.usage ?? usage;
                     break;
@@ -399,12 +504,34 @@ class RuntimeAgentSession {
                 calls.push(call);
                 this.emit({ type: "message_delta", sessionId: this.id, runId, content: call });
             }
+            await recordTurnUsage();
+            const latencyMs = Math.round(performance.now() - startedAt);
+            this.emit({
+                type: "provider_turn_finished",
+                sessionId: this.id,
+                runId,
+                turn,
+                metadata: buildMetadata({ latencyMs }),
+                usage,
+            });
             return { content, calls, messageId, started, usage };
         }
         catch (error) {
+            const latencyMs = Math.round(performance.now() - startedAt);
+            const info = error instanceof ProviderTurnFailure ? redactSecrets(error.info, secrets) : errorToErrorInfo(error, secrets);
+            await recordTurnUsage();
+            this.emit({
+                type: "provider_turn_finished",
+                sessionId: this.id,
+                runId,
+                turn,
+                metadata: buildMetadata({ latencyMs, httpStatus: readProviderHttpStatus(info) }),
+                usage,
+                error: info,
+            });
             if (error instanceof ProviderTurnFailure)
                 throw error;
-            throw new ProviderTurnFailure(errorToErrorInfo(error, secrets), started);
+            throw new ProviderTurnFailure(info, started);
         }
     }
     async applyProviderRequestPolicies(request, runId, options, metadata, signal) {
@@ -555,6 +682,19 @@ function inputToMessages(input) {
         return [input];
     return [...input];
 }
+function finalAssistantMessage(history) {
+    for (let index = history.length - 1; index >= 0; index -= 1) {
+        const message = history[index];
+        if (message.role !== "assistant")
+            continue;
+        const text = message.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("");
+        return { message, content: message.content, text };
+    }
+    return { content: [], text: "" };
+}
 function activeTools(tools) {
     if (!tools)
         return { registry: createToolRegistry(), tools: [] };
@@ -620,6 +760,46 @@ function throwIfAbortedSignal(signal) {
     if (signal?.aborted)
         throw signal.reason instanceof Error ? signal.reason : new Error("Agent run aborted");
 }
+function createUsageAccumulator() {
+    const sums = new Map();
+    let costCurrency;
+    let costCompatible = true;
+    return {
+        add(usage) {
+            for (const key of ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens"]) {
+                const value = usage[key];
+                if (value !== undefined)
+                    sums.set(key, (sums.get(key) ?? 0) + value);
+            }
+            const total = usage.totalTokens
+                ?? (usage.inputTokens !== undefined || usage.outputTokens !== undefined
+                    ? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0)
+                    : undefined);
+            if (total !== undefined)
+                sums.set("totalTokens", (sums.get("totalTokens") ?? 0) + total);
+            if (usage.cost !== undefined && costCompatible) {
+                if (!sums.has("cost"))
+                    costCurrency = usage.currency;
+                else if (usage.currency !== costCurrency)
+                    costCompatible = false;
+                if (costCompatible)
+                    sums.set("cost", (sums.get("cost") ?? 0) + usage.cost);
+            }
+        },
+        value() {
+            if (sums.size === 0)
+                return undefined;
+            const usage = {};
+            for (const [key, value] of sums) {
+                if (key !== "cost" || costCompatible)
+                    usage[key] = value;
+            }
+            if (costCompatible && sums.has("cost") && costCurrency !== undefined)
+                usage.currency = costCurrency;
+            return Object.keys(usage).length > 0 ? usage : undefined;
+        },
+    };
+}
 function randomId(prefix) {
     return `${prefix}_${globalThis.crypto?.randomUUID?.() ?? Math.random().toString(36).slice(2)}`;
 }

package/dist/checkpoints.d.ts

@@ -0,0 +1,11 @@
+import type { CheckpointStore } from "./contracts.js";
+export declare const CHECKPOINT_CONFLICT_CODE = "ERR_PRISM_CHECKPOINT_CONFLICT";
+export declare class CheckpointConflictError extends Error {
+    readonly code = "ERR_PRISM_CHECKPOINT_CONFLICT";
+    constructor(message: string);
+}
+export interface MemoryCheckpointStoreOptions {
+    readonly maxPageSize?: number;
+}
+/** In-process reference implementation of the generic checkpoint contract. */
+export declare function createMemoryCheckpointStore(options?: MemoryCheckpointStoreOptions): CheckpointStore;

package/dist/checkpoints.js

@@ -0,0 +1,144 @@
+export const CHECKPOINT_CONFLICT_CODE = "ERR_PRISM_CHECKPOINT_CONFLICT";
+export class CheckpointConflictError extends Error {
+    code = CHECKPOINT_CONFLICT_CODE;
+    constructor(message) {
+        super(message);
+        this.name = "CheckpointConflictError";
+    }
+}
+/** In-process reference implementation of the generic checkpoint contract. */
+export function createMemoryCheckpointStore(options = {}) {
+    const records = new Map();
+    const maxPageSize = Math.max(1, options.maxPageSize ?? 500);
+    return {
+        async saveCheckpoint(input) {
+            throwIfAborted(input.signal);
+            assertKey(input);
+            if (!Number.isSafeInteger(input.version) || input.version < 1) {
+                throw new CheckpointConflictError("Checkpoint version must be a positive safe integer");
+            }
+            const id = recordKey(input);
+            const existing = records.get(id);
+            if (existing)
+                assertOwnership(input, existing);
+            if (input.expectedVersion !== undefined && input.expectedVersion !== (existing?.version ?? 0)) {
+                throw new CheckpointConflictError(`Checkpoint compare-and-swap failed (expected ${input.expectedVersion}, current ${existing?.version ?? 0})`);
+            }
+            if (existing && input.version <= existing.version) {
+                throw new CheckpointConflictError(`Stale checkpoint version ${input.version} (current ${existing.version})`);
+            }
+            if (existing?.fencingToken !== undefined && (input.fencingToken === undefined || input.fencingToken < existing.fencingToken)) {
+                throw new CheckpointConflictError(`Stale checkpoint fencing token ${input.fencingToken ?? "missing"} (current ${existing.fencingToken})`);
+            }
+            const now = new Date().toISOString();
+            const value = cloneJson(input.value, "Checkpoint value");
+            const metadata = input.metadata === undefined ? undefined : cloneJson(input.metadata, "Checkpoint metadata");
+            const record = {
+                namespace: input.namespace,
+                key: input.key,
+                version: input.version,
+                ...(input.fencingToken === undefined ? {} : { fencingToken: input.fencingToken }),
+                value,
+                ...(input.category === undefined ? {} : { category: input.category }),
+                ...ownership(input),
+                createdAt: existing?.createdAt ?? now,
+                updatedAt: now,
+                ...(metadata === undefined ? {} : { metadata }),
+            };
+            records.set(id, record);
+            return record;
+        },
+        async loadCheckpoint(input) {
+            throwIfAborted(input.signal);
+            assertKey(input);
+            const record = records.get(recordKey(input));
+            if (!record)
+                return null;
+            assertOwnership(input, record);
+            return record;
+        },
+        async listCheckpoints(query = {}) {
+            throwIfAborted(query.signal);
+            const offset = decodeCursor(query.cursor);
+            const limit = Math.min(Math.max(1, query.limit ?? 100), maxPageSize);
+            const categories = query.category === undefined
+                ? undefined
+                : new Set(Array.isArray(query.category) ? query.category : [query.category]);
+            const items = [...records.values()]
+                .filter((record) => query.namespace === undefined || record.namespace === query.namespace)
+                .filter((record) => query.keyPrefix === undefined || record.key.startsWith(query.keyPrefix))
+                .filter((record) => categories === undefined || (record.category !== undefined && categories.has(record.category)))
+                .filter((record) => ownershipFilterMatches(query, record))
+                .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || a.key.localeCompare(b.key));
+            const page = items.slice(offset, offset + limit);
+            const next = offset + page.length;
+            return {
+                items: page,
+                ...(next < items.length ? { nextCursor: String(next) } : {}),
+            };
+        },
+        async deleteCheckpoint(input) {
+            throwIfAborted(input.signal);
+            assertKey(input);
+            const id = recordKey(input);
+            const record = records.get(id);
+            if (!record)
+                return false;
+            assertOwnership(input, record);
+            return records.delete(id);
+        },
+    };
+}
+function recordKey(input) {
+    return `${input.namespace}\0${input.key}`;
+}
+function assertKey(input) {
+    if (!input.namespace || !input.key)
+        throw new CheckpointConflictError("Checkpoint namespace and key are required");
+}
+function ownership(input) {
+    return {
+        ...(input.tenantId === undefined ? {} : { tenantId: input.tenantId }),
+        ...(input.accountId === undefined ? {} : { accountId: input.accountId }),
+        ...(input.userId === undefined ? {} : { userId: input.userId }),
+    };
+}
+function ownershipMatches(expected, actual) {
+    return expected.tenantId === actual.tenantId
+        && expected.accountId === actual.accountId
+        && expected.userId === actual.userId;
+}
+function ownershipFilterMatches(expected, actual) {
+    return (expected.tenantId === undefined || expected.tenantId === actual.tenantId)
+        && (expected.accountId === undefined || expected.accountId === actual.accountId)
+        && (expected.userId === undefined || expected.userId === actual.userId);
+}
+function assertOwnership(expected, actual) {
+    if (!ownershipMatches(expected, actual)) {
+        throw new CheckpointConflictError("Checkpoint ownership mismatch");
+    }
+}
+function cloneJson(value, label) {
+    try {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined)
+            throw new Error("not JSON serializable");
+        return JSON.parse(encoded);
+    }
+    catch (error) {
+        throw new CheckpointConflictError(`${label} must be JSON serializable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function decodeCursor(cursor) {
+    if (cursor === undefined)
+        return 0;
+    const value = Number(cursor);
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new CheckpointConflictError("Invalid checkpoint cursor");
+    return value;
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw signal.reason ?? new DOMException("Aborted", "AbortError");
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/cli-init.d.ts

@@ -0,0 +1,41 @@
+import type { Writable } from "node:stream";
+export declare class InitUsageError extends Error {
+}
+export type InitProvider = string;
+export interface InitOptions {
+    readonly directory: string;
+    readonly provider: InitProvider;
+    readonly withWorkflows: boolean;
+    readonly withEvals: boolean;
+    readonly force: boolean;
+    readonly help: boolean;
+}
+export interface InitRuntime {
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+    /** Override template root (tests). Defaults to package `templates/init`. */
+    readonly templatesRoot?: string;
+    /** Override package version stamped into generated package.json. */
+    readonly packageVersion?: string;
+    /** Working directory used to resolve relative destinations. Defaults to process.cwd(). */
+    readonly cwd?: string;
+}
+export interface InitResult {
+    readonly targetDir: string;
+    readonly writtenFiles: readonly string[];
+    readonly provider: InitProvider;
+    readonly withWorkflows: boolean;
+    readonly withEvals: boolean;
+    readonly totalBytes: number;
+}
+/** Provider ids supported by `prism init --provider`. Loaded from templates data. */
+export declare function listInitProviders(templatesRoot?: string): readonly string[];
+/** @deprecated Prefer listInitProviders(); retained for tests that import the name. */
+export declare const INIT_PROVIDERS: readonly string[];
+export declare function getInitUsage(templatesRoot?: string): string;
+export declare const initUsage: string;
+export declare function parseInitArgs(argv: readonly string[], templatesRoot?: string): InitOptions;
+export declare function runInitCommand(argv: readonly string[], runtime: InitRuntime): Promise<number>;
+export declare function createInitProject(options: InitOptions, runtime?: InitRuntime): Promise<InitResult>;
+export declare function defaultTemplatesRoot(): string;
+export declare function isInitProvider(value: string, templatesRoot?: string): value is InitProvider;