From 46d900c3f54501f417407fd4f0e30a9d8edae3a0 Mon Sep 17 00:00:00 2001 From: DanliaQwerty20 Date: Mon, 26 Oct 2026 23:48:05 +0300 Subject: [PATCH] feat: add compact action status contract --- README.md | 4 +-- asyncapi/action-events.yaml | 2 +- docs/channel-gateway.md | 3 +++ openapi/action-api.yaml | 2 +- openapi/agent-runtime-api.yaml | 2 +- openapi/channel-gateway-api.yaml | 46 +++++++++++++++++++++++++++++++- openapi/connection-api.yaml | 2 +- openapi/conversation-api.yaml | 2 +- openapi/mcp-gateway-api.yaml | 2 +- package.json | 2 +- test/channel-gateway.test.mjs | 18 +++++++++++++ test/schemas.test.mjs | 2 +- 12 files changed, 76 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 43d5954..27b429f 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,8 @@ OpenAPI в pull request с `main` и блокирует нарушение эт ## Версии и release -Текущая версия — `4.0.0`. Новый тип ответа подключения описан в -[migration guide](docs/migrations/4.0.0.md). +Текущая версия — `4.1.0`. Добавлено короткое состояние действия для всех каналов. +Изменения предыдущей major-версии описаны в [migration guide](docs/migrations/4.0.0.md). Версия в `package.json`, OpenAPI и AsyncAPI должна совпадать. Тег `vX.Y.Z` запускает release workflow. Он проверяет репозиторий и прикладывает к GitHub Release bundle `portable-agent-contracts-X.Y.Z.tgz`. diff --git a/asyncapi/action-events.yaml b/asyncapi/action-events.yaml index 8cb26ed..27ae31a 100644 --- a/asyncapi/action-events.yaml +++ b/asyncapi/action-events.yaml @@ -1,7 +1,7 @@ asyncapi: 3.0.0 info: title: Portable Agent Action Events - version: 4.0.0 + version: 4.1.0 description: События жизненного цикла безопасных действий. defaultContentType: application/json servers: diff --git a/docs/channel-gateway.md b/docs/channel-gateway.md index d12e325..d6e8784 100644 --- a/docs/channel-gateway.md +++ b/docs/channel-gateway.md @@ -23,5 +23,8 @@ `POST /api/v1/actions/{actionId}/decisions` принимает безопасную команду из Widget SDK и передаёт решение в Action Service с тем же Bearer JWT. Благодаря этому адаптер канала работает только с публичной границей Gateway и не знает адрес внутренних сервисов. +`GET /api/v1/actions/{actionId}/status` возвращает только `actionId`, `status`, `kind` и `title`. +Полный payload и `payloadHash` не выходят в ответ статуса. Действие другого пользователя внутри +того же tenant возвращает `404`. Голос и файлы появятся отдельными совместимыми изменениями. Так текстовый контракт не привязан к конкретному мессенджеру. diff --git a/openapi/action-api.yaml b/openapi/action-api.yaml index e2df9cc..a272823 100644 --- a/openapi/action-api.yaml +++ b/openapi/action-api.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Portable Agent Action API - version: 4.0.0 + version: 4.1.0 description: Создание, просмотр и подтверждение безопасных действий агента. license: name: Apache-2.0 diff --git a/openapi/agent-runtime-api.yaml b/openapi/agent-runtime-api.yaml index 3b537c1..8598253 100644 --- a/openapi/agent-runtime-api.yaml +++ b/openapi/agent-runtime-api.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Portable Agent Runtime API - version: 4.0.0 + version: 4.1.0 description: Подготовка предложения действия из текста пользователя. license: name: Apache-2.0 diff --git a/openapi/channel-gateway-api.yaml b/openapi/channel-gateway-api.yaml index 6935a90..b1bc4a0 100644 --- a/openapi/channel-gateway-api.yaml +++ b/openapi/channel-gateway-api.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Portable Agent Channel Gateway API - version: 4.0.0 + version: 4.1.0 description: Единый текстовый вход для независимых каналов пользователя. license: name: Apache-2.0 @@ -79,6 +79,30 @@ paths: application/json: schema: $ref: "#/components/schemas/Problem" + /api/v1/actions/{actionId}/status: + get: + tags: [actions] + operationId: getActionStatus + summary: Получить короткое состояние своего действия + security: + - bearerAuth: [] + parameters: + - $ref: "./action-api.yaml#/components/parameters/ActionId" + responses: + "200": + description: Состояние действия без сохранённого payload + content: + application/json: + schema: + $ref: "#/components/schemas/ActionStatusView" + "401": + description: JWT отсутствует или не подходит Channel Gateway + "404": + description: Действие не найдено либо принадлежит другому пользователю + "422": + description: Некорректный actionId + "502": + description: Action Service временно недоступен /api/v1/actions/{actionId}/decisions: post: tags: [actions] @@ -128,6 +152,26 @@ components: scheme: bearer bearerFormat: JWT schemas: + ActionStatusView: + type: object + additionalProperties: false + required: [actionId, status, kind, title] + properties: + actionId: { type: string, format: uuid } + status: + type: string + enum: + [ + PROPOSED, + AWAITING_APPROVAL, + APPROVED, + EXECUTING, + SUCCEEDED, + FAILED, + CANCELLED, + ] + kind: { type: string, minLength: 1 } + title: { type: string, minLength: 1, maxLength: 200 } MessageRequest: type: object additionalProperties: false diff --git a/openapi/connection-api.yaml b/openapi/connection-api.yaml index 1affbd1..dab3ba6 100644 --- a/openapi/connection-api.yaml +++ b/openapi/connection-api.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Portable Agent Connection API - version: 4.0.0 + version: 4.1.0 description: Подключения внешних аккаунтов. Публичные операции используют владельца из JWT. license: name: Apache-2.0 diff --git a/openapi/conversation-api.yaml b/openapi/conversation-api.yaml index b79a12e..df4bba8 100644 --- a/openapi/conversation-api.yaml +++ b/openapi/conversation-api.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Portable Agent Conversation API - version: 4.0.0 + version: 4.1.0 description: Внутренний API состояния диалога и оркестрации предложения действия. license: name: Apache-2.0 diff --git a/openapi/mcp-gateway-api.yaml b/openapi/mcp-gateway-api.yaml index 61763ec..735956e 100644 --- a/openapi/mcp-gateway-api.yaml +++ b/openapi/mcp-gateway-api.yaml @@ -1,7 +1,7 @@ openapi: 3.1.0 info: title: Portable Agent MCP Gateway API - version: 4.0.0 + version: 4.1.0 description: Безопасный внутренний вызов разрешённых tools в настроенных MCP-сервисах. license: name: Apache-2.0 diff --git a/package.json b/package.json index da64427..7669790 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@portable-agent/contracts", - "version": "4.0.0", + "version": "4.1.0", "private": true, "files": [ "openapi", diff --git a/test/channel-gateway.test.mjs b/test/channel-gateway.test.mjs index a453c31..b11e7c4 100644 --- a/test/channel-gateway.test.mjs +++ b/test/channel-gateway.test.mjs @@ -87,6 +87,24 @@ test("action decision reuses Action API request and response", async () => { assert.deepEqual(decide.security, [{ bearerAuth: [] }]); }); +test("action status is a small protected view without action payload", async () => { + const api = await readApi(); + const route = api.paths["/api/v1/actions/{actionId}/status"].get; + const view = api.components.schemas.ActionStatusView; + + assert.deepEqual(route.security, [{ bearerAuth: [] }]); + assert.equal( + route.responses["200"].content["application/json"].schema.$ref, + "#/components/schemas/ActionStatusView", + ); + assert.ok(route.responses["401"]); + assert.ok(route.responses["404"]); + assert.deepEqual(view.required, ["actionId", "status", "kind", "title"]); + assert.equal(view.additionalProperties, false); + assert.equal(view.properties.payload, undefined); + assert.equal(view.properties.payloadHash, undefined); +}); + test("compatibility workflow checks Channel Gateway contract", async () => { const workflow = await readFile(".github/workflows/ci.yml", "utf8"); diff --git a/test/schemas.test.mjs b/test/schemas.test.mjs index 7fab3c6..aab7b84 100644 --- a/test/schemas.test.mjs +++ b/test/schemas.test.mjs @@ -14,7 +14,7 @@ const readJson = async (path) => JSON.parse(await readFile(path, "utf8")); test("breaking policy reads the real OpenAPI version", async () => { const source = await readFile("openapi/action-api.yaml", "utf8"); - assert.equal(readVersion(source), "4.0.0"); + assert.equal(readVersion(source), "4.1.0"); }); test("compatibility workflow skips policy when oasdiff finds no breaking changes", async () => {