@vercel/factory 0.0.16 → 0.0.18

package/dist/store/driver.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"driver.mjs","names":[],"sources":["../../src/store/driver.ts"],"sourcesContent":["/** Closed set of persistence collections understood by Factory store drivers. */\nexport type CollectionName =\n  | \"repositories\"\n  | \"signals\"\n  | \"tasks\"\n  | \"changes\"\n  | \"receipts\"\n  | \"budgets\"\n  | \"answers\"\n  | \"sessions\"\n  | \"externalSessions\"\n  | \"transcripts\"\n  | \"images\"\n  | \"questionRoutes\"\n  | \"taskCatalogs\"\n  | \"changeCatalogs\"\n  | \"sessionCatalogs\"\n  | \"externalSessionCatalogs\"\n  | \"taskRoutes\"\n  | \"outboxQueues\"\n  | \"outboxDeliveries\"\n  | \"communicationSettings\"\n  | \"taskGraphs\"\n  | \"taskMessages\"\n  | \"taskEffects\"\n  | \"taskInboxes\"\n  | \"taskMessageProcessing\"\n  | \"taskMessageDecisions\"\n  | \"taskMessageDiscards\"\n  | \"plannerActivations\"\n  | \"plannerCancellations\";\n\n/** Opaque persisted value paired with its compare-and-swap version. */\nexport interface StoredRecord {\n  readonly value: unknown;\n  readonly version: number;\n}\n\n/** Collection-listing entry containing its storage key and versioned record. */\nexport interface StoredEntry {\n  readonly id: string;\n  readonly record: StoredRecord;\n}\n\n/** Collection, storage key, and opaque value for one insert-only write. */\nexport interface InsertStoreRecordInput {\n  readonly collection: CollectionName;\n  readonly id: string;\n  readonly value: unknown;\n}\n\n/** Collection, storage key, opaque value, and compare-and-swap version for one update. */\nexport interface UpdateStoreRecordInput extends InsertStoreRecordInput {\n  readonly expectedVersion: number;\n}\n\n/** Error raised when an insert targets an already occupied storage key. */\nexport class RecordExistsError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" already exists in \"${collection}\"`);\n    this.name = \"RecordExistsError\";\n  }\n}\n\n/** Error raised when an operation requires a storage record that does not exist. */\nexport class RecordNotFoundError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" not found in \"${collection}\"`);\n    this.name = \"RecordNotFoundError\";\n  }\n}\n\n/** Error raised when atomic update loses its expected-version comparison. */\nexport class VersionConflictError extends Error {\n  constructor(collection: CollectionName, id: string, expectedVersion: number) {\n    super(`record \"${id}\" in \"${collection}\" changed since version ${expectedVersion} was read`);\n    this.name = \"VersionConflictError\";\n  }\n}\n\n/**\n * A transient infrastructure failure (network error, 5xx/429 response) that\n * a driver's own bounded, backed-off low-level retries could not resolve.\n * Distinct from VersionConflictError (a concurrent writer legitimately won)\n * and from validation or \"already exists\" errors (the request itself is\n * rejected): the same operation may still succeed if retried again later,\n * but every caller retrying on this error must keep its own bound so a real\n * outage surfaces as a failure instead of hanging a dispatch cycle.\n */\nexport class TransientStoreError extends Error {\n  constructor(collection: CollectionName, id: string, cause: unknown) {\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      `record \"${id}\" in \"${collection}\" failed after transient retries were exhausted: ${reason}`,\n      { cause: cause instanceof Error ? cause : undefined },\n    );\n    this.name = \"TransientStoreError\";\n  }\n}\n\n/**\n * Raw persistence contract. Drivers store opaque values and enforce nothing\n * about their content; every invariant lives in the engine above. `update`\n * must be an atomic compare-and-swap on `expectedVersion`. A driver may\n * throw TransientStoreError for a read or write that failed only because of\n * infrastructure trouble (network errors, 5xx/429 responses); it must not\n * use TransientStoreError for version conflicts or malformed input.\n */\nexport interface StoreDriver {\n  readonly name: string;\n  get(collection: CollectionName, id: string): Promise<StoredRecord | null>;\n  insert(input: InsertStoreRecordInput): Promise<void>;\n  update(input: UpdateStoreRecordInput): Promise<void>;\n  list(collection: CollectionName): Promise<readonly StoredEntry[]>;\n}\n"],"mappings":";;AAyDA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,uBAAuB,WAAW,EAAE;EACxD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,kBAAkB,WAAW,EAAE;EACnD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,uBAAb,cAA0C,MAAM;CAC9C,YAAY,YAA4B,IAAY,iBAAyB;EAC3E,MAAM,WAAW,GAAG,QAAQ,WAAW,0BAA0B,gBAAgB,UAAU;EAC3F,KAAK,OAAO;CACd;AACF;;;;;;;;;;AAWA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY,OAAgB;EAClE,MAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACpE,MACE,WAAW,GAAG,QAAQ,WAAW,mDAAmD,UACpF,EAAE,OAAO,iBAAiB,QAAQ,QAAQ,KAAA,EAAU,CACtD;EACA,KAAK,OAAO;CACd;AACF"}
+{"version":3,"file":"driver.mjs","names":[],"sources":["../../src/store/driver.ts"],"sourcesContent":["/** Closed set of persistence collections understood by Factory store drivers. */\nexport type CollectionName =\n  | \"approvalRecords\"\n  | \"applicationState\"\n  | \"applicationChunks\"\n  | \"conversations\"\n  | \"conversationQuestions\"\n  | \"conversationExecutions\"\n  | \"repositories\"\n  | \"signals\"\n  | \"tasks\"\n  | \"changes\"\n  | \"receipts\"\n  | \"budgets\"\n  | \"answers\"\n  | \"sessions\"\n  | \"externalSessions\"\n  | \"sessionContinuations\"\n  | \"sessionNotifications\"\n  | \"transcripts\"\n  | \"transcriptBlocks\"\n  | \"transcriptChunks\"\n  | \"images\"\n  | \"questionRoutes\"\n  | \"taskCatalogs\"\n  | \"changeCatalogs\"\n  | \"sessionCatalogs\"\n  | \"externalSessionCatalogs\"\n  | \"taskRoutes\"\n  | \"outboxQueues\"\n  | \"outboxDeliveries\"\n  | \"communicationSettings\"\n  | \"taskGraphs\"\n  | \"taskMessages\"\n  | \"taskEffects\"\n  | \"taskInboxes\"\n  | \"taskMessageProcessing\"\n  | \"taskMessageDecisions\"\n  | \"taskMessageDiscards\"\n  | \"plannerActivations\"\n  | \"plannerCancellations\";\n\n/** Opaque persisted value paired with its compare-and-swap version. */\nexport interface StoredRecord {\n  readonly value: unknown;\n  readonly version: number;\n}\n\n/** Collection-listing entry containing its storage key and versioned record. */\nexport interface StoredEntry {\n  readonly id: string;\n  readonly record: StoredRecord;\n}\n\n/** Collection, storage key, and opaque value for one insert-only write. */\nexport interface InsertStoreRecordInput {\n  readonly collection: CollectionName;\n  readonly id: string;\n  readonly value: unknown;\n}\n\n/** Collection, storage key, opaque value, and compare-and-swap version for one update. */\nexport interface UpdateStoreRecordInput extends InsertStoreRecordInput {\n  readonly expectedVersion: number;\n}\n\n/** Error raised when an insert targets an already occupied storage key. */\nexport class RecordExistsError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" already exists in \"${collection}\"`);\n    this.name = \"RecordExistsError\";\n  }\n}\n\n/** Error raised when an operation requires a storage record that does not exist. */\nexport class RecordNotFoundError extends Error {\n  constructor(collection: CollectionName, id: string) {\n    super(`record \"${id}\" not found in \"${collection}\"`);\n    this.name = \"RecordNotFoundError\";\n  }\n}\n\n/** Error raised when atomic update loses its expected-version comparison. */\nexport class VersionConflictError extends Error {\n  constructor(collection: CollectionName, id: string, expectedVersion: number) {\n    super(`record \"${id}\" in \"${collection}\" changed since version ${expectedVersion} was read`);\n    this.name = \"VersionConflictError\";\n  }\n}\n\n/**\n * A transient infrastructure failure (network error, 5xx/429 response) that\n * a driver's own bounded, backed-off low-level retries could not resolve.\n * Distinct from VersionConflictError (a concurrent writer legitimately won)\n * and from validation or \"already exists\" errors (the request itself is\n * rejected): the same operation may still succeed if retried again later,\n * but every caller retrying on this error must keep its own bound so a real\n * outage surfaces as a failure instead of hanging a dispatch cycle.\n */\nexport class TransientStoreError extends Error {\n  constructor(collection: CollectionName, id: string, cause: unknown) {\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      `record \"${id}\" in \"${collection}\" failed after transient retries were exhausted: ${reason}`,\n      { cause: cause instanceof Error ? cause : undefined },\n    );\n    this.name = \"TransientStoreError\";\n  }\n}\n\n/**\n * Raw persistence contract. Drivers store opaque values and enforce nothing\n * about their content; every invariant lives in the engine above. `update`\n * must be an atomic compare-and-swap on `expectedVersion`. A driver may\n * throw TransientStoreError for a read or write that failed only because of\n * infrastructure trouble (network errors, 5xx/429 responses); it must not\n * use TransientStoreError for version conflicts or malformed input.\n */\nexport interface StoreDriver {\n  readonly name: string;\n  get(collection: CollectionName, id: string): Promise<StoredRecord | null>;\n  insert(input: InsertStoreRecordInput): Promise<void>;\n  update(input: UpdateStoreRecordInput): Promise<void>;\n  list(collection: CollectionName): Promise<readonly StoredEntry[]>;\n}\n"],"mappings":";;AAmEA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,uBAAuB,WAAW,EAAE;EACxD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY;EAClD,MAAM,WAAW,GAAG,kBAAkB,WAAW,EAAE;EACnD,KAAK,OAAO;CACd;AACF;;AAGA,IAAa,uBAAb,cAA0C,MAAM;CAC9C,YAAY,YAA4B,IAAY,iBAAyB;EAC3E,MAAM,WAAW,GAAG,QAAQ,WAAW,0BAA0B,gBAAgB,UAAU;EAC3F,KAAK,OAAO;CACd;AACF;;;;;;;;;;AAWA,IAAa,sBAAb,cAAyC,MAAM;CAC7C,YAAY,YAA4B,IAAY,OAAgB;EAClE,MAAM,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;EACpE,MACE,WAAW,GAAG,QAAQ,WAAW,mDAAmD,UACpF,EAAE,OAAO,iBAAiB,QAAQ,QAAQ,KAAA,EAAU,CACtD;EACA,KAAK,OAAO;CACd;AACF"}

