@numa-tech/numa 1.12.7 → 1.12.8

package/README.md

@@ -187,9 +187,11 @@ numa config \
 | `numa admin context` | 需角色 | 要求 `platform-admin` 或 `numa-admin` |
 | `numa registry instances list/create/update/delete` | 需登录 | 管理数据库中的 Nacos 实例和 OIDC 配置；写操作需要 Registry admin |
 | `numa registry namespaces list/resolve/check/create/update/delete` | 需登录 | 管理多实例 namespace 路由与跨集群默认项；写操作需要 Registry admin |
-| `numa registry skill list/inspect/install/upload/...` | 需登录 | 发现、安装和治理 Nacos Skills；发布类操作需要 Registry admin |
-| `numa registry mcp list/inspect/install/create/update/delete` | 需登录 | 发现、安装和维护 Nacos MCP Servers；写操作需要 Registry admin |
-| `numa registry tui` | 需登录 | 在终端交互浏览、安装和治理 Skill/MCP |
+| `numa registry capabilities/init/lock/sync/upgrade` | 需登录 | 读取授权边界并以可提交的 manifest/lock 确定性安装 |
+| `numa registry skill list/inspect/install/upload/...` | 需登录 | 发现、安装和治理 Nacos Skills；服务端按团队、角色和生命周期授权 |
+| `numa registry mcp list/inspect/install/bridge/...` | 需登录 | 通过企业 Router 安装/桥接 MCP，并维护版本、标签和工具状态 |
+| `numa registry approvals/router/audit` | 需登录 | 两人制发布、Router 健康/对账和追加式审计 |
+| `numa registry tui` | 需登录 | 打开 namespace、Skills、MCP、审批、Router、审计全屏工作台 |
 | `numa media capabilities` | 需登录 | 查询媒体 API、Provider 和版本能力 |
 | `numa media tts submit` | 需登录 | 提交 TTS 异步任务 |
 | `numa media video submit` | 需登录 | 提交视频生成异步任务 |
@@ -232,6 +234,8 @@ CLI 的本地角色检查用于快速反馈和隐藏无权限入口，不能替
 - `profileUrl`：完整的公开 client-configuration URL；设置后各模块只使用该
   profile 声明的 service 与 authority；
 - `profileId`：可选的 profile 标识锁定；远端返回其他标识时拒绝启用；
+- `aiRegistryDefaultNamespaceKey`：用户级 Registry 默认 namespace；优先级低于命令行和
+  项目 `.numa/registry.json`，高于 profile 默认值；
 - `registryUrl`：npm registry，默认公共 npm，也可配置公司私有 registry；
 - `checkUpdates`：是否检查 CLI 更新。
 
