@cavi-ai/api-client 0.1.0

package/package.json

@@ -0,0 +1,152 @@
+{
+  "name": "@cavi-ai/api-client",
+  "version": "0.1.0",
+  "description": "Gateway-agnostic TypeScript client for agent runtimes — one HTTP + WebSocket surface, provider adapters, and graceful degradation across workspaces, UIs, and gateways",
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "sasan1200 <sasan.sotoodehfar@gmail.com>",
+  "homepage": "https://github.com/sasan1200/cavi-api-client#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sasan1200/cavi-api-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sasan1200/cavi-api-client/issues"
+  },
+  "keywords": [
+    "api-client",
+    "gateway",
+    "websocket",
+    "rpc",
+    "sse",
+    "typescript",
+    "esm",
+    "agent",
+    "llm",
+    "hermes",
+    "openclaw",
+    "fetch",
+    "react",
+    "cavi"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "ARCHITECTURE.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "docs",
+    "dist",
+    "!dist/test-support",
+    "!dist/__tests__",
+    "src",
+    "!src/__tests__",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./core/http": {
+      "types": "./dist/core/http/index.d.ts",
+      "import": "./dist/core/http/index.js",
+      "default": "./dist/core/http/index.js"
+    },
+    "./core/data": {
+      "types": "./dist/core/data/index.d.ts",
+      "import": "./dist/core/data/index.js",
+      "default": "./dist/core/data/index.js"
+    },
+    "./core/runtime": {
+      "types": "./dist/core/runtime/index.d.ts",
+      "import": "./dist/core/runtime/index.js",
+      "default": "./dist/core/runtime/index.js"
+    },
+    "./core/sse": {
+      "types": "./dist/core/sse/index.d.ts",
+      "import": "./dist/core/sse/index.js",
+      "default": "./dist/core/sse/index.js"
+    },
+    "./core/ws": {
+      "types": "./dist/core/ws/index.d.ts",
+      "import": "./dist/core/ws/index.js",
+      "default": "./dist/core/ws/index.js"
+    },
+    "./core/gateway": {
+      "types": "./dist/core/gateway/index.d.ts",
+      "import": "./dist/core/gateway/index.js",
+      "default": "./dist/core/gateway/index.js"
+    },
+    "./core/env": {
+      "types": "./dist/core/env/index.d.ts",
+      "import": "./dist/core/env/index.js",
+      "default": "./dist/core/env/index.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts/index.d.ts",
+      "import": "./dist/contracts/index.js",
+      "default": "./dist/contracts/index.js"
+    },
+    "./extensions/cavi": {
+      "types": "./dist/extensions/cavi/index.d.ts",
+      "import": "./dist/extensions/cavi/index.js",
+      "default": "./dist/extensions/cavi/index.js"
+    },
+    "./providers/hermes": {
+      "types": "./dist/providers/hermes/index.d.ts",
+      "import": "./dist/providers/hermes/index.js",
+      "default": "./dist/providers/hermes/index.js"
+    },
+    "./providers/openclaw": {
+      "types": "./dist/providers/openclaw/index.d.ts",
+      "import": "./dist/providers/openclaw/index.js",
+      "default": "./dist/providers/openclaw/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "default": "./dist/react/index.js"
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.15",
+    "@vitest/coverage-v8": "^4.1.5",
+    "husky": "^9.1.7",
+    "jsdom": "^29.1.1",
+    "markdownlint-cli2": "^0.17.2",
+    "react": "^19.2.6",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.14",
+    "vitest": "^4.1.5"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "lint:md": "markdownlint-cli2",
+    "typecheck": "tsc --noEmit",
+    "verify": "pnpm test && pnpm run build && pnpm run lint:md && HUSKY=0 pnpm pack --dry-run",
+    "release:dry": "pnpm run verify && HUSKY=0 pnpm publish --access public --no-git-checks --dry-run",
+    "release": "pnpm publish --access public"
+  }
+}

package/src/contracts/index.ts

@@ -0,0 +1,4 @@
+export * from "./paths.js";
+export * from "./surfaces.js";
+export * from "./resolve.js";
+export * from "./team-manifest.js";

package/src/contracts/paths.ts

