@arnilo/prism 0.2.4 → 0.2.6

package/dist/contracts-core/loop.d.ts

@@ -0,0 +1,98 @@
+/** Contracts-core loop family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
+import type { AgentEvent, ProviderTurnResult, ToolResult } from "../contracts-protocol.js";
+import type { AgentInput } from "../input.js";
+import type { JsonValue, Message, ToolCallContent, Usage } from "./content.js";
+import type { ProviderRequest, StructuredOutputOptions } from "./provider.js";
+export interface LoopContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly metadata: Readonly<Record<string, unknown>>;
+    readonly signal: AbortSignal;
+    readonly history: Message[];
+    readonly input: AgentInput;
+    readonly inputMessages: readonly Message[];
+    readonly maxToolRounds: number;
+    /** Maximum independent tool calls dispatched concurrently per provider turn. Default `1`. */
+    readonly toolConcurrency: number;
+    assemble(nextInput: AgentInput, toolResults?: readonly ToolResult[], turn?: number): Promise<ProviderRequest>;
+    /**
+     * Charges a complete tool round before any call in it can start. On durable interrupt
+     * runs this is also the round-level approval gate: it collects every gated call of the
+     * round into one suspension. Loops must await it; dispatch without it falls back to
+     * per-call single-decision suspensions.
+     */
+    chargeToolRound?(calls: readonly ToolCallContent[]): void | Promise<void>;
+    generate(request: ProviderRequest): Promise<ProviderTurnResult>;
+    dispatchToolCall(call: ToolCallContent): Promise<ToolResult>;
+    isToolCallExclusive?(call: ToolCallContent): boolean;
+    appendMessage(message: Message): Promise<void>;
+    emit(event: AgentEvent): void;
+    /** True when mid-run steers are queued for the next provider turn. */
+    hasPendingSteers?(): boolean;
+    /** Drain pending steers into history/session. Returns true when any were applied. */
+    applyPendingSteers?(): Promise<boolean>;
+    /** Snapshot captured at the last suspension when the strategy declared snapshot/restore. Present only on resume. */
+    readonly restoredLoopState?: JsonValue;
+}
+export interface AgentLoopStrategy {
+    readonly name: string;
+    /** Host-authored loop revision. Joins the durable-run fingerprint when snapshot hooks are present. */
+    readonly revision?: string;
+    run(ctx: LoopContext): Promise<Usage | undefined>;
+    /**
+     * Capture loop-local resumable state at suspension. Must return a JSON-compatible value;
+     * core bounds and redacts it inside the durable run-state envelope. Declare together with
+     * `restore`; a custom strategy without both hooks is rejected before any provider call on
+     * durable runs (`AgentLoopStateError` / `ERR_PRISM_LOOP_NOT_DURABLE`).
+     */
+    snapshot?(): JsonValue;
+    /** Rehydrate from a previously captured snapshot; must throw on drift. Called before `run` on resume. */
+    restore?(snapshot: JsonValue): void;
+}
+export type AgentLoopOptions = {
+    readonly strategy: "single-shot";
+    /** Independent tool calls per turn run concurrently up to this limit. Default `1` (sequential). */
+    readonly toolConcurrency?: number;
+} | {
+    readonly strategy: "generate-validate-revise";
+    readonly validator: ArtifactValidator<unknown>;
+    readonly parser?: ArtifactParser<unknown>;
+    readonly repairer?: ArtifactRepairer<unknown>;
+    readonly maxRevisions?: number;
+    /** Dispatch provider tool calls in artifact turns. Default `"disabled"`; `"bounded"` uses RunOptions.maxToolRounds sequentially. */
+    readonly toolCalls?: "disabled" | "bounded";
+    /** Native provider JSON-schema output. Ignored when `structuredOutputMode` is `artifact-loop`. */
+    readonly structuredOutput?: StructuredOutputOptions;
+    /** `native` maps schema to capable providers; `artifact-loop` keeps repair turns only. */
+    readonly structuredOutputMode?: "native" | "artifact-loop";
+    /**
+     * When to attach native `structuredOutput` under `toolCalls: "bounded"`.
+     * `every-turn` (default): schema on every provider request (legacy).
+     * `final-turn-only`: tool-eligible turns omit schema; artifact/revision turns send schema and withdraw tools.
+     */
+    readonly structuredOutputTiming?: "every-turn" | "final-turn-only";
+};
+export interface ArtifactValidation {
+    readonly ok: boolean;
+    readonly errors?: readonly {
+        readonly path?: string;
+        readonly message: string;
+    }[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactContext {
+    readonly sessionId: string;
+    readonly runId: string;
+    readonly turn: number;
+    readonly signal: AbortSignal;
+    readonly metadata: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactParseResult<T> {
+    readonly ok: boolean;
+    readonly value?: T;
+    readonly error?: string;
+}
+export type ArtifactParser<T> = (text: string, ctx: ArtifactContext) => ArtifactParseResult<T> | Promise<ArtifactParseResult<T>>;
+export type ArtifactValidator<T> = (value: T, ctx: ArtifactContext) => ArtifactValidation | Promise<ArtifactValidation>;
+export type ArtifactRepairer<T> = (value: T | undefined, failure: ArtifactValidation, ctx: ArtifactContext) => AgentInput | Promise<AgentInput>;

package/dist/contracts-core/loop.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=loop.js.map

package/dist/contracts-core/persistence.d.ts

@@ -0,0 +1,366 @@
+/** Contracts-core persistence family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
+import type { AgentEventRecord, AgentEventSource, AgentEventType, RunRecord, RunStatus, ToolCallRecord, ToolCallStatus, UsageRecord, UsageScope } from "../contracts-protocol.js";
+import type { AgentDefinition } from "./agent.js";
+import type { JsonObject } from "./content.js";
+import type { SessionBranchRead, SessionEntry, SessionEntryKind, SessionStore } from "./session.js";
+export interface StoreFactory {
+    readonly name: string;
+    create(config?: JsonObject): Promise<SessionStore> | SessionStore;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Ownership scope identifiers. Hosts may use these for multi-tenant isolation. */
+export interface OwnershipScope {
+    readonly tenantId?: string;
+    readonly accountId?: string;
+    readonly userId?: string;
+}
+/** Cursor-paginated result page. */
+export interface PersistencePage<T> {
+    readonly items: readonly T[];
+    readonly nextCursor?: string;
+    readonly total?: number;
+}
+/** Common query controls for cursor-based pagination. */
+export interface PersistenceQuery {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly order?: "asc" | "desc";
+}
+/** Generic versioned checkpoint key. Namespaces prevent consumer collisions. */
+export interface CheckpointKey extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly signal?: AbortSignal;
+}
+/** Input for an optimistic checkpoint write. Versions must strictly increase. */
+export interface CheckpointSaveInput extends CheckpointKey {
+    readonly version: number;
+    /** Exact current version required before update; use 0 for create-only. */
+    readonly expectedVersion?: number;
+    /** Monotonic lease fence. Lower or absent worker fences cannot replace a fenced record. */
+    readonly fencingToken?: number;
+    readonly value: unknown;
+    readonly category?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Durable generic checkpoint record. */
+export interface CheckpointRecord extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly version: number;
+    readonly fencingToken?: number;
+    readonly value: unknown;
+    readonly category?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Bounded checkpoint query. */
+export interface CheckpointQuery extends PersistenceQuery, OwnershipScope {
+    readonly namespace?: string;
+    readonly keyPrefix?: string;
+    readonly category?: string | readonly string[];
+    readonly signal?: AbortSignal;
+}
+/** Generic versioned checkpoint capability for persistence adapters. */
+export interface CheckpointStore {
+    saveCheckpoint(input: CheckpointSaveInput): Promise<CheckpointRecord>;
+    loadCheckpoint(input: CheckpointKey): Promise<CheckpointRecord | null>;
+    listCheckpoints(query?: CheckpointQuery): Promise<PersistencePage<CheckpointRecord>>;
+    deleteCheckpoint(input: CheckpointKey): Promise<boolean>;
+}
+/** Generic lease key. Ownership fields are part of the trust boundary. */
+export interface LeaseKey extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly signal?: AbortSignal;
+}
+export interface LeaseAcquireInput extends LeaseKey {
+    readonly ownerId: string;
+    readonly ttlMs: number;
+}
+export interface LeaseClaimInput extends LeaseKey {
+    readonly ownerId: string;
+    readonly token: string;
+    readonly ttlMs?: number;
+}
+export interface LeaseRecord extends OwnershipScope {
+    readonly namespace: string;
+    readonly key: string;
+    readonly ownerId: string;
+    readonly token: string;
+    readonly fencingToken: number;
+    readonly acquiredAt: string;
+    readonly expiresAt: string;
+    readonly updatedAt: string;
+}
+/** Atomic distributed lease capability. Expired rows retain fencing counters. */
+export interface LeaseStore {
+    tryAcquireLease(input: LeaseAcquireInput): Promise<LeaseRecord | null>;
+    renewLease(input: LeaseClaimInput & {
+        readonly ttlMs: number;
+    }): Promise<LeaseRecord | null>;
+    releaseLease(input: LeaseClaimInput): Promise<boolean>;
+    getLease(input: LeaseKey): Promise<LeaseRecord | null>;
+}
+/** Stored session record. Does not include provider objects or credentials. */
+export interface SessionRecord extends OwnershipScope {
+    readonly id: string;
+    readonly parentSessionId?: string;
+    readonly agentDefinitionId?: string;
+    readonly agentDefinitionVersion?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly expiresAt?: string;
+    readonly retentionPolicyId?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /** Write version for optimistic metadata CAS; undefined on legacy/never-written rows. */
+    readonly version?: number;
+}
+/** Stored branch handle / leaf pointer. The leaf is the current entry id for the branch. */
+export interface BranchRecord {
+    readonly id: string;
+    readonly sessionId: string;
+    readonly name?: string;
+    readonly rootEntryId?: string;
+    readonly parentBranchId?: string;
+    /** Durable leaf entry id for this branch (the persistence-side branch tip). */
+    readonly leafEntryId?: string;
+    readonly createdAt: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface RunFeedbackRecord extends OwnershipScope {
+    readonly id: string;
+    readonly runId: string;
+    readonly sessionId: string;
+    readonly traceId?: string;
+    readonly rating?: number;
+    readonly comment?: string;
+    readonly tags: readonly string[];
+    readonly scorerIds: readonly string[];
+    readonly evaluationIds: readonly string[];
+    readonly createdAt: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface AppendRunFeedbackInput extends OwnershipScope {
+    readonly id: string;
+    readonly runId: string;
+    readonly sessionId?: string;
+    readonly traceId?: string;
+    readonly rating?: number;
+    readonly comment?: string;
+    readonly tags?: readonly string[];
+    readonly scorerIds?: readonly string[];
+    readonly evaluationIds?: readonly string[];
+    readonly createdAt?: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+/** Cursor-paginated, ownership-scoped feedback query. */
+export interface RunFeedbackQuery extends PersistenceQuery, OwnershipScope {
+    readonly runId?: string;
+    readonly sessionId?: string;
+    readonly traceId?: string;
+    readonly rating?: number;
+    readonly scorerId?: string;
+    readonly evaluationId?: string;
+    readonly tag?: string;
+    readonly fromCreatedAt?: string;
+    readonly toCreatedAt?: string;
+    readonly signal?: AbortSignal;
+}
+export interface DeleteRunFeedbackInput extends OwnershipScope {
+    readonly id: string;
+    readonly signal?: AbortSignal;
+}
+/** Feedback storage seam. Records are append-only; correction uses a new record and deletion is explicit. */
+export interface RunFeedbackStore {
+    append(input: AppendRunFeedbackInput): Promise<RunFeedbackRecord>;
+    query(query: RunFeedbackQuery): Promise<PersistencePage<RunFeedbackRecord>>;
+    delete(input: DeleteRunFeedbackInput): Promise<boolean>;
+}
+/** Stored agent definition version. Does not include provider credentials/resolvers/provider instances. */
+export interface AgentDefinitionRecord extends OwnershipScope {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly source?: string;
+    readonly agentDefinition: AgentDefinition;
+    readonly createdAt: string;
+    readonly createdBy?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Stored retention policy. */
+export interface RetentionPolicy extends OwnershipScope {
+    readonly id: string;
+    readonly name?: string;
+    readonly maxAgeDays?: number;
+    readonly maxEntriesPerSession?: number;
+    readonly maxTotalBytes?: number;
+    readonly archiveStore?: string;
+    readonly appliedKinds?: readonly SessionEntryKind[];
+    readonly createdAt: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Stored migration record. */
+export interface MigrationRecord {
+    readonly id: string;
+    readonly name: string;
+    readonly version: string;
+    readonly appliedAt: string;
+    readonly appliedBy?: string;
+    readonly checksum?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/** Query for sessions. */
+export interface SessionQuery extends PersistenceQuery, OwnershipScope {
+    readonly id?: string;
+    readonly parentSessionId?: string;
+    readonly agentDefinitionId?: string;
+    readonly agentDefinitionVersion?: string;
+    readonly retentionPolicyId?: string;
+    /** Match sessions whose `metadata` object contains this top-level key (e.g. conversation marker). */
+    readonly metadataKey?: string;
+    readonly fromCreatedAt?: string;
+    readonly toCreatedAt?: string;
+    readonly fromUpdatedAt?: string;
+    readonly toUpdatedAt?: string;
+    readonly hasExpired?: boolean;
+}
+/** Validate a top-level `SessionRecord.metadata` key used by `SessionQuery.metadataKey` filters. */
+export declare function assertSessionMetadataKey(key: string): string;
+/** Query for session entries. */
+export interface SessionEntryQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly parentId?: string;
+    /** Filter to entries on the branch ending at this leaf id. */
+    readonly leafId?: string;
+    readonly kind?: SessionEntryKind | readonly SessionEntryKind[];
+    readonly fromTimestamp?: string;
+    readonly toTimestamp?: string;
+}
+/** Query for branch handles/leaves. */
+export interface BranchQuery extends PersistenceQuery {
+    readonly sessionId?: string;
+    readonly name?: string;
+    readonly parentBranchId?: string;
+    readonly hasLeaf?: boolean;
+}
+/** Query for runs. */
+export interface RunQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly branchId?: string;
+    readonly agentDefinitionId?: string;
+    readonly agentDefinitionVersion?: string;
+    readonly status?: RunStatus | readonly RunStatus[];
+    readonly fromStartedAt?: string;
+    readonly toStartedAt?: string;
+    readonly fromFinishedAt?: string;
+    readonly toFinishedAt?: string;
+    readonly isFinished?: boolean;
+}
+/** Query for agent event ledger rows. */
+export interface AgentEventQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly type?: AgentEventType | readonly AgentEventType[];
+    readonly fromTimestamp?: string;
+    readonly toTimestamp?: string;
+    readonly redacted?: boolean;
+}
+/** Query for tool-call rows. */
+export interface ToolCallQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly name?: string;
+    readonly status?: ToolCallStatus | readonly ToolCallStatus[];
+    readonly fromStartedAt?: string;
+    readonly toStartedAt?: string;
+    readonly fromFinishedAt?: string;
+    readonly toFinishedAt?: string;
+    readonly redacted?: boolean;
+}
+/** Query for usage rows. */
+export interface UsageQuery extends PersistenceQuery, OwnershipScope {
+    readonly sessionId?: string;
+    readonly runId?: string;
+    readonly entryId?: string;
+    readonly scope?: UsageScope;
+    readonly turn?: number;
+    readonly attempt?: number;
+    readonly fromRecordedAt?: string;
+    readonly toRecordedAt?: string;
+}
+/** Query for agent definition versions. */
+export interface AgentDefinitionQuery extends PersistenceQuery, OwnershipScope {
+    readonly name?: string;
+    readonly version?: string;
+    readonly source?: string;
+    readonly fromCreatedAt?: string;
+    readonly toCreatedAt?: string;
+}
+/** Query for retention policies. */
+export interface RetentionPolicyQuery extends PersistenceQuery, OwnershipScope {
+    readonly name?: string;
+    readonly archiveStore?: string;
+}
+/** Query for migration records. */
+export interface MigrationQuery extends PersistenceQuery {
+    readonly name?: string;
+    readonly version?: string;
+    readonly fromAppliedAt?: string;
+    readonly toAppliedAt?: string;
+}
+/**
+ * Production database-neutral persistence store contract.
+ * Hosts implement this interface to provide durable, paginated storage
+ * for sessions, entries, runs, events, tool calls, usage, agent definitions,
+ * and migrations, with optional generic checkpoint and atomic lease capabilities. No SQL client, ORM, host file storage, or network dependency is
+ * required by the contract.
+ */
+export interface ProductionPersistenceStore {
+    readonly name?: string;
+    /** Optional generic write capability for resumable consumers such as workflows. */
+    readonly checkpoints?: CheckpointStore;
+    /** Optional atomic distributed lease capability for coordinators and workers. */
+    readonly leases?: LeaseStore;
+    /** Optional immutable run/trace feedback storage capability. */
+    readonly feedback?: RunFeedbackStore;
+    /** Optional durable, cross-replica-capable event source. */
+    readonly events?: AgentEventSource;
+    querySessions(query: SessionQuery): Promise<PersistencePage<SessionRecord>>;
+    queryBranches(query: BranchQuery): Promise<PersistencePage<BranchRecord>>;
+    queryEntries(query: SessionEntryQuery): Promise<PersistencePage<SessionEntry>>;
+    queryRuns(query: RunQuery): Promise<PersistencePage<RunRecord>>;
+    queryEvents(query: AgentEventQuery): Promise<PersistencePage<AgentEventRecord>>;
+    queryToolCalls(query: ToolCallQuery): Promise<PersistencePage<ToolCallRecord>>;
+    queryUsage(query: UsageQuery): Promise<PersistencePage<UsageRecord>>;
+    queryAgentDefinitions(query: AgentDefinitionQuery): Promise<PersistencePage<AgentDefinitionRecord>>;
+    queryRetentionPolicies(query: RetentionPolicyQuery): Promise<PersistencePage<RetentionPolicy>>;
+    queryMigrations(query: MigrationQuery): Promise<PersistencePage<MigrationRecord>>;
+    /** Optional session-record write capability (conversation threads, host-managed sessions).
+     *  Upserts by id; ownership columns are set on create, `metadata`/`updatedAt` on update.
+     *  Additive CAS: pass `expectedVersion` to require the stored version to match before the
+     *  write (0 = create-only, a positive number = exact current version); omit it for legacy
+     *  last-write-wins. Returns the new `version` when the underlying store supports it. */
+    appendSession?(record: SessionRecord & {
+        readonly expectedVersion?: number;
+    }): Promise<{
+        readonly version: number;
+    } | undefined>;
+    /** DB-friendly branch read (mirrors `SessionStore.readBranchPath`): one ancestor-chain
+     *  query instead of `queryEntries({ sessionId })` + in-memory walk. Optional. */
+    readBranchPath?(query: SessionBranchRead): Promise<PersistencePage<SessionEntry>>;
+    /**
+     * Optional Phase 8 retention / legal-hold / export / tenant-quota lifecycle.
+     * Prefer attaching `createMemoryPersistenceLifecycle()` or adapter-native methods.
+     */
+    readonly lifecycle?: import("../persistence-lifecycle.js").PersistenceLifecycleStore;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}

package/dist/contracts-core/persistence.js

@@ -0,0 +1,9 @@
+const SESSION_METADATA_KEY_PATTERN = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/;
+/** Validate a top-level `SessionRecord.metadata` key used by `SessionQuery.metadataKey` filters. */
+export function assertSessionMetadataKey(key) {
+    if (typeof key !== "string" || !SESSION_METADATA_KEY_PATTERN.test(key)) {
+        throw new RangeError("metadataKey must match /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$/");
+    }
+    return key;
+}
+//# sourceMappingURL=persistence.js.map

package/dist/contracts-core/provider.d.ts

@@ -0,0 +1,97 @@
+/** Contracts-core provider family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
+import type { ProviderEvent, RealtimeEvent, ToolDefinition } from "../contracts-protocol.js";
+import type { ContextBlock } from "./agent.js";
+import type { JsonObject, Message, ModelConfig } from "./content.js";
+export type CacheRetention = "none" | "short" | "long";
+export type PromptCacheKind = "implicit" | "openai_key" | "cache_control" | "provider_specific" | "none";
+export interface ModelCacheCapabilities {
+    readonly kind?: PromptCacheKind;
+    readonly maxKeyLength?: number;
+    readonly maxBreakpoints?: number;
+    readonly minCacheableTokens?: number;
+    readonly longRetention?: boolean;
+}
+export type PromptCacheMode = "auto" | "on" | "off";
+export type PromptCacheBreakpointLocation = "system_prompt" | "tools" | "stable_context" | "last_stable_message" | "last_user_message" | "message_id";
+export type PromptCacheBreakpointTtl = "short" | "long";
+export interface PromptCacheBreakpoint {
+    readonly location: PromptCacheBreakpointLocation;
+    readonly messageId?: string;
+    readonly ttl?: PromptCacheBreakpointTtl;
+}
+export interface PromptCacheHints {
+    readonly mode?: PromptCacheMode;
+    readonly key?: string;
+    readonly retention?: CacheRetention;
+    readonly breakpoints?: readonly PromptCacheBreakpoint[];
+}
+export interface StructuredOutputOptions {
+    readonly name: string;
+    readonly schema: JsonObject;
+    readonly strict?: boolean;
+}
+export interface ProviderRequestOptions {
+    readonly sessionId?: string;
+    readonly cacheRetention?: CacheRetention;
+    readonly cacheKey?: string;
+    readonly cache?: PromptCacheHints;
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly compat?: JsonObject;
+    readonly extra?: JsonObject;
+    /** Provider-neutral JSON-schema structured output request. Requires model `capabilities.structuredOutput`. */
+    readonly structuredOutput?: StructuredOutputOptions;
+    /** Opaque provider continuation cursor (e.g. OpenAI `previous_response_id`). When set,
+     *  the provider resumes from this cursor instead of re-sending full history. */
+    readonly continuation?: {
+        readonly cursor: string;
+    };
+}
+export interface ProviderRequest {
+    readonly model: ModelConfig;
+    readonly messages: readonly Message[];
+    readonly tools?: readonly ToolDefinition[];
+    readonly context?: readonly ContextBlock[];
+    readonly options?: ProviderRequestOptions;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly signal?: AbortSignal;
+}
+export interface AIProvider {
+    readonly id: string;
+    generate(request: ProviderRequest): AsyncIterable<ProviderEvent>;
+}
+export type ProviderResolver = (model: ModelConfig) => AIProvider | undefined;
+/** Realtime audio/session event. Realtime is a bidirectional session, not a request/response
+ *  stream, so it is a separate neutral seam from `AIProvider.generate()`. Credentials are
+ *  bound to the session handshake only and never appear in events. */
+export interface RealtimeSession {
+    readonly id: string;
+    readonly provider: string;
+    /** Send an audio chunk (PCM/Opus; provider-specific format set at creation). */
+    sendAudio(chunk: Uint8Array, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /** Inbound events (audio out, transcripts, hosted tool calls, interruption, close, error). */
+    events(): AsyncIterable<RealtimeEvent>;
+    /** Request the provider stop the current response mid-stream. */
+    interrupt(options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /** Close the session and release the transport. Idempotent. */
+    close(reason?: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+}
+/** Factory a provider exposes for realtime sessions; not part of `AIProvider`. */
+export type RealtimeSessionFactory = (options: RealtimeSessionOptions) => RealtimeSession;
+export interface RealtimeSessionOptions {
+    readonly model: ModelConfig;
+    readonly signal?: AbortSignal;
+    /** Provider-specific caps override; providers enforce finite defaults. */
+    readonly caps?: RealtimeCaps;
+}
+export interface RealtimeCaps {
+    readonly maxAudioEventsPerSecond?: number;
+    readonly maxBytesPerSecond?: number;
+    readonly maxWallMs?: number;
+}

package/dist/contracts-core/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/contracts-core/resources.d.ts

@@ -0,0 +1,44 @@
+/** Contracts-core resources family (0.2.5 plan 025 Task 1 split).
+ * Moved verbatim from contracts-core.ts; public surface unchanged behind the barrel. */
+import type { PermissionPolicy, TrustPolicy } from "../security.js";
+import type { OAuthCredentials } from "./extensions.js";
+export interface Resource {
+    readonly uri: string;
+    readonly mediaType?: string;
+    readonly text?: string;
+    readonly data?: Uint8Array;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ResourceLoader {
+    load(uri: string, context?: ResourceLoadContext): Promise<Resource>;
+    list?(context?: ResourceLoadContext): Promise<readonly Resource[]>;
+}
+export interface ResourceLoadContext {
+    readonly signal?: AbortSignal;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly permission?: PermissionPolicy;
+    readonly trust?: TrustPolicy;
+}
+export interface SettingsProvider {
+    get<T = unknown>(key: string): Promise<T | undefined> | T | undefined;
+}
+export interface CredentialRequest {
+    readonly name: string;
+    readonly provider?: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface Credential {
+    readonly type: "bearer" | "api_key" | "basic" | "custom";
+    readonly value: string;
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface CredentialResolver {
+    resolve(request: CredentialRequest): Promise<Credential | undefined> | Credential | undefined;
+}
+export interface CredentialResolverSource {
+    readonly name: string;
+    readonly resolver: CredentialResolver;
+}
+export interface OAuthCredentialStore {
+    set(provider: string, credentials: OAuthCredentials): void | Promise<void>;
+}

package/dist/contracts-core/resources.js

@@ -0,0 +1,7 @@
+export {};
+// ponytail: AgentLoopStrategy orchestrates shared runtime primitives via
+// LoopContext; it never re-implements provider calls, retry, abort, store, or
+// events. Single-shot is the default; loops are opt-in. T is host-defined,
+// Prism never instantiates it. No domain control-flow vocabulary (boundary
+// guard); artifact types are generic over host T.
+//# sourceMappingURL=resources.js.map