@arnilo/prism-server 0.0.13 → 0.0.15

package/dist/conversations.d.ts

@@ -0,0 +1,149 @@
+import { type AgentEventRecord, type AgentIdentity, type AgentRunResult, type AgentSession, type JsonObject, type Message, type OwnershipScope, type PersistencePage, type RunOptions, type SecretRedactor, type SessionRecord } from "@arnilo/prism";
+import type { PersistenceLifecycleStore } from "@arnilo/prism";
+import type { PrismRequestHandler, PrismServerAuthorization } from "./types.js";
+/** Phase 9 freeze: thread page 50/200; replay page 100/500; cursor 4/16 KiB; title 256 B/2 KiB;
+ *  request id 256 B/2 KiB; active branches 16/64; export 8/32 MiB and 100/500 pages; body 64 KiB/1 MiB. */
+export declare const DEFAULT_CONVERSATION_THREAD_PAGE_LIMIT = 50;
+export declare const HARD_CONVERSATION_THREAD_PAGE_LIMIT = 200;
+export declare const DEFAULT_CONVERSATION_REPLAY_PAGE_LIMIT = 100;
+export declare const HARD_CONVERSATION_REPLAY_PAGE_LIMIT = 500;
+export declare const DEFAULT_CONVERSATION_CURSOR_BYTES: number;
+export declare const HARD_CONVERSATION_CURSOR_BYTES: number;
+export declare const DEFAULT_CONVERSATION_TITLE_BYTES = 256;
+export declare const HARD_CONVERSATION_TITLE_BYTES: number;
+export declare const DEFAULT_CONVERSATION_REQUEST_ID_BYTES = 256;
+export declare const HARD_CONVERSATION_REQUEST_ID_BYTES: number;
+export declare const DEFAULT_CONVERSATION_MAX_ACTIVE_BRANCHES = 16;
+export declare const HARD_CONVERSATION_MAX_ACTIVE_BRANCHES = 64;
+export declare const DEFAULT_CONVERSATION_EXPORT_BYTES: number;
+export declare const HARD_CONVERSATION_EXPORT_BYTES: number;
+export declare const DEFAULT_CONVERSATION_EXPORT_PAGES = 100;
+export declare const HARD_CONVERSATION_EXPORT_PAGES = 500;
+export declare const DEFAULT_CONVERSATION_REQUEST_BYTES: number;
+export declare const HARD_CONVERSATION_REQUEST_BYTES: number;
+export interface ConversationLimits {
+    readonly threadPageLimit?: number;
+    readonly replayPageLimit?: number;
+    readonly cursorBytes?: number;
+    readonly titleBytes?: number;
+    readonly requestIdBytes?: number;
+    readonly maxActiveBranches?: number;
+    readonly exportBytes?: number;
+    readonly exportPages?: number;
+    readonly maxRequestBytes?: number;
+}
+export interface ResolvedConversationLimits {
+    readonly threadPageLimit: number;
+    readonly replayPageLimit: number;
+    readonly cursorBytes: number;
+    readonly titleBytes: number;
+    readonly requestIdBytes: number;
+    readonly maxActiveBranches: number;
+    readonly exportBytes: number;
+    readonly exportPages: number;
+    readonly maxRequestBytes: number;
+}
+export declare function resolveConversationLimits(input?: ConversationLimits): ResolvedConversationLimits;
+/** Narrow persistence seam. sqlite/postgres adapters implement it; stores without
+ *  `appendSession` cannot host conversations (fail-closed at factory time). */
+export interface ConversationServiceStore {
+    querySessions(query: import("@arnilo/prism").SessionQuery): Promise<PersistencePage<SessionRecord>>;
+    queryEvents(query: import("@arnilo/prism").AgentEventQuery): Promise<PersistencePage<AgentEventRecord>>;
+    /** Required at factory time; optional in the type so persistence unions stay assignable. */
+    appendSession?(record: SessionRecord): Promise<void>;
+    readonly lifecycle?: Pick<PersistenceLifecycleStore, "applyRetention">;
+}
+export interface ConversationSessionFactoryInput {
+    readonly thread: import("@arnilo/prism").ConversationThread;
+    readonly ownership: OwnershipScope;
+    /** Recorded branch leaf to continue from; undefined continues the session's current tip. */
+    readonly leafId?: string;
+    readonly signal?: AbortSignal;
+}
+export interface CreateConversationServiceOptions {
+    /** Binds an agent session to the thread (host owns agent, store, and leaf checkout). */
+    readonly sessionFactory: (input: ConversationSessionFactoryInput) => AgentSession | Promise<AgentSession>;
+    /** Required: replay/export only serve redacted ledger rows, and `continue` runs with this redactor. */
+    readonly redactor: SecretRedactor;
+    readonly runOptions?: Omit<RunOptions, "ownership" | "identity" | "signal" | "redactor" | "idempotencyKey">;
+    readonly limits?: ConversationLimits;
+}
+export interface ConversationServiceInput {
+    readonly ownership: OwnershipScope;
+    readonly identity?: AgentIdentity;
+    readonly signal?: AbortSignal;
+}
+export interface ConversationCreateInput extends ConversationServiceInput {
+    /** Explicit thread id makes create idempotent (get-or-create). Generated when omitted. */
+    readonly id?: string;
+    readonly title?: string;
+    readonly requestId?: string;
+    readonly metadata?: JsonObject;
+}
+export interface ConversationListInput extends ConversationServiceInput {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface ConversationRefInput extends ConversationServiceInput {
+    readonly threadId: string;
+}
+export interface ConversationContinueInput extends ConversationRefInput {
+    readonly message: string | Message | readonly Message[];
+    /** Client request id; flows into session append idempotency so duplicate continues deduplicate. */
+    readonly requestId?: string;
+    /** Must be a branch ref recorded by `branch()`; undefined continues the current tip. */
+    readonly leafId?: string;
+}
+export interface ConversationBranchInput extends ConversationRefInput {
+    readonly leafId: string;
+}
+export interface ConversationExportInput extends ConversationRefInput {
+    readonly cursor?: string;
+}
+export interface ConversationReplayInput extends ConversationRefInput {
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface ConversationReplayPage {
+    readonly records: readonly AgentEventRecord[];
+    readonly nextCursor?: string;
+    readonly terminal: boolean;
+}
+export interface ConversationExportPage {
+    readonly thread: import("@arnilo/prism").ConversationThread;
+    readonly events: readonly AgentEventRecord[];
+    readonly nextCursor?: string;
+    readonly truncated: boolean;
+}
+export interface ConversationService {
+    create(input: ConversationCreateInput): Promise<import("@arnilo/prism").ConversationThread>;
+    list(input: ConversationListInput): Promise<PersistencePage<import("@arnilo/prism").ConversationThread>>;
+    get(input: ConversationRefInput): Promise<import("@arnilo/prism").ConversationThread>;
+    continue(input: ConversationContinueInput): Promise<AgentRunResult>;
+    branch(input: ConversationBranchInput): Promise<import("@arnilo/prism").ConversationThread>;
+    archive(input: ConversationRefInput): Promise<import("@arnilo/prism").ConversationThread>;
+    export(input: ConversationExportInput): Promise<ConversationExportPage>;
+    delete(input: ConversationRefInput): Promise<{
+        readonly deleted: boolean;
+        readonly held: boolean;
+    }>;
+    replay(input: ConversationReplayInput): Promise<ConversationReplayPage>;
+}
+export declare function createConversationService(store: ConversationServiceStore, options: CreateConversationServiceOptions): ConversationService;
+export type ConversationOperation = "conversation.create" | "conversation.list" | "conversation.get" | "conversation.continue" | "conversation.branch" | "conversation.archive" | "conversation.export" | "conversation.delete" | "conversation.replay";
+export interface ConversationAuthorizationInput {
+    readonly request: Request;
+    readonly operation: ConversationOperation;
+    readonly threadId?: string;
+    readonly signal: AbortSignal;
+}
+export type ConversationAuthorizer = (input: ConversationAuthorizationInput) => false | PrismServerAuthorization | Promise<false | PrismServerAuthorization>;
+export interface CreateConversationHandlerOptions {
+    readonly service: ConversationService;
+    readonly authorize: ConversationAuthorizer;
+    readonly basePath?: string;
+    readonly redactor?: SecretRedactor;
+    readonly limits?: ConversationLimits;
+}
+/** Framework-free HTTP adapter for one mounted conversation service (default base `/prism/conversations`). */
+export declare function createConversationHandler(options: CreateConversationHandlerOptions): PrismRequestHandler;