@@ -268,9 +272,9 @@ numa login --no-console --no-config --json
 ```
 
 控制台展示当前身份、Realm/Client 角色、AI Registry、ChatGPT 账号、基础配置和机器可读命令目录。
-AI Registry 页按“namespace → Skill/MCP → 详情/动作”组织，支持搜索、详情、安装以及 Skill
-提交/发布/上下线。发布按钮是否可用只是界面提示，实际权限始终由平台 Keycloak Policy
-Enforcer 决定。
+AI Registry 页包含目录、发布收件箱、实例/双凭据、Namespace/Profile、Router、权限/审计六个
+工作区，并展示 capability 返回的环境、动作和 Router 状态。按钮是否可用只是界面提示，实际
+权限、两人制和生命周期始终由平台服务端决定。
 ChatGPT 账号页先读取 `codex-multi-auth` 的本地账号与额度缓存并立即展示，再使用当前
 Keycloak 会话连接平台补充当前用户可用账号、剩余 limit 和同步状态。平台不可用时页面
 保留本地结果并明确显示“远程同步失败”，不会把 access token 或 refresh token 返回给页面。
@@ -287,20 +291,27 @@ CSP。OIDC access/refresh token 始终保留在 CLI 进程及私有缓存中，
 
 ## 私有 Nacos AI Registry
 
-`numa registry` 对接 `mci-devops-platform` 的 `/api/v1/ai-registry` 类型化 API。客户端只携带
-当前用户 Keycloak Bearer Token；平台从自己的数据库解析 Nacos 实例、namespace 和该实例的
-OIDC client-credentials，再访问目标 Nacos。Nacos token、OIDC client secret 和 endpoint
-credential 不写入 Numa 配置，也不由读取 API 返回。
+`numa registry` 对接 `mci-devops-platform` 的 `/api/v1/ai-registry` 类型化 API。Nacos 是
+Skill/MCP 内容、版本、标签和上下线状态的主仓库；平台只维护组织、团队、权限、审批、profile、
+Router 绑定、对账和审计。Numa 只携带当前用户 Keycloak Bearer Token，且 capability 响应若
+包含 Nacos 地址、token、secret、password 或 credential 字段会被客户端拒绝。
+
+`GET /api/v1/ai-registry/capabilities` 返回当前用户可见 namespace、环境、动作、Router
+Streamable HTTP/OAuth resource 和客户端适配器。profile v1 可追加
+`services.aiRegistry.capabilityUrl` 与
+`services.aiRegistry.configuration.defaultNamespaceKey`，旧客户端会忽略这些字段。
 
 权限契约：
 
-- `mci-devops-platform-ai-registry-reader`：`view`，可列出、检查、下载和安装；
-- `mci-devops-platform-ai-registry-admin`：`view` + `edit`，作为操作管理员管理实例、namespace、Skill 和 MCP；
-- 平台 operations admin 同时拥有 `view` + `edit`。
+- 团队 `MEMBER+` 可使用已授权 namespace；
+- 团队 `MAINTAINER/ADMIN/OWNER` 可维护本团队草稿；
+- `ai-registry-reviewer` 可审核发布申请，且不得审核或发布自己的申请；
+- `ai-registry-admin` 管理 Registry，`ops-admin` 才能执行 `*` allowlist、Admin API 和紧急操作。
 
-Nacos 的 `baseUrl`、token URI、client ID、client secret 和 scope 全部按实例保存在
-`mci-devops-platform` 数据库。client secret 使用 AES-256-GCM 密文存储，读取接口只返回
-`credentialConfigured`，不会返回明文或密文。平台部署只需从 Secret/KMS 注入数据库密文的
+每个 Nacos 实例分别配置 `READER` 和 `MAINTAINER` 凭据，可使用 OIDC client credentials 或
+Nacos username/password，并为每套凭据设置精确 namespace allowlist。凭据使用 AES-256-GCM
+密文存储，读取接口只返回 configured 状态，不返回明文或密文。旧单凭据作为 `LEGACY_BOTH`
+继续工作，管理员验证两套新凭据后再显式停用。平台部署从 Secret/KMS 注入数据库密文的
 主密钥环 `AI_REGISTRY_SECRET_ENCRYPTION_KEYS` 与当前 key ID
 `AI_REGISTRY_SECRET_CURRENT_KEY_ID`；这两项是密钥管理材料，不是某个 Nacos 实例的配置。
 密钥环格式为逗号分隔的 `keyId=Base64(32-byte-key)`；轮换时先加入新 key 并切换当前 key ID，
@@ -309,25 +320,35 @@ SSRF 安全策略仍由 `AI_REGISTRY_ALLOWED_UPSTREAM_HOSTS`、
 `AI_REGISTRY_ALLOWED_TOKEN_HOSTS` 控制，allow-list 为空时 fail closed；HTTP 只可通过
 `AI_REGISTRY_ALLOW_HTTP=true` 用于开发环境。
 
-Nacos 实例文件示例（`clientSecret` 仅写入）：
+Nacos 实例文件示例（凭据字段仅写入，实际字段以平台 capability/API revision 为准）：
 
 ```json
 {
   "code": "cluster-a",
   "displayName": "Nacos Cluster A",
   "baseUrl": "https://nacos.internal.example:8848",
-  "authenticationType": "OIDC_CLIENT_CREDENTIALS",
-  "tokenUri": "https://sso.internal.example/realms/mci/protocol/openid-connect/token",
-  "clientId": "nacos-registry-broker",
-  "clientSecret": "write-only-secret",
-  "scope": "openid",
+  "credentials": {
+    "reader": {
+      "authenticationType": "OIDC_CLIENT_CREDENTIALS",
+      "tokenUri": "https://sso.internal.example/realms/mci/protocol/openid-connect/token",
+      "clientId": "nacos-registry-reader",
+      "clientSecret": "write-only-secret",
+      "namespaceAllowlist": ["team-ai"]
+    },
+    "maintainer": {
+      "authenticationType": "NACOS_USERNAME_PASSWORD",
+      "username": "registry-maintainer",
+      "password": "write-only-password",
+      "namespaceAllowlist": ["team-ai"]
+    }
+  },
   "description": "A 集群",
   "status": "ACTIVE"
 }
 ```
 
-`instances update` 必须带列表结果中的当前 `version`，用于乐观锁保护；省略 `clientSecret`
-表示保留已有密文。建议让包含明文 secret 的输入文件仅对当前用户可读，并在写入后安全删除。
+`instances update` 必须带列表结果中的当前 `version`，用于乐观锁保护；省略某套凭据表示保留
+已有密文。建议让包含明文 secret 的输入文件仅对当前用户可读，并在写入后安全删除。
 
 namespace 文件示例：
 
@@ -343,13 +364,13 @@ namespace 文件示例：
 ```
 
 `namespaceKey` 是客户端使用的稳定名称，`namespaceId` 是该 Nacos 实例中的真实 ID。同一个
