@arnilo/prism-server 0.0.13 → 0.0.14

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.0.14] - 2026-07-26
+
+### Added
+
+- Durable user-scoped conversation service (`createConversationService`/`createConversationHandler`) and durable artifact service with review/approval/authorized delivery links (`createArtifactService`/`createArtifactHandler`) (Plan 077 Tasks 1, 3).
+
 ## [0.0.13] - 2026-07-24
 
 ### Changed

package/README.md

@@ -26,6 +26,8 @@ const response = await handler(new Request("https://api.example.test/prism/agent
 
 Routes: direct/SSE agent run, explicitly selected durable agent status/resume through `agentRuns`, direct/SSE workflow run, durable workflow enqueue/status/cancel/resume/replay, and optional ownership-scoped schedule create/list/pause/resume/trigger/delete. `agentRuns` uses core `createAgentRunLifecycle()`; no lifecycle route exists by default. All bodies, responses, events, queues, concurrency, and timeouts are bounded.
 
+Optional 0.0.14 co-work handlers (mount beside the API handler): `createConversationHandler` (durable user-scoped conversation threads with reconnectable redacted replay — `createConversationService`) and `createArtifactHandler` (artifact revisions, approve/reject review, expiring authorized delivery links — `createArtifactService` over the existing checkpoint store). Both are ownership-scoped and fail closed without authorization.
+
 Optional deployment helpers (compose beside the API handler — no embedded listener):
 
 ```ts

package/dist/artifacts.d.ts

@@ -0,0 +1,199 @@
+import { type AgentIdentity, type ArtifactCitation, type ArtifactDeliveryToken, type ArtifactRecord, type ArtifactRevision, type CheckpointStore, type OwnershipScope, type PersistencePage, type SecretRedactor } from "@arnilo/prism";
+import type { PrismRequestHandler, PrismServerAuthorization } from "./types.js";
+/** Phase 9 freeze: artifacts/thread 64/256; revisions 32/128; record 8/64 KiB; preview 16/64 KiB;
+ *  citations 32/128 and 2/8 KiB each; mime 128/512 B; hash 256/1 KiB; delivery TTL 5 min/24 h;
+ *  delivery token 4/16 KiB. Compare is exactly 2 revisions (hash+metadata only; host renders content). */
+export declare const DEFAULT_ARTIFACTS_PER_THREAD = 64;
+export declare const HARD_ARTIFACTS_PER_THREAD = 256;
+export declare const DEFAULT_ARTIFACT_REVISIONS = 32;
+export declare const HARD_ARTIFACT_REVISIONS = 128;
+export declare const DEFAULT_ARTIFACT_RECORD_BYTES: number;
+export declare const HARD_ARTIFACT_RECORD_BYTES: number;
+export declare const DEFAULT_ARTIFACT_PREVIEW_BYTES: number;
+export declare const HARD_ARTIFACT_PREVIEW_BYTES: number;
+export declare const DEFAULT_ARTIFACT_CITATIONS = 32;
+export declare const HARD_ARTIFACT_CITATIONS = 128;
+export declare const DEFAULT_ARTIFACT_CITATION_BYTES: number;
+export declare const HARD_ARTIFACT_CITATION_BYTES: number;
+export declare const DEFAULT_ARTIFACT_MIME_BYTES = 128;
+export declare const HARD_ARTIFACT_MIME_BYTES = 512;
+export declare const DEFAULT_ARTIFACT_HASH_BYTES = 256;
+export declare const HARD_ARTIFACT_HASH_BYTES = 1024;
+export declare const DEFAULT_ARTIFACT_URI_BYTES: number;
+export declare const HARD_ARTIFACT_URI_BYTES: number;
+export declare const DEFAULT_ARTIFACT_NOTE_BYTES = 1024;
+export declare const HARD_ARTIFACT_NOTE_BYTES: number;
+export declare const DEFAULT_ARTIFACT_TITLE_BYTES = 256;
+export declare const HARD_ARTIFACT_TITLE_BYTES: number;
+export declare const DEFAULT_ARTIFACT_LIST_PAGE_LIMIT = 50;
+export declare const HARD_ARTIFACT_LIST_PAGE_LIMIT = 200;
+export declare const DEFAULT_DELIVERY_LINK_TTL_SECONDS = 300;
+export declare const HARD_DELIVERY_LINK_TTL_SECONDS: number;
+export declare const DEFAULT_DELIVERY_LINK_TOKEN_BYTES: number;
+export declare const HARD_DELIVERY_LINK_TOKEN_BYTES: number;
+export declare const DEFAULT_ARTIFACT_REQUEST_BYTES: number;
+export declare const HARD_ARTIFACT_REQUEST_BYTES: number;
+export interface ArtifactLimits {
+    readonly artifactsPerThread?: number;
+    readonly revisionsPerArtifact?: number;
+    readonly recordBytes?: number;
+    readonly previewBytes?: number;
+    readonly citations?: number;
+    readonly citationBytes?: number;
+    readonly mimeBytes?: number;
+    readonly hashBytes?: number;
+    readonly uriBytes?: number;
+    readonly noteBytes?: number;
+    readonly titleBytes?: number;
+    readonly listPageLimit?: number;
+    readonly deliveryLinkTtlSeconds?: number;
+    readonly deliveryLinkTokenBytes?: number;
+    readonly maxRequestBytes?: number;
+}
+export interface ResolvedArtifactLimits {
+    readonly artifactsPerThread: number;
+    readonly revisionsPerArtifact: number;
+    readonly recordBytes: number;
+    readonly previewBytes: number;
+    readonly citations: number;
+    readonly citationBytes: number;
+    readonly mimeBytes: number;
+    readonly hashBytes: number;
+    readonly uriBytes: number;
+    readonly noteBytes: number;
+    readonly titleBytes: number;
+    readonly listPageLimit: number;
+    readonly deliveryLinkTtlSeconds: number;
+    readonly deliveryLinkTokenBytes: number;
+    readonly maxRequestBytes: number;
+}
+export declare function resolveArtifactLimits(input?: ArtifactLimits): ResolvedArtifactLimits;
+export interface ArtifactServiceInput {
+    readonly ownership: OwnershipScope;
+    readonly identity?: AgentIdentity;
+    readonly signal?: AbortSignal;
+}
+export interface ArtifactAttachInput extends ArtifactServiceInput {
+    readonly threadId: string;
+    readonly uri: string;
+    readonly mime: string;
+    readonly hash: string;
+    /** Explicit id makes attach idempotent (get-or-create). Generated when omitted. */
+    readonly id?: string;
+    readonly title?: string;
+    readonly changeNote?: string;
+    readonly producerRunId?: string;
+    readonly citations?: readonly ArtifactCitation[];
+    readonly preview?: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactListInput extends ArtifactServiceInput {
+    readonly threadId: string;
+    readonly cursor?: string;
+    readonly limit?: number;
+}
+export interface ArtifactRefInput extends ArtifactServiceInput {
+    readonly threadId: string;
+    readonly artifactId: string;
+}
+export interface ArtifactReviseInput extends ArtifactRefInput {
+    readonly uri: string;
+    /** Defaults to the previous revision's mime when omitted. */
+    readonly mime?: string;
+    readonly hash: string;
+    readonly changeNote?: string;
+    readonly producerRunId?: string;
+    readonly citations?: readonly ArtifactCitation[];
+    readonly preview?: Readonly<Record<string, unknown>>;
+}
+export interface ArtifactCompareInput extends ArtifactRefInput {
+    readonly from: number;
+    readonly to: number;
+}
+export interface ArtifactCompareResult {
+    readonly artifactId: string;
+    readonly from: ArtifactRevision;
+    readonly to: ArtifactRevision;
+    /** Hash+metadata-bounded change flags; the host renders content bodies. */
+    readonly changed: {
+        readonly hash: boolean;
+        readonly mime: boolean;
+        readonly uri: boolean;
+        readonly citations: boolean;
+    };
+}
+export interface ArtifactDecisionInput extends ArtifactRefInput {
+    readonly version: number;
+    readonly note?: string;
+    /** Redacted reviewer ref; derived from identity when omitted. */
+    readonly reviewer?: string;
+}
+export interface ArtifactDeliveryInput extends ArtifactRefInput {
+    /** Defaults to the last validated revision, else the latest. */
+    readonly version?: number;
+    readonly ttlSeconds?: number;
+}
+export interface ArtifactDeliveryResult {
+    readonly link: string;
+    readonly token: ArtifactDeliveryToken;
+}
+export type ArtifactDecisionEvent = {
+    readonly type: "artifact_attached" | "artifact_revised";
+    readonly artifactId: string;
+    readonly threadId: string;
+    readonly version: number;
+    readonly actor?: string;
+    readonly timestamp: string;
+} | {
+    readonly type: "artifact_approved" | "artifact_rejected";
+    readonly artifactId: string;
+    readonly threadId: string;
+    readonly version: number;
+    readonly reviewer: string;
+    readonly timestamp: string;
+};
+export interface CreateArtifactServiceOptions {
+    /** Required: records are redacted before persist and on every response. */
+    readonly redactor: SecretRedactor;
+    /** Host HMAC key material for signing/verifying delivery links. */
+    readonly linkSecret: string;
+    readonly limits?: ArtifactLimits;
+    /** Audit seam (redacted refs only); hosts bridge to @arnilo/prism-policy. */
+    readonly onDecision?: (event: ArtifactDecisionEvent) => void | Promise<void>;
+}
+export interface ArtifactService {
+    attach(input: ArtifactAttachInput): Promise<ArtifactRecord>;
+    list(input: ArtifactListInput): Promise<PersistencePage<ArtifactRecord>>;
+    get(input: ArtifactRefInput): Promise<ArtifactRecord>;
+    revise(input: ArtifactReviseInput): Promise<ArtifactRecord>;
+    compare(input: ArtifactCompareInput): Promise<ArtifactCompareResult>;
+    approve(input: ArtifactDecisionInput): Promise<ArtifactRecord>;
+    reject(input: ArtifactDecisionInput): Promise<ArtifactRecord>;
+    lastValidated(input: ArtifactRefInput): Promise<ArtifactRevision>;
+    deliveryLink(input: ArtifactDeliveryInput): Promise<ArtifactDeliveryResult>;
+}
+export declare function createArtifactService(store: CheckpointStore, options: CreateArtifactServiceOptions): ArtifactService;
+/** Sign an expiring delivery token: base64url(payload).base64url(HMAC-SHA256). */
+export declare function signArtifactDeliveryLink(token: ArtifactDeliveryToken, secret: string): string;
+/** Verify signature + expiry and parse a delivery link. Fail-closed on any tamper/expiry. */
+export declare function verifyArtifactDeliveryLink(link: string, secret: string, maxBytes?: number): ArtifactDeliveryToken;
+export type ArtifactOperation = "artifact.attach" | "artifact.list" | "artifact.get" | "artifact.revise" | "artifact.compare" | "artifact.approve" | "artifact.reject" | "artifact.last-validated" | "artifact.delivery-link" | "artifact.download";
+export interface ArtifactAuthorizationInput {
+    readonly request: Request;
+    readonly operation: ArtifactOperation;
+    readonly threadId?: string;
+    readonly artifactId?: string;
+    /** Present for download: the verified delivery token to reauthorize against. */
+    readonly deliveryToken?: ArtifactDeliveryToken;
+    readonly signal: AbortSignal;
+}
+export type ArtifactAuthorizer = (input: ArtifactAuthorizationInput) => false | PrismServerAuthorization | Promise<false | PrismServerAuthorization>;
+export interface CreateArtifactHandlerOptions {
+    readonly service: ArtifactService;
+    readonly authorize: ArtifactAuthorizer;
+    readonly linkSecret: string;
+    readonly basePath?: string;
+    readonly redactor?: SecretRedactor;
+    readonly limits?: ArtifactLimits;
+}
+/** Framework-free HTTP adapter for one mounted artifact service (default base `/prism/artifacts`). */
+export declare function createArtifactHandler(options: CreateArtifactHandlerOptions): PrismRequestHandler;