@adaptivemcp/spec 0.2.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kemal Elmizan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/events.d.ts

@@ -6,6 +6,7 @@ export interface ToolEventContext {
     sessionId?: string;
     requestId?: string;
     model?: string;
+    metadata?: Record<string, unknown>;
 }
 /**
  * Construct a tool execution event with sensible defaults. Timestamps use the

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEjE,eAAO,MAAM,oBAAoB,EAAG,0CAAmD,CAAC;AAExF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,UAAU,EAClB,KAAK,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACtC,kBAAkB,CAYpB"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEjE,eAAO,MAAM,oBAAoB,EAAG,0CAAmD,CAAC;AAExF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,gBAAgB,EACrB,MAAM,EAAE,UAAU,EAClB,KAAK,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACtC,kBAAkB,CAYpB"}

package/dist/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,oBAAoB,GAAG,0CAAmD,CAAC;AAUxF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAqB,EACrB,MAAkB,EAClB,QAAqC,EAAE;IAEvC,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE;QACnC,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,MAAM;QACN,GAAG,KAAK;KACT,CAAC;AACJ,CAAC"}
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,oBAAoB,GAAG,0CAAmD,CAAC;AAWxF;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAqB,EACrB,MAAkB,EAClB,QAAqC,EAAE;IAEvC,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,MAAM,CAAC,UAAU,EAAE;QACnC,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACtD,MAAM;QACN,GAAG,KAAK;KACT,CAAC;AACJ,CAAC"}

package/dist/execution-graph.d.ts

@@ -0,0 +1,63 @@
+import type { ExecutionNode } from "./types.js";
+/**
+ * Canonical, JSON-serializable wire format for a session's execution graph —
+ * the shape any MCP server can emit (and any client can parse) for
+ * cross-server graph correlation. Field names are snake_case, matching the
+ * convention already used by every other *Document wire type in this
+ * codebase (`WorkflowGraphDocument`, `GraphInsightsDocument`); TS-internal
+ * types like `ExecutionNode` stay camelCase.
+ *
+ * This replaces the old `ExecutionGraph` type (Map-based `nodes`, never
+ * built or consumed anywhere in the codebase) — Maps aren't directly
+ * JSON-serializable, so they were never a viable wire format to begin with.
+ * "Federation" here means a shared, importable schema + builder other MCP
+ * servers' code can construct against — not an implemented multi-server
+ * aggregation/discovery protocol, which would need infrastructure (server
+ * registries, cross-server RPC) that doesn't exist in this codebase.
+ */
+export interface ExecutionGraphResource {
+    version: string;
+    etag: string;
+    generated_at: string;
+    session_id: string;
+    workflow_id?: string;
+    nodes: Array<{
+        id: string;
+        tool: string;
+        server?: string;
+        parent?: string;
+        children: string[];
+        timestamp: string;
+        duration_ms?: number;
+        status: string;
+        cost?: number;
+        model?: string;
+        /** W3C `traceparent` recorded on the node, if graph tracking generated one. */
+        trace_parent?: string;
+    }>;
+    edges: Array<{
+        from: string;
+        to: string;
+    }>;
+    /**
+     * Opaque pagination cursor (the `id` of the last returned node) — present
+     * when more nodes exist beyond this page. Absent on the last page or when
+     * the caller didn't request pagination.
+     */
+    next_cursor?: string;
+}
+export interface BuildExecutionGraphOptions {
+    version: string;
+    sessionId: string;
+    generatedAt?: string;
+    workflowId?: string;
+    nextCursor?: string;
+}
+/**
+ * Pure builder: maps a flat `ExecutionNode[]` (already the desired page) into
+ * the canonical wire shape. `etag` is returned empty — it's a hash of this
+ * very output, so callers compute it over the returned object and assign it
+ * afterward (see `ExtensionController.buildExecutionGraphDocument`).
+ */
+export declare function buildExecutionGraph(nodes: ExecutionNode[], opts: BuildExecutionGraphOptions): ExecutionGraphResource;
+//# sourceMappingURL=execution-graph.d.ts.map

