{"version":3,"file":"queue-adapter.cjs","names":[],"sources":["../../src/stream/queue-adapter.ts"],"sourcesContent":["import type { RunsClient } from \"../client/index.js\";\nimport type { StreamSubmitOptions } from \"./types.js\";\n\n/**\n * What {@link AgentServerQueueAdapter} needs to back `\"enqueue\"` with\n * real, durable server-side runs. Supplied from `client.runs` when\n * `queue: \"server\"` is set; see {@link SubmitCoordinator}.\n */\nexport type ServerQueueCapability = Pick<\n  RunsClient,\n  \"create\" | \"list\" | \"cancel\"\n>;\n\n/** A single queued submission. */\nexport interface SubmissionQueueEntry<\n  StateType extends object = Record<string, unknown>,\n> {\n  /** Stable id minted on enqueue (uuidv7) or the server run id for a hydrated entry. */\n  readonly id: string;\n  /** Server run id, once accepted. Absent while a dispatch is still in flight. */\n  readonly runId?: string;\n  /** Original submit input, narrowed to the partial state shape. */\n  readonly values: Partial<StateType> | null | undefined;\n  /** Original submit options, minus the strategy slot which is reset on drain. */\n  readonly options?: StreamSubmitOptions<StateType>;\n  /** Wall-clock timestamp at enqueue. */\n  readonly createdAt: Date;\n}\n\n/**\n * Read-only snapshot of the queue. The queue store hands this out\n * directly; consumers must not mutate the array.\n */\nexport type SubmissionQueueSnapshot<\n  StateType extends object = Record<string, unknown>,\n> = ReadonlyArray<SubmissionQueueEntry<StateType>>;\n\n/** Frozen empty queue, reused for referential stability across resets. */\nexport const EMPTY_QUEUE: SubmissionQueueSnapshot<never> = Object.freeze([]);\n\n/**\n * Pluggable backing for `useStream`'s \"enqueue\" multitask strategy. Owns\n * how a deferred submission is tracked while it waits its turn: where\n * it's recorded, how it's hydrated on load, how it learns a run started,\n * and how it's cancelled. {@link SubmitCoordinator} only delegates to\n * this for the `\"enqueue\"` case; see {@link LocalQueueAdapter}\n * (`queue-adapter-local.ts`) and {@link AgentServerQueueAdapter}\n * (`queue-adapter-agent-server.ts`) for the two implementations.\n *\n * Not exported from the package. Which implementation backs a given\n * call is decided by `useStream`'s `queue` option (`\"local\"` by\n * default), never a class a consumer picks between directly.\n */\nexport interface QueueAdapter<\n  StateType extends object = Record<string, unknown>,\n> {\n  /**\n   * Populate the queue store from whatever this adapter considers the\n   * source of truth: a real `runs.list` hydrate, or a no-op for the\n   * local adapter. Called once, when the controller first binds to a\n   * thread.\n   */\n  hydrate(threadId: string): Promise<void>;\n\n  /**\n   * Record a deferred submission. Resolves once it's safe to consider\n   * *accepted*: for the server-backed adapter, once the server has\n   * durably recorded it.\n   */\n  enqueue(\n    threadId: string,\n    values: Partial<StateType> | null | undefined,\n    options: StreamSubmitOptions<StateType> | undefined\n  ): Promise<void>;\n\n  /**\n   * Cancel one queued entry by its {@link SubmissionQueueEntry.id}.\n   * Idempotent: cancelling an entry that's already started running or\n   * was already removed resolves `false` rather than throwing.\n   */\n  cancel(id: string): Promise<boolean>;\n\n  /** Cancel and remove every currently-queued entry. */\n  clear(): Promise<void>;\n\n  /**\n   * Release whatever this adapter is watching. Called once, on\n   * controller disposal or thread rebind.\n   */\n  detach(): void;\n\n  /**\n   * Called whenever the active run settles (nothing currently in\n   * flight). Only meaningful for adapters that gate dispatch on\n   * client-side timing: {@link LocalQueueAdapter} uses this to drain\n   * its next entry via `dispatch`. {@link AgentServerQueueAdapter}\n   * omits it entirely: the server's own scheduler decides when the next\n   * pending run starts and the adapter only observes it.\n   */\n  onIdle?(\n    dispatch: (\n      values: unknown,\n      options: StreamSubmitOptions<StateType> | undefined\n    ) => Promise<void>\n  ): void;\n}\n"],"mappings":";;AAsCA,MAAa,cAA8C,OAAO,OAAO,EAAE,CAAC"}