pantheon-opencode 1.5.0-beta.1 → 1.5.0-beta.3

package/src/pantheon/delegate-manager.ts

@@ -23,7 +23,14 @@
  * @module delegate-manager
  */
 
+import { z } from 'zod'
 import type { BackgroundJobBoard, BackgroundJobRecord } from './background-job-board.ts'
+import type { DelegationToolset } from './delegation.ts'
+import {
+  DELEGATION_DEFAULTS,
+  type DelegationClient,
+  readDelegationReport,
+} from './delegation-finalize.ts'
 import {
   buildStopInstruction,
   cappedSummary,
@@ -113,6 +120,13 @@ export function isDelegationEnabled(
   return (env.PANTHEON_DELEGATION ?? '').trim().toLowerCase() !== 'off'
 }
 
+export type DelegateMode = 'native' | 'legacy'
+export function resolveDelegateMode(
+  env: Record<string, string | undefined> = process.env,
+): DelegateMode {
+  return (env.PANTHEON_DELEGATE_MODE ?? '').trim().toLowerCase() === 'native' ? 'native' : 'legacy'
+}
+
 // ─── Helpers ───────────────────────────────────────────────────────────
 
 const LINE_MAX = 160
@@ -382,3 +396,274 @@ export function createDelegateManager(options: DelegateManagerOptions): Delegate
     },
   }
 }