package/dist/execution-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-graph.d.ts","sourceRoot":"","sources":["../src/execution-graph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,KAAK,CAAC;QACX,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,+EAA+E;QAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC,CAAC;IACH,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,0BAA0B,GAAG,sBAAsB,CA0BpH"}

package/dist/execution-graph.js

@@ -0,0 +1,33 @@
+/**
+ * Pure builder: maps a flat `ExecutionNode[]` (already the desired page) into
+ * the canonical wire shape. `etag` is returned empty — it's a hash of this
+ * very output, so callers compute it over the returned object and assign it
+ * afterward (see `ExtensionController.buildExecutionGraphDocument`).
+ */
+export function buildExecutionGraph(nodes, opts) {
+    const renderedNodes = nodes.map((n) => ({
+        id: n.id,
+        tool: n.toolName,
+        server: n.serverName,
+        parent: n.parentId,
+        children: n.childrenIds,
+        timestamp: n.timestamp,
+        duration_ms: n.durationMs,
+        status: n.status,
+        cost: n.cost?.amount,
+        model: n.model,
+        trace_parent: n.metadata?.traceparent,
+    }));
+    const edges = nodes.flatMap((n) => n.childrenIds.map((childId) => ({ from: n.id, to: childId })));
+    return {
+        version: opts.version,
+        etag: "",
+        generated_at: opts.generatedAt ?? new Date().toISOString(),
+        session_id: opts.sessionId,
+        workflow_id: opts.workflowId ?? nodes[0]?.workflowId ?? "unknown",
+        nodes: renderedNodes,
+        edges,
+        next_cursor: opts.nextCursor,
+    };
+}
+//# sourceMappingURL=execution-graph.js.map

package/dist/execution-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-graph.js","sourceRoot":"","sources":["../src/execution-graph.ts"],"names":[],"mappings":"AAuDA;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAsB,EAAE,IAAgC;IAC1F,MAAM,aAAa,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACtC,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,IAAI,EAAE,CAAC,CAAC,QAAQ;QAChB,MAAM,EAAE,CAAC,CAAC,UAAU;QACpB,MAAM,EAAE,CAAC,CAAC,QAAQ;QAClB,QAAQ,EAAE,CAAC,CAAC,WAAW;QACvB,SAAS,EAAE,CAAC,CAAC,SAAS;QACtB,WAAW,EAAE,CAAC,CAAC,UAAU;QACzB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM;QACpB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,YAAY,EAAE,CAAC,CAAC,QAAQ,EAAE,WAAiC;KAC5D,CAAC,CAAC,CAAC;IACJ,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC;IAElG,OAAO;QACL,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,IAAI,EAAE,EAAE;QACR,YAAY,EAAE,IAAI,CAAC,WAAW,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC1D,UAAU,EAAE,IAAI,CAAC,SAAS;QAC1B,WAAW,EAAE,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,UAAU,IAAI,SAAS;QACjE,KAAK,EAAE,aAAa;QACpB,KAAK;QACL,WAAW,EAAE,IAAI,CAAC,UAAU;KAC7B,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from "./types.js";
+export * from "./result.js";
 export * from "./extensions.js";
 export * from "./events.js";
+export * from "./execution-graph.js";
 export { SPEC_VERSION } from "./version.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,5 +1,7 @@
 export * from "./types.js";
+export * from "./result.js";
 export * from "./extensions.js";
 export * from "./events.js";
+export * from "./execution-graph.js";
 export { SPEC_VERSION } from "./version.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/result.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Result classification.