@@ -0,0 +1,126 @@
+export function appendHttpQuery(
+  path: string,
+  query?: Record<string, string | number | boolean | undefined>,
+): string {
+  if (!query) return path;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== undefined) params.set(key, String(value));
+  }
+  const suffix = params.toString();
+  return suffix ? `${path}?${suffix}` : path;
+}
+
+export const HERMES_API_ENDPOINT_TEMPLATES = {
+  ecgSharedFiles: "/api/v1/files?agent={agent}&folder={folder}",
+  runApproval: "/v1/runs/{run_id}/approval",
+} as const;
+
+export const HERMES_API_ENDPOINTS = {
+  health: "/health",
+  healthDetailed: "/health/detailed",
+  models: "/v1/models",
+  capabilities: "/v1/capabilities",
+  chatCompletions: "/v1/chat/completions",
+  responses: "/v1/responses",
+  response: (responseId: string) => `/v1/responses/${encodeURIComponent(responseId)}`,
+  runs: "/v1/runs",
+  run: (runId: string) => `/v1/runs/${encodeURIComponent(runId)}`,
+  runEvents: (runId: string) => `/v1/runs/${encodeURIComponent(runId)}/events`,
+  runApproval: (runId: string) => `/v1/runs/${encodeURIComponent(runId)}/approval`,
+  runStop: (runId: string) => `/v1/runs/${encodeURIComponent(runId)}/stop`,
+  jobs: "/api/jobs",
+  job: (jobId: string) => `/api/jobs/${encodeURIComponent(jobId)}`,
+} as const;
+
+export const GATEWAY_API_ENDPOINT_TEMPLATES = HERMES_API_ENDPOINT_TEMPLATES;
+export const GATEWAY_API_ENDPOINTS = HERMES_API_ENDPOINTS;
+
+export const GATEWAY_MEDIA_API_BASE_PATH = "/v1/media" as const;
+
+export const GATEWAY_MEDIA_API_ENDPOINTS = {
+  root: GATEWAY_MEDIA_API_BASE_PATH,
+  providers: (kind?: string | null) =>
+    kind
+      ? `${GATEWAY_MEDIA_API_BASE_PATH}/${encodeURIComponent(kind)}/providers`
+      : `${GATEWAY_MEDIA_API_BASE_PATH}/providers`,
+  generate: (kind: string) =>
+    `${GATEWAY_MEDIA_API_BASE_PATH}/${encodeURIComponent(kind)}/generate`,
+  job: (kind: string, jobId: string) =>
+    `${GATEWAY_MEDIA_API_BASE_PATH}/${encodeURIComponent(kind)}/jobs/${encodeURIComponent(jobId)}`,
+  assets: (query?: {
+    kind?: string | null;
+    cursor?: string | null;
+    limit?: number | null;
+  } | null) =>
+    appendHttpQuery(`${GATEWAY_MEDIA_API_BASE_PATH}/assets`, {
+      kind: query?.kind ?? undefined,
+      cursor: query?.cursor ?? undefined,
+      limit: query?.limit ?? undefined,
+    }),
+  asset: (assetId: string) =>
+    `${GATEWAY_MEDIA_API_BASE_PATH}/assets/${encodeURIComponent(assetId)}`,
+} as const;
+
+export const HERMES_MEDIA_API_ENDPOINTS = GATEWAY_MEDIA_API_ENDPOINTS;
+export const OPENCLAW_MEDIA_API_ENDPOINTS = GATEWAY_MEDIA_API_ENDPOINTS;
+
+export const GATEWAY_WIKI_API_BASE_PATH = "/v1/wiki" as const;
+
+export const GATEWAY_WIKI_API_ENDPOINTS = {
+  root: GATEWAY_WIKI_API_BASE_PATH,
+  vaults: `${GATEWAY_WIKI_API_BASE_PATH}/vaults`,
+  vault: (vaultId: string) =>
+    `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}`,
+  tree: (vaultId: string) =>
+    `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/tree`,
+  read: (vaultId: string, path: string) =>
+    appendHttpQuery(
+      `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/read`,
+      { path },
+    ),
+  ingest: (vaultId: string) =>
+    `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/ingest`,
+  compile: (vaultId: string) =>
+    `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/compile`,
+  promote: (vaultId: string) =>
+    `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/promote`,
+  job: (vaultId: string, jobId: string) =>
+    `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/jobs/${encodeURIComponent(jobId)}`,
+  artifact: (vaultId: string, artifactId: string) =>
+    `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/artifacts/${encodeURIComponent(artifactId)}`,
+} as const;
+
+export const HERMES_WIKI_API_ENDPOINTS = GATEWAY_WIKI_API_ENDPOINTS;
+export const OPENCLAW_WIKI_API_ENDPOINTS = GATEWAY_WIKI_API_ENDPOINTS;
+
+export const GATEWAY_SESSION_API_PATHS = {
+  list: "/api/sessions/list",
+  usage: "/api/sessions/usage",
+  preview: "/api/sessions/preview",
+  detail: "/api/sessions/detail",
+  patch: "/api/sessions/patch",
+} as const;
+
+export const GATEWAY_AGENT_CONFIG_API_ENDPOINTS = {
+  profiles: "/api/profiles",
+  config: "/api/config",
+  configDefaults: "/api/config/defaults",
+  configSchema: "/api/config/schema",
+  agentConfigs: "/api/agent-configs",
+  agentConfig: (agentId: string) =>
+    `/api/agent-configs/${encodeURIComponent(agentId)}/config`,
+} as const;
+
+export const HERMES_AGENT_CONFIG_API_ENDPOINTS = GATEWAY_AGENT_CONFIG_API_ENDPOINTS;
+export const OPENCLAW_AGENT_CONFIG_API_ENDPOINTS = GATEWAY_AGENT_CONFIG_API_ENDPOINTS;
+
+export const GATEWAY_PORTAL_API_ENDPOINTS = {
+  config: (portalSlug: string) =>
+    `/api/plugins/portal/${encodeURIComponent(portalSlug)}/config`,
+} as const;
+
+export const GATEWAY_PROBE_ENDPOINTS = {
+  healthz: "/healthz",
+  readyz: "/readyz",
+} as const;

