AgoraIO-Extensions / AgoraIO-Extensions/agent-infra

feat(connection): publish Pilot browser catalog and invocation contracts

Abierto
#398 5 comentarios 0 reacciones 1 asignado Asignado a @guoxianzhe Ver en GitHub
enhancement ready-for-human
Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
8 h 51 min
PR fusionados (30 d)
99

Descripción

## Problem

Connection 与 Web、Platform 和 Provider Adapter 无法独立实施,直到 Browser、Catalog、delegated consumer、Action schema、调用状态和稳定错误具备一套版本化 wire contract。

## Scope

- 在现有 contract toolchain 和已完成 delegated Execution Grant contract 上,定义 Connection Pilot 所需 Browser API、只读 Catalog API、delegated assertion consumer binding、ActionCall/Effect 状态和稳定错误 Schema。
- 保持 Zod 手写源、OpenAPI 3.1 和 JSON Schema 的既有单向生成与兼容门禁;不建立第二套 DTO。
- Catalog 只暴露 Provider/Action、immutable version、schema、effect、required scope 和发布状态,不暴露用户 Connection、Grant、Credential 或审计。
- 定义三项 GitHub Action 的输入输出契约、repository policy denial、`RESULT_PENDING`、`NEEDS_MANUAL_REVIEW`、`UNRESOLVED` 和 Provider revoke 状态。
- 稳定区分 Provider 已明确响应的失败与无法确认提交结果:已收到 GitHub HTTP 响应的非成功结果必须映射为脱敏、可审计的 `PROVIDER_FAILED`;只有传输中断导致是否提交不可知,或 Provider 已成功但 Connection 无法持久化终态时,才能进入 `RESULT_PENDING/UNCERTAIN`。
- 提供 Platform、Connection Web 和 Connection runtime 可复用的正负向 consumer tests/Fakes;不实现 Hono route、React 页面、数据库或 Provider 调用。

## Acceptance criteria

- [ ] **AC-1:** Browser、Catalog、delegated 和调用状态契约均有唯一版本、稳定 ID/correlation/error 语义及规范生成产物。
- [ ] **AC-2:** Catalog 契约不含 Principal、Connection、Grant、Credential 或可写授权字段,并能表达 immutable ActionVersion、effect、scope 和状态。
- [ ] **AC-3:** 三项 GitHub Action、repository denial、pending/manual/unresolved 和 revoke 状态具有可校验的成功与失败 Schema;明确 Provider HTTP 失败不得退化为 unknown,unknown 仅表达无法判定副作用是否发生。
- [ ] **AC-4:** consumer tests 拒绝未知版本、调用方提交的身份/账号/Credential selector、Secret-bearing result 和不兼容 Schema 漂移,并覆盖 `add_issue_labels` 已明确失败与响应不确定的差异。
- [ ] **AC-5:** Platform、Web 和 Connection 侧测试使用同一生成产物;连续两次生成字节一致且无未提交漂移。

## Validation

- 运行 focused schema、generation、drift、compatibility、consumer/Fake 和 package-surface tests。
- 以真实 `add_issue_labels` 误判为 unknown 的场景建立回归用例:GitHub 非成功响应得到脱敏 `PROVIDER_FAILED`,仅响应丢失或终态落库失败得到 `RESULT_PENDING/UNCERTAIN`。
- 连续生成两次并确认第二次不产生 diff;运行完整仓库验证序列。

## Blocked by

- #252
- #393

Guía de contribución

No hay ninguna guía de contribución indexada para este repositorio

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.