@axiom-lattice/protocols 4.11.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiom-lattice/protocols",
-  "version": "4.11.0",
+  "version": "6.0.0",
   "description": "Unified protocol type definitions for Axiom Lattice framework",
   "main": "dist/index.js",
   "module": "dist/index.mjs",

package/src/AgentInterruptProtocol.ts

@@ -0,0 +1,15 @@
+/**
+ * Normalized human-in-the-loop interrupt exposed by the Agent Server surface.
+ */
+export interface AgentInterrupt {
+  /** Stable id derived from the LangGraph interrupt id or task/index. */
+  interruptId: string;
+  /** Normalized interrupt kind. */
+  type: "clarify" | "task_review" | "custom";
+  /** Thread whose graph is interrupted. */
+  threadId: string;
+  /** Task id that owns the interrupt, when available. */
+  taskId?: string;
+  /** Raw or normalized interrupt payload. */
+  payload: unknown;
+}

package/src/AgentLatticeProtocol.ts

@@ -14,7 +14,6 @@ import { BaseLatticeProtocol } from "./BaseLatticeProtocol";
 export enum AgentType {
   REACT = "react",
   DEEP_AGENT = "deep_agent",
-  TEAM = "team",
   PROCESSING = "processing",
   /** Remote A2A agent — delegates to an external A2A-compatible server */
   A2A_REMOTE = "a2a_remote",
@@ -203,52 +202,6 @@ export interface ProcessingAgentConfig extends BaseAgentConfig {
   internalSubAgents?: AgentConfig[];
 }
 
-/**
- * Team teammate configuration -- describes an available teammate.
- */
-export interface TeamTeammateConfig {
-  /** Unique name for this teammate (used as agent ID) */
-  name: string;
-  /** Role category (e.g. "research", "writing", "review") */
-  role: string;
-  /** Human-readable description of what this teammate does */
-  description: string;
-  /** Tool keys this teammate has access to */
-  tools?: string[];
-  /** Custom system prompt for this teammate */
-  prompt?: string;
-  /** Model key override for this teammate */
-  modelKey?: string;
-}
-
-/**
- * TEAM agent configuration -- a team lead that dynamically creates teammates.
- * Teammates are created on-the-fly from create_team tool input (name, role, description).
- */
-export interface TeamAgentConfig extends BaseAgentConfig {
-  type: AgentType.TEAM;
-  /** Tool keys available to the team lead */
-  tools?: string[];
-  /** Maximum number of teammates running concurrently */
-  maxConcurrency?: number;
-  /**
-   * Schedule lattice key for polling task list / mailbox.
-   * When set, teammates use ScheduleLattice for periodic polling instead of event-driven wait.
-   */
-  scheduleLatticeKey?: string;
-  /** Poll interval in ms when using schedule lattice (default: 5000) */
-  pollIntervalMs?: number;
-}
-
-/**
- * Type guard to check if config is TeamAgentConfig
- */
-export function isTeamAgentConfig(
-  config: AgentConfig
-): config is TeamAgentConfig {
-  return config.type === AgentType.TEAM;
-}
-
 // ─── A2A_REMOTE Agent ──────────────────────────────────────────────────────
 
 export interface LocalRuntimeConfig {
@@ -361,7 +314,6 @@ export function isWorkflowAgentConfig(
 export type AgentConfig =
   | ReactAgentConfig
   | DeepAgentConfig
-  | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
   | WorkflowAgentConfig
@@ -372,7 +324,6 @@ export type AgentConfig =
 export type AgentConfigWithTools =
   | ReactAgentConfig
   | DeepAgentConfig
-  | TeamAgentConfig
   | ProcessingAgentConfig
   | A2ARemoteAgentConfig
   | WorkflowAgentConfig

package/src/AgentWebAppRuntimeProtocol.ts

@@ -104,6 +104,8 @@ export type AgentWebAppErrorCode =
   | "THREAD_NOT_FOUND"
   | "STREAM_CONFLICT"
   | "STREAM_FAILED"
+  | "RUN_CANCEL_UNAVAILABLE"
+  | "RUN_CANCEL_STORE_UNAVAILABLE"
   | "INVALID_REQUEST"
   | "INTERNAL_ERROR";
 

package/src/ChannelAdapterProtocol.ts

@@ -87,6 +87,16 @@ export type MessageMiddleware = (
 export interface ChannelAdapter<TConfig = unknown> {
   readonly channel: string;
   readonly configSchema: z.ZodSchema<TConfig>;
+  /**
+   * Whether `sendReply` is safe to call from any Gateway replica.
+   *
+   * @remarks
+   * Only adapters whose reply transport is stateless/HTTP (for example Lark)
+   * may set this. Connection-bound adapters (WeCom/WeChat/Room) leave it
+   * undefined: their replies depend on process-local sockets or context tokens,
+   * so the durable cross-replica reply path must not claim their jobs.
+   */
+  readonly durableReply?: boolean;
   receive(
     rawPayload: unknown,
     installation: ChannelInstallation,

package/src/ChannelReplyJobProtocol.ts

@@ -0,0 +1,184 @@
+/** Lifecycle of one durable channel reply delivery attempt. */
+export type ChannelReplyJobStatus = "pending" | "delivered" | "failed";
+
+/**
+ * A durable, cross-replica channel reply job.
+ *
+ * @remarks
+ * The row is keyed by `runId` but always read/written inside a tenant scope.
+ * Claiming is a lease-based CAS: only a pending, due row with no live lease can
+ * be claimed, and terminal writes must present the current lease owner.
+ */
+export interface ChannelReplyJob {
+  runId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  adapterChannel: string;
+  channelInstallationId: string;
+  replyTarget: Record<string, unknown>;
+  inputMessageId: string;
+  /**
+   * Legacy chunk-buffer cursor captured before the run was created.
+   *
+   * @remarks Retained for schema compatibility. The durable dispatcher now
+   * reads final text from the thread checkpoint and does not use this field.
+   */
+  streamCursor?: string | null;
+  status: ChannelReplyJobStatus;
+  attempts: number;
+  /** Epoch milliseconds. */
+  availableAt: number;
+  leaseOwner: string | null;
+  /** Epoch milliseconds. */
+  leaseExpiresAt: number | null;
+  lastError: string | null;
+  outputMessageId: string | null;
+  /** Epoch milliseconds. */
+  createdAt: number;
+  /** Epoch milliseconds. */
+  updatedAt: number;
+  /** Epoch milliseconds. */
+  deliveredAt: number | null;
+}
+
+/** Fields accepted when enqueuing a reply job. Status/lease/output fields are assigned by the store. */
+export interface CreateChannelReplyJobInput {
+  runId: string;
+  tenantId: string;
+  assistantId: string;
+  threadId: string;
+  adapterChannel: string;
+  channelInstallationId: string;
+  replyTarget: Record<string, unknown>;
+  inputMessageId: string;
+  /**
+   * Legacy chunk-buffer cursor captured before the run was created.
+   *
+   * @remarks Retained for schema compatibility. The durable dispatcher now
+   * reads final text from the thread checkpoint and does not use this field.
+   */
+  streamCursor?: string | null;
+  /** Earliest epoch-ms time the job may be claimed. */
+  availableAt: number;
+}
+
+/** Persistence boundary for durable channel reply jobs. */
+export interface ChannelReplyJobStore {
+  /** Creates a pending job. */
+  create(input: CreateChannelReplyJobInput): Promise<ChannelReplyJob>;
+  /** Reads one job within a tenant scope. */
+  get(tenantId: string, runId: string): Promise<ChannelReplyJob | null>;
+  /** Lists claimable pending jobs that are due at `now`, oldest first. */
+  listPending(now: number, limit?: number): Promise<ChannelReplyJob[]>;
+  /**
+   * Atomically leases a pending, due job that is unleased or has an expired
+   * lease. Returns the claimed job, or `null` when another owner won.
+   */
+  claim(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    leaseMs: number,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Marks a job delivered when `owner` still holds the lease. */
+  markDelivered(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    outputMessageId?: string | null,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Returns a job to pending with an incremented attempt count. */
+  reschedule(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    error: string,
+    availableAt: number,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Marks a job terminally failed. */
+  markFailed(
+    tenantId: string,
+    runId: string,
+    owner: string,
+    error: string,
+    now?: number,
+  ): Promise<ChannelReplyJob | null>;
+  /** Deletes one job. Returns whether a row was removed. */
+  delete(tenantId: string, runId: string): Promise<boolean>;
+  /**
+   * Deletes up to `limit` terminal (`delivered`/`failed`) jobs whose last update
+   * is strictly older than `before`.
+   *
+   * @param before Epoch milliseconds retention cutoff.
+   * @param limit Maximum rows to prune in this batch (normalized 1..200).
+   * @returns Number of rows removed.
+   */
+  deleteTerminalBefore(before: number, limit?: number): Promise<number>;
+}
+
+/** Smallest accepted page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_MIN = 1;
+/** Largest accepted page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_MAX = 200;
+/** Default page size for {@link ChannelReplyJobStore.listPending}. */
+export const CHANNEL_REPLY_JOB_LIST_LIMIT_DEFAULT = 100;
+
+/**
+ * Normalizes a caller-supplied page size into the shared 1..200 range.
+ *
+ * @remarks Zero and negative values clamp to 1; non-finite values fall back to
+ * the default. Stores must use this helper so InMemory and PostgreSQL agree.
+ */
+export function normalizeChannelReplyJobListLimit(limit?: number): number {
+  if (limit === undefined || !Number.isFinite(limit)) {
+    return CHANNEL_REPLY_JOB_LIST_LIMIT_DEFAULT;
+  }
+  return Math.min(
+    CHANNEL_REPLY_JOB_LIST_LIMIT_MAX,
+    Math.max(CHANNEL_REPLY_JOB_LIST_LIMIT_MIN, Math.trunc(limit)),
+  );
+}
+
+/** Rejects missing/blank required fields and malformed create payloads at runtime. */
+export function assertValidCreateChannelReplyJobInput(
+  input: CreateChannelReplyJobInput,
+): void {
+  if (input === null || typeof input !== "object") {
+    throw new Error("ChannelReplyJob create input is required");
+  }
+  const required: Array<[string, unknown]> = [
+    ["runId", input.runId],
+    ["tenantId", input.tenantId],
+    ["assistantId", input.assistantId],
+    ["threadId", input.threadId],
+    ["adapterChannel", input.adapterChannel],
+    ["channelInstallationId", input.channelInstallationId],
+    ["inputMessageId", input.inputMessageId],
+  ];
+  for (const [field, value] of required) {
+    if (typeof value !== "string" || value.trim() === "") {
+      throw new Error(`ChannelReplyJob requires a non-empty ${field}`);
+    }
+  }
+  if (
+    typeof input.replyTarget !== "object" ||
+    input.replyTarget === null ||
+    Array.isArray(input.replyTarget)
+  ) {
+    throw new Error("ChannelReplyJob requires a replyTarget object");
+  }
+  if (typeof input.availableAt !== "number" || !Number.isFinite(input.availableAt)) {
+    throw new Error("ChannelReplyJob requires a finite availableAt");
+  }
+  if (
+    input.streamCursor !== undefined &&
+    input.streamCursor !== null &&
+    typeof input.streamCursor !== "string"
+  ) {
+    throw new Error("ChannelReplyJob streamCursor must be a string");
+  }
+}

package/src/CheckpointStorageProtocol.ts

@@ -0,0 +1,98 @@
+/**
+ * Checkpoint storage usage for a single thread.
+ *
+ * This is a read-only accounting view over the checkpointer's persisted rows.
+ */
+export interface ThreadCheckpointStorage {
+  /** Thread whose checkpoint rows were measured. */
+  threadId: string;
+  /** Sum of checkpoint, channel-value, and pending-write bytes. */
+  totalBytes: number;
+  /** Persisted checkpoint rows (`checkpoints` table). */
+  checkpoints: { count: number; bytes: number };
+  /** Persisted channel values (`checkpoint_blobs` table). */
+  channelValues: { count: number; bytes: number };
+  /** Persisted pending writes (`checkpoint_writes` table). */
+  pendingWrites: { count: number; bytes: number };
+}
+
+/**
+ * Read-only checkpoint storage accounting.
+ *
+ * Implementations must not create, copy, prune, or mutate checkpoint rows.
+ */
+export interface CheckpointStorage {
+  /**
+   * Measure the checkpoint storage used by one thread.
+   *
+   * @param threadId - Thread id whose checkpoint rows should be measured.
+   * @returns Counts and byte sizes grouped by checkpoint storage category.
+   */
+  get(threadId: string): Promise<ThreadCheckpointStorage>;
+}
+
+/**
+ * Checkpoint maintenance operations over persisted thread checkpoints.
+ *
+ * Implementations copy, delete, and prune raw checkpoint rows for a thread.
+ * Callers must verify thread ownership and refuse to run while the thread is
+ * active.
+ */
+export interface CheckpointMaintenance {
+  /**
+   * Copy every checkpoint row from a source thread to an empty target thread.
+   *
+   * @param sourceThreadId - Thread whose rows are copied.
+   * @param targetThreadId - Empty thread that receives the rows.
+   * @returns Resolves when the copy commits; an empty source is a no-op.
+   * @throws When the target already has checkpoint rows.
+   */
+  copyThread(sourceThreadId: string, targetThreadId: string): Promise<void>;
+
+  /**
+   * Delete every checkpoint row for a thread.
+   *
+   * @param threadId - Thread whose checkpoint rows are deleted.
+   * @returns Resolves when the deletion commits.
+   */
+  deleteThread(threadId: string): Promise<void>;
+
+  /**
+   * Delete the checkpoints that descend from a base checkpoint.
+   *
+   * Preserves the base checkpoint and every checkpoint that is not descended
+   * from it. Descendants are discovered by following both same-namespace
+   * `parent_checkpoint_id` edges and cross-namespace `metadata.parents` edges
+   * (the `{ "<parent checkpoint_ns>": "<parent checkpoint id>" }` map that
+   * LangGraph writes for subgraph checkpoints), recursively across all
+   * namespaces. Checkpoint-id ordering is not used. LangGraph keys the first
+   * superstep's writes of a resumed execution to the parent/base checkpoint, so
+   * writes keyed to the base itself belong to the rolled-back run and are
+   * deleted with descendant writes. Channel blobs are removed only when no
+   * retained checkpoint references them.
+   *
+   * @param threadId - Thread whose later checkpoint history is deleted.
+   * @param baseCheckpointId - Checkpoint to retain as the new tip, or `null` to
+   * delete every checkpoint for the thread. An empty string is invalid and must
+   * never be treated as the `null` wildcard.
+   * @returns Resolves when the deletion commits; no descendants is a no-op.
+   * @throws When the base checkpoint does not exist on the thread. Callers must
+   * fail closed rather than deleting an unknown range.
+   * @remarks The operation is transactional and idempotent so rollback recovery
+   * can retry it.
+   */
+  deleteAfter(threadId: string, baseCheckpointId: string | null): Promise<void>;
+
+  /**
+   * Retain only the latest N checkpoints per checkpoint namespace.
+   *
+   * @param threadId - Thread whose checkpoint history is pruned.
+   * @param options - Retention options.
+   * @param options.keepLatest - Number of latest checkpoints to retain per namespace.
+   * @returns Counts of deleted checkpoint, blob, and write rows.
+   */
+  pruneThread(
+    threadId: string,
+    options: { keepLatest: number },
+  ): Promise<{ checkpoints: number; blobs: number; writes: number }>;
+}

package/src/EvalStoreProtocol.ts

@@ -104,6 +104,8 @@ export interface EvalRun {
   interruptedCases?: number;
   avgScore: number;
   error?: string;
+  /** A client requested cancellation; the executing worker polls this flag. */
+  cancelRequested?: boolean;
   /**
    * When true, this run executed ONLY the hold-out validation suite.
    * Per-case results of holdout runs are withheld from agents (aggregate
@@ -179,6 +181,8 @@ export interface EvalStore {
   getRunById(tenantId: string, id: string): Promise<EvalRun | null>;
   createRun(tenantId: string, projectId: string, id: string, data: CreateEvalRunRequest): Promise<EvalRun>;
   updateRunStatus(tenantId: string, id: string, updates: { status?: EvalRun['status']; passedCases?: number; failedCases?: number; interruptedCases?: number; avgScore?: number; error?: string; completedAt?: Date }): Promise<EvalRun | null>;
+  /** Request cooperative cancellation for a running evaluation. */
+  requestCancel?(tenantId: string, id: string): Promise<boolean>;
   deleteRun(tenantId: string, id: string): Promise<boolean>;
 
   getResultsByRun(tenantId: string, runId: string): Promise<EvalRunResult[]>;

package/src/McpUiProtocol.ts

@@ -32,7 +32,15 @@ export type McpUiRef =
        */
       structuredContent?: unknown;
     }
-  | { kind: "plugin"; pluginType: string; resource: string; displayMode: McpUiDisplayMode; title?: string };
+  | {
+      kind: "plugin";
+      pluginType: string;
+      resource: string;
+      displayMode: McpUiDisplayMode;
+      title?: string;
+      /** Opaque HMAC-signed run/connection scope (1..4096 chars); never contains secrets. */
+      scope?: string;
+    };
 
 /** Resolved UI resource body returned by the gateway. */
 export interface McpUiResourcePayload {
@@ -45,6 +53,7 @@ export interface McpUiResourcePayload {
 }
 
 const MODES: McpUiDisplayMode[] = ["inline", "fullscreen", "pip"];
+const MAX_MCP_UI_SCOPE_LENGTH = 4096;
 const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null;
 
 /** Type guard for a parsed `McpUiRef`. */
@@ -70,7 +79,18 @@ export function parseMcpUiRef(value: unknown): McpUiRef | null {
     };
   }
   if (value.kind === "plugin" && typeof value.pluginType === "string" && typeof value.resource === "string") {
-    return { kind: "plugin", pluginType: value.pluginType, resource: value.resource, displayMode, ...(title ? { title } : {}) };
+    const scope =
+      typeof value.scope === "string" && value.scope.length > 0 && value.scope.length <= MAX_MCP_UI_SCOPE_LENGTH
+        ? value.scope
+        : undefined;
+    return {
+      kind: "plugin",
+      pluginType: value.pluginType,
+      resource: value.resource,
+      displayMode,
+      ...(title ? { title } : {}),
+      ...(scope ? { scope } : {}),
+    };
   }
   return null;
 }

package/src/MenuProtocol.ts

@@ -54,6 +54,8 @@ export type McpAppMenuConfig =
       resource: string;
       displayMode?: McpUiDisplayMode;
       title?: string;
+      /** Signed scope copied from the ref so a pinned App can keep calling. */
+      scope?: string;
       toolInput?: Record<string, unknown>;
       toolResult?: unknown;
       ui?: ToolCallUi;

package/src/MessageProtocol.ts

@@ -114,6 +114,14 @@ export type MessageChunkType = typeof MessageChunkTypes[keyof typeof MessageChun
 
 export interface MessageChunk {
   type: MessageChunkType;
+  /**
+   * Shared append-log cursor for this chunk.
+   *
+   * Set by streaming transports when the chunk is read from a cursor-addressable
+   * log (for example Redis Streams) so reconnects can resume via SSE
+   * `Last-Event-ID`. Omitted by in-memory buffers configured without a log.
+   */
+  cursor?: string;
   data: {
     id: string;
     content?: string;

package/src/ObservabilityDashboardProtocol.ts

@@ -0,0 +1,167 @@
+/**
+ * Time range accepted by an observability dashboard.
+ */
+export type ObservabilityDashboardRange = "1h" | "24h" | "7d" | "30d";
+
+/**
+ * Input passed by the gateway to the selected observability provider.
+ */
+export interface ObservabilityDashboardInput {
+  /** Time window to aggregate. */
+  range: ObservabilityDashboardRange;
+  /** Tenant resolved from the authenticated request, never from the client. */
+  tenantId: string;
+}
+
+/**
+ * Provider-owned dashboard result.
+ *
+ * The `payload` shape belongs to the provider; consumers must check `version`
+ * before rendering it.
+ */
+export interface ObservabilityDashboardResult {
+  /** Provider payload version. */
+  version: number;
+  /** Section keys that could not be loaded. */
+  warnings?: string[];
+  /** Provider-specific dashboard data. */
+  payload: unknown;
+}
+
+/**
+ * Cross-provider response envelope returned by the gateway.
+ */
+export interface ObservabilityDashboardEnvelope {
+  /** Provider type, also used as the UI element key suffix. */
+  provider: string;
+  /** Requested time window. */
+  range: ObservabilityDashboardRange;
+  /** Server generation timestamp. */
+  generatedAt: string;
+  /** Provider payload version. */
+  version: number;
+  /** Section keys that could not be loaded. */
+  warnings?: string[];
+  /** Provider-specific dashboard data. */
+  payload: unknown;
+}
+
+/** Prefix used to register a dashboard renderer in the GenUI element registry. */
+export const OBSERVABILITY_DASHBOARD_ELEMENT_KEY_PREFIX =
+  "observability_dashboard_";
+
+/**
+ * Returns the GenUI element key for a provider dashboard.
+ *
+ * @param provider - Provider type such as `"langfuse"`.
+ * @returns The registry key used by both the provider renderer and the panel.
+ */
+export function observabilityDashboardElementKey(provider: string): string {
+  return `${OBSERVABILITY_DASHBOARD_ELEMENT_KEY_PREFIX}${provider}`;
+}
+
+/** Version of the built-in Langfuse dashboard payload. */
+export const LANGFUSE_OBSERVABILITY_DASHBOARD_VERSION = 3;
+
+/** One point in a Langfuse dashboard time series. */
+export interface LangfuseObservabilitySeriesPoint {
+  /** ISO timestamp of the bucket start. */
+  bucket: string;
+  /** Aggregated value, or `null` when the bucket has no value. */
+  value: number | null;
+}
+
+/** Agent breakdown row, derived from the `assistant:<id>` trace tag. */
+export interface LangfuseAgentBreakdownRow {
+  /** Assistant id from the trace tag. */
+  assistantId: string;
+  /** Display name from the trace name, when Langfuse captured one. */
+  name?: string;
+  /** Root-observation count, i.e. invocations started by this agent. */
+  calls: number;
+  /** All observations emitted by this agent. */
+  observations: number;
+  /** Total cost in USD. */
+  costUsd: number;
+  /** Input tokens consumed. */
+  inputTokens: number;
+  /** Output tokens produced. */
+  outputTokens: number;
+  /** Error-level observation count. */
+  errorCount: number;
+  /** Error ratio in `[0, 1]` over observations. */
+  errorRate: number;
+}
+
+/** One model's cost over time. */
+export interface LangfuseModelCostSeries {
+  /** Model name. */
+  model: string;
+  /** Cost points for this model. */
+  points: LangfuseObservabilitySeriesPoint[];
+}
+
+/** Model breakdown row. */
+export interface LangfuseModelBreakdownRow {
+  /** Model name reported by Langfuse. */
+  model: string;
+  /** Observation count. */
+  count: number;
+  /** Total cost in USD. */
+  costUsd: number;
+  /** Input tokens consumed. */
+  inputTokens: number;
+  /** Output tokens produced. */
+  outputTokens: number;
+  /** p95 generation latency in milliseconds, or `null` when unknown. */
+  p95LatencyMs: number | null;
+}
+
+/** Tool breakdown row. */
+export interface LangfuseToolBreakdownRow {
+  /** Tool observation name. */
+  tool: string;
+  /** Observation count. */
+  count: number;
+}
+
+/**
+ * Built-in Langfuse dashboard payload.
+ *
+ * Aggregated for one tenant and time range; it never contains prompts,
+ * completions, user text, or credentials.
+ */
+export interface LangfuseObservabilityDashboardPayload {
+  /** Provider sample rate; values below 1 mean the numbers are sampled. */
+  samplingRate: number;
+  /** Tracing environment used for the query, when configured. */
+  environment?: string;
+  kpis: {
+    traces: number;
+    costUsd: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** Error observation ratio in `[0, 1]`. */
+    errorRate: number;
+  };
+  series: {
+    traces: LangfuseObservabilitySeriesPoint[];
+    cost: LangfuseObservabilitySeriesPoint[];
+    tokens: {
+      input: LangfuseObservabilitySeriesPoint[];
+      output: LangfuseObservabilitySeriesPoint[];
+    };
+    latency: {
+      p50: LangfuseObservabilitySeriesPoint[];
+      p95: LangfuseObservabilitySeriesPoint[];
+      p99: LangfuseObservabilitySeriesPoint[];
+    };
+    errorRate: LangfuseObservabilitySeriesPoint[];
+    toolCalls: LangfuseObservabilitySeriesPoint[];
+    /** Per-model cost trend. Optional so older payloads keep working. */
+    costByModel?: LangfuseModelCostSeries[];
+  };
+  agents: LangfuseAgentBreakdownRow[];
+  models: LangfuseModelBreakdownRow[];
+  tools: LangfuseToolBreakdownRow[];
+}