+
+// Native delegation tools live with the manager so the plugin mounts the
+// manager directly; there is intentionally no adapter or kill-switch wrapper.
+const delegateArgs = {
+  prompt: z.string().min(1),
+  agent: z.string().min(1),
+  description: z.string().optional(),
+  read_only: z.boolean().optional(),
+  model: z.string().optional(),
+} satisfies z.ZodRawShape
+const readArgs = { id: z.string().min(1) } satisfies z.ZodRawShape
+const listArgs = {} satisfies z.ZodRawShape
+export interface ToolContextLike {
+  sessionID: string
+  agent?: string
+}
+export interface SessionTaskOptions {
+  client: DelegationClient
+  board: BackgroundJobBoard
+  outputDir?: string
+  promptTimeoutMs?: number
+  settleTimeoutMs?: number
+}
+export function parseModelRef(model: string): { id: string; providerID: string } | undefined {
+  const idx = model.indexOf('/')
+  return idx > 0 && idx < model.length - 1
+    ? { providerID: model.slice(0, idx), id: model.slice(idx + 1) }
+    : undefined
+}
+export function extractOutputSection(md: string | undefined): string {
+  if (md === undefined) return ''
+  const at = md.indexOf('## Output')
+  const body = at < 0 ? md : md.slice(at + 9)
+  const errAt = body.indexOf('\n**Error**:')
+  return (errAt < 0 ? body : body.slice(0, errAt)).trim()
+}
+async function promptAccept(
+  client: DelegationClient,
+  taskID: string,
+  agent: string,
+  prompt: string,
+  model: string | undefined,
+  signal: AbortSignal | undefined,
+  timeoutMs: number,
+): Promise<void> {
+  const modelRef = model === undefined ? undefined : parseModelRef(model)
+  let timer: ReturnType<typeof setTimeout> | undefined
+  try {
+    await Promise.race([
+      client.session
+        .promptAsync({
+          path: { id: taskID },
+          body: {
+            agent,
+            ...(modelRef === undefined ? {} : { model: modelRef }),
+            parts: [{ type: 'text', text: prompt }],
+          },
+          ...(signal === undefined ? {} : { signal }),
+        })
+        .then(undefined, (error: unknown) => {
+          throw new Error(
+            `promptAsync rejected: ${error instanceof Error ? error.message : String(error)}`,
+          )
+        }),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`promptAsync timed out after ${timeoutMs}ms`)),
+          timeoutMs,
+        )
+        timer.unref?.()
+      }),
+    ])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+export function createSessionTaskFn(options: SessionTaskOptions): NativeTaskFn {
+  const {
+    client,
+    board,
+    outputDir = DELEGATION_DEFAULTS.outputDir,
+    promptTimeoutMs = 60_000,
+    settleTimeoutMs = DELEGATION_DEFAULTS.timeoutMs,
+  } = options
+  return async ({ agent, prompt, model, signal, taskID }) => {
+    await promptAccept(client, taskID, agent, prompt, model, signal, promptTimeoutMs)
+    const terminal = await board.waitForTerminal(taskID, settleTimeoutMs)
+    const md = await readDelegationReport(outputDir, terminal)
+    return { content: extractOutputSection(md) || terminal.resultSummary || '' }
+  }
+}
+export interface NativeDelegateWiring {
+  board: BackgroundJobBoard
+  client: DelegationClient
+  outputDir?: string
+  env?: Record<string, string | undefined>
+  isRootSession: (sessionID: string) => boolean
+  registerChildSession?: (sessionID: string, parentID: string) => void
+  registerReadOnlySession?: (
+    sessionID: string,
+    info: { agent: string; readOnlyFlag?: boolean },
+  ) => void
+  isReadOnlyAgent?: (agent: string) => boolean
+  agentModel?: (agent: string) => string | undefined
+  managerOptions?: Partial<
+    Omit<DelegateManagerOptions, 'board' | 'task' | 'parentSessionID' | 'env'>
+  >
+  stepCap?: StepCapTracker
+}
+export interface NativeDelegateToolset {
+  pantheon_delegate: {
+    description: string
+    args: typeof delegateArgs
+    execute(args: z.infer<z.ZodObject<typeof delegateArgs>>, ctx: ToolContextLike): Promise<string>
+  }
+  pantheon_delegation_read: {
+    description: string
+    args: typeof readArgs
+    execute(args: z.infer<z.ZodObject<typeof readArgs>>, ctx: ToolContextLike): Promise<string>
+  }
+  pantheon_delegation_list: {
+    description: string
+    args: typeof listArgs
+    execute(args: z.infer<z.ZodObject<typeof listArgs>>, ctx: ToolContextLike): Promise<string>
+  }
+}
+function shortFirstLine(text: string, max = 60): string {
+  const line =
+    text
+      .split('\n')
+      .map((item) => item.trim())
+      .find(Boolean) ?? ''
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line
+}
+export function createNativeDelegateTools(wiring: NativeDelegateWiring): NativeDelegateToolset {
+  const {
+    board,
+    client,
+    env = process.env,
+    isRootSession,
+    registerChildSession,
+    registerReadOnlySession,
+    isReadOnlyAgent,
+    agentModel,
+    managerOptions = {},
+    stepCap,
+  } = wiring
+  const task = createSessionTaskFn({
+    client,
+    board,
+    ...(wiring.outputDir === undefined ? {} : { outputDir: wiring.outputDir }),
+    ...(managerOptions.timeoutMs === undefined
+      ? {}
+      : { promptTimeoutMs: managerOptions.timeoutMs }),
+  })
+  const managers = new Map<string, DelegateManager>()
+  const managerFor = (parentSessionID: string): DelegateManager => {
+    const existing = managers.get(parentSessionID)
+    if (existing !== undefined) return existing
+    const manager = createDelegateManager({
+      ...managerOptions,
+      board,
+      task,
+      parentSessionID,
+      env,
+      ...(stepCap === undefined ? {} : { stepCap }),
+    })
+    managers.set(parentSessionID, manager)
+    return manager
+  }
+  return {
+    pantheon_delegate: {
+      description: 'Dispatch a background agent as a child session and return a verified receipt.',
+      args: delegateArgs,
+      execute: async (args, ctx) => {
+        if (!isDelegationEnabled(env))
+          throw new Error('pantheon delegation disabled (PANTHEON_DELEGATION=off)')
+        if (!isRootSession(ctx.sessionID))
+          throw new Error(
+            `pantheon_delegate rejected: session ${ctx.sessionID} is a sub-session — only root sessions can delegate`,
+          )
+        const model = args.model ?? agentModel?.(args.agent)
+        let childID: string
+        try {
+          const modelRef = model === undefined ? undefined : parseModelRef(model)
+          const created = await client.session.create({
+            body: {
+              parentID: ctx.sessionID,
+              title: args.description ?? shortFirstLine(args.prompt),
+              ...(modelRef === undefined ? {} : { model: modelRef }),
+            },
+          })
+          childID = created.id
+        } catch (error) {
+          return `pantheon_delegate failed: session.create rejected: ${error instanceof Error ? error.message : String(error)}`
+        }
+        registerChildSession?.(childID, ctx.sessionID)
+        if (args.read_only === true || isReadOnlyAgent?.(args.agent) === true)
+          registerReadOnlySession?.(childID, {
+            agent: args.agent,
+            ...(args.read_only === undefined ? {} : { readOnlyFlag: args.read_only }),
+          })
+        const receipt = await managerFor(ctx.sessionID).launch({
+          agent: args.agent,
+          prompt: args.prompt,
+          ...(args.description === undefined ? {} : { description: args.description }),
+          ...(args.model === undefined ? {} : { model: args.model }),
+          taskID: childID,
+        })
+        return receipt.line
+      },
+    },
+    pantheon_delegation_read: {
+      description: 'Block until a delegation finishes, then return its verified report.',
+      args: readArgs,
+      execute: async (args, ctx) => {
+        if (!isDelegationEnabled(env))
+          throw new Error('pantheon delegation disabled (PANTHEON_DELEGATION=off)')
+        return managerFor(ctx.sessionID).read(args.id)
+      },
+    },
+    pantheon_delegation_list: {
+      description: 'List background delegations.',
+      args: listArgs,
+      execute: async (_args, ctx) => {
+        if (!isDelegationEnabled(env))
+          throw new Error('pantheon delegation disabled (PANTHEON_DELEGATION=off)')
+        const lines = await managerFor(ctx.sessionID).list()
+        return lines.length > 0 ? lines.join('\n') : 'No delegations.'
+      },
+    },
+  }
+}
+export interface PluginNativeDelegationWiring {
+  board: BackgroundJobBoard
+  client: DelegationClient
+  isRootSession: (sessionID: string) => boolean
+  registerChildSession: (sessionID: string, parentID: string) => void
+  registerReadOnlySession: (
+    sessionID: string,
+    info: { agent: string; readOnlyFlag?: boolean },
+  ) => void
+  readOnlyAgents: ReadonlySet<string>
+  agentModels: Record<string, string | undefined>
+  stepCap: StepCapTracker
+  wallClockTimeoutMs?: number
+  finalizeDelegation: DelegationToolset['finalizeDelegation']
+}
+export type PluginNativeDelegation = NativeDelegateToolset & {
+  finalizeDelegation: DelegationToolset['finalizeDelegation']
+}
+export function buildPluginNativeDelegation(
+  wiring: PluginNativeDelegationWiring,
+): PluginNativeDelegation {
+  return {
+    ...createNativeDelegateTools({
+      board: wiring.board,
+      client: wiring.client,
+      isRootSession: wiring.isRootSession,
+      registerChildSession: wiring.registerChildSession,
+      registerReadOnlySession: wiring.registerReadOnlySession,
+      isReadOnlyAgent: (agent) => wiring.readOnlyAgents.has(agent.toLowerCase()),
+      agentModel: (agent) => wiring.agentModels[agent.toLowerCase()],
+      stepCap: wiring.stepCap,
+      ...(wiring.wallClockTimeoutMs === undefined
+        ? {}
+        : { managerOptions: { timeoutMs: wiring.wallClockTimeoutMs } }),
+    }),
+    finalizeDelegation: wiring.finalizeDelegation,
+  }
+}