package/dist/store/engine.d.mts

@@ -1,25 +1,27 @@
-import { Signal, SignalOutcome, SignalSource, SignalTriage } from "../schema/signal.mjs";
 import { AnswerId, ChangeId, FactoryId, OutboxId, ReceiptId, RepositoryId, RepositoryIds, SignalId, TaskId } from "../schema/id.mjs";
-import { Repository } from "../schema/repository.mjs";
+import { FactoryRecordPage, FactoryRecordQuery } from "./query.mjs";
+import { StoreDriver } from "./driver.mjs";
+import "./indexed.mjs";
 import { ExecutionReference, Task, TaskOrigin, TaskQuestion, TaskState } from "../schema/task.mjs";
 import { WorkflowRegistry } from "../workflows.mjs";
 import { TaskMessageProtocols } from "../schema/task-message.mjs";
 import { WorkNotifications } from "./work-notifications.mjs";
 import { IsoDateTimeClock, ReplyTo } from "../schema/common.mjs";
-import { StoreDriver } from "./driver.mjs";
 import { TaskMessageAuthorize, TaskMessageStore } from "./task-messages.mjs";
 import { TaskGraphStore } from "./task-graphs.mjs";
 import { TaskEffectStore } from "./task-effects.mjs";
 import { TaskWorkStore } from "./task-work.mjs";
 import { ImageAttachment, ImageId, imageUploadSchema } from "../image-input.mjs";
 import { AnswerEvent } from "../schema/answer.mjs";
