@cavi-ai/api-client 0.1.0

package/dist/contracts/paths.d.ts

@@ -0,0 +1,154 @@
+export declare function appendHttpQuery(path: string, query?: Record<string, string | number | boolean | undefined>): string;
+export declare const HERMES_API_ENDPOINT_TEMPLATES: {
+    readonly ecgSharedFiles: "/api/v1/files?agent={agent}&folder={folder}";
+    readonly runApproval: "/v1/runs/{run_id}/approval";
+};
+export declare const HERMES_API_ENDPOINTS: {
+    readonly health: "/health";
+    readonly healthDetailed: "/health/detailed";
+    readonly models: "/v1/models";
+    readonly capabilities: "/v1/capabilities";
+    readonly chatCompletions: "/v1/chat/completions";
+    readonly responses: "/v1/responses";
+    readonly response: (responseId: string) => string;
+    readonly runs: "/v1/runs";
+    readonly run: (runId: string) => string;
+    readonly runEvents: (runId: string) => string;
+    readonly runApproval: (runId: string) => string;
+    readonly runStop: (runId: string) => string;
+    readonly jobs: "/api/jobs";
+    readonly job: (jobId: string) => string;
+};
+export declare const GATEWAY_API_ENDPOINT_TEMPLATES: {
+    readonly ecgSharedFiles: "/api/v1/files?agent={agent}&folder={folder}";
+    readonly runApproval: "/v1/runs/{run_id}/approval";
+};
+export declare const GATEWAY_API_ENDPOINTS: {
+    readonly health: "/health";
+    readonly healthDetailed: "/health/detailed";
+    readonly models: "/v1/models";
+    readonly capabilities: "/v1/capabilities";
+    readonly chatCompletions: "/v1/chat/completions";
+    readonly responses: "/v1/responses";
+    readonly response: (responseId: string) => string;
+    readonly runs: "/v1/runs";
+    readonly run: (runId: string) => string;
+    readonly runEvents: (runId: string) => string;
+    readonly runApproval: (runId: string) => string;
+    readonly runStop: (runId: string) => string;
+    readonly jobs: "/api/jobs";
+    readonly job: (jobId: string) => string;
+};
+export declare const GATEWAY_MEDIA_API_BASE_PATH: "/v1/media";
+export declare const GATEWAY_MEDIA_API_ENDPOINTS: {
+    readonly root: "/v1/media";
+    readonly providers: (kind?: string | null) => string;
+    readonly generate: (kind: string) => string;
+    readonly job: (kind: string, jobId: string) => string;
+    readonly assets: (query?: {
+        kind?: string | null;
+        cursor?: string | null;
+        limit?: number | null;
+    } | null) => string;
+    readonly asset: (assetId: string) => string;
+};
+export declare const HERMES_MEDIA_API_ENDPOINTS: {
+    readonly root: "/v1/media";
+    readonly providers: (kind?: string | null) => string;
+    readonly generate: (kind: string) => string;
+    readonly job: (kind: string, jobId: string) => string;
+    readonly assets: (query?: {
+        kind?: string | null;
+        cursor?: string | null;
+        limit?: number | null;
+    } | null) => string;
+    readonly asset: (assetId: string) => string;
+};
+export declare const OPENCLAW_MEDIA_API_ENDPOINTS: {
+    readonly root: "/v1/media";
+    readonly providers: (kind?: string | null) => string;
+    readonly generate: (kind: string) => string;
+    readonly job: (kind: string, jobId: string) => string;
+    readonly assets: (query?: {
+        kind?: string | null;
+        cursor?: string | null;
+        limit?: number | null;
+    } | null) => string;
+    readonly asset: (assetId: string) => string;
+};
+export declare const GATEWAY_WIKI_API_BASE_PATH: "/v1/wiki";
+export declare const GATEWAY_WIKI_API_ENDPOINTS: {
+    readonly root: "/v1/wiki";
+    readonly vaults: "/v1/wiki/vaults";
+    readonly vault: (vaultId: string) => string;
+    readonly tree: (vaultId: string) => string;
+    readonly read: (vaultId: string, path: string) => string;
+    readonly ingest: (vaultId: string) => string;
+    readonly compile: (vaultId: string) => string;
+    readonly promote: (vaultId: string) => string;
+    readonly job: (vaultId: string, jobId: string) => string;
+    readonly artifact: (vaultId: string, artifactId: string) => string;
+};
+export declare const HERMES_WIKI_API_ENDPOINTS: {
+    readonly root: "/v1/wiki";
+    readonly vaults: "/v1/wiki/vaults";
+    readonly vault: (vaultId: string) => string;
+    readonly tree: (vaultId: string) => string;
+    readonly read: (vaultId: string, path: string) => string;
+    readonly ingest: (vaultId: string) => string;
+    readonly compile: (vaultId: string) => string;
+    readonly promote: (vaultId: string) => string;
+    readonly job: (vaultId: string, jobId: string) => string;
+    readonly artifact: (vaultId: string, artifactId: string) => string;
+};
+export declare const OPENCLAW_WIKI_API_ENDPOINTS: {
+    readonly root: "/v1/wiki";
+    readonly vaults: "/v1/wiki/vaults";
+    readonly vault: (vaultId: string) => string;
+    readonly tree: (vaultId: string) => string;
+    readonly read: (vaultId: string, path: string) => string;
+    readonly ingest: (vaultId: string) => string;
+    readonly compile: (vaultId: string) => string;
+    readonly promote: (vaultId: string) => string;
+    readonly job: (vaultId: string, jobId: string) => string;
+    readonly artifact: (vaultId: string, artifactId: string) => string;
+};
+export declare const GATEWAY_SESSION_API_PATHS: {
+    readonly list: "/api/sessions/list";
+    readonly usage: "/api/sessions/usage";
+    readonly preview: "/api/sessions/preview";
+    readonly detail: "/api/sessions/detail";
+    readonly patch: "/api/sessions/patch";
+};
+export declare const GATEWAY_AGENT_CONFIG_API_ENDPOINTS: {
+    readonly profiles: "/api/profiles";
+    readonly config: "/api/config";
+    readonly configDefaults: "/api/config/defaults";
+    readonly configSchema: "/api/config/schema";
+    readonly agentConfigs: "/api/agent-configs";
+    readonly agentConfig: (agentId: string) => string;
+};
+export declare const HERMES_AGENT_CONFIG_API_ENDPOINTS: {
+    readonly profiles: "/api/profiles";
+    readonly config: "/api/config";
+    readonly configDefaults: "/api/config/defaults";
+    readonly configSchema: "/api/config/schema";
+    readonly agentConfigs: "/api/agent-configs";
+    readonly agentConfig: (agentId: string) => string;
+};
+export declare const OPENCLAW_AGENT_CONFIG_API_ENDPOINTS: {
+    readonly profiles: "/api/profiles";
+    readonly config: "/api/config";
+    readonly configDefaults: "/api/config/defaults";
+    readonly configSchema: "/api/config/schema";
+    readonly agentConfigs: "/api/agent-configs";
+    readonly agentConfig: (agentId: string) => string;
+};
+export declare const GATEWAY_PORTAL_API_ENDPOINTS: {
+    readonly config: (portalSlug: string) => string;
+};
+export declare const GATEWAY_PROBE_ENDPOINTS: {
+    readonly healthz: "/healthz";
+    readonly readyz: "/readyz";
+};
+//# sourceMappingURL=paths.d.ts.map