+ *
+ * A client's transport may report a tool call as "ok" while the server has, in
+ * fact, signalled a *logical* failure in-band — for example a JSON envelope with
+ * `status: "error"` instead of the protocol-level `isError` flag. Left alone,
+ * that outcome is recorded as a success, which poisons every derived signal:
+ * failure rate, insights, routing, drift.
+ *
+ * A `ToolResultClassifier` is the seam that corrects this. It runs on each
+ * execution *attempt*, before the outcome is recorded (and therefore before the
+ * retry decision), so a reclassified failure can also trigger a retry. It is
+ * advisory in the same sense as the rest of Adaptive MCP: the host opts in by
+ * supplying a classifier; returning `undefined` leaves the outcome untouched.
+ */
+/** A raw tool outcome, as produced by the transport before classification. */
+export interface ToolCallOutcome {
+    ok: boolean;
+    error?: string;
+    output?: unknown;
+}
+/** Fields a classifier may override; omitted fields keep their raw value. */
+export interface ToolResultClassification {
+    ok?: boolean;
+    error?: string;
+}
+/** Context identifying the call an outcome belongs to. */
+export interface ToolResultContext {
+    toolName: string;
+    serverName?: string;
+}
+/**
+ * Inspect a raw outcome and optionally re-classify it. Return `undefined` (or
+ * nothing) to leave it unchanged.
+ */
+export type ToolResultClassifier = (outcome: ToolCallOutcome, context: ToolResultContext) => ToolResultClassification | void | undefined;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,0DAA0D;AAC1D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,iBAAiB,KACvB,wBAAwB,GAAG,IAAI,GAAG,SAAS,CAAC"}

package/dist/result.js

@@ -0,0 +1,17 @@
+/**
+ * Result classification.
+ *
+ * A client's transport may report a tool call as "ok" while the server has, in
+ * fact, signalled a *logical* failure in-band — for example a JSON envelope with
+ * `status: "error"` instead of the protocol-level `isError` flag. Left alone,
+ * that outcome is recorded as a success, which poisons every derived signal:
+ * failure rate, insights, routing, drift.
+ *
+ * A `ToolResultClassifier` is the seam that corrects this. It runs on each
+ * execution *attempt*, before the outcome is recorded (and therefore before the
+ * retry decision), so a reclassified failure can also trigger a retry. It is
+ * advisory in the same sense as the rest of Adaptive MCP: the host opts in by
+ * supplying a classifier; returning `undefined` leaves the outcome untouched.
+ */
+export {};
+//# sourceMappingURL=result.js.map

package/dist/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/types.d.ts