package/src/contracts/resolve.ts

@@ -0,0 +1,42 @@
+import { SURFACE_CONTRACTS } from "./surfaces.js";
+import type { GatewayMode, SurfaceContract } from "./surfaces.js";
+
+export type SurfaceContractMap = Record<string, SurfaceContract>;
+
+export type SurfacePathResolver = (
+  key: string,
+  mode?: GatewayMode,
+  params?: Record<string, string>,
+) => string;
+
+export function resolveSurfaceContractPath(
+  contract: SurfaceContract,
+  mode: GatewayMode = "legacy",
+  params?: Record<string, string>,
+): string {
+  if (mode === "canonical") return contract.canonicalPath(params);
+  return contract.legacyPath
+    ? contract.legacyPath(params)
+    : contract.canonicalPath(params);
+}
+
+export function createSurfacePathResolver(
+  extensionContracts: SurfaceContractMap = {},
+  baseResolver: SurfacePathResolver = resolvePath,
+): SurfacePathResolver {
+  return (key, mode = "legacy", params) => {
+    const contract = extensionContracts[key];
+    if (contract) return resolveSurfaceContractPath(contract, mode, params);
+    return baseResolver(key, mode, params);
+  };
+}
+
+export function resolvePath(
+  key: string,
+  mode: GatewayMode = "legacy",
+  params?: Record<string, string>,
+): string {
+  const contract = SURFACE_CONTRACTS[key];
+  if (!contract) throw new Error(`resolvePath: unknown surface "${key}"`);
+  return resolveSurfaceContractPath(contract, mode, params);
+}

package/src/contracts/surfaces.ts