package/dist/contracts/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/contracts/paths.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC5D,MAAM,CAQR;AAED,eAAO,MAAM,6BAA6B;;;CAGhC,CAAC;AAEX,eAAO,MAAM,oBAAoB;;;;;;;oCAOR,MAAM;;0BAEhB,MAAM;gCACA,MAAM;kCACJ,MAAM;8BACV,MAAM;;0BAEV,MAAM;CACX,CAAC;AAEX,eAAO,MAAM,8BAA8B;;;CAAgC,CAAC;AAC5E,eAAO,MAAM,qBAAqB;;;;;;;oCAXT,MAAM;;0BAEhB,MAAM;gCACA,MAAM;kCACJ,MAAM;8BACV,MAAM;;0BAEV,MAAM;CAIoC,CAAC;AAE1D,eAAO,MAAM,2BAA2B,EAAG,WAAoB,CAAC;AAEhE,eAAO,MAAM,2BAA2B;;gCAEnB,MAAM,GAAG,IAAI;8BAIf,MAAM;yBAEX,MAAM,SAAS,MAAM;8BAEhB;QACf,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GAAG,IAAI;8BAMS,MAAM;CAEf,CAAC;AAEX,eAAO,MAAM,0BAA0B;;gCAtBlB,MAAM,GAAG,IAAI;8BAIf,MAAM;yBAEX,MAAM,SAAS,MAAM;8BAEhB;QACf,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GAAG,IAAI;8BAMS,MAAM;CAI4C,CAAC;AACtE,eAAO,MAAM,4BAA4B;;gCAvBpB,MAAM,GAAG,IAAI;8BAIf,MAAM;yBAEX,MAAM,SAAS,MAAM;8BAEhB;QACf,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACrB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GAAG,IAAI;8BAMS,MAAM;CAK8C,CAAC;AAExE,eAAO,MAAM,0BAA0B,EAAG,UAAmB,CAAC;AAE9D,eAAO,MAAM,0BAA0B;;;8BAGpB,MAAM;6BAEP,MAAM;6BAEN,MAAM,QAAQ,MAAM;+BAKlB,MAAM;gCAEL,MAAM;gCAEN,MAAM;4BAEV,MAAM,SAAS,MAAM;iCAEhB,MAAM,cAAc,MAAM;CAEtC,CAAC;AAEX,eAAO,MAAM,yBAAyB;;;8BArBnB,MAAM;6BAEP,MAAM;6BAEN,MAAM,QAAQ,MAAM;+BAKlB,MAAM;gCAEL,MAAM;gCAEN,MAAM;4BAEV,MAAM,SAAS,MAAM;iCAEhB,MAAM,cAAc,MAAM;CAImB,CAAC;AACpE,eAAO,MAAM,2BAA2B;;;8BAtBrB,MAAM;6BAEP,MAAM;6BAEN,MAAM,QAAQ,MAAM;+BAKlB,MAAM;gCAEL,MAAM;gCAEN,MAAM;4BAEV,MAAM,SAAS,MAAM;iCAEhB,MAAM,cAAc,MAAM;CAKqB,CAAC;AAEtE,eAAO,MAAM,yBAAyB;;;;;;CAM5B,CAAC;AAEX,eAAO,MAAM,kCAAkC;;;;;;oCAMtB,MAAM;CAErB,CAAC;AAEX,eAAO,MAAM,iCAAiC;;;;;;oCAJrB,MAAM;CAIoD,CAAC;AACpF,eAAO,MAAM,mCAAmC;;;;;;oCALvB,MAAM;CAKsD,CAAC;AAEtF,eAAO,MAAM,4BAA4B;kCAClB,MAAM;CAEnB,CAAC;AAEX,eAAO,MAAM,uBAAuB;;;CAG1B,CAAC"}