@@ -28,13 +28,30 @@ export interface ToolExecutionEvent {
     requestId?: string;
     timestamp: string;
     durationMs?: number;
+    /** Total execution attempts (1 = no retry); for retry-rate metrics. */
+    attempts?: number;
     status: ToolStatus;
     input?: unknown;
     output?: unknown;
     error?: ToolError;
     model?: string;
     cost?: CostInfo;
+    /**
+     * The decoding Adaptive MCP actually applied to the completion that produced
+     * this call. Recording the *resolved* values + `resolverVersion` keeps past
+     * decisions reproducible after the resolver's tables change (ROADMAP 8d).
+     */
+    decoding?: ToolDecoding;
+    /** Token usage for that completion, when the host knows it. */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
     metadata?: Record<string, unknown>;
+    /** Parent node ID in the execution graph (for DAG construction) */
+    parentId?: string;
+    /** Human-readable workflow name (e.g., "deploy_release") */
+    workflowId?: string;
 }
 export type InsightSource = "telemetry" | "evaluation" | "human" | "memory";
 /**
@@ -43,6 +60,7 @@ export type InsightSource = "telemetry" | "evaluation" | "human" | "memory";
  */
 export interface Insight {
     toolName: string;
+    serverName?: string;
     key: string;
     value: unknown;
     confidence: number;
@@ -51,29 +69,154 @@ export interface Insight {
     sampleSize?: number;
 }
 export type RiskLevel = "low" | "medium" | "high";
+/**
+ * Core MCP `ToolAnnotations` (the `annotations` object on a tool in
+ * `tools/list`). Adaptive MCP maps its *static* risk onto these native hints so
+ * hosts don't have to learn a parallel taxonomy. See `riskToToolAnnotations`.
+ */
+export interface ToolAnnotationsLike {
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
+/**
+ * Map an Adaptive MCP static `risk` level onto core MCP `ToolAnnotations`.
+ *
+ * The MCP spec says clients MUST treat `ToolAnnotations` as untrusted unless
+ * from a trusted server, so this is advisory — but it rides the host's native,
+ * already-parsed risk signal (higher uptake than a custom `risk` field). The
+ * server-published tools-metadata resource keeps `risk` for the *learned/
+ * observed* dimension only (e.g. "observed flaky / costly in practice"), which
+ * core hints cannot express. See doubts.md §10/§11 (Strategy 2 of the hybrid).
+ */
+export declare function riskToToolAnnotations(risk?: RiskLevel): ToolAnnotationsLike;
 /**
  * Written metadata attached to a tool by a human or operator.
+ *
+ * `risk` here is the *static* operator-assigned risk. Per the governance hybrid
+ * (doubts.md §11), static risk SHOULD be projected onto core `Tool.annotations`
+ * via `riskToToolAnnotations` rather than emitted in the resource; the resource's
+ * `annotation.risk` is reserved for learned/observed risk. `owner`/`tags`/
+ * `description` are non-governance metadata with no core-MCP equivalent.
  */
 export interface Annotation {
     toolName: string;
+    serverName?: string;
     risk?: RiskLevel;
     owner?: string;
     tags?: string[];
     description?: string;
     metadata?: Record<string, unknown>;
 }
-export type RecommendationType = "model" | "approval" | "workflow" | "routing";
+export type RecommendationType = "model" | "approval" | "workflow" | "routing" | "sampling" | "decoding";
 /**
  * A suggested adaptation derived from accumulated knowledge.
  */
 export interface Recommendation {
     toolName: string;
+    serverName?: string;
     type: RecommendationType;
     payload: unknown;
     rationale: string;
     confidence: number;
     generatedAt: string;
 }
+/**
+ * Payload shape for `Recommendation.type === "sampling"`: suggested LLM
+ * sampling parameters for the *next* generation turn involving this tool.
+ * All fields optional — an advisor only emits the parameters it has an
+ * opinion about; a host applying this should treat an absent field as "no
+ * change from your own default," never as "set to undefined/null."
+ *
+ * Advisory only: nothing in this repo makes an LLM completion call, so this
+ * payload has no effect unless a host reads it and applies it to its own
+ * request.
+ *
+ * @deprecated Superseded by `DecodingProfile` + `DecodingResolver` (Phase 8,
+ * see docs/ROADMAP.md and docs/doubts.md §13 D5). Kept exported and working —
+ * a shipped public shape shouldn't break existing consumers for a rename —
+ * but new code should produce/consume `DecodingRecommendation` instead. Will
+ * be removed at the next `SPEC_VERSION` major bump.
+ */
+export interface SamplingRecommendationPayload {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    presencePenalty?: number;
+    repetitionPenalty?: number;
+}
+/**
+ * A symbolic, backend-agnostic decoding intent. `DecodingAdvisor` emits this
+ * instead of raw sampling numbers — nothing backend-specific belongs here.
+ * `DecodingResolver` is the only thing that translates it into concrete
+ * knobs for a specific backend. See docs/doubts.md §13 D1.
+ */
+export interface DecodingProfile {
+    id: "deterministic" | "balanced" | "creative";
+}
+/**
+ * Which decoding knobs a specific model/inference backend actually exposes.
+ * `DecodingResolver` uses this to translate a `DecodingProfile` into
+ * `ResolvedDecodingSettings`, dropping (never approximating) knobs a backend
+ * doesn't support — e.g. `minP` and `topP` aren't equivalent, so one is never
+ * substituted for the other.
+ */
+export interface ModelCapabilities {
+    supports: {
+        temperature?: boolean;
+        topP?: boolean;
+        topK?: boolean;
+        minP?: boolean;
+        presencePenalty?: boolean;
+        repetitionPenalty?: boolean;
+        frequencyPenalty?: boolean;
+    };
+}
+/**
+ * Concrete, backend-specific decoding parameters produced by a
+ * `DecodingResolver`. Superset of the deprecated `SamplingRecommendationPayload`
+ * (adds `minP`/`frequencyPenalty`) — all fields optional, absent means "no
+ * opinion," never "set to null."
+ */
+export interface ResolvedDecodingSettings {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    minP?: number;
+    presencePenalty?: number;
+    repetitionPenalty?: number;
+    frequencyPenalty?: number;
+}
+/**
+ * What `DecodingAdvisor` + `DecodingResolver` jointly produce: a suggested
+ * decoding profile, its concrete resolved settings for a specific backend,
+ * the resolver version that produced them (so past decisions stay
+ * reproducible after the resolver's tables change), and enough evidence
+ * (`confidence`/`reasons`) for a host to decide whether to trust it.
+ *
+ * Advisory only, same as `SamplingRecommendationPayload` — nothing here is
+ * auto-applied; a host reads this and chooses whether to act on it.
+ */
+export interface DecodingRecommendation {
+    profile: DecodingProfile;
+    resolved: ResolvedDecodingSettings;
+    resolverVersion: string;
+    confidence: number;
+    reasons: string[];
+}
+/**
+ * The decoding actually applied to a completion, as stored on a
+ * `ToolExecutionEvent` (ROADMAP 8d). A flattened `DecodingRecommendation`:
+ * the profile id, the concrete knobs, and the resolver version that produced
+ * them.
+ */
+export interface ToolDecoding {
+    profile: DecodingProfile["id"];
+    resolverVersion: string;
+    resolved: ResolvedDecodingSettings;
+}
 /**
  * The store record for a tool, persisted in SQLite.
  * The YAML tools-metadata view is derived from this record.
@@ -94,6 +237,160 @@ export interface ToolStats {
     avgDurationMs: number | null;
     totalCost: number;
     lastObservedAt: string | null;
+    /** Average output tokens per invocation (for context cost tracking) */
+    avgOutputTokens?: number;
+}
+/**
+ * A bounded dimension tuple for a metric cell. Keys with undefined values are
+ * omitted. Kept open-ended (`[key]`) so new dimensions don't need a migration;
+ * cardinality is bounded by the host (models from its catalog, 3 decoding
+ * profiles, few resolver versions).
+ */
+export interface MetricDimensions {
+    model?: string;
+    decodingProfile?: string;
+    resolverVersion?: string;
+    [key: string]: string | undefined;
+}
+/**
+ * A pre-aggregated metric cell: events folded into a bounded dimension tuple and
+ * window. This is how Adaptive MCP keeps *rich, queryable* metadata without a
+ * raw events table — counters, sums, a fixed-bucket duration histogram, EWMA
+ * recency, and a bounded exemplar ring, instead of every event.
+ */
+export interface MetricCell {
+    toolName: string;
+    serverName?: string;
+    /** Retention window key; `"all"` is the lifetime aggregate. */
+    window: string;
+    dimensions: MetricDimensions;
+    invocations: number;
+    failures: number;
+    /** Sum of execution attempts (> invocations when retries happened). */
+    attempts: number;
+    /** Error-code → count. */
+    errorCodes: Record<string, number>;
+    durationSum: number;
+    durationCount: number;
+    /** Counts per fixed duration bucket (ms); see the store's bucket bounds. */
+    durationHistogram: number[];
+    tokenInSum: number;
+    tokenOutSum: number;
+    tokenCount: number;
+    costSum: number;
+    /** Exponentially-weighted failure rate / duration, for recency-aware drift. */
+    ewmaFailureRate?: number;
+    ewmaDurationMs?: number;
+    firstSeen: string;
+    lastSeen: string;
+    /** Bounded ids of the most recent contributing events (drill-down). */
+    exemplars: string[];
+}
+/**
+ * A single node in the execution graph (DAG).
+ * Each tool invocation becomes a node with parent/children relationships.
+ */
+export interface ExecutionNode {
+    id: string;
+    toolName: string;
+    serverName?: string;
+    sessionId: string;
+    workflowId?: string;
+    parentId?: string;
+    childrenIds: string[];
+    timestamp: string;
+    durationMs?: number;
+    status: ToolStatus;
+    input?: unknown;
+    output?: unknown;
+    error?: ToolError;
+    model?: string;
+    cost?: CostInfo;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Graph analysis results.
+ */
+export interface CriticalPathResult {
+    path: ExecutionNode[];
+    totalDurationMs: number;
+}
+export interface Bottleneck {
+    node: ExecutionNode;
+    impactScore: number;
+    reason: "duration" | "fan_out" | "failure_rate" | "cost";
+}
+export interface FanOutReport {
+    maxFanOut: number;
+    avgFanOut: number;
+    parallelizableNodes: ExecutionNode[];
+    sequentialChains: ExecutionNode[][];
+}
+/**
+ * A recurring structural anti-pattern detected in a session's graph.
+ * Deliberately limited to two named shapes rather than general subgraph
+ * isomorphism (NP-hard, unnecessary for small execution DAGs).
+ */
+export interface AntiPattern {
+    type: "sequential_bottleneck" | "diamond_dependency";
+    nodes: ExecutionNode[];
+    severity: number;
+}
+export interface FailureCascade {
+    rootCause: ExecutionNode;
+    affectedNodes: ExecutionNode[];
+    blastRadius: number;
+}
+/**
+ * Ancestor-based causal ordering among the failed nodes of a session: a
+ * failed node with no failed ancestor is a root cause; a failed node
+ * downstream of a failed ancestor is a symptom of the nearest one. This is
+ * NOT counterfactual causal inference (which would require replaying
+ * execution without the trigger) — it's graph-ancestry ordering over the
+ * failures actually recorded.
+ */
+export interface CausalCascade {
+    rootCauses: ExecutionNode[];
+    symptoms: Array<{
+        node: ExecutionNode;
+        causedBy: ExecutionNode;
+    }>;
+    blastRadius: number;
+}
+export interface CostBreakdown {
+    totalCost: number;
+    byTool: Record<string, number>;
+    byNode: Record<string, number>;
+    criticalPathCost: number;
+}
+export interface WorkflowStats {
+    workflowId: string;
+    totalExecutions: number;
+    successRate: number;
+    avgDurationMs: number;
+    avgCost: number;
+    commonPatterns: WorkflowPattern[];
+}
+export interface WorkflowPattern {
+    pattern: string;
+    frequency: number;
+    avgDurationMs: number;
+    successRate: number;
+}
+/**
+ * A heuristic forecast for an in-progress workflow session, extrapolated
+ * from historical runs of the same workflow. NOT a trained/statistical
+ * model — a ratio-vs-baseline projection, in the same spirit as
+ * `detectAnomalies`'s duration/cost ratio checks.
+ */
+export interface WorkflowForecast {
+    workflowId: string;
+    /** Nodes seen so far / historical avg node count for this workflow, capped at 1. */
+    progressRatio: number;
+    projectedDurationMs: number;
+    projectedCost: number;
+    /** Blend of historical failure rate and this session's own failures observed so far. */
+    failureProbability: number;
 }
 /**
  * The persistence boundary for Adaptive MCP.
@@ -102,15 +399,27 @@ export interface ToolStats {
  * backend (SQLite, Postgres, in-memory, remote) can be swapped without touching
  * the middleware. `MemoryStore` in `@adaptivemcp/memory` is the reference
  * implementation.
+ *
+ * Records are identified by the `(toolName, serverName)` pair, not `toolName`
+ * alone: two different MCP servers may expose a tool with the same name, and
+ * without the server in the key their records would collide. `serverName` is
+ * optional on read/write because not every call site knows which server it's
+ * dealing with; when omitted, lookups fall back to the most recently updated
+ * record with that `toolName` (ambiguous only if the same tool name is in use
+ * across multiple servers).
  */
 export interface Store {
     /** Close the underlying backend and release resources. */
     close(): void;
     /** Ensure a tool record exists, seeding it with an empty annotation. */
     ensureTool(toolName: string, serverName?: string): ToolRecord;
-    /** Read a single tool record, or `undefined` if it has never been observed. */
-    getTool(toolName: string): ToolRecord | undefined;
-    /** Read every tool record, ordered by tool name. */
+    /**
+     * Read a single tool record, or `undefined` if it has never been observed.
+     * Pass `serverName` to disambiguate when the same tool name may exist on
+     * multiple servers; otherwise the most recently updated match is returned.
+     */
+    getTool(toolName: string, serverName?: string): ToolRecord | undefined;
+    /** Read every tool record, ordered by tool name then server name. */
     allTools(): ToolRecord[];
     /** Persist a human-written annotation (the static metadata layer). */
     setAnnotation(annotation: Annotation): ToolRecord;
@@ -123,8 +432,39 @@ export interface Store {
      * orchestration, and approval packages so each adaptation pass recomputes its
      * own recommendations instead of appending duplicates on every observation.
      */
-    clearRecommendations(toolName: string, type: RecommendationType): ToolRecord;
+    clearRecommendations(toolName: string, type: RecommendationType, serverName?: string): ToolRecord;
     /** Fold a tool execution event into the persisted stats. */
     recordExecution(event: ToolExecutionEvent): ToolRecord;
+    /**
+     * Read pre-aggregated metric cells (bounded dimensional rollups folded from
+     * events). Optional: a backend without the rollup may omit it, in which case
+     * callers should fall back to sample-level data.
+     */
+    metricCells?(options?: {
+        toolName?: string;
+        serverName?: string;
+    }): MetricCell[];
+    /** Record an execution node in the graph. */
+    recordExecutionNode?(node: ExecutionNode): ExecutionNode;
+    /** Get an execution node by ID. */
+    getExecutionNode?(id: string): ExecutionNode | undefined;
+    /** Get all nodes for a session. */
+    getNodesBySession?(sessionId: string): ExecutionNode[];
+    /** Get all nodes for a workflow (across sessions). */
+    getNodesByWorkflow?(workflowId: string): ExecutionNode[];
+    /** Get every distinct workflow ID that has at least one recorded execution node. */
+    getWorkflowIds?(): string[];
+    /** Get every distinct session ID that has at least one recorded execution node. */
+    getSessionIds?(): string[];
+    /** Get children of a node. */
+    getChildren?(parentId: string): ExecutionNode[];
+    /** Get parent of a node. */
+    getParent?(childId: string): ExecutionNode | undefined;
+    /** Get root nodes (no parent) for a session. */
+    getRootNodes?(sessionId: string): ExecutionNode[];
+    /** Get leaf nodes (no children) for a session. */
+    getLeafNodes?(sessionId: string): ExecutionNode[];
+    /** Update children IDs of a parent node. */
+    updateChildrenIds?(parentId: string, childrenIds: string[]): void;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -5,5 +5,26 @@
  * They intentionally avoid coupling to shell commands, filesystems, processes,
  * sockets, or HTTP requests — those remain implementation details of MCP servers.
  */
-export {};
+/**
+ * Map an Adaptive MCP static `risk` level onto core MCP `ToolAnnotations`.
+ *
+ * The MCP spec says clients MUST treat `ToolAnnotations` as untrusted unless
+ * from a trusted server, so this is advisory — but it rides the host's native,
+ * already-parsed risk signal (higher uptake than a custom `risk` field). The
+ * server-published tools-metadata resource keeps `risk` for the *learned/
+ * observed* dimension only (e.g. "observed flaky / costly in practice"), which
+ * core hints cannot express. See doubts.md §10/§11 (Strategy 2 of the hybrid).
+ */
+export function riskToToolAnnotations(risk) {
+    switch (risk) {
+        case "high":
+            return { destructiveHint: true, openWorldHint: true };
+        case "medium":
+            return { idempotentHint: false, openWorldHint: true };
+        case "low":
+            return { readOnlyHint: true };
+        default:
+            return {};
+    }
+}
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmFH;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAgB;IACpD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;QACxD,KAAK,QAAQ;YACX,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;QACxD,KAAK,KAAK;YACR,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QAChC;YACE,OAAO,EAAE,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptivemcp/spec",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Extension identifiers, event schemas, and shared types for Adaptive MCP.",
   "license": "MIT",
   "type": "module",
@@ -17,12 +17,12 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "vitest run --config ../../vitest.config.ts"
-  },
   "devDependencies": {
     "typescript": "^5.6.0",
     "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --config ../../vitest.config.ts"
   }
-}
+}