diff --git a/api/README.md b/api/README.md index 7e2a08a..592dcef 100644 --- a/api/README.md +++ b/api/README.md @@ -93,3 +93,9 @@ v5 只对 `/more/changelog/v10.0.180` 和 `/en/more/changelog/v10.0.180` 做定 RunMeta 接受 `handed_off`,但现行 runtime-state HTTP 入口仍对该状态返回 `404`。共享 Schema 的五值枚举不能直接当作该路由的实际响应合同。历史消息的分页窗口与返回消息条数不同,示例按请求窗口推进;媒体读取使用短期签名,附件下载使用实例身份。 `publication.json`、生产和搜索验收 JSON 保留已经发布批次的事实;本批提交 PR 不代表这些新页面已经部署或收录。 + +## 2026-10-22 稳定性复核 + +最新核对源码为 `a101a40c14cc9d478c7f9a23d8a125ac2404509b`,内部文档指针为 `34178859da7a70cfab0b4726b85d9a37f22608a7`。本次维持35个公开HTTP操作,补齐敏感工具结果占位、引用移除、状态保留与客户端兼容处理说明,Agent Service规范描述修订为1.1.1;不把描述版本写成服务兼容性保证。详见[本次复核与验证](./stability-verification-2026-10-22.md)。 + +RunMeta五态与runtime-state HTTP四态/转交404的差异仍存在,公开文件继续按实际路由呈现。历史读取并非无损备份,不能从占位文字自动恢复执行。此前发布与搜索验收的记录保持各自历史基线,不将本次源码核对当作新生产或安装包验收。 diff --git a/api/endpoint-catalog.json b/api/endpoint-catalog.json index b7efae7..966d380 100644 --- a/api/endpoint-catalog.json +++ b/api/endpoint-catalog.json @@ -1,11 +1,11 @@ { "schemaVersion": 1, "reviewBaseline": { - "reviewedAt": "2026-10-15", + "reviewedAt": "2026-10-22", "clientRepository": "desirecore/desirecore", - "clientRevision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", - "internalDocsRevision": "b17e6a7a2d3dc4d969ea422ee37825ae39eb6177", - "publicDocsBaseRevision": "3e0e3de7168e2392802d37d295f73a65af070f5e" + "clientRevision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", + "internalDocsRevision": "34178859da7a70cfab0b4726b85d9a37f22608a7", + "publicDocsBaseRevision": "4530b1797db7bbe68961069cce599af1c7e5e258" }, "pages": [ { @@ -75,7 +75,7 @@ "resultDelivery": "Synchronous JSON metadata. A 200 response verifies this authenticated request, not every optional capability.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/client-handshake-routes.ts", "packages/agent-service/src/service-metadata.ts", @@ -92,7 +92,7 @@ "verification": { "record": "api/verification.md", "scope": "Fixed-source auth and handshake unit tests plus a real loopback HTTPS readiness integration; no public-domain or Caddy-container run.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -114,7 +114,7 @@ "resultDelivery": "200 {accepted:true,agentId,event} acknowledges receipt, with no Run ID or delivery deduplication. Only explicit authorized SendUserMessage output is delivered to the user; final model answers are not automatically returned to the caller or added to chat.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/webhook-routes.ts", "packages/agent-service/src/routes/webhook-state.ts", @@ -133,7 +133,7 @@ "verification": { "record": "api/verification.md", "scope": "Real production owner management, atomic AgentFS snapshot writes, local fake-provider runtime and SendUserMessage delivery, rotation, failure and disable/delete integration. No commercial-provider or packaged-client claim.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -154,21 +154,21 @@ "resultDelivery": "Synchronous read; live state is observational, not a query completion signal.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/agent-routes.ts", "packages/agent-service/src/agent/list-projection.ts" ] }, "schemaRefs": [ - "packages/schemas/src/agent-service/agent-summary.ts" + "packages/schemas/src/agent/agent-summary.ts" ], "effectiveVersion": null, "versionEvidence": null, "verification": { "record": "api/verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -189,7 +189,7 @@ "resultDelivery": "Synchronous read; live state is observational, not a query completion signal.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/runs-routes.ts", "packages/agent-service/src/session/run-manager.ts" @@ -203,7 +203,7 @@ "verification": { "record": "api/history-attachments-verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -224,7 +224,7 @@ "resultDelivery": "Synchronous read; live state is observational, not a query completion signal.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/runs-routes.ts", "packages/agent-service/src/session/run-meta-read.ts" @@ -238,7 +238,7 @@ "verification": { "record": "api/history-attachments-verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -259,7 +259,7 @@ "resultDelivery": "Synchronous read; live state is observational, not a query completion signal.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/runs-routes.ts" ] @@ -272,7 +272,7 @@ "verification": { "record": "api/history-attachments-verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -293,7 +293,7 @@ "resultDelivery": "Synchronous read; live state is observational, not a query completion signal.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/runs-routes.ts", "packages/agent-service/src/receipts/reader.ts" @@ -307,7 +307,7 @@ "verification": { "record": "api/verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -328,7 +328,7 @@ "resultDelivery": "HTTP admission or lookup JSON; query completion and incremental messages arrive through correlated Socket.IO events.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/query-routes.ts", "packages/agent-service/src/query/client-request-registry.ts" @@ -342,7 +342,7 @@ "verification": { "record": "api/verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -363,7 +363,7 @@ "resultDelivery": "HTTP admission or lookup JSON; query completion and incremental messages arrive through correlated Socket.IO events.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/query-routes.ts", "packages/agent-service/src/query/client-request-registry.ts" @@ -377,7 +377,7 @@ "verification": { "record": "api/verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -398,7 +398,7 @@ "resultDelivery": "HTTP admission or lookup JSON; query completion and incremental messages arrive through correlated Socket.IO events.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/query-routes.ts", "packages/agent-service/src/query/client-request-registry.ts" @@ -412,7 +412,7 @@ "verification": { "record": "api/verification.md", "scope": "Fixed-source request/response examples and focused HTTP + Socket.IO client contract; runtime fake in the public client fixture.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -433,7 +433,7 @@ "resultDelivery": "Synchronous configuration or explicit delivery JSON. First configuration and rotation disclose a secret once; GET does not return it.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/webhook-management-routes.ts", "packages/agent-service/src/auth/governed-endpoint-auth.ts" @@ -447,7 +447,7 @@ "verification": { "record": "api/verification.md", "scope": "Production Webhook management integration with local fake model upstream and real delivery persistence; no commercial model or desktop package verification.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -468,7 +468,7 @@ "resultDelivery": "Synchronous configuration or explicit delivery JSON. First configuration and rotation disclose a secret once; GET does not return it.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/webhook-management-routes.ts", "packages/agent-service/src/auth/governed-endpoint-auth.ts" @@ -482,7 +482,7 @@ "verification": { "record": "api/verification.md", "scope": "Production Webhook management integration with local fake model upstream and real delivery persistence; no commercial model or desktop package verification.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -503,7 +503,7 @@ "resultDelivery": "Synchronous configuration or explicit delivery JSON. First configuration and rotation disclose a secret once; GET does not return it.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/webhook-management-routes.ts", "packages/agent-service/src/auth/governed-endpoint-auth.ts" @@ -517,7 +517,7 @@ "verification": { "record": "api/verification.md", "scope": "Production Webhook management integration with local fake model upstream and real delivery persistence; no commercial model or desktop package verification.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -538,7 +538,7 @@ "resultDelivery": "Synchronous configuration or explicit delivery JSON. First configuration and rotation disclose a secret once; GET does not return it.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/webhook-management-routes.ts", "packages/agent-service/src/auth/governed-endpoint-auth.ts" @@ -552,7 +552,7 @@ "verification": { "record": "api/verification.md", "scope": "Production Webhook management integration with local fake model upstream and real delivery persistence; no commercial model or desktop package verification.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -573,7 +573,7 @@ "resultDelivery": "Synchronous configuration or explicit delivery JSON. First configuration and rotation disclose a secret once; GET does not return it.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/webhook-management-routes.ts", "packages/agent-service/src/auth/governed-endpoint-auth.ts" @@ -587,7 +587,7 @@ "verification": { "record": "api/verification.md", "scope": "Production Webhook management integration with local fake model upstream and real delivery persistence; no commercial model or desktop package verification.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -608,7 +608,7 @@ "resultDelivery": "Synchronous {items,total,limit,offset}; default limit50, maximum200. Items may include other authorized background deliveries.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/schedule-routes.ts", "packages/agent-service/src/auth/governed-endpoint-auth.ts" @@ -620,7 +620,7 @@ "verification": { "record": "api/verification.md", "scope": "Production Webhook management integration with local fake model upstream and real delivery persistence; no commercial model or desktop package verification.", - "baselineNote": "Source contract rechecked at 7fe016c. Historical runtime test results retain their recorded source baseline; this batch coverage is recorded separately in api/history-attachments-verification.md." + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -914,7 +914,7 @@ "resultDelivery": "Complete persisted attachment receipt.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/attachment-routes.ts", "packages/schemas/src/agent-service/attachments.ts", @@ -929,7 +929,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately." + "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -951,7 +952,7 @@ "resultDelivery": "Original file bytes with no-store and nosniff.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/attachment-routes.ts", "packages/schemas/src/agent-service/attachments.ts", @@ -964,7 +965,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately." + "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -986,7 +988,7 @@ "resultDelivery": "Direct media metadata.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/media-routes.ts", "packages/agent-service/src/media/media-store.ts", @@ -1000,7 +1002,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately." + "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1022,7 +1025,7 @@ "resultDelivery": "Links and missing IDs; no universal success/data wrapper.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/media-routes.ts", "packages/agent-service/src/media/media-store.ts", @@ -1038,7 +1041,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately." + "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1060,7 +1064,7 @@ "resultDelivery": "Full media bytes.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/media-routes.ts", "packages/agent-service/src/media/media-store.ts", @@ -1078,7 +1082,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately." + "scope": "Fixed-source route/schema/auth review. Standalone uploader: 12 local HTTP contract tests with a fake server, not production storage or model execution. Root records actual fixed-source route validation separately.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1099,7 +1104,7 @@ "resultDelivery": "Lists ordinary user-visible history by updatedAt descending. Excludes delegated, manual and dedicated schedule/Webhook/Mention timelines. Preserves fork generations; do not concatenate branches as a deduplicated transcript. Pagination is not an immutable snapshot.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/history-routes.ts", "packages/agent-service/src/session/store.ts", @@ -1114,7 +1119,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim." + "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1132,16 +1138,17 @@ ], "authentication": "X-Agent-Service-Token from the deployment administrator", "permissions": "Valid deployment-owner instance credential; exact history is filtered by the trusted user before preview/body reads. Knowing a Run ID does not grant access.", - "resultDelivery": "Checks trusted user ownership before body/image reads. Missing, cleared and unowned Runs return 404. Delegated Runs return 403 delegated_run_requires_inspect_view; use the messages inspection view instead. pendingAssistant is temporary and separate from durable messages. Returned configuration is not execution authority.", + "resultDelivery": "Checks trusted user ownership before body/image reads. Missing, cleared and unowned Runs return 404. Delegated Runs return 403 delegated_run_requires_inspect_view; use the messages inspection view instead. pendingAssistant is temporary and separate from durable messages. Returned configuration is not execution authority. Sensitive tool results may be withheld in the display projection; body references can be removed without changing the underlying execution outcome.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/history-routes.ts", "packages/agent-service/src/session/store.ts", "packages/agent-service/src/session/public-session-projection.ts", "packages/agent-service/src/session/persistent-state/history.ts", - "packages/agent-service/src/auth/instance-auth.ts" + "packages/agent-service/src/auth/instance-auth.ts", + "packages/agent-service/src/builtin-tools/tool-result-privacy.ts" ] }, "schemaRefs": [ @@ -1151,8 +1158,9 @@ "effectiveVersion": null, "versionEvidence": null, "verification": { - "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim." + "record": "api/stability-verification-2026-10-22.md", + "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1170,16 +1178,17 @@ ], "authentication": "X-Agent-Service-Token from the deployment administrator", "permissions": "Valid deployment-owner instance credential; exact history is filtered by the trusted user before preview/body reads. Knowing a Run ID does not grant access.", - "resultDelivery": "Checks ownership before content reads. Delegated Runs require view=inspect-run. total counts source rows, not returned messages; advance offset by the requested limit and stop at total, even if a page is empty. Optional live is a temporary delegated display checkpoint, not a durable message or terminal. There is no cross-page consistency revision.", + "resultDelivery": "Checks ownership before content reads. Delegated Runs require view=inspect-run. total counts source rows, not returned messages; advance offset by the requested limit and stop at total, even if a page is empty. Optional live is a temporary delegated display checkpoint, not a durable message or terminal. There is no cross-page consistency revision. Sensitive tool results may be withheld in the display projection; body references can be removed without changing the underlying execution outcome.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/history-routes.ts", "packages/agent-service/src/session/store.ts", "packages/agent-service/src/session/message-index.ts", "packages/agent-service/src/session/public-session-projection.ts", - "packages/agent-service/src/auth/instance-auth.ts" + "packages/agent-service/src/auth/instance-auth.ts", + "packages/agent-service/src/builtin-tools/tool-result-privacy.ts" ] }, "schemaRefs": [ @@ -1189,8 +1198,9 @@ "effectiveVersion": null, "versionEvidence": null, "verification": { - "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim." + "record": "api/stability-verification-2026-10-22.md", + "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1211,7 +1221,7 @@ "resultDelivery": "Matches extracted message text case-insensitively, newest timestamp first. Includes independent manual conversations; excludes archived and delegated Runs. Default-conversation fork families select the visible history window. preferredRunId is neither a credential nor an exact-Run filter. limit/offset and their sum must be safe nonnegative integers. limit=0 returns all remaining hits and hasMore=false. Match original text before cropping previews.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/history-routes.ts", "packages/agent-service/src/session/store.ts", @@ -1227,7 +1237,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim." + "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1248,7 +1259,7 @@ "resultDelivery": "Reads the instance's current local profile, not a caller-supplied tenant ID. Intended for the deployment owner. Returns all active matters and at most ten recent entries, not a complete transcript. No pagination. An empty overview does not establish Agent existence or absence of history.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/conversation-routes.ts", "packages/agent-service/src/conversation-memory/overview-projection.ts", @@ -1263,7 +1274,8 @@ "versionEvidence": null, "verification": { "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim." + "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ @@ -1281,16 +1293,17 @@ ], "authentication": "X-Agent-Service-Token from the deployment administrator", "permissions": "Deployment owner only: conversation memory is selected by the instance's current local profile. This is not a multi-tenant isolation API. Matter Run sources additionally verify user and Agent ownership.", - "resultDelivery": "Reads the instance owner's local-profile conversation memory. Supports active, recent and archived source data. Underlying Run reads recheck that user and Agent ownership. Reads at most 120 source messages and sets truncated=true if more exist; projection may omit entries. No pagination or limit-override parameter. Entries are not guaranteed to have the per-Run message shape.", + "resultDelivery": "Reads the instance owner's local-profile conversation memory. Supports active, recent and archived source data. Underlying Run reads recheck that user and Agent ownership. Reads at most 120 source messages and sets truncated=true if more exist; projection may omit entries. No pagination or limit-override parameter. Entries are not guaranteed to have the per-Run message shape. Sensitive tool results may be withheld in the display projection; body references can be removed without changing the underlying execution outcome.", "source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb", + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b", "files": [ "packages/agent-service/src/routes/conversation-routes.ts", "packages/agent-service/src/conversation-memory/conversation-store.ts", "packages/agent-service/src/session/run-meta-read.ts", "packages/agent-service/src/session/public-session-projection.ts", - "packages/agent-service/src/auth/instance-auth.ts" + "packages/agent-service/src/auth/instance-auth.ts", + "packages/agent-service/src/builtin-tools/tool-result-privacy.ts" ] }, "schemaRefs": [ @@ -1299,8 +1312,9 @@ "effectiveVersion": null, "versionEvidence": null, "verification": { - "record": "api/history-attachments-verification.md", - "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim." + "record": "api/stability-verification-2026-10-22.md", + "scope": "Fixed-source route/owner/pagination review; real local source history routes and SessionStore fixture verifies authentication, owner isolation, public projection, search validation and empty/404 matter reads. The independent example uses 13 local HTTP contract tests, including paging gaps and truncation; no deployed-instance claim.", + "baselineNote": "Source contract reviewed at a101a40c on 2026-10-22. Historical test results retain their own recorded baseline; current validation is recorded in api/stability-verification-2026-10-22.md." }, "spec": "static/openapi/agent-service.json", "securitySchemes": [ diff --git a/api/examples/agent-client/README.md b/api/examples/agent-client/README.md index df3c0b7..01ed5b0 100644 --- a/api/examples/agent-client/README.md +++ b/api/examples/agent-client/README.md @@ -76,7 +76,7 @@ Run `npm test` for the independent HTTP + Socket.IO contract fixture. It verifie `test/source-route.fixture.ts` can be copied into a fixed-source DesireCore checkout as `packages/agent-service/src/__tests__/api-docs-node-client.integration.test.ts`. Set `DESIRECORE_API_EXAMPLE_PATH` to the absolute path of this directory's `client.mjs`, then run that single file in the repository's integration test project. It verifies this client against the actual query routes, HTTP/Socket authentication, request Schema and digest, durable admission registry and lookup, and renderer delivery room. The query runtime and follow-up execution callback remain fake. Use its isolated temporary data root; do not point it at an existing user profile. -Current source review: `desirecore/desirecore` commit `7fe016c76ab98e0643ab4f2710c3733f757ef4fb`. Historical validation remains in `api/verification.md`; this extension is recorded in `api/history-attachments-verification.md`. +Current source review: `desirecore/desirecore` commit `a101a40c14cc9d478c7f9a23d8a125ac2404509b`. Historical validation remains in `api/verification.md`; this extension is recorded in `api/history-attachments-verification.md`. - HTTP submission: `packages/agent-service/src/routes/query-routes.ts`. - Admission lookup: `packages/agent-service/src/routes/client-request-lookup-routes.ts`; shared Schema in `packages/schemas/src/agent-service/client-request-admission.ts`. @@ -88,3 +88,5 @@ Current source review: `desirecore/desirecore` commit `7fe016c76ab98e0643ab4f271 Keep the three published downloads byte-identical to their maintained files: `client.mjs` → `static/api-examples/agent-client.mjs`, `history.mjs` → `static/api-examples/history.mjs`, and `attachments.mjs` → `static/api-examples/attachments.mjs`. Revalidate the affected contracts after changes. The example is deliberately a small client, not a complete renderer, SDK, or durable execution orchestrator. `test/source-history.fixture.ts` can be copied to the fixed source tree as `packages/agent-service/src/__tests__/api-docs-history.test.ts` and run in the `unit` project. It uses actual instance authentication, history/topic/Run routes and temporary file storage. The local profile and runtime discovery are stubs. It checks owner filtering, public message projection, search validation, empty topic reads, and the actual `handed_off` detail/`404` runtime-state behavior. It does not run a model or real handoff. Website TypeScript checking excludes these two source fixtures because their imports resolve only inside DesireCore’s source repository. + +History output is a display projection: sensitive tool results may be placeholders, and body references may be absent. The reader preserves these payloads and optional response extensions; it does not infer tool success from placeholder text, retrieve withheld references, or execute replacement work. Current stability review and verification are recorded in `api/stability-verification-2026-10-22.md`. diff --git a/api/examples/agent-client/test/history.test.mjs b/api/examples/agent-client/test/history.test.mjs index 7f58a99..7190ac5 100644 --- a/api/examples/agent-client/test/history.test.mjs +++ b/api/examples/agent-client/test/history.test.mjs @@ -114,11 +114,14 @@ test('bounds all-pages requests and reports the next offset', async t => { }); test('uses the exact Run snapshot endpoint and leaves the public payload intact', async t => { - const snapshot = { runId: 'run-a', messages: [], pendingAssistant: { role: 'assistant', content: 'in progress' }, status: 'idle' }; + const snapshot = { runId: 'run-a', messages: [{ role: 'assistant', content: '', toolUse: [ + { id: 'private-call', name: 'BrowserScript', summary: 'Tool result withheld', status: 'failed', isError: true }, + ] }], pendingAssistant: { role: 'assistant', content: 'in progress' }, status: 'idle', optionalExtension: { displayOnly: true } }; const f = await fixture(t, (url, response) => { assert.equal(url.pathname, '/api/sessions/run-a'); json(response, 200, snapshot); }); const out = await read({ command: 'session', id: 'run-a' }, f.env); assert.deepEqual(out.records[0].data, snapshot); assert.equal(out.result.exitCode, 0); + assert.equal(f.requests.length, 2); // Handshake and read only: withheld output never triggers execution. }); test('overview and matter are unpaginated; a truncated matter exits 2', async t => { diff --git a/api/examples/agent-client/test/source-history.fixture.ts b/api/examples/agent-client/test/source-history.fixture.ts index 32de3dc..7909833 100644 --- a/api/examples/agent-client/test/source-history.fixture.ts +++ b/api/examples/agent-client/test/source-history.fixture.ts @@ -84,6 +84,29 @@ describe('公开历史 API 的实际路由合同', () => { expect((await app.inject({ method: 'GET', url: '/api/sessions/missing-run', headers })).statusCode).toBe(404) }) + it('真实历史读取隐藏敏感失败正文和引用,同时保留失败状态', async () => { + createRun('privacy-run') + writeFileSync(join(rootRef.current, 'runs', 'privacy-run', 'messages.jsonl'), [ + { role: 'user', content: 'fixture privacy request', timestamp: 1 }, + { role: 'assistant', content: '', timestamp: 2, toolUse: [{ + id: 'private-call', name: 'BrowserScript', status: 'failed', isError: true, + summary: 'PRIVATE-RESULT-BODY', summaryRef: { filename: 'private-result.txt', size: 19 }, + summaryIncomplete: true, + }] }, + ].map(value => JSON.stringify(value)).join('\n') + '\n') + for (const suffix of ['', '/messages?offset=0&limit=2']) { + const response = await app.inject({ method: 'GET', url: '/api/sessions/privacy-run' + suffix, headers }) + expect(response.statusCode).toBe(200) + const tool = response.json().messages[1].toolUse[0] + expect(tool).toMatchObject({ status: 'failed', isError: true }) + expect(typeof tool.summary).toBe('string') + expect(tool.summary).toContain('failed') + expect(tool).not.toHaveProperty('summaryRef') + expect(tool).not.toHaveProperty('summaryIncomplete') + expect(response.body).not.toMatch(/PRIVATE-RESULT-BODY|private-result\.txt/) + } + }) + it('搜索使用真实历史,缺少Agent或非法分页返回400', async () => { createRun('search-run') const response = await app.inject({ method: 'GET', url: '/api/sessions/messages/search?agentId=docs-agent&q=needle&limit=1&offset=0&previewChars=20', headers }) diff --git a/api/stability-verification-2026-10-22.md b/api/stability-verification-2026-10-22.md new file mode 100644 index 0000000..8d98a35 --- /dev/null +++ b/api/stability-verification-2026-10-22.md @@ -0,0 +1,43 @@ +# API契约与稳定性复核(2026-10-22) + +本次复核已公开的35个HTTP操作及相关事件、历史恢复边界。它是契约和文档一致性检查,不是压测、服务可用性SLA或所有客户端版本的兼容承诺。 + +## 来源 + +- 源码:`desirecore/desirecore@a101a40c14cc9d478c7f9a23d8a125ac2404509b`。 +- 内部文档gitlink:`34178859da7a70cfab0b4726b85d9a37f22608a7`。 +- 公共文档基线:`4530b17`,本次从最新main建立独立分支,不改原有源码工作树。 +- Agent Service的27个操作重新核对至当前SHA。Compat Proxy、Workflow的装配与所选合同另行比较,规范仍保留各自原固定来源,未将历史运行结果改写为当前提交实跑。 + +## 发现与修订 + +| 范围 | 核对事实 | 本次更新 | +|---|---|---| +| 历史、快照和话题公开投影 | 敏感工具结果可变成占位;缺少可信调用身份或身份矛盾的协议结果也会收窄;正文引用可被移除 | 中英08、错误排查、HistoryMessage/快照/话题Schema与操作说明同步,不依赖占位措辞或假定引用必有 | +| 工具结局 | 失败事实不会因为脱敏变成成功;部分运行中或中断摘要可缺席 | 明确保留status/isError,不能从摘要单词推断Query终态或自动重跑 | +| 可选事件关联 | query:retrying、query:warning增加可选请求/对话标识;不是终态事件 | 中英04补充关联使用边界,不扩大成必须接收的新协议 | +| Run转交 | RunMeta仍五态;runtime-state HTTP路由仍四态,转交返回404 | 保留已实测差异,未把共享Schema误当实际HTTP输出 | +| 客户端兼容 | 所选请求Schema、摘要与主要接纳字段未变;响应扩展、未知状态、历史显示变化应分别处理 | 入口页增加兼容与稳定性章节,不声明没有依据的全局版本保证 | +| 来源台账 | AgentSummary的旧schemaRefs路径误写到agent-service目录 | 修为实际的packages/schemas/src/agent/agent-summary.ts,并逐项检查固定提交来源路径 | + +媒体所有权写入加强了新媒体落盘失败时的清理与隔离;上传/下载路径、请求和成功响应合同未变。Webhook的模型路由决策透传及Compat Proxy的启动/序列化装配变化未改变所选HTTP合同。新增Kimi设置入口、移除旧dev路由、团队/工作目录/任务管理治理收紧均不扩入本批公开接口。 + +没有把历史读取说成无副作用的数据库原始直读。原有恢复、显示去重、图片补全、跨页并发变化和话题120条截断规则继续适用;本批说明的是公开返回视图和调用方处理边界。 + +## 定向验证 + +| 层次 | 结果 | 范围 | +|---|---|---| +| 当前源码既有测试 | 4文件34项通过 | public-session-projection 17、冷工具隐私规则3、媒体路由13、附件路由1 | +| 公开历史源码夹具 | 1文件6项通过 | 实际鉴权/路由/临时SessionStore;新增敏感失败结果占位、移除引用、保留失败事实回归;原Run转交404等用例继续通过 | +| 独立Node示例 | 3文件41项通过 | 包括读取器原样保留脱敏和新增可选响应字段,不因为占位额外请求或执行 | +| 站点与规范清单 | 通过 | api:check:10组双语页面、35操作、66个JSON块、3规范;typecheck、双语build及api:check --build通过 | +| JSON Schema与规范工具 | 通过 | AJV Draft7:68个组件Schema、44个JSON媒体示例;Redocly CLI2.63.0:三规范0错误,保留既有47条条件Schema和3条license告警 | + +源码验证使用隔离的固定提交worktree,子模块初始化并fetch;Node依赖复用既有本机安装。源码夹具的本机profile和运行时发现为替身,不启动模型。测试使用临时数据,不读取个人历史或真实凭据。 + +独立示例没有改运行逻辑或新增依赖:history读取器本来就只读并透传公开payload。本次增强现有测试输入与源码夹具;三个可下载脚本仍逐字对应维护文件。 + +## 交付边界 + +本批提交PR供审阅,未合并、未自动部署,也未重新触发搜索抓取。此前PR #77的生产和搜索验收继续保留其原始基线;本批本地验证不能替代新一轮生产验收。商业模型、真实用户工具副作用、已发行安装包和全量服务压测不在本次范围内。 diff --git a/api/verification.md b/api/verification.md index dfd4f78..c9e7c2b 100644 --- a/api/verification.md +++ b/api/verification.md @@ -1,5 +1,7 @@ # 当前扩展验证入口 +2026-10-22的最新契约复核见[API稳定性验证](./stability-verification-2026-10-22.md);下面各批记录保留原来源和测试范围。 + Run状态、会话历史与消息、附件媒体的新增实现见[本批核查与验证](./history-attachments-verification.md)。下面保留既有已发布批次的来源和运行结果;其中8组页面、24个操作的数字属于当时范围,不代表本批扩展后的总数。 --- diff --git a/docs/07-api/03-errors-and-troubleshooting.md b/docs/07-api/03-errors-and-troubleshooting.md index f5bcc1d..f0e81e2 100644 --- a/docs/07-api/03-errors-and-troubleshooting.md +++ b/docs/07-api/03-errors-and-troubleshooting.md @@ -103,3 +103,9 @@ Webhook 的 `200` 和 `accepted: true` 表示已接收触发。响应中没有 R ## 对话、代理与工作流排查 对话超时后先使用示例的 `--recover` 读取准入记录;保留原请求 ID、摘要和状态文件,避免将未知状态当作未执行。详见[对话与 Run](./04-conversations-and-runs.md)。模型代理应核对本机 Base URL 和安全 token 的供应商绑定;Workflow Service 应核对独立地址和 `X-Workflow-Service-Token`,再按[工作流指南](./06-workflow-integration.md)检查 `runId` 与终态。 + +## 历史读取成功但结果不完整 {#history-projection-troubleshooting} + +HTTP `200` 表示读取成功,不保证返回完整的工具结果正文。敏感结果或无法核验调用身份的结果可能只提供占位提示,并省略正文引用;这与执行失败、历史损坏或需要重跑不是一回事。保留实际的 `status`、`isError`,按[历史结果的读取边界](./08-session-history-and-messages.md#history-result-privacy)处理,不从占位文字推断成功或自动重试。 + +逐 Run 消息中的 `offset` 是字节位置,而分页请求的 `offset` 是源行位置;按请求窗口推进,不能用返回消息条数补算下一页。历史可能在读取期间变化,参见[会话历史与消息](./08-session-history-and-messages.md)。 diff --git a/docs/07-api/04-conversations-and-runs.md b/docs/07-api/04-conversations-and-runs.md index 750b4d0..f67b0a6 100644 --- a/docs/07-api/04-conversations-and-runs.md +++ b/docs/07-api/04-conversations-and-runs.md @@ -351,6 +351,8 @@ node agent-client.mjs \ 没有匹配的 `clientRequestId` 或没有结构化 `terminal` 时,示例不会把事件判成这次请求已经成功。状态文件保留已观察的信息,供后续对账。 +`query:retrying` 和 `query:warning` 是可选的诊断事件,可能携带 `conversationId`、`clientRequestId` 等关联字段。只在能关联到当前请求时显示为该轮的提示;缺少标识的事件不能据此结束、重发或切换当前请求。它们也不替代 `query:complete.terminal`。 + ### 区分各种 ID {#conversation-identifiers} | ID | 标识范围与生命周期 | diff --git a/docs/07-api/08-session-history-and-messages.md b/docs/07-api/08-session-history-and-messages.md index aaad6c5..5e6b8d0 100644 --- a/docs/07-api/08-session-history-and-messages.md +++ b/docs/07-api/08-session-history-and-messages.md @@ -249,6 +249,17 @@ curl --silent --show-error --get \ } ``` +## 工具结果与读取稳定性 {#history-result-privacy} + +这些接口返回供显示和检索使用的消息视图。某些工具结果含凭据、界面内容等敏感信息,读取历史、会话快照或话题消息时,正文会改为占位提示。协议记录缺少可核验的工具调用身份、或身份信息矛盾时,也可能不返回结果正文。 + +- `toolUse[].summary` 或内容块中的工具结果可能被替换;执行中或中断的工具摘要也可能缺席。不要依赖占位文字的固定措辞。 +- 对被隐藏的结果,`summaryRef`、`summaryIncomplete`、`externalizedPreview` 等正文引用或预览标记可能被移除。缺少引用不表示工具没有执行,也不表示可以自行拼接文件名取得正文。 +- 判断工具结局时保留并读取实际的 `status`、`isError` 等状态字段。失败结果的占位仍表示失败;摘要中出现 `completed` 也不能证明本轮请求或整项业务成功。 +- 需要敏感结果时,让用户通过原工具或应用重新取得所需数据。不要因为占位提示自动重跑工具、重复提交对话或代替用户批准操作。 + +同一条历史记录在不同读取时间可能因脱敏规则、显示去重或正在发生的写入得到不同的显示内容。消息 ID 和源行窗口用于定位,不保证正文始终逐字相同;这些读取接口也不代替完整备份或模型协议回放。上面的分页规则和请求终态判断仍分别适用。 + ## 可运行的读取示例 {#history-example} **[下载 history.mjs](pathname:///api-examples/history.mjs)**。需要 Node.js 22 或之后版本,不需要安装 npm 依赖。 diff --git a/docs/07-api/index.md b/docs/07-api/index.md index f4125b5..0400627 100644 --- a/docs/07-api/index.md +++ b/docs/07-api/index.md @@ -30,6 +30,15 @@ Agent Service 使用 `X-Agent-Service-Token`,外部 Webhook 使用 `Authorizat 握手的 `200` 证明该次请求已通过认证。对话提交的 `202` 和 Webhook 的 `200 accepted` 表示接纳或接收,应按对应指南观察完成与交付。对话事件使用 Socket.IO,工作流进度使用 SSE。 +## 兼容性与稳定性 {#api-compatibility} + +接入前验证握手与所需能力,并按具体端点处理状态码、字段和异步结果。连接成功不代表所有功能都可用;三种服务的地址与凭据也不能互换。 + +- 请求严格按对应 Schema 发送;不要把某个端点的额外字段或响应外壳套用到其它端点。 +- 响应允许扩展时,可以忽略未使用的新增可选字段;仍要校验实例身份、必要字段和已知状态。遇到未知状态或缺席字段时保留未知,不自动补成 `idle` 或成功。 +- OpenAPI 的 `info.version` 标识接口描述文件的修订,不是所有服务的统一兼容承诺,也不是客户端生效版本。具体支持条件见相应指南与实例返回值。 +- 历史读取是显示视图,可能含脱敏占位并省略正文引用;详见[历史结果的读取边界](./08-session-history-and-messages.md#history-result-privacy)。网络超时、断线和结果未知时,按[接纳对账](./04-conversations-and-runs.md#request-reconciliation)处理,不直接创建新的执行。 + ## 开始接入 1. 向管理员取得实际服务地址与对应凭据。远程调用使用经过证书验证的 HTTPS 地址。 diff --git a/i18n/en/docusaurus-plugin-content-docs/current/07-api/03-errors-and-troubleshooting.md b/i18n/en/docusaurus-plugin-content-docs/current/07-api/03-errors-and-troubleshooting.md index 23fa516..0f91dd6 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/07-api/03-errors-and-troubleshooting.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/07-api/03-errors-and-troubleshooting.md @@ -103,3 +103,9 @@ Configuration management requires instance owner access and `capabilities.webhoo ## Conversations, proxy and workflow troubleshooting After a conversation timeout, use the example's `--recover` to read admission records. Preserve request IDs, digest and state files; an unknown outcome does not prove execution never started. See [conversations and Runs](./04-conversations-and-runs.md). For model calls, check the local Base URL and provider binding of the safe token. For workflows, check the independent address and `X-Workflow-Service-Token`, then follow the [workflow guide](./06-workflow-integration.md) to inspect the `runId` and terminal status. + +## A history read succeeds but output is incomplete {#history-projection-troubleshooting} + +HTTP `200` confirms the read, not availability of every tool-result body. Sensitive results or results whose call identity cannot be verified may contain only placeholders with body references omitted. This does not by itself establish execution failure, damaged history, or a need to rerun work. Preserve actual `status` and `isError` facts and follow [history-result read boundaries](./08-session-history-and-messages.md#history-result-privacy); do not infer success or retry automatically from placeholder text. + +A per-Run message's `offset` is a byte position, whereas the pagination request's `offset` is a source-row position. Advance by the requested window, not the number of returned messages. History can change while being read; see [session history and messages](./08-session-history-and-messages.md). diff --git a/i18n/en/docusaurus-plugin-content-docs/current/07-api/04-conversations-and-runs.md b/i18n/en/docusaurus-plugin-content-docs/current/07-api/04-conversations-and-runs.md index e11a6c8..c5f8a9e 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/07-api/04-conversations-and-runs.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/07-api/04-conversations-and-runs.md @@ -351,6 +351,8 @@ An admitted follow-up returns `202` with `ok: true`, `sessionId`, and the corres Without a matching `clientRequestId` or structured `terminal`, the example does not declare that this request succeeded. Its state file retains observed information for reconciliation. +`query:retrying` and `query:warning` are optional diagnostic events and may carry correlation fields such as `conversationId` and `clientRequestId`. Show them as hints for a turn only when they can be associated with that request. Uncorrelated events must not end, replay, or switch the current request, and do not replace `query:complete.terminal`. + ### Distinguish Identifiers {#conversation-identifiers} | Identifier | Scope and lifetime | diff --git a/i18n/en/docusaurus-plugin-content-docs/current/07-api/08-session-history-and-messages.md b/i18n/en/docusaurus-plugin-content-docs/current/07-api/08-session-history-and-messages.md index de65833..af4199f 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/07-api/08-session-history-and-messages.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/07-api/08-session-history-and-messages.md @@ -249,6 +249,17 @@ Use a topic ID from the overview; there are no pagination parameters. The source } ``` +## Tool results and read consistency {#history-result-privacy} + +These endpoints return message views for display and search. Some tool results contain credentials, interface content, or other sensitive information; history, session snapshots, and topic messages replace that content with a placeholder. Protocol records may also withhold result bodies when the tool-call identity cannot be verified or contains conflicting facts. + +- `toolUse[].summary` or a tool-result content block may be replaced. Summaries for running or interrupted tools may also be absent. Do not depend on the exact placeholder wording. +- For withheld results, body references or preview markers such as `summaryRef`, `summaryIncomplete`, and `externalizedPreview` may be removed. An absent reference does not mean the tool never ran, and does not permit constructing a filename to obtain its body. +- Preserve and read the actual `status`, `isError`, and other outcome fields. A placeholder for a failed result still represents failure; the word `completed` in a summary does not establish completion of the submitted turn or the business task. +- If sensitive output is needed, have the user obtain it through the original tool or application. A placeholder is not a reason to rerun tools, resubmit a conversation, or approve an action automatically. + +The same historical record may produce different display content over time because of privacy rules, display deduplication, or concurrent writes. Message IDs and source-row windows locate records; they do not guarantee byte-identical bodies. These reads are not a full backup or model-protocol replay. The pagination rules and request-terminal rules above continue to apply independently. + ## Runnable read example {#history-example} **[Download history.mjs](pathname:///api-examples/history.mjs)**. It requires Node.js 22 or later, with no npm dependencies to install. diff --git a/i18n/en/docusaurus-plugin-content-docs/current/07-api/index.md b/i18n/en/docusaurus-plugin-content-docs/current/07-api/index.md index 87ec982..6aee526 100644 --- a/i18n/en/docusaurus-plugin-content-docs/current/07-api/index.md +++ b/i18n/en/docusaurus-plugin-content-docs/current/07-api/index.md @@ -30,6 +30,15 @@ Agent Service uses `X-Agent-Service-Token`; external Webhooks use `Authorization A handshake `200` confirms the authenticated request. Query submission `202` and Webhook `200 accepted` acknowledge admission or receipt; follow the corresponding guide to observe completion and delivery. Conversation events use Socket.IO, while Workflow progress uses SSE. +## Compatibility and stability {#api-compatibility} + +Verify the handshake and required capabilities before integrating, then follow each endpoint's status codes, fields, and asynchronous results. A successful connection does not establish every capability. The three services' addresses and credentials are not interchangeable. + +- Send requests according to their own Schema. Do not apply one endpoint's extra fields or response wrapper to another. +- Where a response permits extensions, ignore new optional fields you do not use while validating instance identity, required fields, and known states. Treat unknown states and absent fields as unknown rather than silently substituting `idle` or success. +- OpenAPI `info.version` identifies a revision of the interface description. It is neither a compatibility guarantee shared by every service nor an effective client version. Follow each guide and the actual instance response for support conditions. +- History is a display view that may contain privacy placeholders and omit body references. See [history-result read boundaries](./08-session-history-and-messages.md#history-result-privacy). For timeouts, disconnects, and unknown outcomes, follow [admission reconciliation](./04-conversations-and-runs.md#request-reconciliation) instead of creating a new execution immediately. + ## Start integrating 1. Obtain the actual service address and its credential. Use verified HTTPS for remote access. diff --git a/static/openapi/agent-service.json b/static/openapi/agent-service.json index 78b735b..e19b414 100644 --- a/static/openapi/agent-service.json +++ b/static/openapi/agent-service.json @@ -3,7 +3,7 @@ "jsonSchemaDialect": "http://json-schema.org/draft-07/schema#", "info": { "title": "DesireCore Agent Service — public HTTP subset", - "version": "1.1.0", + "version": "1.1.1", "description": "Selected externally callable endpoints for an administrator-provided standalone instance. This document is a subset of the service, and is not an application release declaration. Consult the linked guides for deployment, authorization and asynchronous results." }, "servers": [ @@ -3653,7 +3653,7 @@ "Session history" ], "summary": "Read an owned ordinary session snapshot", - "description": "Checks trusted user ownership before body/image reads. Missing, cleared and unowned Runs return 404. Delegated Runs return 403 delegated_run_requires_inspect_view; use the messages inspection view instead. pendingAssistant is temporary and separate from durable messages. Returned configuration is not execution authority.", + "description": "Checks trusted user ownership before body/image reads. Missing, cleared and unowned Runs return 404. Delegated Runs return 403 delegated_run_requires_inspect_view; use the messages inspection view instead. pendingAssistant is temporary and separate from durable messages. Returned configuration is not execution authority. Returns a display projection: sensitive tool results may be withheld and their body references removed. Do not infer success, reconstruct private protocol or automatically rerun work from placeholder text.", "externalDocs": { "url": "https://docs.desirecore.com/api/session-history-and-messages#get-session" }, @@ -3782,7 +3782,7 @@ "Session history" ], "summary": "Read a source-record window from an owned Run", - "description": "Checks ownership before content reads. Delegated Runs require view=inspect-run. total counts source rows, not returned messages; advance offset by the requested limit and stop at total, even if a page is empty. Optional live is a temporary delegated display checkpoint, not a durable message or terminal. There is no cross-page consistency revision.", + "description": "Checks ownership before content reads. Delegated Runs require view=inspect-run. total counts source rows, not returned messages; advance offset by the requested limit and stop at total, even if a page is empty. Optional live is a temporary delegated display checkpoint, not a durable message or terminal. There is no cross-page consistency revision. Returns a display projection: sensitive tool results may be withheld and their body references removed. Do not infer success, reconstruct private protocol or automatically rerun work from placeholder text.", "externalDocs": { "url": "https://docs.desirecore.com/api/session-history-and-messages#session-messages" }, @@ -4228,7 +4228,7 @@ "Session history" ], "summary": "Read bounded public source entries for one matter", - "description": "Reads the instance owner's local-profile conversation memory. Supports active, recent and archived source data. Underlying Run reads recheck that user and Agent ownership. Reads at most 120 source messages and sets truncated=true if more exist; projection may omit entries. No pagination or limit-override parameter. Entries are not guaranteed to have the per-Run message shape.", + "description": "Reads the instance owner's local-profile conversation memory. Supports active, recent and archived source data. Underlying Run reads recheck that user and Agent ownership. Reads at most 120 source messages and sets truncated=true if more exist; projection may omit entries. No pagination or limit-override parameter. Entries are not guaranteed to have the per-Run message shape. Returns a display projection: sensitive tool results may be withheld and their body references removed. Do not infer success, reconstruct private protocol or automatically rerun work from placeholder text.", "externalDocs": { "url": "https://docs.desirecore.com/api/session-history-and-messages#matter-messages" }, @@ -8555,7 +8555,8 @@ "type": "string" }, "summary": { - "type": "string" + "type": "string", + "description": "Display summary. Sensitive results may be replaced by a placeholder; running/interrupted summaries may be absent. Do not parse outcome or replay instructions from this text." }, "summaryRef": { "type": "object", @@ -8564,7 +8565,16 @@ "type": "string" } }, - "additionalProperties": true + "additionalProperties": true, + "description": "Optional body reference for public output. Withheld results omit this reference; its absence does not mean the tool did not run." + }, + "isError": { + "type": "boolean", + "description": "When present, preserve the actual tool error fact even if its summary is withheld." + }, + "status": { + "type": "string", + "description": "Tool-call state when present. Preserve this independently from display summaries; it is not the Query terminal or a child Run/Worker status." } }, "additionalProperties": true @@ -8584,7 +8594,7 @@ } }, "additionalProperties": true, - "description": "Known fields of the public SessionMessage projection, derived from sessionMessageSchema. Runtime-private recovery fields are not part of this contract. Additional public fields remain allowed." + "description": "Known fields of the public SessionMessage projection, derived from sessionMessageSchema. Runtime-private recovery fields are not part of this contract. Additional public fields remain allowed. Sensitive tool results and unverifiable protocol results may be withheld; privacy placeholders are display text, not execution outcomes. Body references may be omitted." }, "HistoryLiveInspectionTool": { "type": "object", @@ -8743,7 +8753,7 @@ "updatedAt" ], "additionalProperties": true, - "description": "Known public fields derived from sessionSnapshotSchema and the public session projection; additional public fields are allowed. Images may be expanded to data URLs." + "description": "Known public fields derived from sessionSnapshotSchema and the public session projection; additional public fields are allowed. Images may be expanded to data URLs. Tool summaries and result blocks may be replaced by privacy placeholders with body references removed." }, "HistorySessionPage": { "type": "object", @@ -8971,7 +8981,7 @@ "type": "array", "maxItems": 120, "items": {}, - "description": "Public source entries; not guaranteed to have the per-Run SessionMessage shape." + "description": "Public source entries; not guaranteed to have the per-Run SessionMessage shape. Sensitive or unverifiable tool-result bodies may be replaced and external result references removed." }, "truncated": { "type": "boolean", @@ -8990,6 +9000,6 @@ "x-service": "agent-service", "x-source": { "repository": "desirecore/desirecore", - "revision": "7fe016c76ab98e0643ab4f2710c3733f757ef4fb" + "revision": "a101a40c14cc9d478c7f9a23d8a125ac2404509b" } }