通过认证 HTTP 提交与恢复 Agent。

接入可信身份与资源授权

必须配置 AgentHttpAuthenticator，验证签名或令牌内省证据、签发方、受众、有效期与吊销状态，再映射可信租户、主体，以及彼此独立的 Submit、Read、Cancel 权限。框架没有默认放行器，也没有匿名模式。

底层 AgentServiceAuthorizer 仍在查询资源前，检查精确 Agent/请求、Run 或提交键摘要的访问权限。请求 JSON、未验证的 JWT 和任意转发头不能决定身份。客户端预算只能收窄宿主策略。

use std::sync::Arc;
use stateknot::agent_http::{AgentHttpOptions, AgentHttpService};

// service：已绑定精确部署版本与资源授权策略的 AgentServiceV1。
// verifier：接入真实身份系统的 AgentHttpAuthenticator，不能使用测试凭据。
let options = AgentHttpOptions::new(["agents.example.com".to_owned()])?;
let http = AgentHttpService::new(service, Arc::new(verifier), options);
let router = http.router();
// 在 TLS 入口后挂载；单独运行 Worker；由宿主启动和排空监听器。

接入真实身份服务：在线令牌验证

AgentHttpIntrospection 可直接接入 OAuth 2.0 令牌内省端点， 使用固定 HTTPS 地址，严格核对签发方、受众、主体、有效期和操作 Scope。 已通过真实 Keycloak 26.7.3 TLS、密钥轮换和身份撤销测试；没有跳转、环境代理、 自动重试、令牌缓存或不安全 TLS 开关。这不等于 JWT/JWKS 本地验签或完整 OIDC。

TenantPolicy 只接受可信控制面提供的精确主体与租户绑定， 权限取令牌 Scope 与本地授权的交集。策略最多 1024 项，租期必须显式指定且不超过一小时； 使用带预期代数的 replace 原子更新，过期后拒绝放行。 租户绑定不是 Run 所有权，原有 AgentServiceAuthorizer 仍须逐资源授权。

用 replace_client_secret 安装密钥管理服务下发的新凭据。 就绪检查通过真实客户端认证发送随机无效令牌，要求返回 inactive； 它只验证端点和凭据可用，不能替代业务授权或资源策略就绪检查。 没有凭据重叠窗口的轮换会短暂返回 503，不能降级放行。

默认整次验证最多 3 秒、32 个并发请求、64 KiB 响应； 每次 HTTP 请求和 SSE 授权循环都在线验证，需规划身份服务容量。 已进入网络缓冲的字节无法撤回。测试身份服务和测试账号不会部署到官网。

完整接线、轮换与故障恢复指南 · RFC-0011（Draft）

使用 JWT/JWKS 在本地验证访问令牌

AgentHttpJwtJwks 使用可信控制面分发的公钥，验证 RS256 at+jwt 访问令牌。通过 JwtJwksOptions 指定精确签发方、资源受众和操作 Scope。通过签名的身份仍须满足 TenantPolicy 与独立 AgentServiceAuthorizer 授权。此功能位于当前源码。

最多提供 16 把公钥、16 KiB 数据，显式有效时间最长一小时。 replace_jwks 完整验证集合，并核对预期版本后原子发布。 必须从重新验证的可信来源刷新，公钥过期返回 503；移除密钥会拒绝 后续验证，并关闭使用它的 SSE 事件流。令牌默认总生命周期为 15 分钟， 不通过时钟偏差延长有效期。

本地验证不需要每个请求访问身份服务，部署方负责可信公钥分发和及时刷新。 需要即时观察服务端逐令牌撤销时，使用在线 introspection。 本地就绪检查验证公钥与策略的新鲜度，仍需组合实际资源策略和数据库依赖。 PostgreSQL 16/17 测试覆盖跨租户与资源拒绝、轮换、SSE 关闭、 过期恢复及新验证器下的准入重放。

完整 JWT 接入与公钥轮换指南 · RFC-0018（Accepted）

单独运行执行角色

现在可使用独立的持久执行 Worker， 管理具体租户或公平调度器、真实依赖就绪检查、固定并发和停机回收。 HTTP 接入仍独立运行，提交 Run 不会自动启动 Worker 或维护任务。