-`namespaceKey` 可以存在于多个实例；其中最多一个 ACTIVE 路由可设为 `isDefault=true`。
-客户端只传 `--namespace team-ai` 时，平台会选择唯一匹配项或默认项；同名且没有默认项时返回
-`AI_REGISTRY_NAMESPACE_AMBIGUOUS`，此时必须加 `--instance cluster-b` 消歧。
+`namespaceKey` 可以存在于多个实例。Numa 的选择顺序固定为 `--namespace` → 最近的
+`.numa/registry.json` → 用户 `aiRegistryDefaultNamespaceKey` → profile 默认值；选择结果必须
+存在于 capability 授权列表。同名绑定必须由 manifest/`--instance` 消歧，默认值无效时明确失败，
+不会切换到其他可用 namespace。旧 `isDefault` 仅供迁移期兼容客户端使用。
 
-V34 会把旧服务行拆成实例和 namespace，但旧 `credentialRef` 无法自动转换为数据库密文，
-所以迁移后的实例会先置为 `DISABLED`。管理员写入完整 OIDC 配置和 `clientSecret` 后再启用；
-跨集群重复的旧 namespace 不会自动猜测默认项。
+profile 管理员发布 `defaultNamespaceKey` 且满足最低客户端版本后，才可逐步移除旧 `isDefault`
+fallback。服务器端数据库迁移必须从当前版本新增 Flyway migration，不修改历史迁移。
 
 先发现实例和 namespace，再通过 namespace 操作资源：
 
@@ -359,6 +380,13 @@ numa registry namespaces list --namespace team-ai --json
 numa registry namespaces resolve team-ai --json
 numa registry namespaces check team-ai --json
 
+numa registry capabilities --json
+numa registry init --namespace team-ai --instance cluster-b --json
+# 编辑 .numa/registry.json 后：
+numa registry lock --json
+numa registry sync --json
+numa registry upgrade release-helper --json
+
 numa registry skill list --namespace team-ai --search deploy --json
 numa registry skill inspect release-helper --namespace team-ai --json
 numa registry skill install release-helper \
@@ -367,50 +395,118 @@ numa registry skill install release-helper \
 numa registry mcp list --namespace team-ai --json
 numa registry mcp inspect internal-docs --namespace team-ai --json
 numa registry mcp install internal-docs \
-  --namespace team-ai --instance cluster-b --agent claude --scope project --json
+  --namespace team-ai --instance cluster-b --agent claude --scope project --transport remote --json
+
+# 仅供 stdio Agent；复用 Numa 登录/刷新连接 Router
+numa registry mcp bridge --namespace team-ai
 
 # 也可使用终端交互界面
 numa registry tui
 ```
 
-Skill 发布生命周期：
+两人制发布生命周期：
 
 ```bash
 numa registry skill upload ./release-helper.zip \
   --namespace team-ai --target-version 1.0.0 --json