package/dist/contracts/paths.js

@@ -0,0 +1,89 @@
+export function appendHttpQuery(path, query) {
+    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",
+};
+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) => `/v1/responses/${encodeURIComponent(responseId)}`,
+    runs: "/v1/runs",
+    run: (runId) => `/v1/runs/${encodeURIComponent(runId)}`,
+    runEvents: (runId) => `/v1/runs/${encodeURIComponent(runId)}/events`,
+    runApproval: (runId) => `/v1/runs/${encodeURIComponent(runId)}/approval`,
+    runStop: (runId) => `/v1/runs/${encodeURIComponent(runId)}/stop`,
+    jobs: "/api/jobs",
+    job: (jobId) => `/api/jobs/${encodeURIComponent(jobId)}`,
+};
+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";
+export const GATEWAY_MEDIA_API_ENDPOINTS = {
+    root: GATEWAY_MEDIA_API_BASE_PATH,
+    providers: (kind) => kind
+        ? `${GATEWAY_MEDIA_API_BASE_PATH}/${encodeURIComponent(kind)}/providers`
+        : `${GATEWAY_MEDIA_API_BASE_PATH}/providers`,
+    generate: (kind) => `${GATEWAY_MEDIA_API_BASE_PATH}/${encodeURIComponent(kind)}/generate`,
+    job: (kind, jobId) => `${GATEWAY_MEDIA_API_BASE_PATH}/${encodeURIComponent(kind)}/jobs/${encodeURIComponent(jobId)}`,
+    assets: (query) => appendHttpQuery(`${GATEWAY_MEDIA_API_BASE_PATH}/assets`, {
+        kind: query?.kind ?? undefined,
+        cursor: query?.cursor ?? undefined,
+        limit: query?.limit ?? undefined,
+    }),
+    asset: (assetId) => `${GATEWAY_MEDIA_API_BASE_PATH}/assets/${encodeURIComponent(assetId)}`,
+};
+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";
+export const GATEWAY_WIKI_API_ENDPOINTS = {
+    root: GATEWAY_WIKI_API_BASE_PATH,
+    vaults: `${GATEWAY_WIKI_API_BASE_PATH}/vaults`,
+    vault: (vaultId) => `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}`,
+    tree: (vaultId) => `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/tree`,
+    read: (vaultId, path) => appendHttpQuery(`${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/read`, { path }),
+    ingest: (vaultId) => `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/ingest`,
+    compile: (vaultId) => `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/compile`,
+    promote: (vaultId) => `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/promote`,
+    job: (vaultId, jobId) => `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/jobs/${encodeURIComponent(jobId)}`,
+    artifact: (vaultId, artifactId) => `${GATEWAY_WIKI_API_BASE_PATH}/vaults/${encodeURIComponent(vaultId)}/artifacts/${encodeURIComponent(artifactId)}`,
+};
+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",
+};
+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) => `/api/agent-configs/${encodeURIComponent(agentId)}/config`,
+};
+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) => `/api/plugins/portal/${encodeURIComponent(portalSlug)}/config`,
+};
+export const GATEWAY_PROBE_ENDPOINTS = {
+    healthz: "/healthz",
+    readyz: "/readyz",
+};