@@ -0,0 +1,366 @@
+import {
+  GATEWAY_MEDIA_API_ENDPOINTS,
+  GATEWAY_WIKI_API_ENDPOINTS,
+} from "./paths.js";
+import { resolveTeamRoutePath } from "./team-manifest.js";
+
+export type GatewayMode = "legacy" | "canonical";
+
+export type SurfaceContract = {
+  key: string;
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+  canonicalPath: (params?: Record<string, string>) => string;
+  legacyPath?: (params?: Record<string, string>) => string;
+  classification: "gateway-native" | "compatibility-shim" | "blocked";
+  degradation: "hard" | "gap" | "silent";
+  owner: string;
+  note: string;
+};
+
+const p = (params: Record<string, string> | undefined, k: string): string => {
+  const v = params?.[k];
+  if (!v) throw new Error(`SURFACE_CONTRACTS: missing path param "${k}"`);
+  return encodeURIComponent(v);
+};
+
+const raw = (params: Record<string, string> | undefined, k: string): string => {
+  const v = params?.[k];
+  if (!v) throw new Error(`SURFACE_CONTRACTS: missing path param "${k}"`);
+  return v;
+};
+
+export const SURFACE_CONTRACTS: Record<string, SurfaceContract> = {
+  "vault.tree": {
+    key: "vault.tree",
+    method: "GET",
+    legacyPath: () => "/api/obsidian/tree",
+    canonicalPath: () => "/api/obsidian/tree",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "vault/gateway owner",
+    note: "Obsidian vault tree; no native gateway route identified yet.",
+  },
+  "vault.read": {
+    key: "vault.read",
+    method: "GET",
+    legacyPath: () => "/api/obsidian/read",
+    canonicalPath: () => "/api/obsidian/read",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "vault/gateway owner",
+    note: "Obsidian file read; query string appended by caller.",
+  },
+  "gateway.health": {
+    key: "gateway.health",
+    method: "GET",
+    canonicalPath: () => "/health",
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/core contract",
+    note: "Primary reachability check for the selected gateway API server.",
+  },
+  "gateway.healthDetailed": {
+    key: "gateway.healthDetailed",
+    method: "GET",
+    canonicalPath: () => "/health/detailed",
+    classification: "gateway-native",
+    degradation: "gap",
+    owner: "gateway/core contract",
+    note: "Detailed gateway health check; absence is a compatibility gap when basic health/capabilities pass.",
+  },
+  "gateway.capabilities": {
+    key: "gateway.capabilities",
+    method: "GET",
+    canonicalPath: () => "/v1/capabilities",
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/core contract",
+    note: "Authenticated API-server capability proof for saved bearer tokens.",
+  },
+  "gateway.websocket": {
+    key: "gateway.websocket",
+    method: "GET",
+    canonicalPath: () => "/api/ws",
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/core contract",
+    note: "Dashboard/TUI JSON-RPC websocket path for chat, sessions, logs, and health snapshots.",
+  },
+  "gateway.mediaProviders": {
+    key: "gateway.mediaProviders",
+    method: "GET",
+    canonicalPath: () => GATEWAY_MEDIA_API_ENDPOINTS.providers(),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native media provider inventory shared by audio, image, video, and music generation.",
+  },
+  "gateway.mediaAudioGenerate": {
+    key: "gateway.mediaAudioGenerate",
+    method: "POST",
+    canonicalPath: () => GATEWAY_MEDIA_API_ENDPOINTS.generate("audio"),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native audio generation route.",
+  },
+  "gateway.mediaImageGenerate": {
+    key: "gateway.mediaImageGenerate",
+    method: "POST",
+    canonicalPath: () => GATEWAY_MEDIA_API_ENDPOINTS.generate("image"),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native image generation route.",
+  },
+  "gateway.mediaVideoGenerate": {
+    key: "gateway.mediaVideoGenerate",
+    method: "POST",
+    canonicalPath: () => GATEWAY_MEDIA_API_ENDPOINTS.generate("video"),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native video generation route.",
+  },
+  "gateway.mediaMusicGenerate": {
+    key: "gateway.mediaMusicGenerate",
+    method: "POST",
+    canonicalPath: () => GATEWAY_MEDIA_API_ENDPOINTS.generate("music"),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native music generation route.",
+  },
+  "gateway.mediaJob": {
+    key: "gateway.mediaJob",
+    method: "GET",
+    canonicalPath: (params) =>
+      GATEWAY_MEDIA_API_ENDPOINTS.job(raw(params, "kind"), raw(params, "jobId")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native media job status route.",
+  },
+  "gateway.mediaAssets": {
+    key: "gateway.mediaAssets",
+    method: "GET",
+    canonicalPath: (params) =>
+      GATEWAY_MEDIA_API_ENDPOINTS.assets({ kind: params?.kind }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native media asset inventory route.",
+  },
+  "gateway.mediaAssetCreate": {
+    key: "gateway.mediaAssetCreate",
+    method: "POST",
+    canonicalPath: (params) =>
+      GATEWAY_MEDIA_API_ENDPOINTS.assets({ kind: params?.kind }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native media asset creation route.",
+  },
+  "gateway.mediaAsset": {
+    key: "gateway.mediaAsset",
+    method: "GET",
+    canonicalPath: (params) =>
+      GATEWAY_MEDIA_API_ENDPOINTS.asset(raw(params, "assetId")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native media asset retrieval and metadata route.",
+  },
+  "gateway.mediaAssetDelete": {
+    key: "gateway.mediaAssetDelete",
+    method: "DELETE",
+    canonicalPath: (params) =>
+      GATEWAY_MEDIA_API_ENDPOINTS.asset(raw(params, "assetId")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/media contract",
+    note: "Gateway-native media asset deletion route.",
+  },
+  "gateway.wikiVaults": {
+    key: "gateway.wikiVaults",
+    method: "GET",
+    canonicalPath: () => GATEWAY_WIKI_API_ENDPOINTS.vaults,
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/wiki contract",
+    note: "Gateway-native wiki vault inventory for external Obsidian/QMD plugin vaults.",
+  },
+  "gateway.wikiTree": {
+    key: "gateway.wikiTree",
+    method: "GET",
+    canonicalPath: (params) => GATEWAY_WIKI_API_ENDPOINTS.tree(raw(params, "vaultId")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/wiki contract",
+    note: "Gateway-native wiki tree route.",
+  },
+  "gateway.wikiRead": {
+    key: "gateway.wikiRead",
+    method: "GET",
+    canonicalPath: (params) =>
+      GATEWAY_WIKI_API_ENDPOINTS.read(raw(params, "vaultId"), raw(params, "path")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/wiki contract",
+    note: "Gateway-native wiki page read route.",
+  },
+  "gateway.wikiIngest": {
+    key: "gateway.wikiIngest",
+    method: "POST",
+    canonicalPath: (params) =>
+      GATEWAY_WIKI_API_ENDPOINTS.ingest(raw(params, "vaultId")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/wiki contract",
+    note: "Gateway-native wiki ingest route.",
+  },
+  "gateway.wikiCompile": {
+    key: "gateway.wikiCompile",
+    method: "POST",
+    canonicalPath: (params) =>
+      GATEWAY_WIKI_API_ENDPOINTS.compile(raw(params, "vaultId")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/wiki contract",
+    note: "Gateway-native QMD compile route.",
+  },
+  "gateway.wikiPromote": {
+    key: "gateway.wikiPromote",
+    method: "POST",
+    canonicalPath: (params) =>
+      GATEWAY_WIKI_API_ENDPOINTS.promote(raw(params, "vaultId")),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/wiki contract",
+    note: "Gateway-native wiki promotion route.",
+  },
+  "hermes.runs": {
+    key: "hermes.runs",
+    method: "POST",
+    canonicalPath: () => "/v1/runs",
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "providers/hermes",
+    note: "Hermes REST/SSE run creation endpoint.",
+  },
+  "kanban.tasks": {
+    key: "kanban.tasks",
+    method: "POST",
+    canonicalPath: () => "/api/plugins/kanban/tasks",
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/kanban owner",
+    note: "Kanban task creation endpoint for workspace and operator surfaces.",
+  },
+  "kanban.board": {
+    key: "kanban.board",
+    method: "GET",
+    canonicalPath: () => "/api/plugins/kanban/board",
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/kanban owner",
+    note: "Unified Kanban board endpoint.",
+  },
+  "team.kanban": {
+    key: "team.kanban",
+    method: "GET",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("kanban", { teamId: raw(params, "teamId") }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic team Kanban route derived from the team manifest identity.",
+  },
+  "team.runs": {
+    key: "team.runs",
+    method: "GET",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("runs", { teamId: raw(params, "teamId") }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic team runs route derived from the team manifest identity.",
+  },
+  "team.config": {
+    key: "team.config",
+    method: "GET",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("config", { teamId: raw(params, "teamId") }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic team config route derived from the team manifest identity.",
+  },
+  "team.workspace": {
+    key: "team.workspace",
+    method: "GET",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("workspace", {
+        teamId: raw(params, "teamId"),
+        workspacePath: raw(params, "workspacePath"),
+      }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic whitelisted team workspace route.",
+  },
+  "team.action": {
+    key: "team.action",
+    method: "POST",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("action", {
+        teamId: raw(params, "teamId"),
+        actionId: raw(params, "actionId"),
+      }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic team action route derived from a manifest action contract.",
+  },
+  "team.agent.config": {
+    key: "team.agent.config",
+    method: "GET",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("agent.config", {
+        teamId: raw(params, "teamId"),
+        agentId: raw(params, "agentId"),
+      }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic team member config route.",
+  },
+  "team.agent.action": {
+    key: "team.agent.action",
+    method: "POST",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("agent.action", {
+        teamId: raw(params, "teamId"),
+        agentId: raw(params, "agentId"),
+        actionId: raw(params, "actionId"),
+      }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic team member action route.",
+  },
+  "team.agent.workspace": {
+    key: "team.agent.workspace",
+    method: "GET",
+    canonicalPath: (params) =>
+      resolveTeamRoutePath("agent.workspace", {
+        teamId: raw(params, "teamId"),
+        agentId: raw(params, "agentId"),
+        workspacePath: raw(params, "workspacePath"),
+      }),
+    classification: "gateway-native",
+    degradation: "hard",
+    owner: "gateway/team contract",
+    note: "Agnostic whitelisted team-member workspace route.",
+  },
+};