package/src/pantheon/provider-capabilities.ts

@@ -0,0 +1,221 @@
+/**
+ * Exact provider usage contract and the independent V1/V2 capability probes.
+ *
+ * This module deliberately does not inspect credentials, call a provider, read
+ * the TUI, calculate percentages, or derive token counts from text. A provider
+ * is supported only when it supplies the complete numeric contract below.
+ *
+ * @module provider-capabilities
+ */
+
+/** The only capability statuses exposed by the usage contract. */
+export const USAGE_STATUS = {
+  SUPPORTED: 'SUPPORTED',
+  UNSUPPORTED: 'UNSUPPORTED',
+} as const
+
+export type UsageStatus = (typeof USAGE_STATUS)[keyof typeof USAGE_STATUS]
+
+/** Exact token counters supplied by the provider. No totals are inferred. */
+export interface ExactProviderUsage {
+  inputTokens: number
+  outputTokens: number
+}
+
+/** Exact context limit supplied by the provider. */
+export interface ExactProviderLimit {
+  contextTokens: number
+}
+
+/**
+ * Minimum complete provider payload accepted by either capability probe.
+ * `resetAt`, when present, is an exact non-negative numeric provider value;
+ * date strings and other reset representations are unsupported.
+ */
+export interface ExactProviderUsageData {
+  sessionId: string
+  providerId: string
+  modelId: string
+  usage: ExactProviderUsage
+  limit: ExactProviderLimit
+  resetAt?: number
+}
+
+/** Stream event metadata required for de-duplication and freshness ordering. */
+export interface ProviderUsageEvent extends ExactProviderUsageData {
+  eventId: string
+  partId: string
+  /** Optional provider sequence. When supplied, it must be an integer. */
+  sequence?: number
+  /** Optional provider observation time in milliseconds or another numeric scale. */
+  observedAt?: number
+}
+
+/** A complete snapshot that has passed the exact contract validation. */
+export interface ProviderUsageSnapshot extends ProviderUsageEvent {}
+
+export type CapabilityProbeVersion = 'v1' | 'v2'
+
+export type CapabilityProbeReason =
+  | 'MISSING_SESSION_ID'
+  | 'MISSING_PROVIDER_ID'
+  | 'MISSING_MODEL_ID'
+  | 'MISSING_USAGE'
+  | 'MISSING_LIMIT'
+  | 'INVALID_USAGE'
+  | 'INVALID_LIMIT'
+  | 'INVALID_RESET'
+
+export type ProviderCapabilityResult =
+  | {
+      apiVersion: CapabilityProbeVersion
+      status: typeof USAGE_STATUS.SUPPORTED
+      data: ExactProviderUsageData
+    }
+  | {
+      apiVersion: CapabilityProbeVersion
+      status: typeof USAGE_STATUS.UNSUPPORTED
+      reason: CapabilityProbeReason
+    }
+
+type UnknownRecord = Record<string, unknown>
+
+function isRecord(value: unknown): value is UnknownRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0
+}
+
+function isFiniteNonNegativeNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0
+}
+
+function hasOnlyKeys(value: UnknownRecord, allowed: readonly string[]): boolean {
+  return Object.keys(value).every((key) => allowed.includes(key))
+}
+
+function unsupported(
+  apiVersion: CapabilityProbeVersion,
+  reason: CapabilityProbeReason,
+): ProviderCapabilityResult {
+  return { apiVersion, status: USAGE_STATUS.UNSUPPORTED, reason }
+}
+
+/**
+ * Validate the complete exact payload without coercion or estimation.
+ *
+ * This is intentionally shared only as a validator. V1 and V2 entry points
+ * below remain separate capability probes and do not fall back to one another.
+ */
+function probeExactData(
+  apiVersion: CapabilityProbeVersion,
+  input: unknown,
+): ProviderCapabilityResult {
+  if (!isRecord(input)) return unsupported(apiVersion, 'MISSING_SESSION_ID')
+
+  if (!isNonEmptyString(input.sessionId)) {
+    return unsupported(apiVersion, 'MISSING_SESSION_ID')
+  }
+  if (!isNonEmptyString(input.providerId)) {
+    return unsupported(apiVersion, 'MISSING_PROVIDER_ID')
+  }
+  if (!isNonEmptyString(input.modelId)) {
+    return unsupported(apiVersion, 'MISSING_MODEL_ID')
+  }
+  if (!isRecord(input.usage)) return unsupported(apiVersion, 'MISSING_USAGE')
+  if (!isRecord(input.limit)) return unsupported(apiVersion, 'MISSING_LIMIT')
+  if (!hasOnlyKeys(input.usage, ['inputTokens', 'outputTokens'])) {
+    return unsupported(apiVersion, 'INVALID_USAGE')
+  }
+  if (!hasOnlyKeys(input.limit, ['contextTokens'])) {
+    return unsupported(apiVersion, 'INVALID_LIMIT')
+  }
+
+  const usage = input.usage
+  if (!isFiniteNonNegativeNumber(usage.inputTokens)) {
+    return unsupported(apiVersion, 'INVALID_USAGE')
+  }
+  if (!isFiniteNonNegativeNumber(usage.outputTokens)) {
+    return unsupported(apiVersion, 'INVALID_USAGE')
+  }
+
+  const limit = input.limit
+  if (!isFiniteNonNegativeNumber(limit.contextTokens)) {
+    return unsupported(apiVersion, 'INVALID_LIMIT')
+  }
+
+  let resetAt: number | undefined
+  if ('reset' in input) return unsupported(apiVersion, 'INVALID_RESET')
+  if ('resetAt' in input) {
+    const value = input.resetAt
+    if (!isFiniteNonNegativeNumber(value)) return unsupported(apiVersion, 'INVALID_RESET')
+    resetAt = value
+  }
+
+  const data: ExactProviderUsageData = {
+    sessionId: input.sessionId,
+    providerId: input.providerId,
+    modelId: input.modelId,
+    usage: {
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+    },
+    limit: { contextTokens: limit.contextTokens },
+  }
+  if (resetAt !== undefined) data.resetAt = resetAt
+
+  return { apiVersion, status: USAGE_STATUS.SUPPORTED, data }
+}
+
+/**
+ * Probe the V1 exact payload shape supplied by a caller.
+ *
+ * V1 does not inherit V2 capability, credentials, cache, or lifecycle data.
+ * The caller must pass the exact payload after its host-specific extraction.
+ */
+export function probeV1Capability(input: unknown): ProviderCapabilityResult {
+  return probeExactData('v1', input)
+}
+
+/**
+ * Probe the V2 exact payload shape supplied by a caller.
+ *
+ * V2 is intentionally independent from V1: no V1 event, retry, cache, or
+ * fallback value is consulted when the exact payload is absent.
+ */
+export function probeV2Capability(input: unknown): ProviderCapabilityResult {
+  return probeExactData('v2', input)
+}
+
+/** Validate one complete stream event using the same exact data contract. */
+export function validateProviderUsageEvent(input: unknown): ProviderUsageEvent | null {
+  if (!isRecord(input)) return null
+  if (!isNonEmptyString(input.eventId) || !isNonEmptyString(input.partId)) return null
+
+  const data = probeExactData('v1', input)
+  if (data.status !== USAGE_STATUS.SUPPORTED) return null
+
+  let sequence: number | undefined
+  if ('sequence' in input) {
+    const value = input.sequence
+    if (!isFiniteNonNegativeNumber(value) || !Number.isInteger(value)) return null
+    sequence = value
+  }
+  let observedAt: number | undefined
+  if ('observedAt' in input) {
+    const value = input.observedAt
+    if (!isFiniteNonNegativeNumber(value)) return null
+    observedAt = value
+  }
+
+  const event: ProviderUsageEvent = {
+    ...data.data,
+    eventId: input.eventId,
+    partId: input.partId,
+  }
+  if (sequence !== undefined) event.sequence = sequence
+  if (observedAt !== undefined) event.observedAt = observedAt
+  return event
+}