package/dist/contracts/resolve.d.ts

@@ -0,0 +1,7 @@
+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 declare function resolveSurfaceContractPath(contract: SurfaceContract, mode?: GatewayMode, params?: Record<string, string>): string;
+export declare function createSurfacePathResolver(extensionContracts?: SurfaceContractMap, baseResolver?: SurfacePathResolver): SurfacePathResolver;
+export declare function resolvePath(key: string, mode?: GatewayMode, params?: Record<string, string>): string;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/contracts/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/contracts/resolve.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;AAEjE,MAAM,MAAM,mBAAmB,GAAG,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,WAAW,EAClB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC5B,MAAM,CAAC;AAEZ,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,eAAe,EACzB,IAAI,GAAE,WAAsB,EAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAKR;AAED,wBAAgB,yBAAyB,CACvC,kBAAkB,GAAE,kBAAuB,EAC3C,YAAY,GAAE,mBAAiC,GAC9C,mBAAmB,CAMrB;AAED,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,WAAsB,EAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAIR"}

package/dist/contracts/resolve.js

@@ -0,0 +1,22 @@
+import { SURFACE_CONTRACTS } from "./surfaces.js";
+export function resolveSurfaceContractPath(contract, mode = "legacy", params) {
+    if (mode === "canonical")
+        return contract.canonicalPath(params);
+    return contract.legacyPath
+        ? contract.legacyPath(params)
+        : contract.canonicalPath(params);
+}
+export function createSurfacePathResolver(extensionContracts = {}, baseResolver = resolvePath) {
+    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, mode = "legacy", params) {
+    const contract = SURFACE_CONTRACTS[key];
+    if (!contract)
+        throw new Error(`resolvePath: unknown surface "${key}"`);
+    return resolveSurfaceContractPath(contract, mode, params);
+}

package/dist/contracts/surfaces.d.ts

@@ -0,0 +1,13 @@
+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;
+};
+export declare const SURFACE_CONTRACTS: Record<string, SurfaceContract>;
+//# sourceMappingURL=surfaces.d.ts.map

package/dist/contracts/surfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surfaces.d.ts","sourceRoot":"","sources":["../../src/contracts/surfaces.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEjD,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACpD,aAAa,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC;IAC3D,UAAU,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC;IACzD,cAAc,EAAE,gBAAgB,GAAG,oBAAoB,GAAG,SAAS,CAAC;IACpE,WAAW,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAcF,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CA8U7D,CAAC"}

package/dist/contracts/surfaces.js

@@ -0,0 +1,332 @@
+import { GATEWAY_MEDIA_API_ENDPOINTS, GATEWAY_WIKI_API_ENDPOINTS, } from "./paths.js";
+import { resolveTeamRoutePath } from "./team-manifest.js";
+const p = (params, k) => {
+    const v = params?.[k];
+    if (!v)
+        throw new Error(`SURFACE_CONTRACTS: missing path param "${k}"`);
+    return encodeURIComponent(v);
+};
+const raw = (params, k) => {
+    const v = params?.[k];
+    if (!v)
+        throw new Error(`SURFACE_CONTRACTS: missing path param "${k}"`);
+    return v;
+};
+export const SURFACE_CONTRACTS = {
+    "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.",
+    },
+};