@axiom-lattice/protocols 5.0.0 → 6.0.0

package/package.json

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

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/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[];
+}

package/src/ScheduleLatticeProtocol.ts

@@ -361,6 +361,12 @@ export interface ScheduleClient {
    */
   restore(): Promise<number>;
 
+  /**
+   * Reconcile this replica's timers with the shared store. Implementations
+   * that support multi-replica scheduling should expose this.
+   */
+  reconcile?(): Promise<number>;
+
   // ===== Storage =====
 
   /**
@@ -414,4 +420,5 @@ export interface ScheduleLatticeProtocol
 
   // Recovery
   restore: () => Promise<number>;
+  reconcile?: () => Promise<number>;
 }

package/src/TaskStoreProtocol.ts

@@ -379,6 +379,14 @@ export interface TaskListFilter {
    */
   priority?: string;
 
+  /**
+   * Filter by the isolated run thread linked from `context.thread_id`.
+   *
+   * @remarks Used to authorize read-only views of task execution threads that
+   * do not have a durable Thread row or AgentRun row.
+   */
+  threadId?: string;
+
   /**
    * Filter by workspace ID
    */

package/src/__tests__/McpUiProtocol.test.ts

@@ -41,3 +41,51 @@ describe("parseMcpUiRef", () => {
     expect(isMcpUiRef("x")).toBe(false);
   });
 });
+
+describe("plugin scope", () => {
+  const plugin = {
+    kind: "plugin" as const,
+    pluginType: "p",
+    resource: "ui/x.html",
+  };
+
+  it("preserves a scope between 1 and 4096 characters", () => {
+    const scope = "a".repeat(64);
+    expect(parseMcpUiRef({ ...plugin, scope })).toEqual({
+      ...plugin,
+      displayMode: "inline",
+      scope,
+    });
+  });
+
+  it("preserves boundary scopes of 1 and 4096 characters", () => {
+    for (const scope of ["a", "b".repeat(4096)]) {
+      expect(parseMcpUiRef({ ...plugin, scope })).toEqual({
+        ...plugin,
+        displayMode: "inline",
+        scope,
+      });
+    }
+  });
+
+  it("drops empty, non-string, and over-long scopes", () => {
+    for (const scope of ["", 42, "x".repeat(4097)]) {
+      const ref = parseMcpUiRef({ ...plugin, scope });
+      expect(ref && "scope" in ref).toBe(false);
+    }
+  });
+
+  it("does not carry scope on an mcp ref", () => {
+    const ref = parseMcpUiRef({
+      kind: "mcp",
+      serverKey: "weather",
+      resourceUri: "ui://weather/dashboard",
+      scope: "signed-scope-token",
+    });
+    expect(ref && "scope" in ref).toBe(false);
+  });
+
+  it("keeps a legacy plugin ref unchanged", () => {
+    expect(parseMcpUiRef(plugin)).toEqual({ ...plugin, displayMode: "inline" });
+  });
+});

package/src/__tests__/MenuProtocol.test.ts

@@ -15,10 +15,14 @@ describe("MenuProtocol mcpApp content type", () => {
       pluginType: "my-plugin",
       resource: "ui/report.html",
       title: "Report",
+      scope: "signed-scope-token",
     };
     for (const cfg of [mcp, plugin] as MenuContentConfig[]) {
       expect(JSON.parse(JSON.stringify(cfg))).toEqual(cfg);
     }
+    const parsed = JSON.parse(JSON.stringify(plugin)) as McpAppMenuConfig;
+    expect(parsed.kind).toBe("plugin");
+    expect(parsed.kind === "plugin" ? parsed.scope : undefined).toBe("signed-scope-token");
   });
 
   it("includes file and mcpApp in MenuContentType", () => {

package/src/__tests__/ObservabilityDashboardProtocol.test.ts

@@ -0,0 +1,17 @@
+import {
+  LANGFUSE_OBSERVABILITY_DASHBOARD_VERSION,
+  OBSERVABILITY_DASHBOARD_ELEMENT_KEY_PREFIX,
+  observabilityDashboardElementKey,
+} from "../ObservabilityDashboardProtocol";
+
+describe("observabilityDashboardElementKey", () => {
+  it("namespaces the provider key", () => {
+    expect(observabilityDashboardElementKey("langfuse")).toBe(
+      "observability_dashboard_langfuse",
+    );
+    expect(OBSERVABILITY_DASHBOARD_ELEMENT_KEY_PREFIX).toBe(
+      "observability_dashboard_",
+    );
+    expect(LANGFUSE_OBSERVABILITY_DASHBOARD_VERSION).toBe(3);
+  });
+});

package/src/index.ts

@@ -106,3 +106,4 @@ export * from "./RunCancelProtocol";
 export * from "./AgentAffinity";
 export * from "./OpenProtocol";
 export * from "./McpUiProtocol";
+export * from "./ObservabilityDashboardProtocol";