Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down
2 changes: 1 addition & 1 deletion asyncapi/action-events.yaml
Original file line number Diff line number Diff line change
@@ -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:
Expand Down
3 changes: 3 additions & 0 deletions docs/channel-gateway.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Голос и файлы появятся отдельными совместимыми изменениями. Так текстовый контракт не привязан к
конкретному мессенджеру.
2 changes: 1 addition & 1 deletion openapi/action-api.yaml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion openapi/agent-runtime-api.yaml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
46 changes: 45 additions & 1 deletion openapi/channel-gateway-api.yaml
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion openapi/connection-api.yaml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion openapi/conversation-api.yaml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion openapi/mcp-gateway-api.yaml
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@portable-agent/contracts",
"version": "4.0.0",
"version": "4.1.0",
"private": true,
"files": [
"openapi",
Expand Down
18 changes: 18 additions & 0 deletions test/channel-gateway.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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");

Expand Down
2 changes: 1 addition & 1 deletion test/schemas.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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 () => {
Expand Down
Loading