通过独立的维护角色驱动 截止时间取消、子 Run 结算、Join 发布与失败收敛；即使没有可执行的 Run，维护仍应运行。

通过独立授权的运维接口查看宿主

AgentHostOperations::start 独立接管 loopback 监听器，读取实际宿主健康视图。 每个请求必须同时满足真实身份验证、InspectHost 权限和有效的 AgentHostOperationsPolicy。业务 Read 权限不能替代运维授权。 令牌内省需显式配置 with_host_inspection_scope，同时检查令牌 scope 与可信租户授权。

仅支持 GET /v1/host/status、/v1/host/live、 /v1/host/ready。业务依赖故障或宿主停止后仍可授权查看状态； 身份服务或运维策略失效则拒绝访问。没有匿名探针、浏览器 Origin、请求体或管理写操作。

最多 128 个精确运维调用方，有效期不超过一小时，更新检查 generation 且不自动续期。 默认 16 连接/请求、5 秒请求/排空、3 秒读头、60 秒连接寿命。快照只输出固定标签和计数， 不含租户/Run ID 或凭据；累计计数用十进制字符串，读取不探测数据库。

先停止并等待业务宿主，按需查看最终状态，再等待 operations.shutdown().await。 取消等待不丢失所有权，强制排空也会等待连接销毁。PostgreSQL 16/17 与真实 TLS 身份测试覆盖 专属运维 scope、过期、撤销、上限与资源回收；这些验证不等于生产容量或恢复 SLO。 官网仍仅部署静态文档。 接线、响应格式与运维指南 · RFC-0016（Draft）

统一管理同进程的三个角色

AgentHostBindings::new 接管实际接入、Worker 和维护绑定； AgentHostDependencies 强制提供真实身份、资源策略和执行依赖检查。 AgentHost::launch 独占认领共享接入，在异步启动之前返回拥有所有权的句柄； 取消 host.wait_ready().await 不会丢失所有权。 应用仍须验证三者的数据库、注册表与租户范围兼容。

启动顺序为“维护 → Worker → HTTP”。已有持久化任务可在启动期间执行， 后续启动失败会回收已启动角色，但不回滚已提交工作。 每个 HTTP 请求都会检查实际兄弟角色的新鲜就绪状态，维护不可用时 Worker 暂停接纳新工作。 已接纳任务仍可能完成；不要另外挂载输入服务的克隆 Router 绕过统一入口门禁。

host.health() 是不含业务载荷的内部视图，不是匿名运维接口。 任一角色意外退出都会关闭入口并排空其他角色。 host.shutdown().await 按“HTTP → Worker → 维护”完成回收， 保留 Worker 清理期间的维护能力。Drop 只能发起停止，不能同步等待回收。 操作系统停机预算必须覆盖三个角色的期限之和与任务销毁时间；进程停止不等于持久化用户取消。

PostgreSQL 16/17 与真实 TLS Keycloak 验证组合恢复、依赖门禁、启动失败、角色退出及任务回收。 受保护运维接口在上方独立授权，实测部署与容量 SLO 仍需后续完成。 官网仅部署静态文档，不部署使用测试身份的 Agent 运行服务。 接线与恢复指南 · RFC-0015（Draft）

配置真实资源授权：精确权限与可恢复提交

runtime::agent_policy::AgentResourcePolicy 提供离线、默认拒绝的资源授权。 提交规则精确匹配租户、签发方与主体、Agent 版本和输入 Schema，并附带 Scope 与预算限制。 Run 读取、取消以及提交键查找分别授权；知道 Run ID 不代表拥有权限。 TenantRuns 是明确授予的租户运维权限，不是自动所有权判断。

使用 PolicyDocument 构造 PolicyArtifact，激活前私下保留规范化文件与可信摘要。 总计最多 1024 条规则、256 KiB JSON；重复或重叠选择器直接拒绝。 冻结注册表前调用 register_agent_policy_evidence_schema， 再把共享策略传给 AgentServiceV1，并将资源策略就绪与身份服务就绪组合检查。

策略绝对到期时间跨重启保留，本地新鲜度租期最多一小时；replace 通过预期代数原子更新。 过期返回 503，无授权规则返回 403；撤销后 SSE 在后续授权检查中关闭。 Admission 保留命中规则、请求摘要与预算证据；更新其他资源的权限不会破坏原键重试。 若修改实际命中的提交规则而返回 409，应在当前授权下按键找回，不自动换键重复提交。