-import { AgentSession, AgentSessionId } from "../schema/session.mjs";
+import { AgentSession, AgentSessionId, SessionContinuation } from "../schema/session.mjs";
 import { CommunicationEvent } from "../schema/communication.mjs";
 import { Budget, BudgetMonth } from "../schema/budget.mjs";
 import { Change, ChangeInState, ChangeLevel, ChangeState } from "../schema/change.mjs";
 import { OutboxMessage } from "../schema/outbox.mjs";
-import { TranscriptSnapshot } from "../schema/transcript.mjs";
+import { TranscriptBlock, TranscriptPage, TranscriptPageQuery, TranscriptSnapshot } from "../schema/transcript.mjs";
 import { Cost, Receipt, ReceiptDelivery, ReceiptKind, ReceiptPhase, ReceiptState, StandardReceiptKind, StandardReceiptPhase, StandardReceiptState } from "../schema/receipt.mjs";
+import { Repository } from "../schema/repository.mjs";
+import { Signal, SignalOutcome, SignalSource, SignalTriage } from "../schema/signal.mjs";
 import { z } from "zod";
 //#region src/store/engine.d.ts
 declare const storedImageSchema: z.ZodObject<{
@@ -364,6 +366,14 @@ interface FactoryStores {
   /** Materialized transcript snapshots keyed by exact provider execution. */
   transcripts: {
     get(execution: ExecutionReference): Promise<TranscriptSnapshot | null>;
+    /** Current metadata without replaying or loading the transcript body. */
+    head(execution: ExecutionReference): Promise<(TranscriptSnapshot & {
+      blockCount: number;
+    }) | null>;
+    /** A bounded page, with large blocks represented by explicit content references. */
+    page(execution: ExecutionReference, query: TranscriptPageQuery): Promise<TranscriptPage | null>;
+    /** Full content of one authorized execution's block, requested explicitly. */
+    block(execution: ExecutionReference, blockId: string): Promise<TranscriptBlock | null>;
     /** Persist only forward progress; safe to repeat from response-boundary hooks. */
     put(execution: ExecutionReference, snapshot: TranscriptSnapshot): Promise<TranscriptSnapshot>;
   };
@@ -377,7 +387,7 @@ interface FactoryStores {
   sessions: {
     /** Looks up an admitted session without recomputing defaults on a repeated operation. */
     getByOperation(owner: string, operationId: string): Promise<AgentSession | null>;
-    create(input: Omit<AgentSession, "schemaVersion" | "id" | "createdAt" | "execution" | "taskId" | "notifications" | "attached" | "continuations" | "external"> & {
+    create(input: Omit<AgentSession, "schemaVersion" | "id" | "createdAt" | "execution" | "taskId" | "latestNotificationId" | "attached" | "latestContinuationId" | "external"> & {
       operationId: string;
     }): Promise<AgentSession>;
     attachTask(input: {
@@ -403,9 +413,11 @@ interface FactoryStores {
       attachments?: readonly ImageAttachment[];
     }): Promise<AgentSession>;
     get(id: AgentSessionId): Promise<AgentSession | null>;
-    list(): Promise<readonly AgentSession[]>;
-    /** Compact session snapshots from fixed shards for discovery; large cached continuation context is omitted. */
-    summaries(): Promise<readonly AgentSession[]>;
+    getContinuation(id: AgentSessionId, taskId: TaskId): Promise<SessionContinuation | null>;
+    getContinuationByOperation(id: AgentSessionId, operationId: string): Promise<SessionContinuation | null>;
+    listContinuations(id: AgentSessionId, query: FactoryRecordQuery): Promise<FactoryRecordPage<SessionContinuation>>;
+    listNotifications(id: AgentSessionId, query: FactoryRecordQuery): Promise<FactoryRecordPage<CommunicationEvent>>;
+    list(query: FactoryRecordQuery): Promise<FactoryRecordPage<AgentSession>>;
     bind(id: AgentSessionId, reference: AgentSessionBinding): Promise<AgentSession>;
     notify(event: CommunicationEvent): Promise<void>;
   };
@@ -418,7 +430,7 @@ interface FactoryStores {
     }): Promise<Repository>;
     put(repository: Repository): Promise<Repository>;
     get(id: RepositoryId): Promise<Repository | null>;
-    list(): Promise<readonly Repository[]>;
+    list(query: FactoryRecordQuery): Promise<FactoryRecordPage<Repository>>;
   };
   /** External intake records and their explicit triage lifecycle. */
   signals: {
@@ -432,7 +444,7 @@ interface FactoryStores {
     }): Promise<Signal>;
     updateTriage(id: SignalId, attempt: number, observation: Pick<SignalTriage, "state" | "failure" | "sessionId">): Promise<Signal>;
     decide(id: SignalId, input: DecideSignalInput): Promise<Signal>;
-    list(): Promise<readonly Signal[]>;
+    list(query: FactoryRecordQuery): Promise<FactoryRecordPage<Signal>>;
   };
   /** Canonical Task lifecycle operations. */
   tasks: {
@@ -557,9 +569,7 @@ interface FactoryStores {
       at?: string;
       attempt?: number;
     }): Promise<Task>;
-    /** Tasks addressed to one connector or operator conversation without a collection scan. */
-    forReplyTo(replyTo: ReplyTo): Promise<readonly Task[]>;
-    list(): Promise<readonly Task[]>;
+    list(query: FactoryRecordQuery): Promise<FactoryRecordPage<Task>>;
   };
   /** Canonical software Change admission and lifecycle operations. */
   changes: {
@@ -568,7 +578,7 @@ interface FactoryStores {
     /** Save evidence without inventing a lifecycle transition; reject a changed snapshot. */
     updateEvidence(id: ChangeId, input: UpdateChangeEvidenceInput): Promise<Change>;
     transition<To extends ChangeState>(id: ChangeId, to: To, ...args: ChangeTransitionArguments<NoInfer<To>>): Promise<ChangeInState<To>>;
-    list(): Promise<readonly Change[]>;
+    list(query: FactoryRecordQuery): Promise<FactoryRecordPage<Change>>;
   };
   /** Immutable audit evidence appended by engine and application policy. */
   receipts: {
@@ -578,7 +588,7 @@ interface FactoryStores {
       phase?: Phase;
     }): Promise<Receipt>;
     get(id: ReceiptId): Promise<Receipt | null>;
-    list(): Promise<readonly Receipt[]>;
+    list(query: FactoryRecordQuery): Promise<FactoryRecordPage<Receipt>>;
   };
   /** Monthly budget snapshots, limits, and once-only notification stamps. */
   budgets: {
@@ -617,6 +627,18 @@ interface CreateStoresOptions {
    * callback and never rolls back the canonical write.
    */
   workNotifications?: WorkNotifications;
+  /**
+   * Pure application predicate opting child Tasks into durable lifecycle communication.
+   * Defaults to excluding children. Root notifications and human questions keep their existing
+   * behavior; this predicate only selects among otherwise communicable lifecycle receipts.
+   *
+   * A child Task delegated directly from a `conversation`-route parent (an interactive chat's
+   * own handoff to a planner or specialist) is always treated as communicable regardless of this
+   * predicate: it is the user-requested delegation itself, not an internal worker child. This
+   * predicate still gates deeper descendants (e.g. a planner's own delegations to workers), so
+   * ordinary internal work stays quiet.
+   */
+  includeChildTaskCommunication?: (task: Task, state: ReceiptState) => boolean;
   /** ISO timestamp source used for engine-owned records. Defaults to the current wall clock. */
   now?: IsoDateTimeClock;
   /**