package/src/pantheon/provider-stream-tracker.ts

@@ -0,0 +1,182 @@
+/**
+ * Pure provider stream usage tracker.
+ *
+ * The tracker stores only complete exact provider snapshots. It has no timers,
+ * polling, persistence, TUI dependency, provider client, credential fallback,
+ * token/cost estimation, or compaction/FSM integration.
+ *
+ * @module provider-stream-tracker
+ */
+
+import {
+  type ProviderUsageEvent,
+  type ProviderUsageSnapshot,
+  USAGE_STATUS,
+  type UsageStatus,
+  validateProviderUsageEvent,
+} from './provider-capabilities.ts'
+
+export type TrackerUpdateReason = 'PUBLISHED' | 'DUPLICATE' | 'STALE' | 'OUT_OF_SCOPE' | 'INVALID'
+
+export interface ProviderStreamTrackerOptions {
+  /** Optional exact stream scope. Events from another stream are unsupported. */
+  sessionId?: string
+  providerId?: string
+  modelId?: string
+  /** Injectable sink called only after a complete snapshot is stored. */
+  onSnapshot?: (snapshot: ProviderUsageSnapshot) => void
+}
+
+export interface ProviderStreamTrackerResult {
+  status: UsageStatus
+  published: boolean
+  reason: TrackerUpdateReason
+  snapshot?: ProviderUsageSnapshot
+}
+
+export interface ProviderStreamTracker {
+  /** Ingest one raw event without coercion or heuristic recovery. */
+  ingest(input: unknown): ProviderStreamTrackerResult
+  /** Read one complete snapshot for an isolated session/provider/model stream. */
+  getSnapshot(
+    sessionId: string,
+    providerId: string,
+    modelId: string,
+  ): ProviderUsageSnapshot | undefined
+  /** Read all complete snapshots, each isolated by stream identity. */
+  snapshots(): ProviderUsageSnapshot[]
+  /** Remove all in-memory stream state. */
+  clear(): void
+}
+
+interface StreamState {
+  snapshot: ProviderUsageSnapshot
+  eventIds: Set<string>
+  partIds: Set<string>
+  orderKind?: 'sequence' | 'observedAt'
+  orderValue?: number
+}
+
+function streamKey(sessionId: string, providerId: string, modelId: string): string {
+  return JSON.stringify([sessionId, providerId, modelId])
+}
+
+function copySnapshot(snapshot: ProviderUsageSnapshot): ProviderUsageSnapshot {
+  const copy: ProviderUsageSnapshot = {
+    eventId: snapshot.eventId,
+    partId: snapshot.partId,
+    sessionId: snapshot.sessionId,
+    providerId: snapshot.providerId,
+    modelId: snapshot.modelId,
+    usage: { ...snapshot.usage },
+    limit: { ...snapshot.limit },
+  }
+  if (snapshot.resetAt !== undefined) copy.resetAt = snapshot.resetAt
+  if (snapshot.sequence !== undefined) copy.sequence = snapshot.sequence
+  if (snapshot.observedAt !== undefined) copy.observedAt = snapshot.observedAt
+  return copy
+}
+
+function result(
+  status: UsageStatus,
+  reason: TrackerUpdateReason,
+  snapshot?: ProviderUsageSnapshot,
+): ProviderStreamTrackerResult {
+  return snapshot === undefined
+    ? { status, published: false, reason }
+    : { status, published: true, reason, snapshot: copySnapshot(snapshot) }
+}
+
+function isInScope(event: ProviderUsageEvent, options: ProviderStreamTrackerOptions): boolean {
+  return (
+    (options.sessionId === undefined || options.sessionId === event.sessionId) &&
+    (options.providerId === undefined || options.providerId === event.providerId) &&
+    (options.modelId === undefined || options.modelId === event.modelId)
+  )
+}
+
+function isStale(event: ProviderUsageEvent, state: StreamState): boolean {
+  if (event.sequence !== undefined) {
+    if (state.orderKind === 'sequence' && state.orderValue !== undefined) {
+      return event.sequence <= state.orderValue
+    }
+    return false
+  }
+
+  if (event.observedAt !== undefined) {
+    if (state.orderKind === 'observedAt' && state.orderValue !== undefined) {
+      return event.observedAt <= state.orderValue
+    }
+    return state.orderKind === 'sequence'
+  }
+
+  return state.orderKind !== undefined
+}
+
+function updateOrder(event: ProviderUsageEvent, state: StreamState): void {
+  if (event.sequence !== undefined) {
+    state.orderKind = 'sequence'
+    state.orderValue = event.sequence
+  } else if (event.observedAt !== undefined) {
+    state.orderKind = 'observedAt'
+    state.orderValue = event.observedAt
+  }
+}
+
+/**
+ * Create an in-memory tracker. With no scope options, multiple streams are
+ * tracked independently by their session/provider/model identity.
+ */
+export function createProviderStreamTracker(
+  options: ProviderStreamTrackerOptions = {},
+): ProviderStreamTracker {
+  const streams = new Map<string, StreamState>()
+
+  return {
+    ingest(input: unknown): ProviderStreamTrackerResult {
+      const event = validateProviderUsageEvent(input)
+      if (event === null) return result(USAGE_STATUS.UNSUPPORTED, 'INVALID')
+      if (!isInScope(event, options)) return result(USAGE_STATUS.UNSUPPORTED, 'OUT_OF_SCOPE')
+
+      const key = streamKey(event.sessionId, event.providerId, event.modelId)
+      const state = streams.get(key)
+      if (state?.eventIds.has(event.eventId) || state?.partIds.has(event.partId)) {
+        return result(USAGE_STATUS.SUPPORTED, 'DUPLICATE')
+      }
+
+      if (state !== undefined && isStale(event, state)) {
+        state.eventIds.add(event.eventId)
+        state.partIds.add(event.partId)
+        return result(USAGE_STATUS.SUPPORTED, 'STALE')
+      }
+
+      const nextState: StreamState = state ?? {
+        snapshot: event,
+        eventIds: new Set<string>(),
+        partIds: new Set<string>(),
+      }
+      nextState.snapshot = event
+      nextState.eventIds.add(event.eventId)
+      nextState.partIds.add(event.partId)
+      updateOrder(event, nextState)
+      streams.set(key, nextState)
+
+      const snapshot = copySnapshot(event)
+      options.onSnapshot?.(snapshot)
+      return result(USAGE_STATUS.SUPPORTED, 'PUBLISHED', snapshot)
+    },
+
+    getSnapshot(sessionId: string, providerId: string, modelId: string) {
+      const state = streams.get(streamKey(sessionId, providerId, modelId))
+      return state === undefined ? undefined : copySnapshot(state.snapshot)
+    },
+
+    snapshots() {
+      return [...streams.values()].map((state) => copySnapshot(state.snapshot))
+    },
+
+    clear() {
+      streams.clear()
+    },
+  }
+}