读取与拒绝决策不自动写入持久审计账本，取消只保留策略与决策摘要；宿主须按要求保留受保护的审计上下文。 已接入真实 PostgreSQL 16/17 与 Keycloak 验证；不包含自动所有权存储，也不代表完整生产版本。 配置、接线与运维指南 · RFC-0012（Draft）

四个操作，共用持久化服务

POST /v1/agent-runs

序列化 AgentHttpSubmission：submission_key、含版本的完整 agent 身份，以及绑定 Schema 的 request。201 表示新建；200 表示找回原 Run。

GET /v1/agent-runs/{run_id}

不带请求体。200 返回通过完整性校验的公开快照，不包含私有检查点和对话记录。

POST /v1/agent-runs/lookup

序列化带 submission_key 的 AgentHttpLookup。提交键不进入 URL，也不要记录到访问日志。

POST /v1/agent-runs/{run_id}/cancellation

序列化已保存的 AgentCancellationIds，包含 event_id 与 failure_id。202 表示请求已记录；200 表示找回同一对身份对应的请求。

请求使用 Bearer 凭据，POST 使用 JSON。Accept 只能省略、设为 application/json 或 */*。Rust 类型可生成 JSON Schema；未知字段、嵌套重复键、查询参数及非规范路径均会被拒绝。

成功响应为 AgentHttpRunResponse { request_id, snapshot }。request_id 只关联本次响应，不是幂等键。Active 不代表 Worker 此刻正在执行，也可能处于失败收尾阶段；CancellationRequested 不代表取消清理已经完成。

断线后按活动游标继续读取

在同一个认证宿主上启用 with_sse(AgentHttpSseOptions::default())， 使用 Bearer 凭据和 Accept: text/event-stream 连接 GET /v1/agent-runs/{run_id}/events。 重连时携带最后完整处理并保存的 Last-Event-ID。 原生 EventSource 不能设置这个认证头，应使用支持认证的流式 HTTP 客户端， 不能把凭据放进 URL 或改成匿名访问。

activity

每条保留日志对应一个公开通知。id 是经数据库核对的 续传游标，JSON 只有十进制字符串序号与记录时间，不暴露私有载荷、日志种类或对话。

snapshot

当前经过验证的 AgentHttpRunResponse，不带 id。 它不是游标位置上的历史状态，中间快照可能合并；仅隔离状态变化也会通知。

error / heartbeat

都不推进续传进度。错误帧只尽力发送， 心跳是注释；连接结束不能证明任务执行成功。

先幂等处理活动，再保存完整游标。更换进程后仍从该精确事件之后续传。 畸形编码返回 400；被篡改、跨范围或历史不可用的游标返回 agent_http.invalid_cursor（409），不能悄悄重置进度。 这不是 Token 流、完整历史状态重放，也不承诺 exactly-once 交付。

默认最多 16 个流生产任务、60 秒连接时限、1 秒轮询/心跳、5 秒队列等待、 单槽有界缓冲及每条连接累计 64 MiB 输出。事件流与 JSON 请求使用独立额度。 每轮重新验证凭据与资源权限；已授权并交给网络缓冲区的字节无法撤回。 丢弃响应、队列超时和停机都会停止生产任务。宿主还须限制 Socket 并关闭该路由的代理缓冲和压缩。

完整客户端恢复与生产部署指南 · RFC-0009

管理就绪状态、连接与优雅停机

AgentHttpServer::start 接管只绑定本机回环地址的 HTTP/1 监听器，由同一网络命名空间内的代理负责公网 TLS。启动前校验实际使用的 PostgreSQL Schema、精确可执行注册表，并强制提供 AgentHttpReadiness， 检查请求真正使用的凭据验证与资源策略依赖。不会默认安装身份验证器，也不自动执行迁移、启动 Worker 或调度器。

默认每次检查完成后间隔 10 秒再检查，整个检查限时 5 秒，就绪证据有效期为 20 秒。 检查不重叠；依赖失败、超时或证据过期时，新业务请求返回 503，后续检查成功才重新接入。 就绪不等于获得授权，也不保证下一次请求一定成功；已接入的请求仍受原有授权和时限控制。

传输层默认最多 256 个连接、64 个请求头、32 KiB 解析缓冲、5 秒请求头读取时限和 300 秒连接绝对存活时限。超额连接直接关闭，不进入业务处理。JSON 与 SSE 各自的上限继续生效；TLS、代理限制及跨副本配额仍需部署方配置。

server.health() 只提供本地状态和活动连接数，应接入受保护的管理或进程监督界面； 不会在 Agent API 中添加匿名健康检查入口。依赖不可用时可以仍然存活，但不接收新业务。

server.begin_shutdown() 立即撤销就绪状态；等待 server.shutdown() 停止接收连接并允许已接入工作完成。默认排空 30 秒后，取消并回收剩余连接任务；SSE 可能需要这一强制关闭阶段。检查停机报告，并保留原提交键、取消身份及游标：连接关闭不代表事务回滚。 直接丢弃服务句柄会中止工作，但不等于已经等待优雅停机。阻塞式回调仍需进程监督器的外层强制退出期限； 共享数据库连接池由部署方管理，不会被服务擅自关闭。

PostgreSQL 16/17 实测覆盖就绪失效与恢复、启动失败、排空期间成功提交、慢请求体和 SSE 强制关闭、空闲连接及句柄释放、传输上限。真实身份与策略服务的角色集成和稳定版发布仍是后续门禁。 完整接线与运维指南 · RFC-0010

响应丢失后找回任务，不重复创建

首次提交前，持久保存高熵提交键及完整逻辑请求；首次取消前，保存两个取消 ID。超时、断连、服务停机或响应超限，都不等于数据库事务已回滚。

通过原提交键或 Run 查询，或保留原内容和身份进行有界退避重试。相同键却更改提交内容，或者另换一对取消 ID，会返回 409。先核对持久化状态，不要因为没收到响应就生成新键。重试得到的快照可能已推进到更新版本。

资源上限与不泄露载荷的错误

默认请求上限 256 KiB、响应上限 2 MiB、每个共享服务实例最多 64 个并发请求、协作式总超时 15 秒。硬上限分别为 2 MiB、8 MiB、1,024 个请求及 60 秒；JSON 还有结构深度等限制。异步超时不能抢占宿主中的阻塞代码。

400 表示格式错误；401/403 表示认证或策略拒绝；404 只在授权后表示目标不存在；405/406/415 表示不支持的 HTTP 形式；409 表示冲突；413 表示请求体超限或读取失败；429 表示容量已满；503 表示依赖不可用、超时或停机；500 表示完整性、配置或响应上限问题。

JSON 操作均返回禁止缓存的私有 JSON，带关联 ID 和 API 版本头。错误只返回固定的 agent_http.* 代码与 request_id，不转发令牌、SQL 或提供商原始消息。429 与 503 附带 Retry-After: 1。

对外上线前的配置清单

1. 固定兼容的源码、锁文件、数据库迁移、Graph 和 Schema。独立配置调度器与 Worker；仅提交任务不会推动 Run 执行。
2. 配置 TLS、精确 Host 白名单、连接数及请求头上限、租户配额与跨副本流量控制。转发头不能扩大信任。默认拒绝 Origin；可选精确 HTTPS 来源不意味着开放 CORS。
3. 接入真实凭据验证与精确资源策略，验证过期、吊销、错误受众及跨租户访问。不可部署测试中的静态凭据。
4. 日志不记录认证头、提交键、输入输出和原始路径；监控有界延迟/错误指标及依赖就绪状态。
5. 使用运行角色时等待 server.shutdown()。仅嵌入路由的部署仍需调用 http.shutdown() 并自行限制连接排空时间。替换服务后，用原身份恢复可能已经提交的请求。

验证覆盖真实 HTTP + PostgreSQL 16/17、24 路同键并发提交、提交/取消响应丢失恢复、无内联执行、恶意输入、数据库不可用前的授权拒绝、慢请求、过载与停机。 SSE 另外覆盖新进程续传、撤权、仅隔离状态变化及完全不读取响应的情况。 这不等于已完成真实身份提供商、模型或整套生产部署的验收。

完整接口与运维说明（英文） · RFC-0008 · 开发状态