-numa registry skill submit release-helper --namespace team-ai --json
-numa registry skill publish release-helper \
-  --namespace team-ai --version 1.0.0 --json
-numa registry skill online release-helper --namespace team-ai --json
-numa registry skill scope release-helper PRIVATE --namespace team-ai --json
-numa registry skill tags release-helper deploy java --namespace team-ai --json
+numa registry approvals submit skill release-helper \
+  --namespace team-ai --resource-version 1.0.0 --reason "scanner passed" --json
+# 必须由另一位 reviewer 执行
+numa registry approvals review rr_123 \
+  --decision APPROVED --reason "reviewed" --version 1 --json
+numa registry approvals publish rr_123 --version 2 --json
+numa registry audit --namespace team-ai --json
 ```
 
+生命周期由服务端统一为
+`DRAFT → SUBMITTED → APPROVED/REJECTED → PUBLISHING → PUBLISHED/FAILED → OFFLINE`。
+生产及企业默认 namespace 的 Skill 不允许绕过 scanner；非生产豁免也必须带原因并由 Reviewer
+审批。MCP 发布由服务端执行协议、工具 schema、禁用工具和 Endpoint 健康预检。
+
 远端删除必须带 `--yes`。本地同名 Skill/MCP 默认拒绝覆盖；用户明确同意后才使用
 `--force`，支持原子替换的适配器会先保留时间戳备份。Skill 下载必须通过平台返回的
 SHA-256 校验，ZIP 在解压前会检查根 `SKILL.md`、路径穿越、符号链接、重复路径、文件数和
-膨胀大小。MCP 定义中的敏感 env/header 只能使用 `${ENV_VAR}` 占位符，不能携带明文密钥。
+膨胀大小。`.numa/registry.lock.json` 保存解析后的精确版本、Nacos 来源、SHA-256 和安装状态；
+普通 `sync` 不解析标签，只有首次 `lock` 或显式 `upgrade` 会变更版本。MCP 客户端只安装
+capability 发布且健康的企业 Router，不安装 Nacos 中的下游 endpoint。
 
 ### 客户端安装适配
 
 | 客户端 | Skill | MCP Server |
 | --- | --- | --- |
-| ChatGPT / Codex coding workspace | `.codex/skills` | ChatGPT 仅接受远程 HTTPS MCP App；Numa 返回 Developer mode/App 创建指引，不会冒充修改工作区设置 |
+| ChatGPT / Codex coding workspace | `.codex/skills` | ChatGPT 连接企业 Router 的远程 HTTPS OAuth resource；Numa 返回 App 创建指引 |
 | Codex | `.codex/skills` | 调用官方 `codex mcp add`，仅 user scope |
 | Claude | `.claude/skills` | 项目 `.mcp.json`；user scope 使用 `~/.claude.json` |
 | Cursor | `.cursor/skills` | `.cursor/mcp.json` |
 | WorkBuddy | `.workbuddy/skills` | `.workbuddy/mcp.json`；目录可通过 custom adapter 调整 |
 | OpenClaw | `.openclaw/skills` | 调用官方 `openclaw mcp set`，仅 user scope |
 
-ChatGPT 本身不能直接连接本地 stdio MCP。Numa 对 `--agent chatgpt` 只为远程 HTTPS endpoint
-生成受控安装指引；私网或本机 MCP 需要先发布为远程服务，或使用 ChatGPT 支持的 Secure
-MCP Tunnel。ChatGPT workspace 还需管理员按其计划和 RBAC 开启 Developer mode。
+ChatGPT 不能启动本地 stdio bridge；它直接连接企业 Router 的远程 HTTPS OAuth resource。
+其他只支持 stdio 的 Agent 可运行 `numa registry mcp bridge`，由 Numa 获取/刷新用户 Token
+并只发送给 Router，不向 Nacos 或下游 MCP 透传。ChatGPT workspace 仍需管理员按计划和
+RBAC 开启 Developer mode。
 
 仓库内置的自用 Skill 位于 `skills/numa-ai-registry/SKILL.md`，并随 npm 包发布。它指导 AI
 按“认证 → 服务解析 → inspect → 安装/治理 → 复查”的顺序使用 Registry，同时明确禁止索取
 Nacos token、绕过 403 或未经确认覆盖本地配置。对应场景评测在
 `skills/numa-ai-registry/evals/evals.json`。
 
+## Jenkins 流水线与生产操作
+
+`numa pipeline` 通过平台授权代理查询和操作 Jenkins。CLI 不接收 Jenkins 用户名、Token 或
+URL；生产 build、retry 和 stop 由服务端再次校验 `ops-admin` 与审批依据。
+
+三个容易混淆的标识含义不同：
+
+| 标识 | 生成方 | 用途 | 重试规则 |
+| --- | --- | --- | --- |
+| `requestId` | 平台 | 标识已创建的构建任务，用于 status、log、stop、retry | 新任务产生新值 |
+| `idempotency-key` | CLI 或调用者 | 判断重复提交是否属于同一次部署 | 同一次提交重试必须复用；新部署使用新值 |
+| `approve-id` | 审批流程或管理员 | 记录生产操作依据 | 按审批范围使用，不是任务标识 |
+
+`idempotency-key` 是可选参数。不传时 CLI 会自动生成 UUID，并在成功结果中以
+`idempotency_key` 返回。生产部署和自动化脚本建议显式指定：如果网络中断导致结果不明，
+使用原值重新提交，平台会返回原任务或拒绝内容不一致的冲突，不会无意创建第二个构建。
+
+```bash
+numa pipeline inspect mci-devops-platform --json
+
+numa pipeline build mci-devops-platform \
+  --tier production \
+  --branch main \
+  --approve-id OPS-APPROVAL-20260818-001 \
+  --idempotency-key mci-devops-platform-prd-20260818-001 \
+  --wait \
+  --json
+```
+
+生产操作必须提供 `--approve-id` 或至少 10 个字符的 `--production-reason`。CLI 将二者作为
+独立治理字段提交；不能使用 `--param APPROVE_ID=...` 绕过治理。平台保存两者及审计记录，
+仅在生产 trigger/retry 时把经过验证的 `approveId` 映射为 Jenkins `APPROVE_ID`；
+`productionReason` 不会转发给 Jenkins。
+
+`--wait` 和 `status --watch` 约每 2 秒轮询一次，当前没有默认超时，会持续到 `SUCCESS`、
+`FAILED`、`ABORTED`、`CANCELLED` 或 `NOT_BUILT`。按 `Ctrl+C` 或遇到网络错误只会结束本地
+等待，不会停止 Jenkins 构建；真正停止任务需要显式执行 `pipeline stop ... --yes`。
+`build --wait` 仅在 `SUCCESS` 时返回退出码 0，其他终态返回非零。
+
+保存 build 返回的 `requestId`，可以随时恢复查询：
+
+```bash
+numa pipeline status req_01ABC --watch
+numa pipeline log req_01ABC --follow
+```
+
+如果没有保存 `requestId`，先按应用和环境检索构建记录，再使用返回的 `requestId`：
+
+```bash
+numa pipeline builds --app mci-devops-platform --tier production --limit 20 --json
+```
+
+`pipeline builds` 使用游标分页：`--limit` 是每页条数，不是页码；下一页应把上一页响应中的
+`next_cursor` 传给 `--cursor`。面向 AI 和自动化的同一套操作语义也包含在 `numa commands --json` 的
+`operationalNotes` 字段中，因此基本流水线操作不依赖额外 Skill。
+
 ## 平台媒体服务
 
 自 1.8.0 起，`numa media` 通过当前 Keycloak 会话调用 `/api/v1/media`。第三方

package/dist/ai-registry/bridge.d.ts

@@ -0,0 +1,8 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import type { AiRegistryClient } from "./client.js";
+export declare function runMcpBridge(client: AiRegistryClient, options: {
+    namespace?: string;
+    instance?: string;
+    workspace?: string;
+}): Promise<void>;
+export declare function bridgeMcpTransports(local: Transport, remote: Transport): Promise<void>;

package/dist/ai-registry/bridge.js

@@ -0,0 +1,63 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { loadConfig } from "../config.js";
+import { fetchWithKeycloakIdentity } from "../oauth.js";
+import { AiRegistryError, redactRegistryText } from "./errors.js";
+import { resolveRegistryNamespace } from "./namespace.js";
+export async function runMcpBridge(client, options) {
+    const context = await resolveRegistryNamespace(client, options);
+    const router = context.capability.router;
+    if (!router?.endpoint || router.status !== "READY") {
+        throw new AiRegistryError(`Namespace ${context.namespace.namespaceKey} has no ready enterprise Router.`, "ai_registry_router_unavailable");
+    }
+    const endpoint = new URL(router.endpoint);
+    const local = ["localhost", "127.0.0.1", "::1", "[::1]"].includes(endpoint.hostname);
+    if (endpoint.protocol !== "https:" && !(endpoint.protocol === "http:" && local)) {
+        throw new AiRegistryError("Enterprise Router endpoint must use HTTPS.", "ai_registry_router_invalid");
+    }
+    await client.checkRouter(context.namespace.id);
+    const authConfig = loadConfig("aiRegistry");
+    const remote = new StreamableHTTPClientTransport(endpoint, {
+        fetch: async (input, init) => fetchWithKeycloakIdentity(authConfig, String(input), () => ({ ...init, headers: new Headers(init?.headers) }))
+    });
+    await bridgeMcpTransports(new StdioServerTransport(), remote);
+}
+export async function bridgeMcpTransports(local, remote) {
+    let closed = false;
+    let resolveClosed;
+    let rejectClosed;
+    const completed = new Promise((resolvePromise, rejectPromise) => {
+        resolveClosed = resolvePromise;
+        rejectClosed = rejectPromise;
+    });
+    const fail = (error) => {
+        if (closed)
+            return;
+        closed = true;
+        rejectClosed?.(new AiRegistryError(`MCP bridge failed: ${redactRegistryText(error.message)}`, "ai_registry_bridge_failed"));
+        void Promise.allSettled([local.close(), remote.close()]);
+    };
+    const finish = () => {
+        if (closed)
+            return;
+        closed = true;
+        resolveClosed?.();
+        void Promise.allSettled([local.close(), remote.close()]);
+    };
+    local.onmessage = (message) => { void remote.send(message).catch(fail); };
+    remote.onmessage = (message) => { void local.send(message).catch(fail); };
+    local.onerror = fail;
+    remote.onerror = fail;
+    local.onclose = finish;
+    remote.onclose = finish;
+    try {
+        await remote.start();
+        await local.start();
+        await completed;
+    }
+    catch (error) {
+        fail(error instanceof Error ? error : new Error(String(error)));
+        await completed;
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/ai-registry/bridge.js.map

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

package/dist/ai-registry/client.d.ts

@@ -1,6 +1,6 @@
 import type { AuthConfig } from "../config.js";
 import { type KeycloakTokenProvider } from "../oauth.js";
-import { type JsonObject, type RegistryInstance, type RegistryNamespace } from "./schemas.js";
+import { type JsonObject, type RegistryCapabilities, type RegistryInstance, type RegistryNamespace, type RegistryRouter } from "./schemas.js";
 export interface AiRegistryClientDependencies {
     fetch?: typeof fetch;
     tokenProvider?: KeycloakTokenProvider;
@@ -9,6 +9,7 @@ export interface SkillDownload {
     bytes: Buffer;
     fileName: string;
     sha256: string;
+    version?: string;
 }
 export declare class AiRegistryClient {
     private readonly config;
@@ -18,6 +19,7 @@ export declare class AiRegistryClient {
     private authenticatedFetch;
     private json;
     listInstances(): Promise<RegistryInstance[]>;
+    getCapabilities(): Promise<RegistryCapabilities>;
     createInstance(input: JsonObject): Promise<RegistryInstance>;
     updateInstance(instanceId: number, input: JsonObject): Promise<RegistryInstance>;
     deleteInstance(instanceId: number): Promise<void>;
@@ -48,17 +50,41 @@ export declare class AiRegistryClient {
         commitMsg?: string;
         uploadAction?: string;
     }): Promise<unknown>;
-    skillAction(namespaceId: number, skillName: string, action: "submit" | "publish" | "online" | "offline" | "scope" | "biz-tags" | "delete", body?: Record<string, unknown>): Promise<unknown>;
+    skillAction(namespaceId: number, skillName: string, action: "submit" | "publish" | "online" | "offline" | "scope" | "biz-tags" | "labels" | "delete", body?: Record<string, unknown>): Promise<unknown>;
     listMcpServers(namespaceId: number, options?: {
         search?: string;
         mcpName?: string;
         pageNo?: number;
         pageSize?: number;
     }): Promise<JsonObject>;
-    getMcpServer(namespaceId: number, mcpName: string, version?: string): Promise<JsonObject>;
+    getMcpServer(namespaceId: number, mcpName: string, versionOrOptions?: string | {
+        version?: string;
+        label?: string;
+    }): Promise<JsonObject>;
     createMcpServer(namespaceId: number, specification: JsonObject): Promise<unknown>;
     updateMcpServer(namespaceId: number, mcpName: string, specification: JsonObject): Promise<unknown>;
     deleteMcpServer(namespaceId: number, mcpName: string, version?: string): Promise<unknown>;
+    mcpAction(namespaceId: number, mcpName: string, action: "online" | "offline" | "biz-tags", body?: Record<string, unknown>): Promise<unknown>;
+    setMcpToolEnabled(namespaceId: number, mcpName: string, toolName: string, enabled: boolean, version?: number): Promise<unknown>;
+    createSkillDraft(namespaceId: number, skillName: string, body?: Record<string, unknown>): Promise<unknown>;
+    listReleaseRequests(options?: {
+        namespaceId?: number;
+        state?: string;
+        cursor?: string;
+        limit?: number;
+    }): Promise<JsonObject>;
+    createReleaseRequest(body: JsonObject): Promise<unknown>;
+    reviewReleaseRequest(requestId: string, body: JsonObject): Promise<unknown>;
+    publishReleaseRequest(requestId: string, body?: JsonObject): Promise<unknown>;
+    getRouter(namespaceId: number): Promise<RegistryRouter>;
+    connectRouter(namespaceId: number, body?: JsonObject): Promise<unknown>;
+    checkRouter(namespaceId: number): Promise<JsonObject>;
+    reconcileNamespace(namespaceId: number): Promise<JsonObject>;
+    listAuditEvents(options?: {
+        namespaceId?: number;
+        cursor?: string;
+        limit?: number;
+    }): Promise<JsonObject>;
     private object;
     private instanceResponse;
     private namespaceResponse;

package/dist/ai-registry/client.js

@@ -4,7 +4,7 @@ import { readFile, stat } from "node:fs/promises";
 import { resolveBackendUrl } from "../backend.js";
 import { ensureAccessToken, fetchWithKeycloakIdentity } from "../oauth.js";
 import { AiRegistryError, redactRegistryText } from "./errors.js";
-import { ApiErrorSchema, JsonObjectSchema, RegistryInstancesSchema, RegistryNamespacesSchema } from "./schemas.js";
+import { ApiErrorSchema, JsonObjectSchema, RegistryCapabilitiesSchema, RegistryRouterSchema, RegistryInstancesSchema, RegistryNamespacesSchema } from "./schemas.js";
 const API_ROOT = "/api/v1/ai-registry";
 const MAX_DOWNLOAD_BYTES = 50 * 1024 * 1024;
 const MAX_UPLOAD_BYTES = 20 * 1024 * 1024;
@@ -50,7 +50,9 @@ function apiError(response, body) {
         : typeof body === "string"
             ? body
             : response.statusText;
-    return new AiRegistryError(`AI Registry HTTP ${response.status}: ${redactRegistryText(message || "request failed")}`, parsed.success ? parsed.data.code ?? "ai_registry_api_error" : "ai_registry_api_error", response.status, parsed.success ? parsed.data.requestId : response.headers.get("x-request-id") ?? undefined);
+    return new AiRegistryError(`AI Registry HTTP ${response.status}: ${redactRegistryText(message || "request failed")}`, parsed.success ? parsed.data.code ?? "ai_registry_api_error" : "ai_registry_api_error", response.status, parsed.success
+        ? parsed.data.requestId ?? response.headers.get("x-request-id") ?? undefined
+        : response.headers.get("x-request-id") ?? undefined, parsed.success ? parsed.data.details : undefined);
 }
 function safeIdentifier(value, label) {
     if (!value || value.length > 160 || /[\\/?#%\u0000-\u001f\u007f]/u.test(value)) {
@@ -68,7 +70,9 @@ export class AiRegistryClient {
         this.tokenProvider = dependencies.tokenProvider ?? ensureAccessToken;
     }
     async authenticatedFetch(path, init = {}) {
-        const url = resolveBackendUrl(this.config, { method: "GET", path });
+        const url = /^https?:\/\//iu.test(path)
+            ? resolveBackendUrl({ ...this.config, allowAbsoluteBackendUrls: true }, { method: "GET", url: path })
+            : resolveBackendUrl(this.config, { method: "GET", path });
         const headers = new Headers(init.headers);
         if (!headers.has("Accept"))
             headers.set("Accept", "application/json");
@@ -91,6 +95,15 @@ export class AiRegistryClient {
         }
         return parsed.data;
     }
+    async getCapabilities() {
+        const raw = await this.json(this.config.capabilityUrl ?? `${API_ROOT}/capabilities`);
+        assertCapabilitySafe(raw);
+        const parsed = RegistryCapabilitiesSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new AiRegistryError(`Capability response is invalid: ${parsed.error.message}`, "ai_registry_invalid_response");
+        }
+        return parsed.data;
+    }
     async createInstance(input) {
         return this.instanceResponse(await this.json(`${API_ROOT}/instances`, { method: "POST", body: JSON.stringify(input) }));
     }
@@ -179,7 +192,8 @@ export class AiRegistryClient {
         const disposition = response.headers.get("content-disposition") ?? "";
         const matched = /filename="?([^";]+)"?/iu.exec(disposition)?.[1];
         const fileName = matched && matched === basename(matched) ? matched : `${safeIdentifier(skillName, "skillName")}.zip`;
-        return { bytes, fileName, sha256 };
+        const version = response.headers.get("x-resource-version")?.trim() || undefined;
+        return { bytes, fileName, sha256, ...(version ? { version } : {}) };
     }
     async uploadSkill(namespaceId, filePath, options = {}) {
         const info = await stat(filePath);
@@ -202,7 +216,7 @@ export class AiRegistryClient {
         const path = `${API_ROOT}/namespaces/${namespaceId}/skills/${encodeURIComponent(safeIdentifier(skillName, "skillName"))}`;
         if (action === "delete")
             return this.json(path, { method: "DELETE" });
-        const method = action === "scope" || action === "biz-tags" ? "PUT" : "POST";
+        const method = action === "scope" || action === "biz-tags" || action === "labels" ? "PUT" : "POST";
         return this.json(`${path}/${action}`, { method, body: JSON.stringify(body) });
     }
     async listMcpServers(namespaceId, options = {}) {
@@ -215,10 +229,15 @@ export class AiRegistryClient {
         query.set("pageSize", String(options.pageSize ?? 20));
         return this.object(`${API_ROOT}/namespaces/${namespaceId}/mcp-servers?${query}`);
     }
-    async getMcpServer(namespaceId, mcpName, version) {
+    async getMcpServer(namespaceId, mcpName, versionOrOptions) {
+        const options = typeof versionOrOptions === "string" ? { version: versionOrOptions } : versionOrOptions ?? {};
         const query = new URLSearchParams();
-        if (version)
-            query.set("version", version);
+        if (options.version && options.label)
+            throw new AiRegistryError("Specify version or label, not both.", "ai_registry_input_invalid");
+        if (options.version)
+            query.set("version", options.version);
+        if (options.label)
+            query.set("label", options.label);
         const suffix = query.size ? `?${query}` : "";
         return this.object(`${API_ROOT}/namespaces/${namespaceId}/mcp-servers/${encodeURIComponent(safeIdentifier(mcpName, "mcpName"))}${suffix}`);
     }
@@ -235,6 +254,78 @@ export class AiRegistryClient {
         const suffix = query.size ? `?${query}` : "";
         return this.json(`${API_ROOT}/namespaces/${namespaceId}/mcp-servers/${encodeURIComponent(safeIdentifier(mcpName, "mcpName"))}${suffix}`, { method: "DELETE" });
     }
+    async mcpAction(namespaceId, mcpName, action, body = {}) {
+        const path = `${API_ROOT}/namespaces/${namespaceId}/mcp-servers/${encodeURIComponent(safeIdentifier(mcpName, "mcpName"))}`;
+        return this.json(`${path}/${action}`, {
+            method: action === "biz-tags" ? "PUT" : "POST",
+            body: JSON.stringify(body)
+        });
+    }
+    async setMcpToolEnabled(namespaceId, mcpName, toolName, enabled, version) {
+        const path = `${API_ROOT}/namespaces/${namespaceId}/mcp-servers/${encodeURIComponent(safeIdentifier(mcpName, "mcpName"))}/tools/${encodeURIComponent(safeIdentifier(toolName, "toolName"))}`;
+        return this.json(path, {
+            method: "PUT",
+            body: JSON.stringify({ enabled, ...(version == null ? {} : { version }) })
+        });
+    }
+    async createSkillDraft(namespaceId, skillName, body = {}) {
+        return this.json(`${API_ROOT}/namespaces/${namespaceId}/skills/${encodeURIComponent(safeIdentifier(skillName, "skillName"))}/drafts`, { method: "POST", body: JSON.stringify(body) });
+    }
+    async listReleaseRequests(options = {}) {
+        const query = new URLSearchParams();
+        if (options.namespaceId)
+            query.set("namespaceId", String(options.namespaceId));
+        if (options.state)
+            query.set("state", safeIdentifier(options.state, "state"));
+        if (options.cursor)
+            query.set("cursor", options.cursor);
+        if (options.limit)
+            query.set("limit", String(options.limit));
+        return this.object(`${API_ROOT}/release-requests${query.size ? `?${query}` : ""}`);
+    }
+    async createReleaseRequest(body) {
+        return this.json(`${API_ROOT}/release-requests`, { method: "POST", body: JSON.stringify(body) });
+    }
+    async reviewReleaseRequest(requestId, body) {
+        return this.json(`${API_ROOT}/release-requests/${encodeURIComponent(safeIdentifier(requestId, "requestId"))}/review`, {
+            method: "POST",
+            body: JSON.stringify(body)
+        });
+    }
+    async publishReleaseRequest(requestId, body = {}) {
+        return this.json(`${API_ROOT}/release-requests/${encodeURIComponent(safeIdentifier(requestId, "requestId"))}/publish`, {
+            method: "POST",
+            body: JSON.stringify(body)
+        });
+    }
+    async getRouter(namespaceId) {
+        const parsed = RegistryRouterSchema.safeParse(await this.json(`${API_ROOT}/namespaces/${namespaceId}/router`));
+        if (!parsed.success)
+            throw new AiRegistryError(`Router response is invalid: ${parsed.error.message}`, "ai_registry_invalid_response");
+        return parsed.data;
+    }
+    async connectRouter(namespaceId, body = {}) {
+        return this.json(`${API_ROOT}/namespaces/${namespaceId}/router/connection`, {
+            method: "POST",
+            body: JSON.stringify(body)
+        });
+    }
+    async checkRouter(namespaceId) {
+        return this.object(`${API_ROOT}/namespaces/${namespaceId}/router/health`);
+    }
+    async reconcileNamespace(namespaceId) {
+        return this.object(`${API_ROOT}/namespaces/${namespaceId}/reconciliation`);
+    }
+    async listAuditEvents(options = {}) {
+        const query = new URLSearchParams();
+        if (options.namespaceId)
+            query.set("namespaceId", String(options.namespaceId));
+        if (options.cursor)
+            query.set("cursor", options.cursor);
+        if (options.limit)
+            query.set("limit", String(options.limit));
+        return this.object(`${API_ROOT}/audit-events${query.size ? `?${query}` : ""}`);
+    }
     async object(path) {
         const parsed = JsonObjectSchema.safeParse(await this.json(path));
         if (!parsed.success) {
@@ -257,4 +348,17 @@ export class AiRegistryClient {
         return parsed.data;
     }
 }
+function assertCapabilitySafe(value, key = "") {
+    if (/(?:credential|password|secret|token|authorization|nacos(?:Base)?Url|baseUrl)/iu.test(key)) {
+        throw new AiRegistryError("Capability response contains a forbidden address or credential field.", "ai_registry_capability_unsafe");
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            assertCapabilitySafe(item, key);
+    }
+    else if (value && typeof value === "object") {
+        for (const [name, item] of Object.entries(value))
+            assertCapabilitySafe(item, name);
+    }
+}
 //# sourceMappingURL=client.js.map