From cda7c2a3117888d43272a20b3414e8abb7771ce7 Mon Sep 17 00:00:00 2001 From: tzhouam Date: Thu, 29 Oct 2026 17:09:30 +0800 Subject: [PATCH] feat: add consent-gated task learning and shared knowledge feedback --- .env.template | 29 + README.md | 19 + doc/README.md | 1 + doc/architecture/SPEC/cli.md | 18 +- doc/architecture/SPEC/knowledge_context.md | 23 +- doc/architecture/SPEC/knowledge_service.md | 87 ++- doc/architecture/SPEC/sdk.md | 45 +- doc/architecture/SPEC/thin_mcp_server.md | 41 +- doc/guide/knowledge-learning.md | 296 ++++++++++ .../skills/imcifix/SKILL.md | 16 +- .../skills/imcoding/SKILL.md | 12 + .../skills/imdesign/SKILL.md | 17 +- .../skills/imkbinit/SKILL.md | 12 + .../skills/imlearn/SKILL.md | 26 + .../skills/imlearn/agents/openai.yaml | 4 + .../imlearn/references/task-completion.md | 143 +++++ .../skills/imreview/SKILL.md | 14 +- .../infermatrix-copilot/skills/imrfc/SKILL.md | 12 + .../skills/imupdate/SKILL.md | 17 +- pyproject.toml | 1 + src/infermatrix_copilot/cli/entry.py | 9 +- src/infermatrix_copilot/knowledge_context.py | 36 ++ .../knowledge_service/agreement.py | 445 ++++++++++++++ .../knowledge_service/agreement_cli.py | 73 +++ .../knowledge_service/feedback.py | 559 ++++++++++++++++++ .../knowledge_service/feedback_http.py | 236 ++++++++ .../knowledge_service/feedback_hub.py | 238 ++++++++ .../knowledge_service/feedback_server_cli.py | 46 ++ .../knowledge_service/feedback_sync.py | 273 +++++++++ .../knowledge_service/learning.py | 512 ++++++++++++++++ .../knowledge_service/learning_cli.py | 176 ++++++ .../knowledge_service/learning_config.py | 36 ++ .../knowledge_service/learning_privacy.py | 40 ++ .../knowledge_service/learning_publication.py | 155 +++++ src/infermatrix_copilot/sdk/v1/__init__.py | 4 + src/infermatrix_copilot/sdk/v1/direct.py | 132 ++++- src/infermatrix_copilot/sdk/v1/learning.py | 102 ++++ src/infermatrix_copilot/sdk/v1/models.py | 4 + src/infermatrix_copilot/thin_mcp_server.py | 211 ++++++- test/conftest.py | 65 +- test/test_chat_knowledge_learning.py | 343 +++++++++++ test/test_chat_learning_review.py | 123 ++++ test/test_feedback_collection_integration.py | 189 ++++++ test/test_feedback_http.py | 190 ++++++ test/test_feedback_hub.py | 186 ++++++ test/test_feedback_identity.py | 203 +++++++ test/test_feedback_recovery.py | 212 +++++++ test/test_feedback_sync.py | 409 +++++++++++++ test/test_knowledge_feedback.py | 229 +++++++ test/test_knowledge_learning_hosts.py | 203 +++++++ test/test_knowledge_learning_integration.py | 152 +++++ test/test_learning_agreement.py | 334 +++++++++++ test/test_learning_agreement_collection.py | 147 +++++ test/test_learning_agreement_hosts.py | 161 +++++ test/test_learning_agreement_retrieval.py | 71 +++ test/test_learning_agreement_runtime.py | 354 +++++++++++ test/test_learning_config.py | 30 + test/test_learning_privacy.py | 30 + test/test_learning_recovery.py | 265 +++++++++ test/test_thin_mcp_server.py | 13 + 60 files changed, 7974 insertions(+), 55 deletions(-) create mode 100644 doc/guide/knowledge-learning.md create mode 100644 plugins/infermatrix-copilot/skills/imlearn/SKILL.md create mode 100644 plugins/infermatrix-copilot/skills/imlearn/agents/openai.yaml create mode 100644 plugins/infermatrix-copilot/skills/imlearn/references/task-completion.md create mode 100644 src/infermatrix_copilot/knowledge_service/agreement.py create mode 100644 src/infermatrix_copilot/knowledge_service/agreement_cli.py create mode 100644 src/infermatrix_copilot/knowledge_service/feedback.py create mode 100644 src/infermatrix_copilot/knowledge_service/feedback_http.py create mode 100644 src/infermatrix_copilot/knowledge_service/feedback_hub.py create mode 100644 src/infermatrix_copilot/knowledge_service/feedback_server_cli.py create mode 100644 src/infermatrix_copilot/knowledge_service/feedback_sync.py create mode 100644 src/infermatrix_copilot/knowledge_service/learning.py create mode 100644 src/infermatrix_copilot/knowledge_service/learning_cli.py create mode 100644 src/infermatrix_copilot/knowledge_service/learning_config.py create mode 100644 src/infermatrix_copilot/knowledge_service/learning_privacy.py create mode 100644 src/infermatrix_copilot/knowledge_service/learning_publication.py create mode 100644 src/infermatrix_copilot/sdk/v1/learning.py create mode 100644 test/test_chat_knowledge_learning.py create mode 100644 test/test_chat_learning_review.py create mode 100644 test/test_feedback_collection_integration.py create mode 100644 test/test_feedback_http.py create mode 100644 test/test_feedback_hub.py create mode 100644 test/test_feedback_identity.py create mode 100644 test/test_feedback_recovery.py create mode 100644 test/test_feedback_sync.py create mode 100644 test/test_knowledge_feedback.py create mode 100644 test/test_knowledge_learning_hosts.py create mode 100644 test/test_knowledge_learning_integration.py create mode 100644 test/test_learning_agreement.py create mode 100644 test/test_learning_agreement_collection.py create mode 100644 test/test_learning_agreement_hosts.py create mode 100644 test/test_learning_agreement_retrieval.py create mode 100644 test/test_learning_agreement_runtime.py create mode 100644 test/test_learning_config.py create mode 100644 test/test_learning_privacy.py create mode 100644 test/test_learning_recovery.py diff --git a/.env.template b/.env.template index 4ca5520d8..3038ecc03 100644 --- a/.env.template +++ b/.env.template @@ -93,6 +93,35 @@ AFD_PLUGIN_REPO=/path/to/afd-plugin # Push safety: pushes are dry-run unless this is 1 ALLOW_PUSH=0 +# Optional learning/feedback is OFF until a named human accepts the actual +# agreement in a TTY: infermatrix-copilot learning agreement show / accept. +# No environment setting, agent, MCP or SDK action signs it for the person. +# Extra host-model tokens/time/quota and sensitive selected evidence are disclosed. +# Local is the default publication mode. Use a dedicated writable checkout, never the +# installed package or the task's source checkout. Paths stay machine-local. +KNOWLEDGE_LEARNING_STATE_DIR= +KNOWLEDGE_LEARNING_WORKSPACE= +KNOWLEDGE_LEARNING_REPOSITORY=JiusiServe/InferMatrixCopilot +KNOWLEDGE_LEARNING_BASE=main +KNOWLEDGE_LEARNING_PUBLICATION=local +# draft_pr additionally needs current human agreement and both write gates: +# KNOWLEDGE_LEARNING_PUBLICATION=draft_pr +# ALLOW_PUSH=1 +ALLOW_POST=0 + +# Optional team knowledge-quality collection. Configuration alone is not consent: +# selected metadata/reasons/evidence upload only after current human agreement. +# Use HTTPS outside loopback; token comes from the service operator, >=32 chars. +# Changed terms/publication/collector destinations require renewed acknowledgement. +# Revoke with: infermatrix-copilot learning agreement revoke +# Revocation gates future operations; it does not erase prior data or stop all inflight work. +KNOWLEDGE_FEEDBACK_URL= +KNOWLEDGE_FEEDBACK_TOKEN= +KNOWLEDGE_FEEDBACK_TIMEOUT_SECONDS=5 +# Collector process only (separate environment from provider clients): +KNOWLEDGE_FEEDBACK_SERVER_TOKEN= +KNOWLEDGE_FEEDBACK_SERVER_STATE_DIR= + # repo-rebase-v3 remote CI (rebase_mode=remote_ci/full): pushes authenticate # with GITHUB_TOKEN (header auth; no credential helper is consulted) and the # Buildkite provider client needs BUILDKITE_API_TOKEN (write_builds scope). diff --git a/README.md b/README.md index 8af58a09e..300e873ca 100644 --- a/README.md +++ b/README.md @@ -239,6 +239,25 @@ main/分支构建。如果 main 构建早于刚合入的改动，还要追溯该 ## 快速上手 3 · 更新知识库 +任务学习和知识评分**默认关闭**，不影响正常读取知识。宿主先检查协议状态； +只有本人在交互终端阅读实际条款、填写姓名并输入 `I AGREE` 后，才可从当前 +对话提炼正面/负面经验并为实际用过的知识记录带证据的 `-1` / `+1`。 +这会额外消耗宿主模型 token、时间和可能的额度；选取的摘要与证据仍可能含敏感信息。 +Agent、MCP、SDK 和发布配置都不能代替本人接受协议。 + +```sh +infermatrix-copilot learning agreement show +infermatrix-copilot learning agreement accept # 由本人在交互终端执行 +infermatrix-copilot learning agreement status +infermatrix-copilot learning agreement revoke +``` + +接受后，安装的 Skill 在任务结束时触发学习，`imlearn` 也可手动补跑；知识 draft PR +仍需配置目标及 push/post 闸，团队评分上传仍需独立配置 collector。 +条款版本或发布/collector 目标变化后需重新接受。撤销阻止后续门禁通过，但不删除 +已经保存或发出的内容，也不能保证中止进行中的操作；不会每个任务反复要求签署。 +配置、质量统计和接口见[任务学习指南](doc/guide/knowledge-learning.md)。 + 上游发版或目录变化后，用 `imupdate` 把**结构事实**（模型清单、registry、 deploy、路径路由、source pin）同步进知识库——只改 InferMatrixCopilot 的 知识，不动目标仓库： diff --git a/doc/README.md b/doc/README.md index 943bbc294..663085957 100644 --- a/doc/README.md +++ b/doc/README.md @@ -17,6 +17,7 @@ | 文档 | 内容 | |---|---| | [`guide/backends.md`](guide/backends.md) | **后端**：五个 provider 怎么选、怎么配、权限如何保持（Strict） | +| [`guide/knowledge-learning.md`](guide/knowledge-learning.md) | 任务完成时提炼正负经验、自动知识 draft PR 与实际使用质量评分 | | [`guide/hosts/`](guide/hosts/README.md) | **宿主端**：在 Codex / Claude Code / Cursor 里使用 copilot（Direct） | | [`guide/mcp.md`](guide/mcp.md) | MCP 安装与七个工具接口 | | [`guide/self-evolution.md`](guide/self-evolution.md) | 用自进化引擎改进评审、知识摄取与引擎自身 | diff --git a/doc/architecture/SPEC/cli.md b/doc/architecture/SPEC/cli.md index 30ca547c0..9b3313aa3 100644 --- a/doc/architecture/SPEC/cli.md +++ b/doc/architecture/SPEC/cli.md @@ -1,6 +1,6 @@ # cli/ —— 规范 - + `LOC ~1420（6 个文件） · 接口 + 编排门面 · refactor-status: ok` @@ -21,6 +21,22 @@ flag CLI 与 `Copilot` 门面：解析 → 过门 → 执行；并持有 run 目 动作，零 LLM**，需 `--repo `，支持 report-only；见 RUNBOOK）。 - `rfc`：在主 argparse 解析前把其余 argv 原样交给 `rfc_service.cli.main`， 与独立的 `infermatrix-rfc` 共用入口，不创建 Copilot run 或调用模型。 +- `learning` delegates to `knowledge_service.learning_cli.main` before general + parsing: agreement, prepare, submit, status, feedback, report, sync, sync-status. Bounded JSON file/stdin + inputs share SDK/MCP services; this path never constructs a model or Copilot. + `report --scope auto|local|central` selects the team aggregate when configured + by default. `sync --limit 100` retries durable uploads; `sync-status` is local + inspection. `infermatrix-feedback` independently starts the authenticated + collector via `knowledge_service.feedback_server_cli` without a model or MCP. +- `learning agreement show|status|accept|revoke` delegates to `agreement_cli` + before the learning JSON parser. Show/status are side-effect-free inspection. + Accept requires a human TTY, displays the actual versioned terms and configured + destinations, and asks for a name plus exact `I AGREE`; no flags or pipes can + accept. Agents must not execute acceptance for the person. Prepare/submit, + grading and sync are off until current acceptance; task status, source reads + and explicit local reports remain available. Changed terms/destinations require + renewed acknowledgement. Revoke gates future operations, not already completed + or in-flight external effects. See [the learning guide](../../guide/knowledge-learning.md). ## 公开契约（可从 `infermatrix_copilot.cli` import） `main(argv)`；`Copilot`（`resolve`、`run_task`、`run_playbook`、`run_queue`、 diff --git a/doc/architecture/SPEC/knowledge_context.md b/doc/architecture/SPEC/knowledge_context.md index 857e630d9..ef036304d 100644 --- a/doc/architecture/SPEC/knowledge_context.md +++ b/doc/architecture/SPEC/knowledge_context.md @@ -1,6 +1,6 @@ # knowledge_context.py —— 规范 - + ## 职责与公开契约 @@ -9,6 +9,27 @@ `open_session` / `status` / `expand` 管理会话；`related` / `search` / `read` / `inject` 返回同一累计预算下的实际正文和引用。服务不调用模型、不改知识页、不宣称评审准确率。 +With current human agreement, a delivery additionally issues a `knowledge_feedback` +receipt for the exact post-budget fragments, using the session's review ID as task identity. Cached +requests retain a successfully issued receipt. After a transient storage failure, +a cached retry can repair feedback metadata from the exact saved model content, +after the original integrity and availability checks. The cache digest is updated +without rerunning retrieval, spending tokens or changing delivered source content. +Storage failures expose only `feedback_storage_unavailable`, never raw exceptions. +Prior containment receipts remain valid while the updated packet gets its own +issuance record. No omitted sibling rule becomes eligible from +another fragment of its page. Feedback state is outside the knowledge tree and +works independently of optional signed containment. Neither issuance nor a +retrieval increments positive/negative counts; an evidenced use rating does. + +Learning and feedback are disabled by default. Without current acceptance, +feedback metadata is `{status: "agreement_required", targets: []}` with no delivery +ID, and the source delivery remains available. Cached deliveries recheck agreement; +old receipts do not permit grading or uploads after revocation. Host contracts +check status before extra distillation/grading tokens. Agreement version or +destination changes require human renewal, independent of containment and context +budget. Local status/reports and source reads do not require acceptance. + ## 身份与权限 会话身份绑定快照树哈希、仓库 ID、知识切片、源码 pin、目录和政策哈希、PR 源码 pin、 diff --git a/doc/architecture/SPEC/knowledge_service.md b/doc/architecture/SPEC/knowledge_service.md index 50f3bfb3a..d81ccdaab 100644 --- a/doc/architecture/SPEC/knowledge_service.md +++ b/doc/architecture/SPEC/knowledge_service.md @@ -1,6 +1,6 @@ # knowledge_service/ — provider curation components - + Pinned source identities and depth markers accept full SHA-1 or SHA-256 Git commits. Evidence bodies, stored hashes and native approval semantics remain @@ -23,13 +23,94 @@ proposals to page digests; `ApplyMixin` performs locked append-only writes, fixed validators and byte-exact rollback. `common` contains shared syntax, bounds, hashes, errors and lock capability. -No component imports a CLI/MCP transport or ReviewBot, calls a model, clones, -pushes, or publishes. The host owns evidence collection, model calls, retries, +These curator components do not import a CLI/MCP transport or ReviewBot, call a model, clone, +push, or publish. The host owns evidence collection, model calls, retries, local commits and proposal export. The public `sdk.v1.knowledge` module only re-exports the curator and validator error. Existing proposal IDs, errors, wire projections, validator order and rollback behavior are compatibility contracts across the move. +Task completion orchestration is a separate facade in this package: +`agreement.AgreementStore` owns the versioned disclosure, private named local +acknowledgement, status, action gates, minimal upload attestation and revocation. +Learning/feedback start disabled. Only `agreement_cli` can take human interactive +acceptance after displaying actual terms and destinations, obtaining a name and +exact `I AGREE`, then rechecking the displayed version/configuration. Ordinary +SDK/MCP operations can inspect or revoke, never sign or supply acceptance data. +Status/document do not create state. Publication settings and write flags cannot +substitute for acknowledgement. Terms, publication mode/repository/base and +collector URL bind the acceptance; changes require renewal. + +The disclosure covers extra host tokens/time/possible quota charges, selected +conversation-derived sensitive data, local retention and GitHub/collector access. +Redaction is bounded and cannot guarantee removal of every secret/private detail. +Revoke blocks future gated learning, grading and uploads; it does not erase prior +local/remote data and cannot guarantee cancellation of an operation in flight. +Source reads, task status and local feedback reports remain available unsigned. + +`learning.TaskLearningService` owns durable prepare/submit/status, freezes a +governed Git base and owner catalog, validates host-distilled positive/negative +rules with the curator, and applies only in provider-owned worktrees. +`learning_publication.LearningPublisher` can open a draft PR with current human +agreement, fixed host destination configuration, both write flags, create-only push and exact-tree +recovery; it never merges. Original user work is never staged or reset. +`learning_privacy` rejects recognizable credential/private-key/chat-export +forms; the host remains responsible for redacting other private information. +`learning_cli` is the bounded JSON transport adapter, delegating agreement commands +before JSON handling. None calls a model or imports raw host chat. After acceptance, +empty lessons are valid. Identical retries reuse the +task, proposal and publication; conflicting inputs fail. +Each task is serialized with a cross-process file lock. SQLite transactions only +read or persist state; worktree operations, validators, commits and network +publication run without the database-wide writer lock so other tasks can proceed. +New nonempty preparations verify their repository slice at the frozen Git base +before inserting identity or creating a worktree. A repository typo left by an +older version can be corrected only while preparation is unfinished, no proposal +or application exists, all other identity fields match, and its worktree is absent +or provably pristine at the same detached base. Unknown edits are preserved and +refused rather than reset. + +`feedback.KnowledgeFeedbackStore` records trusted delivery receipts with current +agreement, independently of containment. Without agreement, issuance returns +`agreement_required` and empty targets while source reading continues. It stores +hashes and identities, not delivered source text. +Public ratings require a provider-issued target in the same task, integer -1/+1, +explicit actual use, reason and outcome evidence. One immutable vote per task +and exact target version prevents repeated reads/retries inflating scores. +Partial content never exposes undelivered sibling rules. Reports separate +positive, negative, net, mean and distinct-task counts by content version; +feedback is not a semantic gate or automatic rule retirement. All runtime state +lives outside the knowledge tree. + +`feedback_hub.FeedbackHubStore` is the shared team ledger. It accepts only the +existing `knowledge-feedback/1` receipt and ratings from authenticated trusted +providers with minimal current agreement attestations; it verifies canonical receipt and exact target-version hashes, +document/task/repository binding, and eligibility before counting immutable +`(task_id, target_id)` votes. Provider authentication establishes issuance trust, +not independent semantic proof. Reports aggregate in SQLite with bounded target +results. `feedback_http` supplies authenticated ingestion and reporting with a +minimal unauthenticated health endpoint; `feedback_server_cli` starts the +standard-library listener. One persistent service instance owns its state. +Attestations contain protocol/purpose, disclosure version/hash, configuration hash, +acceptance ID and time, never signer names or complete local records. Provider +authentication establishes trust in that claim, not independent human-signature +verification. The collector cannot reconstruct a person's named acknowledgement. + +`feedback_sync` provides a bounded HTTPS transport (HTTP only on loopback), +refuses redirects and redacts transport errors. Credentials/destination come +only from operator configuration. Current agreement is checked before grading, +publication, remote reports and each upload; the actual transport URL must be in +the accepted context. Recording a grade commits a per-rating outbox +entry with the local vote before any network attempt. Exact retries, concurrent +flushes and uncertain acknowledgments cannot create extra votes; failed uploads +remain pending across restart. Sync can backfill preexisting local grades only +with current agreement; missing/revoked consent retains pending data without upload. +Known credential/chat-export forms are blocked before egress. Shared task IDs +must be globally unique and remain stable across hosts. Source text and raw chat +are never uploaded by this protocol. Scoring does not change knowledge rules. +`report_for_scope` selects central data when configured in auto mode; a central +failure is reported, never replaced by local counts. + Knowledge Ops API 2.0 sits beside the v1 curator and does not change it: `lifecycle` parses rule pages (byte-exact) and their `kb:rule` footers, and owns the shared depth format, intact-prose reader and safe source-path diff --git a/doc/architecture/SPEC/sdk.md b/doc/architecture/SPEC/sdk.md index c7d291c50..96e908834 100644 --- a/doc/architecture/SPEC/sdk.md +++ b/doc/architecture/SPEC/sdk.md @@ -1,6 +1,6 @@ # sdk/ —— 规范 - + `Python SDK v1 · 跨仓库唯一 typed 边界 · refactor-status: ok` @@ -17,6 +17,49 @@ ## 公开契约 +- `KnowledgeAgreementClient.document/status/revoke` is the lazy inspection-only + agreement facade. It has no acceptance method, signer/attestation input or + endpoint override. Status/document do not create acceptance state. Named + acknowledgement is human-only through `learning agreement accept` in a TTY, + bound to current terms and configured publication/collector destinations. + Changed terms/destinations require renewal. Revoke gates future work without + deleting prior data or guaranteeing cancellation of in-flight operations. +- `KnowledgeLearningClient.prepare/submit/status` and + `KnowledgeFeedbackClient.record/report/sync/sync_status` lazily delegate to the same durable + services as MCP and `learning` CLI. Importing either class does not open state, + resolve a workspace or initialize model credentials. Prepare/submit/record/sync + require agreement before creating their runtimes. Lesson distillation uses + extra host-model tokens/time and possible quota; it is off until accepted. + Publication additionally requires operator destination and write gates. +- With current agreement, feedback records persist locally before optional configured central sync. + `report(scope="auto"|"local"|"central")` uses the team aggregate when + configured by default; central failures do not silently return local counts. + `sync(limit=100)` retries durable pending uploads and `sync_status()` inspects + the queue without a network request. Neither endpoint nor token is accepted + from model/tool input. An SDK `state_dir` override changes storage location + while retaining the operator's configured transport. + Task status, explicit local reports and sync status remain readable unsigned. + Central reports/uploads require current acceptance for the actual destination. +- `DirectReviewPlan` and `DocumentPage` add `knowledge_feedback` receipts. + Plan receipts bind `review_id`; follow-up `read_document` uses that plan's task + identity, or explicit `task_id` for standalone reads. Receipts contain exact + delivered-version targets, not source text. Adaptive packets carry the same + receipt for only their actual model content. Existing containment issuance + binds the final returned packet including this metadata. + Unsigned/revoked/renewal-required delivery instead returns `agreement_required` + with empty targets and no delivery ID, without blocking the original source + read. A previously issued receipt cannot bypass the later grading/upload gate. +- Feedback repositories are normalized against the pinned view before plan + issuance and follow-up context storage. `read_document(repository=...)` can + bind a standalone general-page read to its task's canonical repository; + an explicit task ID otherwise reuses an unambiguous prior delivery context, + including after client restart. A task with no known or multiple repository + contexts must supply a repository/context for general-page reads. Reads without + an explicit task ID retain standalone behavior. Existing receipts and votes + are immutable; canonicalization does not rewrite historical identities. + Optional feedback-storage failures return a fixed unavailable code and do not + prevent source delivery. + `changes_preview()` / `changes_apply()` 绑定人工编辑的完整候选、版本、摘要及幂等键； 未传 reason 时保留预览原因。`list_rfcs()` 支持可选服务端筛选与分页；`grants()`、 `check_repository()`、`service_status()` 继续委托同一授权应用。HTTP 错误保留 diff --git a/doc/architecture/SPEC/thin_mcp_server.md b/doc/architecture/SPEC/thin_mcp_server.md index 520da72db..3e145926e 100644 --- a/doc/architecture/SPEC/thin_mcp_server.md +++ b/doc/architecture/SPEC/thin_mcp_server.md @@ -1,6 +1,6 @@ # thin_mcp_server.py —— 规范 - + `LOC ~490 · 默认 MCP：Direct 门面 + Strict 入口 · refactor-status: ok` @@ -10,7 +10,7 @@ 同时通过 RFC SDK 委托已配置工作区的草稿、纳管、进度与人工决策操作。 ## 功能 -十五个工具：`review`（按 `mode` 分流）、`validate_direct_review`、 +工具包括：`review`（按 `mode` 分流）、`validate_direct_review`、 `get_review_status` / `get_review_result`（转发给 `CopilotMCP`）、 `update_knowledge`、`doc_search`、`doc_read`，显式自适应会话 `open_knowledge_context` / `read_knowledge_context` / `search_knowledge_context` / @@ -18,7 +18,7 @@ `rfc_request`、`rfc_capabilities`、`rfc_status`。 ## 公开契约 -上述十五个工具；`build_mcp(...)`；`main()`。`review(knowledge_profile="adaptive")` +上述工具；`build_mcp(...)`；`main()`。`review(knowledge_profile="adaptive")` 返回单一实际 `model_content` 和不重复正文的引用；默认 `legacy` 保持旧契约。 会话工具累积预算，跨仓库目标只在主机授权与 confirmed 固定依赖同时成立时可读； 模型不能通过工具参数扩大权限。模型容量与源码/输出留白是明确配置，非探测结果。 @@ -32,6 +32,41 @@ RFC 工具签名为 `rfc_request(action, payload=None)`、`rfc_capabilities()` 可逆节点分组。聊天调用先返回任务 ID，完整候选需通过 preview/apply 明确确认； 本门面不执行模型工具循环，也不能自行通过验收或修改授权。 +Task completion exposes `knowledge_agreement(action="status"|"show"|"revoke")` +through the lazy agreement SDK. It has no accept action, signer, attestation, +credential or endpoint argument. Because revoke changes private local state, the +tool declares `readOnlyHint=false`, `openWorldHint=false`. Status/show do not +create acceptance; only the human interactive CLI can accept actual terms. + +Task completion also exposes `knowledge_learning(action, task_id, repo, +source_pin, lessons, packet_digest, proposals)`, `knowledge_feedback(task_id, +delivery_id, ratings)`, read-only `knowledge_feedback_report(repo, limit, scope)` +and `knowledge_feedback_sync(action="flush"|"status", limit=100)`. +Installed skills and server instructions FIRST check agreement status before +extra learning tokens, distillation, grading or uploads. Default missing/revoked/ +renewal-required/unavailable agreement means skip optional work and finish the +requested task; offer the actual terms and human signing command once, without +repeated per-task reminders. The host may never accept for the user. After +acceptance, the host model distills locally; the server never imports a transcript +or calls another model. Triggering is before the final task response, not during +progress/status turns. Publication requires current acknowledgement, configured +local or draft-PR mode and both write flags; it never merges. Operator settings +are not consent. Mutating tools declare truthful annotations. Feedback +recording/reporting/sync can contact the configured collector and declare +open-world access. Local persistence precedes upload; failed uploads stay +pending. Report scope auto uses central when configured and never silently +falls back to local on remote failure. Sync status makes no network request. +Neither a destination nor a credential is accepted through tool arguments. + +With current agreement, legacy review, doc reads/searches and adaptive packets return +independent `knowledge_feedback` receipts even with containment disabled. Without +agreement, feedback metadata reports `agreement_required` and empty targets with +no delivery ID, while source content remains available. Optional +`task_id` on legacy review/read/search groups follow-up deliveries. Actual +delivery does not imply use: grades require a delivered target, explicit +`used=true`, integer -1/+1, reason and observed evidence. Feedback is private +runtime state, separate from containment and semantic knowledge approval. + ## 不变量（**C1**、**C2**、**D1**） - **Direct 在这个 server 里不跑任何模型。** 它返回知识路由和一份治理契约；阅读由 **宿主自己的模型**完成。执行主脊完全不参与。 diff --git a/doc/guide/knowledge-learning.md b/doc/guide/knowledge-learning.md new file mode 100644 index 000000000..bc81858c6 --- /dev/null +++ b/doc/guide/knowledge-learning.md @@ -0,0 +1,296 @@ +# Learn from completed tasks + +Optional task learning and knowledge feedback start disabled. Normal knowledge +reading remains available. Before doing extra learning work, installed skills +check `knowledge_agreement(action="status")`; only `status="accepted"` enables +distillation, grading or uploads. Otherwise the host finishes the requested task +and can offer the actual agreement and signing command once, without repeating +the reminder on every task. + +After acceptance, the host uses its current conversation and verified results to +distill reusable positive and negative lessons. It can give `+1` or `-1` to +knowledge that actually influenced the task, with a reason and outcome evidence. +This uses the host's current model without a separate extraction backend, but +still consumes extra tokens, execution time and possibly paid model/API quota. +Costs depend on the host, model and account; no free allowance is promised. + +The accepted workflow is part of the `im*` skill contracts and MCP instructions. +It runs for a completed task or terminal handoff, including an honest validation +gap. It does not run for intermediate progress or status checks. Installation +uses the same skill files in Codex, Claude Code and Cursor; it does not assume a +host supports a completion hook. Unrelated chats that never activate a Copilot +workflow are outside this trigger's scope. + +Run it on demand with `$imlearn` in Codex or `/imlearn` in Claude Code and Cursor. +The host selects bounded lesson summaries and relevant evidence; it does not +upload the raw transcript. No reusable lesson is also a valid result. + +## Read, acknowledge and revoke + +Configure the intended publication and collector destinations first, then inspect +the exact terms and configuration: + +```sh +infermatrix-copilot learning agreement show +infermatrix-copilot learning agreement status +``` + +To enable the optional workflow, the person must run this command in an +interactive terminal, read the displayed terms and destinations, enter their +name, and type exactly `I AGREE`: + +```sh +infermatrix-copilot learning agreement accept +``` + +Pipes and acceptance flags are refused. An agent must never run acceptance on +the person's behalf or manufacture their name, confirmation or saved record. +MCP exposes only `knowledge_agreement(action="status"|"show"|"revoke")`; the SDK's +`KnowledgeAgreementClient` exposes only `status()`, `document()` and `revoke()`. +Operator configuration and permission to publish task code are not this named +acknowledgement. The record is a product acknowledgement for the local operating +system user, not independently verified identity or a claim about legal effect. + +Acceptance binds the disclosure version/hash and the displayed publication mode, +repository/base and collector URL. Changed terms or destinations produce +`renewal_required`; a fresh human acknowledgement is required. Missing, revoked +or unavailable acceptance keeps learning and feedback disabled. Checking status +or showing the document does not sign or create an acceptance record. + +```sh +infermatrix-copilot learning agreement revoke +``` + +Revocation prevents future learning, grading and uploads after the next gate +check. An operation already in flight may complete. Revocation does not delete +stored local lessons or ratings, retract a PR, or remove data already received +by a collector. Use the relevant local-storage, GitHub or collector administration +process to remove earlier data. Task status and explicit local feedback reports +remain readable. + +## Privacy and storage + +Lessons, reasons, evidence references and task identifiers can contain personal, +proprietary or confidential information. The host selects bounded summaries and +evidence rather than complete transcripts or command logs. Automated checks reject +recognizable credential and chat-export forms but cannot guarantee complete +redaction; the person and host must select appropriate material. + +Private local runtime state retains selected lessons, evidence, delivery metadata, +ratings, queues and the named acknowledgement. If publication is enabled, rules +and their selected provenance reach the configured GitHub repository: publicly for +a public repository, or to authorized collaborators/operators for a private one. +If collection is enabled, its operators and authorized readers can access the +uploaded feedback. Review each destination's access and retention policies before +accepting. Credentials are deployment configuration, not consent or feedback data. + +## Configure a knowledge workspace + +Set configuration on the machine that runs the MCP server or CLI: + +```dotenv +KNOWLEDGE_LEARNING_STATE_DIR=/path/to/private-learning-state +KNOWLEDGE_LEARNING_WORKSPACE=/path/to/dedicated/InferMatrixCopilot-checkout +KNOWLEDGE_LEARNING_REPOSITORY=JiusiServe/InferMatrixCopilot +KNOWLEDGE_LEARNING_BASE=main +KNOWLEDGE_LEARNING_PUBLICATION=local +``` + +Use a dedicated writable knowledge checkout. The task's target repository and +the knowledge contribution repository are separate identities. The service uses +the configured destination; task input does not select credentials or a remote +destination. Keep local state, paths and secrets outside committed knowledge. + +`local` is the default for knowledge contributions. Feedback is also local unless +the separate team feedback destination below is configured. To authorize automatic +knowledge draft PRs after human acknowledgement, configure `draft_pr` and the +existing push/post gates: + +```dotenv +KNOWLEDGE_LEARNING_PUBLICATION=draft_pr +ALLOW_PUSH=1 +ALLOW_POST=1 +``` + +Current human acknowledgement and that persistent configuration together permit +knowledge publication without a new approval for each task. Configuration alone +does not enable learning or uploads. It does not authorize publishing the task's code, +comments or RFC. Knowledge PRs are never merged by this completion step. A +validation, credential or publication blocker leaves the prepared work available +for inspection and retry using the same task ID. + +## Learning and feedback contracts + +The host calls `knowledge_learning` with `action="prepare"`, a stable `task_id`, +`repo`, frozen `source_pin`, and bounded `lessons`. Preparation returns the owner +catalog and proposal contract. The host drafts executable rules, then calls +`action="submit"` with the original `packet_digest` and `proposals`. Call +`action="status"` with the same task ID to inspect the result or reconcile a +retry. Existing owner rules are reused; empty or redundant lessons do not need +an empty PR. +Repository slices are checked at the frozen Git base before a nonempty task is +retained. Correct an invalid repository using the same task ID; the old invalid +preparation is recoverable when it has no proposals or application and its +worktree remains pristine. Unexpected workspace edits are preserved for inspection. +Slow publication of one task does not hold the shared learning database's write +lock or block unrelated task completion. + +Each lesson has `outcome` (`positive` or `negative`), `summary`, a bounded +`evidence` reference list, and optional `title` and repository-relative +`changed_paths`. The source pin is a full lowercase Git SHA. Proposals have the +shape `{"rules": [...]}` and follow the returned owner-rule schema. + +With accepted agreement, knowledge retrieval returns a `knowledge_feedback` receipt containing +`delivery_id`, `task_id` and exact `targets`. The host grades only targets it +actually used, preserving their identities, through +`knowledge_feedback(task_id, delivery_id, ratings)`. A positive grade requires +evidence that the advice helped; a negative grade requires a concrete harmful or +incorrect effect. Merely retrieved or untested knowledge gets no grade. Feedback +does not automatically change a rule's meaning or lifecycle. +Without agreement, retrieval still returns its source content and feedback +metadata reports `status="agreement_required"` with no targets or delivery ID; +there is nothing to grade. + +Each rating supplies `target_id`, integer `score` (`-1` or `1`), `used: true`, +`reason`, and bounded `evidence`. Use the exact target and task identities from +the receipt. Pass the task ID to retrieval when supported to keep deliveries +from the same task together. +Use a globally unique task identity, such as the host chat UUID with a scoped +task suffix. Preserve it when moving between machines or retrying. Short local +counters such as `task-1` can collide in a shared team ledger. The collector +does not add a machine prefix because that would count the same task twice. + +Prefer a rule target when its complete section was delivered. Use a document +target for page-level guidance; avoid rating the same effect at both levels. + +SDK plans normalize repository aliases before issuing feedback identities. +For an explicit task ID, standalone reads reuse that task's prior repository +context when it is unambiguous. When reading a `general/...` page before any +plan, pass `DirectClient.read_document(..., task_id=..., repository="vllm-omni")` +or use the issued review context. Explicit repository/context is also required +when the task has multiple repository contexts. This preserves the same target +identity across plan and follow-up reads. Historical receipts and votes retain +their original immutable identities. + +If adaptive feedback issuance is temporarily unavailable, source content still +returns with `feedback_storage_unavailable`. Retry the same session/request after +storage recovers: the service repairs the receipt for the originally delivered +fragments without consuming more context budget or including additional rules. + +Lessons become owner-scoped rule proposals, with the existing validators and +publication checks. Local chat evidence stays in private task state; product +knowledge receives reusable rules and appropriate evidence references. Do not +store raw chats, credentials, unrelated personal details or command-log dumps in +the tree or PR. Feedback reports are available on demand through +`knowledge_feedback_report(repo="...", limit=100)`; normal task handoffs show a +compact outcome and a PR link or blocker. + +## Collect team feedback + +Run one collector for a shared team ledger. It uses the standard-library HTTP +server and durable SQLite state; no model backend or MCP dependency is required. +The service state must be on a persistent local disk outside the knowledge tree. +Use one service instance per state directory; horizontally distributed database +coordination is outside this service's contract. + +Set `KNOWLEDGE_FEEDBACK_SERVER_TOKEN` to an operator-provisioned secret of at +least 32 characters in the collector process environment, then start it: + +```sh +infermatrix-feedback --host 127.0.0.1 --port 8788 --state-dir /srv/copilot/feedback +``` + +`KNOWLEDGE_FEEDBACK_SERVER_STATE_DIR` can supply the state directory instead. +For remote clients, put the loopback listener behind an HTTPS reverse proxy that +preserves the Authorization header and `/v1/feedback/` routes. The listener +provides HTTP, not TLS. Provision the matching token only to trusted Copilot +provider runtimes; it authorizes both ingestion and aggregate reports. It is not +an end-user receipt signing key or a token to include in a tool call. + +Configure each provider runtime (the MCP/CLI/SDK process, not its chat input): + +```dotenv +KNOWLEDGE_FEEDBACK_URL=https://feedback.example.org +KNOWLEDGE_FEEDBACK_TOKEN= +KNOWLEDGE_FEEDBACK_TIMEOUT_SECONDS=5 +``` + +HTTP is accepted only for loopback development, for example +`http://127.0.0.1:8788`. Client redirects are rejected rather than forwarding +credentials to a new destination. Keep the token in private runtime configuration. +The knowledge PR publication mode and push/post gates do not configure feedback +transport. This separate destination permits automatic upload only with a current +human acknowledgement that includes its actual URL. Changing the URL requires +renewal before uploading or reading the central report. + +Recording a grade commits the local rating and an upload queue entry together, +then attempts upload after the transaction. Network, authentication or uncertain +response failures leave the grade durable and pending. A returned sync status +distinguishes local acceptance from a confirmed central acknowledgment. Retry +with `learning sync` or `knowledge_feedback_sync`; status inspection does not +make a network request. Existing local ratings can also be uploaded by a sync +after team collection and the corresponding agreement are current. Revoked or +missing agreement leaves queued grades unsent. No background daemon is installed: bounded +upload attempts run on recording and explicit sync. + +The collector accepts the existing `knowledge-feedback/1` receipt, its exact +rating identities and a minimal agreement attestation. It validates receipt/target hashes, task and repository +bindings, and rated-target eligibility before counting a grade. Provider +authentication establishes issuance trust; hash checks alone do not prove that +a provider delivered the content or that an agent's observation is correct. +The attestation contains the protocol/purpose, disclosure version/hash, +configuration hash, acceptance ID and time. It excludes the person's name and +the full local acknowledgement. It is a claim from the authenticated trusted +provider, not independent proof of the human's identity or signature. + +The shared ledger preserves one immutable vote per `(task_id, target_id)` across +all machines and deliveries. Exact retries succeed without increasing counts; +conflicting ratings are rejected. Rule content or upstream-pin changes produce +a different target version. Unrelated page edits can retain an unchanged rule's +identity, while preserving the original delivery provenance. + +Only receipt metadata and selected ratings are uploaded: hashes, relative +knowledge paths, task identity, reason and outcome evidence. Full source pages, +chat history, local machine paths and credentials do not belong in feedback. +The transport rejects recognizable credentials and conversation-export forms; +the host must still select and redact other private information. + +The HTTP surface is: + +| Request | Purpose | +| --- | --- | +| `POST /v1/feedback/events` | Authenticated `{ "receipt": {...}, "ratings": [...], "agreement": {...} }` ingestion | +| `GET /v1/feedback/report?repo=vllm-omni&limit=100` | Authenticated exact-version aggregate | +| `GET /healthz` | Minimal health status without feedback data | + +Aggregates use the same positive, negative, net, mean and distinct-task counts +as local reports. `scope="auto"` (the default) uses the central service when +configured, otherwise the local ledger. Select `scope="local"` or +`scope="central"` explicitly when needed. A central-service failure is an error; +it never silently substitutes local counts for a team report. Querying a report +does not upload pending grades. +Central requests require current agreement; `--scope local` remains available +without it and makes no collector request. + +## CLI + +The CLI delegates to the same services and accepts JSON files or stdin: + +```sh +infermatrix-copilot learning prepare --input task.json +infermatrix-copilot learning submit --input proposals.json +infermatrix-copilot learning feedback --input feedback.json +infermatrix-copilot learning status TASK_ID +infermatrix-copilot learning report --repo vllm-omni --limit 100 +infermatrix-copilot learning report --repo vllm-omni --scope central +infermatrix-copilot learning report --repo vllm-omni --scope local +infermatrix-copilot learning sync --limit 100 +infermatrix-copilot learning sync-status +``` + +For prepare, the object has `task_id`, `repository` (or `repo`), `source_pin` and +`lessons`. Submit has `task_id`, `packet_digest` and `proposals`. Feedback has +`task_id`, `delivery_id` and `ratings`. Use the service's returned lesson, +proposal and rating schemas. `--input -` reads a JSON object from stdin; no +credential or transcript argument is accepted. Reuse the task ID, packet digest +and delivery identities when retrying. diff --git a/plugins/infermatrix-copilot/skills/imcifix/SKILL.md b/plugins/infermatrix-copilot/skills/imcifix/SKILL.md index dc156a50a..6a8cb3c92 100644 --- a/plugins/infermatrix-copilot/skills/imcifix/SKILL.md +++ b/plugins/infermatrix-copilot/skills/imcifix/SKILL.md @@ -38,8 +38,8 @@ exposes one. ## Publishing rules -- Do not commit, push, open a PR, or post an issue comment unless the user asks - explicitly. +- Do not commit, push, open a PR, or post an issue comment for the issue fix + unless the user asks explicitly. - When the user asks to publish, use a fresh branch named `fix/-` and additive commits only. - Never force-push or push to a protected branch. @@ -50,3 +50,15 @@ exposes one. Be concise. Lead with what changed and how it was verified. Include file paths and commands only where they help the user act. + + +## Task completion learning + +Before your final task response, FIRST call `knowledge_agreement(action="status")`. +Only `status="accepted"` permits [task completion learning](../imlearn/references/task-completion.md) +to distill lessons, grade knowledge or upload feedback. Otherwise skip learning, +finish the requested task, and offer the actual agreement and human signing +command once without per-task reminders. Never sign for the user. Accepted +agreement and configured publication/write gates are both required; operator +configuration is not consent. This does not authorize publishing the task's code, +comments or RFC. diff --git a/plugins/infermatrix-copilot/skills/imcoding/SKILL.md b/plugins/infermatrix-copilot/skills/imcoding/SKILL.md index 595311287..f38980591 100644 --- a/plugins/infermatrix-copilot/skills/imcoding/SKILL.md +++ b/plugins/infermatrix-copilot/skills/imcoding/SKILL.md @@ -92,3 +92,15 @@ server-side coding workflow or a second model. Report what now works, the relevant files, checks actually run and their results, and any remaining limitation. Distinguish implemented behavior from verified behavior. Keep the handoff proportionate to the change. + + +## Task completion learning + +Before your final task response, FIRST call `knowledge_agreement(action="status")`. +Only `status="accepted"` permits [task completion learning](../imlearn/references/task-completion.md) +to distill lessons, grade knowledge or upload feedback. Otherwise skip learning, +finish the requested task, and offer the actual agreement and human signing +command once without per-task reminders. Never sign for the user. Accepted +agreement and configured publication/write gates are both required; operator +configuration is not consent. This does not authorize publishing the task's code, +comments or RFC. diff --git a/plugins/infermatrix-copilot/skills/imdesign/SKILL.md b/plugins/infermatrix-copilot/skills/imdesign/SKILL.md index 8e247952e..33ae7c883 100644 --- a/plugins/infermatrix-copilot/skills/imdesign/SKILL.md +++ b/plugins/infermatrix-copilot/skills/imdesign/SKILL.md @@ -35,11 +35,24 @@ small design packet the user can approve or edit before implementation. - Risks, tradeoffs, and open questions 6. When there are multiple plausible designs, compare two or three options and recommend one. Keep the recommendation grounded in repository patterns. -7. Do not implement, commit, post comments, or open a PR unless the user asks - for that after reviewing the design. +7. Do not implement or publish the design, commit target-repository changes, + post target comments, or open an implementation PR unless the user asks for + that after reviewing the design. ## Output style Be direct and useful. Keep the design compact enough to act on, with file paths and command names when they matter. Avoid broad architecture essays unless the change genuinely needs one. + + +## Task completion learning + +Before your final task response, FIRST call `knowledge_agreement(action="status")`. +Only `status="accepted"` permits [task completion learning](../imlearn/references/task-completion.md) +to distill lessons, grade knowledge or upload feedback. Otherwise skip learning, +finish the requested task, and offer the actual agreement and human signing +command once without per-task reminders. Never sign for the user. Accepted +agreement and configured publication/write gates are both required; operator +configuration is not consent. This does not authorize publishing the task's code, +comments or RFC. diff --git a/plugins/infermatrix-copilot/skills/imkbinit/SKILL.md b/plugins/infermatrix-copilot/skills/imkbinit/SKILL.md index 0d8c0a545..1d8662c05 100644 --- a/plugins/infermatrix-copilot/skills/imkbinit/SKILL.md +++ b/plugins/infermatrix-copilot/skills/imkbinit/SKILL.md @@ -358,3 +358,15 @@ original native proofs before any write or model call. Missing or changed archives reject reuse without changing the genuine record; restore the original archive to continue. Changed frozen inputs require a new batch. Published historical records remain unchanged. + + +## Task completion learning + +Before your final task response, FIRST call `knowledge_agreement(action="status")`. +Only `status="accepted"` permits [task completion learning](../imlearn/references/task-completion.md) +to distill lessons, grade knowledge or upload feedback. Otherwise skip learning, +finish the requested task, and offer the actual agreement and human signing +command once without per-task reminders. Never sign for the user. Accepted +agreement and configured publication/write gates are both required; operator +configuration is not consent. This does not authorize publishing the task's code, +comments or RFC. diff --git a/plugins/infermatrix-copilot/skills/imlearn/SKILL.md b/plugins/infermatrix-copilot/skills/imlearn/SKILL.md new file mode 100644 index 000000000..53889abc0 --- /dev/null +++ b/plugins/infermatrix-copilot/skills/imlearn/SKILL.md @@ -0,0 +1,26 @@ +--- +name: imlearn +description: Distill reusable lessons from a completed local task and grade the project knowledge actually used, through InferMatrixCopilot. Use when the user invokes /imlearn or $imlearn, asks to learn from the current task, or another InferMatrixCopilot skill reaches its completion step. +--- + +# InferMatrix task learning + +Use `$imlearn` in Codex or `/imlearn` in Claude Code and Cursor. FIRST call +`knowledge_agreement(action="status")`. Only `status="accepted"` permits +distillation, grading, uploads or extra learning analysis. Otherwise skip those +activities, offer the actual agreement and human signing command once, and +finish the requested task without repeated reminders. Never accept for the user. + +After acceptance, work from the current host conversation and verified artifacts. +The host model extracts the lessons; no second model or raw transcript upload is +needed. + +Follow [task completion learning](references/task-completion.md). Use it once +before the final task response, including a terminal handoff with an explicit +verification gap. For an on-demand invocation, reuse an existing task ID when +retrying the same evidence. Do not run it recursively after its own completion. + +Knowledge publication requires both accepted human agreement and the configured +`local` or `draft_pr` mode with its push/post gates. Operator configuration is not +the user's signature. Report a compact outcome or contribution PR link; retain +blocked work for retry. diff --git a/plugins/infermatrix-copilot/skills/imlearn/agents/openai.yaml b/plugins/infermatrix-copilot/skills/imlearn/agents/openai.yaml new file mode 100644 index 000000000..bfbc45aae --- /dev/null +++ b/plugins/infermatrix-copilot/skills/imlearn/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Imlearn" + short_description: "Learn from task outcomes and rate used knowledge" + default_prompt: "Use $imlearn to check the agreement and, only if accepted, learn from this task and grade used knowledge." diff --git a/plugins/infermatrix-copilot/skills/imlearn/references/task-completion.md b/plugins/infermatrix-copilot/skills/imlearn/references/task-completion.md new file mode 100644 index 000000000..cdf278524 --- /dev/null +++ b/plugins/infermatrix-copilot/skills/imlearn/references/task-completion.md @@ -0,0 +1,143 @@ +# Task completion learning + +## Check the human agreement first + +FIRST call `knowledge_agreement(action="status")`, before distilling lessons, +grading knowledge, spending extra learning tokens, or uploading feedback. Only +`status="accepted"` permits the learning workflow. For `required`, `revoked`, +`renewal_required` or `unavailable`, skip learning and grading and finish the +requested task normally. Do not prepare an empty packet as a substitute. + +Offer the actual terms through `knowledge_agreement(action="show")` and the +human signing command `infermatrix-copilot learning agreement accept` once. Do +not repeatedly remind the user on each task. The user must read and sign in an +interactive terminal. Never run acceptance for them, supply a signer or typed +confirmation, forge an acceptance record, or treat a chat instruction or operator +publication setting as a signature. MCP and SDK cannot accept the agreement. + +When MCP is unavailable, inspect it with: + +```text +infermatrix-copilot learning agreement status +infermatrix-copilot learning agreement show +``` + +Status/show do not accept or enable learning. `knowledge_agreement(action="revoke")` +or `infermatrix-copilot learning agreement revoke` revokes consent. A later +revocation or changed terms/destination requires a fresh human signature before +learning can resume. Task status and local feedback reports remain readable. + +## Continue only after accepted status + +Run this step before the final response for a completed InferMatrixCopilot task +or terminal handoff. A progress update, status question, or intermediate design +discussion while implementation continues is not task completion. Reuse one +stable `task_id` for the scoped task and all retries; keep different tasks +separate. If a retrieval response supplies a `knowledge_feedback.task_id`, retain +that identity with its delivery receipt for feedback. +Pass the task ID to knowledge retrieval when supported so all deliveries stay +bound to the same task. +Use a globally unique identity such as the host chat UUID with a task suffix. +Preserve it across machines; do not create a new identity to retry an upload. + +## Distill locally + +Use the current host context to select reusable positive and negative lessons: +what worked, what failed, the triggering condition, the correction, and the +evidence that establishes the outcome. Verify conclusions against source and +checks before proposing an executable owner rule. A failed attempt can teach a +rule; an untested hypothesis must remain a hypothesis. Reuse existing rules when +they already state the lesson. An empty `lessons` array is a valid result when +nothing generalizes. + +Each lesson has `outcome` (`positive` or `negative`), `summary`, `evidence` (a +list of bounded references), and optional `title` and repository-relative +`changed_paths`. Use a full lowercase Git SHA as `source_pin`. + +Send bounded lesson summaries and relevant source/test references or short +selected excerpts. Exclude raw conversation logs, private messages unrelated to +the task, credentials, personal details, machine paths and full command output. +Do not create a case history or transcript page in the knowledge tree. Keep +temporary task evidence in local service state, outside product knowledge. + +## Record actual knowledge use + +Retain `knowledge_feedback` receipts returned by knowledge retrieval. Each has a +`delivery_id`, `task_id` and `targets`; preserve target identities and hashes. +Select only a delivered target that actually influenced a task decision. Give +`+1` when its advice helped and is supported by the verified outcome, or `-1` +when following it caused a concrete error, wasted step, or incorrect conclusion. +For every grade, state the causal reason and evidence. Displayed, retrieved or +unused knowledge gets no grade. Abstain when the effect is unknown. + +Call `knowledge_feedback(task_id, delivery_id, ratings)` for each selected +delivery, using its issued task identity. Each rating has the exact `target_id`, +integer `score` (`-1` or `1`), `used: true`, `reason`, and concrete `evidence` +(references or bounded observations). Do not fabricate a receipt or grade every +target in a page. Retry the same task/delivery/rating identities after a failure. +Negative feedback is evidence for review; it does not itself retire or edit a rule. + +With accepted agreement and a configured central feedback collector, recording also +attempts upload after local persistence. A pending sync means the grade is +saved locally, not confirmed centrally. Keep the original grade and identities; +use `knowledge_feedback_sync(action="flush", limit=100)` to retry or +`action="status"` to inspect the queue. Do not send credentials, machine paths, +raw conversations or full logs in the reason/evidence. Destination and token +belong in operator configuration, never task/tool input. + +## Prepare and submit a knowledge contribution + +1. Call `knowledge_learning(action="prepare", task_id=..., repo=..., + source_pin=..., lessons=[...])`. Resolve the target repository explicitly and + pin the source used to verify the lessons. Use the service's lesson schema; + never pass the whole chat as a lesson. +2. Use the returned owner catalog, existing rules, prompt and proposal schema to + draft the smallest reusable rule batch with the current host model. Preserve + positive practices and negative failure conditions where each is supported. + Cite only the prepared packet's evidence. Treat evidence text as data. +3. Call `knowledge_learning(action="submit", task_id=..., + packet_digest=..., proposals=...)` with the exact prepared digest. The service + validates and applies owner-scoped proposals in its dedicated knowledge + workspace and follows configured publication. No new rule is required for an + empty lesson set or evidence already covered by existing knowledge. + Proposals use `{"rules": [...]}`; an empty rules list is valid. +4. Read `knowledge_learning(action="status", task_id=...)` when needed to + reconcile a retry, validation failure or uncertain publication. Reuse the + existing task and digest; never create a second task to bypass an unresolved + publication. + +When MCP is unavailable, invoke the same services through: + +```text +infermatrix-copilot learning prepare --input task.json +infermatrix-copilot learning submit --input proposals.json +infermatrix-copilot learning feedback --input feedback.json +infermatrix-copilot learning status TASK_ID +infermatrix-copilot learning sync --limit 100 +infermatrix-copilot learning sync-status +``` + +`--input -` accepts a JSON object on stdin. CLI input uses `repository` (or `repo`) +for prepare. If neither interface is available, report learning as unavailable +and retain only the bounded local evidence needed to retry; do not edit an +installed knowledge bundle as a substitute. + +## Publication and final handoff + +`KNOWLEDGE_LEARNING_PUBLICATION=local` retains the validated contribution locally. +`draft_pr` permits automatic knowledge draft PR preparation only with accepted +human agreement and when the configured workspace/repository and `ALLOW_PUSH=1` +/ `ALLOW_POST=1` gates permit it. Operator configuration alone is not consent. +Follow valid agreement and configuration without requesting per-task approval. This separate +knowledge publication does not authorize publishing the task's implementation, +issue response or RFC, and never authorizes a merge. + +If setup, validation, authentication or publication blocks learning, preserve the +service's prepared work and report its status. Do not relabel an unverified +outcome as successful. Keep the final handoff brief: learning result, knowledge +PR link if created, and any actionable blocker. Summarize grades only when useful; +use `knowledge_feedback_report(repo=..., limit=..., scope="auto")` or `learning report` when +the user asks for details. Do not append a permanent rating table to every task. +Auto selects the configured team aggregate, otherwise local data; explicit +local/central scope is available. A central report failure must not be relabeled +as a successful team report using local counts. diff --git a/plugins/infermatrix-copilot/skills/imreview/SKILL.md b/plugins/infermatrix-copilot/skills/imreview/SKILL.md index 298fffdaf..e02411910 100644 --- a/plugins/infermatrix-copilot/skills/imreview/SKILL.md +++ b/plugins/infermatrix-copilot/skills/imreview/SKILL.md @@ -72,4 +72,16 @@ fix direction. Use the knowledge rules to discover and verify findings, but do not expose rule IDs, coverage tables, matrices, or PASS/MISSING_EVIDENCE rows unless the user explicitly asks for the full audit artifact. If there are no findings, say so briefly and name any material validation gap. Do not post or -edit unless explicitly asked. +edit target-repository artifacts unless explicitly asked. + + +## Task completion learning + +Before your final task response, FIRST call `knowledge_agreement(action="status")`. +Only `status="accepted"` permits [task completion learning](../imlearn/references/task-completion.md) +to distill lessons, grade knowledge or upload feedback. Otherwise skip learning, +finish the requested task, and offer the actual agreement and human signing +command once without per-task reminders. Never sign for the user. Accepted +agreement and configured publication/write gates are both required; operator +configuration is not consent. This does not authorize publishing the task's code, +comments or RFC. diff --git a/plugins/infermatrix-copilot/skills/imrfc/SKILL.md b/plugins/infermatrix-copilot/skills/imrfc/SKILL.md index f98080b16..d64e5bbcc 100644 --- a/plugins/infermatrix-copilot/skills/imrfc/SKILL.md +++ b/plugins/infermatrix-copilot/skills/imrfc/SKILL.md @@ -36,3 +36,15 @@ stable `idempotency_key` and the user's reason. Reuse the key on retry. A never bypass it with a second local tracking copy. Follow `source_update` until synced or help resolve its conflict. `service.status` shows service readiness; authorized administrators can inspect `service.diagnostics` and `grants.list`. + + +## Task completion learning + +Before your final task response, FIRST call `knowledge_agreement(action="status")`. +Only `status="accepted"` permits [task completion learning](../imlearn/references/task-completion.md) +to distill lessons, grade knowledge or upload feedback. Otherwise skip learning, +finish the requested task, and offer the actual agreement and human signing +command once without per-task reminders. Never sign for the user. Accepted +agreement and configured publication/write gates are both required; operator +configuration is not consent. This does not authorize publishing the task's code, +comments or RFC. diff --git a/plugins/infermatrix-copilot/skills/imupdate/SKILL.md b/plugins/infermatrix-copilot/skills/imupdate/SKILL.md index aaf8ba398..115dfc348 100644 --- a/plugins/infermatrix-copilot/skills/imupdate/SKILL.md +++ b/plugins/infermatrix-copilot/skills/imupdate/SKILL.md @@ -68,8 +68,9 @@ When the argument is not a local path, use the host model to resolve it: Read the relevant upstream diff before changing InferMatrixCopilot. 4. Update only facts proven by the report and source: the release baseline, model catalog, component source maps, pins, or adapter manifest. Never - generate or rewrite owner rules automatically; report semantic-rule - candidates for human review. + generate or rewrite owner rules automatically as part of the structural update. Send + reusable semantic lessons through the separate task completion learning + workflow and its reviewable knowledge contribution. 5. When machine audit is available, run the same command with `--mode enforce`, then run: @@ -87,3 +88,15 @@ When the argument is not a local path, use the host model to resolve it: The audit is evidence collection, not the updater. Codex performs the bounded knowledge edits and must not commit, push, or open a PR unless asked. + + +## Task completion learning + +Before your final task response, FIRST call `knowledge_agreement(action="status")`. +Only `status="accepted"` permits [task completion learning](../imlearn/references/task-completion.md) +to distill lessons, grade knowledge or upload feedback. Otherwise skip learning, +finish the requested task, and offer the actual agreement and human signing +command once without per-task reminders. Never sign for the user. Accepted +agreement and configured publication/write gates are both required; operator +configuration is not consent. This does not authorize publishing the task's code, +comments or RFC. diff --git a/pyproject.toml b/pyproject.toml index 6f2ecbcee..b9593c95b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,6 +27,7 @@ infermatrix-copilot = "infermatrix_copilot.cli:main" infermatrix-copilot-mcp = "infermatrix_copilot.thin_mcp_server:main" infermatrix-copilot-workflow-mcp = "infermatrix_copilot.mcp_server:main" infermatrix-rfc = "infermatrix_copilot.rfc_service.cli:main" +infermatrix-feedback = "infermatrix_copilot.knowledge_service.feedback_server_cli:main" imx-omni-pytest = "infermatrix_copilot.rebase_engine.module_pytest:main" [build-system] diff --git a/src/infermatrix_copilot/cli/entry.py b/src/infermatrix_copilot/cli/entry.py index 390a1d363..eaeff59de 100644 --- a/src/infermatrix_copilot/cli/entry.py +++ b/src/infermatrix_copilot/cli/entry.py @@ -92,13 +92,14 @@ def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(prog="infermatrix-copilot", description="Conversational repo-maintenance copilot") parser.add_argument("command", nargs="?", - choices=["doctor", "migrate-knowledge", "rfc"], + choices=["doctor", "migrate-knowledge", "rfc", "learning"], help="doctor: preflight diagnostics with exact " "fixes; migrate-knowledge: the PR4d " "deployment-time knowledge migration " "(explicit owner action; see " "doc/RUNBOOK-rebase.md); rfc: portable RFC " - "drafting and progress service") + "drafting and progress service; learning: task " + "lessons and knowledge quality feedback") parser.add_argument("--repo", default="", help="with migrate-knowledge: target repo; " "with --resume: assert the saved repo name") @@ -144,6 +145,10 @@ def main(argv: list[str] | None = None) -> int: parser.add_argument("--execute-strict-reserved", metavar="RUN_ID", help=argparse.SUPPRESS) raw = list(sys.argv[1:] if argv is None else argv) + if raw and raw[0] == "learning": + from ..knowledge_service.learning_cli import main as learning_main + + return learning_main(raw[1:]) if raw and raw[0] == "rfc": from ..rfc_service.cli import main as rfc_main diff --git a/src/infermatrix_copilot/knowledge_context.py b/src/infermatrix_copilot/knowledge_context.py index cdb97085e..01fbfce18 100644 --- a/src/infermatrix_copilot/knowledge_context.py +++ b/src/infermatrix_copilot/knowledge_context.py @@ -217,6 +217,18 @@ def _deliver(self, session_id: str, request: dict, build: Callable) -> dict: _issue_usage(result, view=self.view, session_id=session_id) return result + def _feedback_receipt(self, task_id: str, repository: str, documents: list[dict]) -> dict: + from .knowledge_service.agreement import AgreementStore + from .knowledge_service.feedback import KnowledgeFeedbackStore + + if AgreementStore.from_env().status()["status"] != "accepted": + return {"status": "agreement_required", "protocol": "knowledge-feedback/1", "targets": []} + try: + return KnowledgeFeedbackStore.from_env().issue_delivery( + task_id=task_id, repository=repository, view=self.view, documents=documents) + except (OSError, sqlite3.Error): + return {"status": "unavailable", "error": "feedback_storage_unavailable"} + def _deliver_current(self, session_id: str, request: dict, build: Callable) -> dict: with self._db() as db: db.execute("BEGIN IMMEDIATE") @@ -239,9 +251,30 @@ def _deliver_current(self, session_id: str, request: dict, build: Callable) -> d raise ContextError("cached context receipt/content integrity check failed") for reference in result["documents"]: self.view.path(reference["path"]) + from .knowledge_service.agreement import AgreementStore + + feedback = result.get("knowledge_feedback", {}) + if AgreementStore.from_env().status()["status"] != "accepted": + feedback = {"status": "agreement_required", "protocol": "knowledge-feedback/1", "targets": []} + elif feedback.get("status") in {"unavailable", "agreement_required"}: + from .knowledge_service.feedback import model_content_documents + + # Repair only delivery metadata after the original packet + # passes integrity checks. Replaying retrieval could spend + # budget again or grant targets that were never delivered. + feedback = self._feedback_receipt( + state["identity"]["review_id"], binding["repo_id"], + model_content_documents(content)) + if feedback != result.get("knowledge_feedback", {}): + result = {**result, "knowledge_feedback": feedback} + state["requests"][key] = {"request": request, "result": result, + "receipt_sha256": _digest({"session_id": session_id, "request": request, + "active_tokens": state["active_tokens"], "result": result})} + self._save(db, session_id, state) return result units, extra = build(docs) rendered, references, truncated = [], [], False + feedback_documents = [] for unit in units: budget_partial = False content = unit.pop("content") @@ -287,6 +320,7 @@ def render(value): state["units"][unit_hash] = {"delivered_chars": previous["delivered_chars"] + len(content), "complete": not budget_partial} references.append({**unit, "repo_id": binding["repo_id"], "content_sha256": hashlib.sha256(content.encode()).hexdigest()}) + feedback_documents.append({"path": unit["path"], "content": content}) rendered.append(full) if state["consumed_tokens"] >= state["active_tokens"]: break @@ -298,6 +332,8 @@ def render(value): "remaining_tokens": state["active_tokens"] - state["consumed_tokens"], "token_accounting": self.tokenizer_id, "actual_provider_usage": "unknown", **extra} result["model_content_sha256"] = hashlib.sha256(result["model_content"].encode()).hexdigest() + result["knowledge_feedback"] = self._feedback_receipt( + state["identity"]["review_id"], binding["repo_id"], feedback_documents) if request["op"] == "read" and references and references[-1].get("partial"): result["next_offset"] = request["offset"] + state["units"][unit_hash]["delivered_chars"] state["requests"][key] = {"request": request, "result": result, diff --git a/src/infermatrix_copilot/knowledge_service/agreement.py b/src/infermatrix_copilot/knowledge_service/agreement.py new file mode 100644 index 000000000..5445fc358 --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/agreement.py @@ -0,0 +1,445 @@ +"""Explicit, versioned local acknowledgement for optional task learning. + +This is a product disclosure and named acknowledgement, not a claim about legal +enforceability or independently verified identity. Only the interactive CLI +calls the private acceptance method; ordinary APIs can inspect or revoke it. +""" +from __future__ import annotations + +import hashlib +import json +import os +import re +import stat +import tempfile +import time +import uuid +from contextlib import contextmanager +from datetime import UTC, datetime, timedelta +from pathlib import Path +from urllib.parse import urlsplit + +AGREEMENT_VERSION = "2026-10-29.1" +AGREEMENT_PROTOCOL = "knowledge-learning-agreement/1" +AGREEMENT_TEXT = """InferMatrixCopilot optional learning and feedback disclosure + +Learning and knowledge feedback are disabled until you explicitly acknowledge +this version of the disclosure. Signing enables the optional learning and +feedback workflow for this local operating-system user and the destinations +shown below. Ordinary knowledge reading remains available without signing. + +1. Extra model work and cost. At task completion or on an explicit learning +request, your current host agent may inspect relevant conversation context, +distill reusable positive and negative lessons, evaluate knowledge actually +used, and draft rule proposals. This consumes additional host-model tokens, +execution time and possibly paid model/API quota. Cost depends on your host, +model and account; no fixed charge or free allowance is promised. + +2. Selected conversation-derived data. Lessons, evidence references, rating +reasons, outcomes and task identifiers can contain personal, proprietary or +confidential information from your conversation or work. The workflow selects +bounded summaries and evidence instead of uploading raw chat histories or +complete command logs by design. You and your agent must select and redact +appropriate material. Automated checks do not guarantee perfect redaction or +detection of every secret, personal detail or confidential fact. + +3. Private local storage. Selected lessons, evidence, delivery metadata, +feedback, upload queues and this named acknowledgement are retained in private +local runtime state outside the product knowledge tree. Local retention is +separate from publication or transmission to another service. + +4. Knowledge pull requests. When draft-PR publication and its existing write +gates are configured, distilled rules and their selected evidence/provenance +may be sent to the configured GitHub repository and branch shown below. A +public repository exposes contributions publicly; a private repository exposes +them to its authorized collaborators and service operators. PRs require the +existing review process and are not automatically merged by this workflow. + +5. Central feedback. When a collector URL is configured, knowledge-version +metadata, task identifiers, +1/-1 ratings, reasons and selected evidence are +sent to that collector for team aggregation. Its operators and authorized +readers may access stored feedback. Signing does not replace your own review +of the destination's access, retention or data-handling policies. Credentials +are deployment configuration and are not part of the acknowledgement or +feedback payload. + +6. Choice and revocation. You may decline, keep the workflow disabled, inspect +the current acknowledgement, or revoke it later. Changed disclosure terms or +configured publication/collector destinations require a new acknowledgement. +Revocation prevents future learning, grading and uploads after the next gate +check. It does not erase data already stored locally or sent elsewhere, and +an operation already in flight may complete. Remove prior data through the +relevant local storage, GitHub or collector administration process. + +By entering your name and the exact words I AGREE in the interactive terminal, +you acknowledge these disclosures and enable this optional workflow for the +displayed configuration. This is a named product acknowledgement; it does not +assert a verified legal signature or a particular jurisdiction's legal effect. +""" +AGREEMENT_SHA256 = hashlib.sha256(AGREEMENT_TEXT.encode("utf-8")).hexdigest() +AGREEMENT_SHA = AGREEMENT_SHA256 +_MAX_RECORD_BYTES = 1024 * 1024 +_SHA = re.compile(r"[0-9a-f]{64}\Z") +_ID = re.compile(r"[0-9a-f]{32}\Z") +_MESSAGE = "Learning and feedback require your current interactive agreement; run infermatrix-copilot learning agreement." + + +class AgreementRequiredError(ValueError): + code = "agreement_required" + + def __init__(self): + super().__init__(_MESSAGE) + + +def _json(value): + return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False, allow_nan=False) + + +def _digest(value): + return hashlib.sha256(_json(value).encode("utf-8")).hexdigest() + + +def _now(): + return datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z") + + +def _timestamp(value): + if not isinstance(value, str) or not value.endswith("Z") or len(value) > 40: + raise ValueError("invalid acknowledgement timestamp") + parsed = datetime.fromisoformat(value) + if parsed.utcoffset() != UTC.utcoffset(parsed): + raise ValueError("invalid acknowledgement timestamp") + if parsed > datetime.now(UTC).replace(microsecond=0) + timedelta(minutes=5): + raise ValueError("invalid acknowledgement timestamp") + return value + + +def _context(value): + fields = {"publication_mode", "publication_repository", "publication_base", "feedback_url"} + if not isinstance(value, dict) or set(value) != fields: + raise ValueError("invalid agreement configuration") + if any(not isinstance(item, str) or len(item) > 2048 or item != item.strip() + or any(ord(char) < 32 or ord(char) == 127 for char in item) for item in value.values()): + raise ValueError("invalid agreement configuration") + if value["publication_mode"] not in {"local", "draft_pr"}: + raise ValueError("invalid agreement configuration") + repository = value["publication_repository"] + if repository and not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository): + raise ValueError("invalid agreement configuration") + base = value["publication_base"] + if (not base or base.startswith(("-", "/")) or base.endswith(("/", ".")) + or any(char.isspace() or char in "~^:?*[\\" for char in base) + or ".." in base or "@{" in base or "//" in base): + raise ValueError("invalid agreement configuration") + url = value["feedback_url"] + if url: + from .feedback_sync import FeedbackSyncConfig + + # Reuse the transport's destination validation without reading a token. + url = FeedbackSyncConfig(url, "x" * 32).url + parts = urlsplit(url) + if parts.username is not None or parts.password is not None: + raise ValueError("invalid agreement configuration") + from .learning_privacy import validate_distilled_text + + validate_distilled_text(value) + return {**value, "feedback_url": url} + + +def _environment_context(environ, feedback_url=None): + return _context({ + "publication_mode": environ.get("KNOWLEDGE_LEARNING_PUBLICATION", "local").strip(), + "publication_repository": environ.get("KNOWLEDGE_LEARNING_REPOSITORY", "").strip(), + "publication_base": environ.get("KNOWLEDGE_LEARNING_BASE", "main").strip(), + "feedback_url": (environ.get("KNOWLEDGE_FEEDBACK_URL", "") if feedback_url is None else feedback_url).strip(), + }) + + +def _pairs(pairs): + result = {} + for key, value in pairs: + if key in result: + raise ValueError("duplicate acknowledgement field") + result[key] = value + return result + + +class AgreementStore: + def __init__(self, state_dir, *, context=None): + supplied = Path(state_dir).expanduser().absolute() + # HOME and parent aliases can legitimately be symlinks. Canonicalize + # them exactly as runtime state does, while refusing an explicit state + # leaf symlink and all acknowledgement-owned symlink entries. + self._unsafe_state_alias = False + try: + self._unsafe_state_alias = supplied.is_symlink() + self.state_dir = supplied.resolve() + except (OSError, RuntimeError, ValueError): + # An optional agreement path must fail closed without breaking + # ordinary knowledge reads. Never mutate this unresolved path. + self._unsafe_state_alias = True + self.state_dir = supplied + self.directory = self.state_dir / "agreement" + self.path = self.directory / "acceptance.json" + self._context_source = None + self._context_error = False + try: + self.context = _context(context) if context is not None else _environment_context({}) + except (ValueError, TypeError, AttributeError): + self.context, self._context_error = {}, True + + @classmethod + def from_env(cls, *, state_dir=None, environ=None, feedback_url=None): + from .learning_config import learning_environment + + values = learning_environment() if environ is None else dict(environ) + configured = values.get("KNOWLEDGE_LEARNING_STATE_DIR", "").strip() + storage = state_dir if state_dir is not None else configured or Path.home() / ".infermatrix-copilot" / "learning" + try: + context = _environment_context(values, feedback_url) + except (ValueError, TypeError, AttributeError): + context = {} + instance = cls(storage, context=context) + if environ is None: + instance._context_source = lambda: _environment_context(learning_environment(), feedback_url) + return instance + + def _current_context(self): + if self._context_error: + raise AgreementRequiredError() + try: + return _context(self._context_source() if self._context_source else self.context) + except (ValueError, TypeError, AttributeError): + raise AgreementRequiredError() from None + + def document(self): + context = self._current_context() + return {"version": AGREEMENT_VERSION, "text": AGREEMENT_TEXT, "sha256": AGREEMENT_SHA256, + "context": context, "context_sha256": _digest(context)} + + def _safe_paths(self): + if self._unsafe_state_alias: + raise ValueError("unsafe acknowledgement state") + for path in (self.state_dir, self.directory, self.path, + self.directory / "agreement.lock"): + if path.is_symlink(): + raise ValueError("unsafe acknowledgement state") + + @staticmethod + def _private(path, *, directory=False): + metadata = path.stat() + if (directory and not stat.S_ISDIR(metadata.st_mode)) or (not directory and not stat.S_ISREG(metadata.st_mode)): + raise ValueError("unsafe acknowledgement state") + if os.name != "nt" and metadata.st_mode & 0o077: + raise ValueError("unsafe acknowledgement permissions") + if hasattr(os, "getuid") and metadata.st_uid != os.getuid(): + raise ValueError("acknowledgement belongs to another operating-system user") + + def _read(self): + self._safe_paths() + if not self.path.exists(): + return None + self._private(self.directory, directory=True) + self._private(self.path) + descriptor = os.open(self.path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0)) + with os.fdopen(descriptor, "rb") as stream: + raw = stream.read(_MAX_RECORD_BYTES + 1) + if len(raw) > _MAX_RECORD_BYTES: + raise ValueError("acknowledgement record is too large") + record = json.loads(raw.decode("utf-8"), object_pairs_hook=_pairs) + if (not isinstance(record, dict) or set(record) != {"protocol", "state", "acceptance", "audit"} + or record["protocol"] != AGREEMENT_PROTOCOL or record["state"] not in {"accepted", "revoked"} + or not isinstance(record["audit"], list) or not record["audit"]): + raise ValueError("invalid acknowledgement record") + acceptance = record["acceptance"] + if acceptance is not None: + self._validate_acceptance(acceptance) + elif record["state"] == "accepted": + raise ValueError("invalid acknowledgement record") + for event in record["audit"]: + if not isinstance(event, dict) or event.get("action") not in {"accepted", "revoked"}: + raise ValueError("invalid acknowledgement audit") + expected = {"action", "at", "acceptance" if event["action"] == "accepted" else "acceptance_id"} + if set(event) != expected: + raise ValueError("invalid acknowledgement audit") + _timestamp(event.get("at")) + if event["action"] == "accepted": + self._validate_acceptance(event.get("acceptance")) + last = record["audit"][-1] + if (last["action"] != record["state"] or (record["state"] == "accepted" and last.get("acceptance") != acceptance) + or (record["state"] == "revoked" and last.get("acceptance_id") != (acceptance or {}).get("acceptance_id"))): + raise ValueError("invalid acknowledgement audit state") + return record + + @staticmethod + def _validate_acceptance(value): + fields = {"signer", "accepted_at", "acceptance_id", "version", "agreement_text", "agreement_sha256", + "context", "context_sha256", "owner_uid", "confirmation"} + if not isinstance(value, dict) or set(value) != fields: + raise ValueError("invalid acknowledgement") + if (not isinstance(value["signer"], str) or not value["signer"].strip() or len(value["signer"]) > 256 + or any(ord(char) < 32 or ord(char) == 127 for char in value["signer"]) + or not isinstance(value["version"], str) or not value["version"] or len(value["version"]) > 80 + or not isinstance(value["agreement_text"], str) + or not _SHA.fullmatch(value["agreement_sha256"]) + or hashlib.sha256(value["agreement_text"].encode()).hexdigest() != value["agreement_sha256"] + or not isinstance(value["acceptance_id"], str) or not _ID.fullmatch(value["acceptance_id"]) + or value["confirmation"] != "I AGREE"): + raise ValueError("invalid acknowledgement") + _timestamp(value["accepted_at"]) + from .learning_privacy import validate_distilled_text + + validate_distilled_text(value["signer"]) + context = _context(value["context"]) + if _digest(context) != value["context_sha256"]: + raise ValueError("invalid acknowledgement context") + if hasattr(os, "getuid") and (type(value["owner_uid"]) is not int or value["owner_uid"] != os.getuid()): + raise ValueError("acknowledgement belongs to another operating-system user") + + def status(self): + try: + document = self.document() + except (OSError, ValueError, TypeError): + return {"status": "unavailable", "version": AGREEMENT_VERSION, "agreement_sha256": AGREEMENT_SHA256} + result = {"status": "required", "version": document["version"], "agreement_sha256": document["sha256"], + "context": document["context"], "context_sha256": document["context_sha256"]} + try: + record = self._read() + if record is None: + return result + acceptance = record["acceptance"] + if record["state"] == "revoked": + return {**result, "status": "revoked"} + if (acceptance["version"] != AGREEMENT_VERSION or acceptance["agreement_sha256"] != AGREEMENT_SHA256 + or acceptance["context_sha256"] != document["context_sha256"]): + return {**result, "status": "renewal_required"} + return {**result, "status": "accepted", "accepted_at": acceptance["accepted_at"], + "acceptance_id": acceptance["acceptance_id"]} + except (OSError, ValueError, TypeError, KeyError, RecursionError): + return {**result, "status": "unavailable"} + + def require(self, action: str): + if not isinstance(action, str) or not action.strip(): + raise AgreementRequiredError() + current = self.status() + if current["status"] != "accepted": + raise AgreementRequiredError() + return {key: current[key] for key in ("version", "agreement_sha256", "context_sha256", "acceptance_id", "accepted_at")} + + def attestation(self): + return {"protocol": AGREEMENT_PROTOCOL, "purpose": "feedback_upload", **self.require("feedback_upload")} + + @contextmanager + def _locked(self): + self._safe_paths() + self.state_dir.mkdir(parents=True, exist_ok=True, mode=0o700) + self.directory.mkdir(mode=0o700, exist_ok=True) + self._safe_paths() + self._private(self.directory, directory=True) + lock = self.directory / "agreement.lock" + descriptor = os.open(lock, os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0), 0o600) + try: + self._private(lock) + from ..trace_store import _try_lock_exclusive, _unlock + + if os.fstat(descriptor).st_size == 0: + os.write(descriptor, b"\0") + deadline = time.monotonic() + 5 + while not _try_lock_exclusive(descriptor): + if time.monotonic() >= deadline: + raise AgreementRequiredError() + time.sleep(0.02) + try: + yield + finally: + _unlock(descriptor) + finally: + os.close(descriptor) + + def _write(self, record): + # Keep a bounded recent audit. Retention cannot prevent revocation, and + # the latest exact acknowledgement remains alongside the current state. + record = {**record, "audit": record["audit"][-128:]} + encoded = (_json(record) + "\n").encode("utf-8") + while len(encoded) > _MAX_RECORD_BYTES and len(record["audit"]) > 1: + record["audit"] = record["audit"][1:] + encoded = (_json(record) + "\n").encode("utf-8") + if len(encoded) > _MAX_RECORD_BYTES: + raise AgreementRequiredError() + descriptor, temporary = tempfile.mkstemp(prefix=".acceptance-", suffix=".tmp", dir=self.directory) + try: + with os.fdopen(descriptor, "wb") as stream: + stream.write(encoded) + stream.flush() + os.fsync(stream.fileno()) + self._safe_paths() + os.replace(temporary, self.path) + if os.name != "nt": + directory_fd = os.open(self.directory, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0)) + try: + os.fsync(directory_fd) + finally: + os.close(directory_fd) + finally: + try: + os.unlink(temporary) + except FileNotFoundError: + pass + + def _accept(self, signer, *, version, agreement_sha256, context_sha256, confirmation="I AGREE"): + """CLI/tests only: persist the exact terms and destinations just shown.""" + if (not isinstance(signer, str) or not signer.strip() or len(signer.strip()) > 256 + or any(ord(char) < 32 or ord(char) == 127 for char in signer) + or confirmation != "I AGREE"): + raise AgreementRequiredError() + try: + from .learning_privacy import validate_distilled_text + + validate_distilled_text(signer) + with self._locked(): + document = self.document() + if (version != document["version"] or agreement_sha256 != document["sha256"] + or context_sha256 != document["context_sha256"]): + raise AgreementRequiredError() + previous = self._read() + acceptance = {"signer": signer.strip(), "accepted_at": _now(), "acceptance_id": uuid.uuid4().hex, + "version": version, "agreement_text": document["text"], + "agreement_sha256": agreement_sha256, "context": document["context"], + "context_sha256": context_sha256, + "owner_uid": os.getuid() if hasattr(os, "getuid") else None, + "confirmation": confirmation} + audit = previous["audit"] if previous else [] + audit.append({"action": "accepted", "at": acceptance["accepted_at"], "acceptance": acceptance}) + self._write({"protocol": AGREEMENT_PROTOCOL, "state": "accepted", "acceptance": acceptance, "audit": audit}) + except (OSError, ValueError, TypeError, KeyError, RecursionError): + raise AgreementRequiredError() from None + return self.status() + + def revoke(self): + try: + with self._locked(): + previous = self._read() + acceptance = previous["acceptance"] if previous else None + audit = previous["audit"] if previous else [] + audit.append({"action": "revoked", "at": _now(), + "acceptance_id": (acceptance or {}).get("acceptance_id")}) + self._write({"protocol": AGREEMENT_PROTOCOL, "state": "revoked", "acceptance": acceptance, "audit": audit}) + except (OSError, ValueError, TypeError, KeyError, RecursionError): + raise AgreementRequiredError() from None + return self.status() + + +def validate_upload_attestation(value): + """Validate a trusted provider's attestation, not independent human proof.""" + fields = {"protocol", "purpose", "version", "agreement_sha256", "context_sha256", "acceptance_id", "accepted_at"} + try: + if (not isinstance(value, dict) or set(value) != fields or value["protocol"] != AGREEMENT_PROTOCOL + or value["purpose"] != "feedback_upload" or value["version"] != AGREEMENT_VERSION + or value["agreement_sha256"] != AGREEMENT_SHA256 + or not isinstance(value["context_sha256"], str) or not _SHA.fullmatch(value["context_sha256"]) + or not isinstance(value["acceptance_id"], str) or not _ID.fullmatch(value["acceptance_id"])): + raise AgreementRequiredError() + _timestamp(value["accepted_at"]) + return json.loads(_json(value)) + except (ValueError, TypeError, KeyError): + raise AgreementRequiredError() from None diff --git a/src/infermatrix_copilot/knowledge_service/agreement_cli.py b/src/infermatrix_copilot/knowledge_service/agreement_cli.py new file mode 100644 index 000000000..cb8a9ec70 --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/agreement_cli.py @@ -0,0 +1,73 @@ +"""Interactive named acknowledgement; never accept from flags or stdin pipes.""" +from __future__ import annotations + +import argparse +import json +import sys + +from .agreement import AgreementRequiredError, AgreementStore + + +class _Parser(argparse.ArgumentParser): + def error(self, message): + self.exit(2, "Invalid agreement command; use --help for accepted arguments.\n") + + +def _error(code, message): + print(json.dumps({"error": {"code": code, "message": message}})) + + +def _show(document): + print(document["text"]) + print("Agreement version:", document["version"]) + print("Agreement SHA256:", document["sha256"]) + print("Configured destinations:") + print(json.dumps(document["context"], ensure_ascii=False, indent=2, sort_keys=True)) + print("Configuration SHA256:", document["context_sha256"]) + + +def main(argv=None): + parser = _Parser(prog="infermatrix-copilot learning agreement") + parser.add_argument("command", choices=("show", "status", "accept", "revoke"), nargs="?", default="show") + args = parser.parse_args(argv) + try: + store = AgreementStore.from_env() + if args.command == "status": + print(json.dumps(store.status(), ensure_ascii=False, sort_keys=True)) + return 0 + if args.command == "revoke": + print(json.dumps(store.revoke(), ensure_ascii=False, sort_keys=True)) + return 0 + document = store.document() + if args.command == "show": + _show(document) + return 0 + if not sys.stdin.isatty() or not sys.stdout.isatty(): + _error("interactive_required", "Agreement was not accepted. Use an interactive terminal; piped or automated acceptance is unavailable.") + return 2 + _show(document) + signer = input("Enter your name to acknowledge these disclosures: ") + confirmation = input("Type exactly I AGREE to enable optional learning and feedback: ") + if not signer.strip() or confirmation != "I AGREE": + _error("agreement_not_accepted", "Agreement was not accepted; learning and feedback remain disabled.") + return 2 + # Resolve again after prompts. A destination or terms change while the + # person was reading cannot authorize an unseen configuration. + current = AgreementStore.from_env() + if current.document() != document: + _error("agreement_changed", "Agreement was not accepted because its terms or destinations changed; read them again.") + return 2 + result = current._accept(signer, version=document["version"], agreement_sha256=document["sha256"], + context_sha256=document["context_sha256"], confirmation=confirmation) + print(json.dumps(result, ensure_ascii=False, sort_keys=True)) + return 0 if result["status"] == "accepted" else 2 + except (EOFError, KeyboardInterrupt): + _error("agreement_not_accepted", "Agreement was not accepted; learning and feedback remain disabled.") + return 2 + except (AgreementRequiredError, OSError, ValueError, TypeError): + _error("agreement_unavailable", "Agreement operation could not complete; inspect agreement status before retrying.") + return 2 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/infermatrix_copilot/knowledge_service/feedback.py b/src/infermatrix_copilot/knowledge_service/feedback.py new file mode 100644 index 000000000..4bddca66a --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/feedback.py @@ -0,0 +1,559 @@ +"""Provider-bound knowledge feedback, stored outside the product knowledge tree. + +Only trusted delivery code calls ``issue_delivery``. Public callers can rate an +issued target, but cannot turn an arbitrary path or hash into evidence of use. +The ledger retains hashes and feedback metadata, never delivered source text. +It operates independently of the optional knowledge containment policy. +""" +from __future__ import annotations + +import hashlib +import json +import os +import re +import sqlite3 +import time +from contextlib import contextmanager +from pathlib import Path + +from ..knowledge_view import KnowledgeView, KnowledgeViewError +from .agreement import AgreementRequiredError, AgreementStore + +PROTOCOL = "knowledge-feedback/1" + + +class FeedbackError(ValueError): + """Invalid delivery, feedback, or reuse of an immutable feedback identity.""" + + +def model_content_documents(content: str) -> list[dict]: + """Extract only exact provider-rendered adaptive source fragments. + + Adaptive rendering escapes literal ``<`` inside JSON values. Parsing each + complete fence therefore never mistakes quoted source text for a delivery. + This helper does not issue a receipt and must receive trusted provider output. + """ + if not isinstance(content, str): + raise FeedbackError("model content must be a string") + documents = [] + for match in re.finditer(r"\n\n(.*?)\n\n", content, re.DOTALL): + try: + fragment = json.loads(match[1]) + except (ValueError, TypeError) as exc: + raise FeedbackError("adaptive source fragment is not valid JSON") from exc + if isinstance(fragment, dict) and isinstance(fragment.get("path"), str) \ + and isinstance(fragment.get("content"), str): + documents.append({"path": fragment["path"], "content": fragment["content"]}) + return documents + + +def _json(value) -> str: + try: + return json.dumps(value, sort_keys=True, separators=(",", ":"), + ensure_ascii=False, allow_nan=False) + except (TypeError, ValueError) as exc: + raise FeedbackError("feedback metadata must be finite JSON") from exc + + +def _digest(value) -> str: + return hashlib.sha256(_json(value).encode("utf-8")).hexdigest() + + +def _text(value, name, maximum=2000): + if not isinstance(value, str) or not value.strip() or len(value) > maximum: + raise FeedbackError(f"{name} must be a nonempty string of at most {maximum} characters") + return value.strip() + + +def _evidence(value): + def has_text(node): + if isinstance(node, str): + return bool(node.strip()) + if isinstance(node, list): + return bool(node) and all(has_text(item) for item in node) + if isinstance(node, dict): + return bool(node) and any(has_text(item) for item in node.values()) + return False + + if not isinstance(value, (str, list, dict)) or not has_text(value): + raise FeedbackError("evidence must contain concrete nonempty references or observations") + encoded = _json(value) + if len(encoded.encode("utf-8")) > 8192: + raise FeedbackError("evidence exceeds 8192 bytes; provide references instead of transcripts") + return json.loads(encoded) + + +class KnowledgeFeedbackStore: + _feedback_sync_enabled = True + + def __init__(self, state_dir: Path, *, sync_config=None, sync_configuration_error=False): + self.state_dir = Path(state_dir).expanduser().resolve() + self.path = self.state_dir / "feedback.sqlite3" + self.sync_config = sync_config + self._sync_configuration_error = sync_configuration_error + + def _agreement(self): + return AgreementStore.from_env(state_dir=self.state_dir, + feedback_url=self.sync_config.url if self.sync_config else None) + + def _require_agreement(self, action): + if self._feedback_sync_enabled: + return self._agreement().require(action) + return None + + def _inspection_rows(self, query, parameters=()): + """Inspect existing state without creating a ledger or migrating it.""" + if not self.path.exists(): + return [] + if self.path.is_symlink(): + raise FeedbackError("feedback database cannot be a symbolic link") + db = sqlite3.connect(self.path.as_uri() + "?mode=ro", uri=True, timeout=30) + try: + db.row_factory = sqlite3.Row + try: + return db.execute(query, parameters).fetchall() + except sqlite3.OperationalError as exc: + if "no such table" in str(exc): + return [] + raise + finally: + db.close() + + def _agreement_blocked_status(self): + totals = self._inspection_rows("SELECT COUNT(*) FROM feedback_ratings") + total = totals[0][0] if totals else 0 + destination = self._destination_hash() + rows = self._inspection_rows("SELECT COUNT(*) FROM feedback_outbox WHERE acknowledged=1 " + "AND destination_hash=?", (destination,)) if destination else [] + acknowledged = rows[0][0] if rows else 0 + return {"status": "agreement_required", "configured": self.is_sync_configured, + "pending_count": max(total - acknowledged, 0), "acknowledged_count": acknowledged} + + @classmethod + def from_env(cls, *, state_dir=None): + from .feedback_sync import FeedbackSyncConfig, FeedbackSyncError + from .learning_config import learning_environment + + environ = learning_environment() + configured = environ.get("KNOWLEDGE_LEARNING_STATE_DIR", "").strip() + try: + sync_config = FeedbackSyncConfig.from_environment(environ) + invalid = False + except FeedbackSyncError: + sync_config, invalid = None, True + storage = (Path(state_dir) if state_dir is not None else Path(configured) if configured + else Path.home() / ".infermatrix-copilot" / "learning") + return cls(storage, + sync_config=sync_config, sync_configuration_error=invalid) + + @contextmanager + def _db(self): + self.state_dir.mkdir(parents=True, exist_ok=True, mode=0o700) + if self.path.is_symlink(): + raise FeedbackError("feedback database cannot be a symbolic link") + def secure_file(path, *, create=False): + if path.is_symlink(): + raise FeedbackError("feedback database files cannot be symbolic links") + flags = (os.O_RDWR | os.O_CREAT if create else os.O_RDONLY) | getattr(os, "O_NOFOLLOW", 0) + descriptor = os.open(path, flags, 0o600) + try: + if path.is_symlink(): + raise FeedbackError("feedback database files cannot be symbolic links") + if hasattr(os, "fchmod"): + os.fchmod(descriptor, 0o600) + else: + os.chmod(path, 0o600) + finally: + os.close(descriptor) + + secure_file(self.path, create=True) + + def secure_sidecars(): + for suffix in ("-wal", "-shm"): + try: + secure_file(Path(str(self.path) + suffix)) + except FileNotFoundError: + continue + + secure_sidecars() + db = sqlite3.connect(self.path, timeout=30) + try: + db.row_factory = sqlite3.Row + db.execute("PRAGMA busy_timeout=30000") + deadline = time.monotonic() + 30 + while True: + try: + db.execute("PRAGMA journal_mode=WAL") + break + except sqlite3.OperationalError as exc: + if (not any(code in str(exc).lower() for code in ("locked", "busy")) + or time.monotonic() >= deadline): + raise + time.sleep(0.01) + db.executescript(""" + CREATE TABLE IF NOT EXISTS feedback_deliveries ( + id TEXT PRIMARY KEY, task_id TEXT NOT NULL, + repository TEXT NOT NULL, payload TEXT NOT NULL); + CREATE TABLE IF NOT EXISTS feedback_ratings ( + task_id TEXT NOT NULL, target_id TEXT NOT NULL, + repository TEXT NOT NULL, rating TEXT NOT NULL, + target TEXT NOT NULL, delivery_id TEXT NOT NULL, + created_at REAL NOT NULL, PRIMARY KEY (task_id, target_id)); + CREATE INDEX IF NOT EXISTS feedback_ratings_by_repository + ON feedback_ratings(repository, target_id); + CREATE INDEX IF NOT EXISTS feedback_deliveries_by_task + ON feedback_deliveries(task_id, repository); + CREATE TABLE IF NOT EXISTS feedback_outbox ( + feedback_id TEXT PRIMARY KEY, task_id TEXT NOT NULL, + target_id TEXT NOT NULL, delivery_id TEXT NOT NULL, + destination_hash TEXT NOT NULL DEFAULT '', + acknowledged INTEGER NOT NULL DEFAULT 0, + attempts INTEGER NOT NULL DEFAULT 0, + last_attempt REAL, acknowledged_at REAL, last_error TEXT); + CREATE UNIQUE INDEX IF NOT EXISTS feedback_outbox_identity + ON feedback_outbox(task_id,target_id); + CREATE TABLE IF NOT EXISTS feedback_sync_meta ( + name TEXT PRIMARY KEY, value TEXT NOT NULL); + """) + secure_sidecars() + with db: + yield db + finally: + db.close() + + def repositories_for_task(self, task_id: str) -> tuple[str, ...]: + """Resolve existing task context without rewriting any issued receipt.""" + task_id = _text(task_id, "task_id", 512) + rows = self._inspection_rows("SELECT DISTINCT repository FROM feedback_deliveries " + "WHERE task_id=? ORDER BY repository", (task_id,)) + return tuple(row["repository"] for row in rows) + + def issue_delivery(self, *, task_id: str, repository: str, view: KnowledgeView, + documents: list[dict]) -> dict: + """Issue metadata for content actually delivered by trusted provider code. + + Documents carry ``path``/``document_id`` and ``content``/``excerpt``/ + ``text``. Rendered provider excerpts may include presentation wrappers. + A rule is eligible only when its complete source section was delivered. + """ + try: + self._require_agreement("feedback_delivery") + except AgreementRequiredError: + return {"status": "agreement_required", "protocol": PROTOCOL, "targets": []} + task_id = _text(task_id, "task_id", 512) + repository = _text(repository, "repository", 256) + root = view.root.resolve() + if self.state_dir.is_relative_to(root) or self.path.resolve().is_relative_to(root): + raise FeedbackError("feedback state must live outside the knowledge tree") + if not isinstance(documents, list) or len(documents) > 256: + raise FeedbackError("documents must be a list of at most 256 delivered fragments") + from ..kb_service.maintenance_units import page_units + + targets, fragments = {}, {} + delivered_bytes = 0 + for document in documents: + if not isinstance(document, dict): + raise FeedbackError("each delivered document must be an object") + supplied = document.get("path", document.get("document_id")) + if not isinstance(supplied, str) or not supplied.strip(): + raise FeedbackError("each delivered document requires a path") + content = next((document[key] for key in ("content", "excerpt", "text") + if key in document), None) + if not isinstance(content, str): + raise FeedbackError("each delivered document requires string content") + try: + relative = view.relative(supplied) if Path(supplied).is_absolute() else supplied + path = view.path(relative) + relative = path.relative_to(root).as_posix() + if path.suffix.casefold() != ".md": + raise FeedbackError("feedback delivery requires a Markdown document") + data = path.read_bytes() + source = data.decode("utf-8") + except (ValueError, OSError, KnowledgeViewError) as exc: + raise FeedbackError(f"invalid knowledge document: {supplied}") from exc + if not content.strip(): + continue + delivered_bytes += len(content.encode("utf-8")) + if delivered_bytes > 16_000_000: + raise FeedbackError("delivered fragments exceed 16000000 bytes") + page_sha = hashlib.sha256(data).hexdigest() + delivered_sha = hashlib.sha256(content.encode("utf-8")).hexdigest() + fragment = {"path": relative, "page_sha256": page_sha, + "delivered_sha256": delivered_sha, "delivered_chars": len(content)} + fragments[_digest(fragment)] = fragment + common = {"repository": repository, "path": relative, + "page_sha256": page_sha, "snapshot": view.public_snapshot} + version = {"repository": repository, "path": relative, + "kind": "document", "content_sha256": page_sha} + target_id = _digest(version) + targets[target_id] = {**common, **version, "target_id": target_id} + parts = Path(relative).parts + owner_repo = parts[1] if len(parts) > 2 and parts[0] == "repos" else "general" + for unit in page_units(relative, source, owner_repo, view.public_snapshot): + if unit["kind"] != "rule" or unit["structural_issues"]: + continue + section = unit["text"].strip() + if not section or section not in content: + continue + version = {"repository": repository, "path": relative, "kind": "rule", + "unit_id": unit["unit_id"], "block_id": unit["block_id"], + "content_sha256": unit["content_sha256"], + "upstream_pins": sorted(unit["upstream_pins"])} + target_id = _digest(version) + targets[target_id] = {**common, **version, "target_id": target_id} + body = {"protocol": PROTOCOL, "task_id": task_id, "repository": repository, + "snapshot": view.public_snapshot, "tree_sha256": view.tree_sha256, + "documents": sorted(fragments.values(), key=lambda row: (row["path"], row["delivered_sha256"])), + "targets": sorted(targets.values(), key=lambda row: (row["path"], row["kind"], row.get("block_id", ""), row["target_id"]))} + receipt = {**body, "delivery_id": _digest(body)} + encoded = _json(receipt) + try: + self._require_agreement("feedback_delivery") + except AgreementRequiredError: + return {"status": "agreement_required", "protocol": PROTOCOL, "targets": []} + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + row = db.execute("SELECT payload FROM feedback_deliveries WHERE id=?", (receipt["delivery_id"],)).fetchone() + if row and row["payload"] != encoded: + raise FeedbackError("delivery identity conflicts with existing issuance") + db.execute("INSERT OR IGNORE INTO feedback_deliveries VALUES (?,?,?,?)", + (receipt["delivery_id"], task_id, repository, encoded)) + return receipt + + def record(self, *, task_id, delivery_id, ratings: list[dict]) -> dict: + self._require_agreement("feedback_record") + task_id = _text(task_id, "task_id", 512) + delivery_id = _text(delivery_id, "delivery_id", 64) + if not isinstance(ratings, list) or len(ratings) > 256: + raise FeedbackError("ratings must be a list of at most 256 entries") + result = [] + self._require_agreement("feedback_record") + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + row = db.execute("SELECT * FROM feedback_deliveries WHERE id=?", (delivery_id,)).fetchone() + if row is None or row["task_id"] != task_id: + raise FeedbackError("delivery was not issued for this task") + receipt = json.loads(row["payload"]) + body = {key: value for key, value in receipt.items() if key != "delivery_id"} + if receipt.get("delivery_id") != delivery_id or _digest(body) != delivery_id \ + or receipt.get("task_id") != task_id or receipt.get("repository") != row["repository"]: + raise FeedbackError("stored delivery integrity check failed") + eligible = {target["target_id"]: target for target in receipt["targets"]} + seen = set() + for rating in ratings: + if not isinstance(rating, dict): + raise FeedbackError("each rating must be an object") + target_id = rating.get("target_id") + if not isinstance(target_id, str) or target_id not in eligible: + raise FeedbackError("target was not delivered for this task") + if target_id in seen: + raise FeedbackError("a feedback batch cannot repeat a target") + seen.add(target_id) + if type(rating.get("score")) is not int or rating["score"] not in (-1, 1): + raise FeedbackError("score must be the integer -1 or 1") + if rating.get("used") is not True: + raise FeedbackError("feedback requires used=true for knowledge actually used") + canonical = {"target_id": target_id, "score": rating["score"], "used": True, + "reason": _text(rating.get("reason"), "reason"), + "evidence": _evidence(rating.get("evidence"))} + encoded = _json(canonical) + existing = db.execute("SELECT rating,target,delivery_id FROM feedback_ratings WHERE task_id=? AND target_id=?", + (task_id, target_id)).fetchone() + if existing and existing["rating"] != encoded: + raise FeedbackError("feedback for this task and content version is immutable") + target = json.loads(existing["target"]) if existing else eligible[target_id] + if not existing: + db.execute("INSERT INTO feedback_ratings VALUES (?,?,?,?,?,?,?)", + (task_id, target_id, row["repository"], encoded, _json(target), delivery_id, time.time())) + # Bind retries to the first immutable delivery, even if the same + # rule was read again under a different receipt or snapshot. + if self._feedback_sync_enabled: + db.execute("INSERT OR IGNORE INTO feedback_outbox " + "(feedback_id,task_id,target_id,delivery_id) VALUES (?,?,?,?)", + (_digest([task_id, target_id]), task_id, target_id, + existing["delivery_id"] if existing else delivery_id)) + result.append({**canonical, "feedback_id": _digest([task_id, target_id]), "target": target}) + accepted = {"task_id": task_id, "delivery_id": delivery_id, "ratings": result} + if not self._feedback_sync_enabled: + return accepted + # Local acceptance and the outbox commit precede all network activity. + # Flush is deliberately bounded; further work remains durable for retry. + try: + sync = self.sync_pending(limit=min(max(len(result), 1), 10)) + except (OSError, sqlite3.Error, FeedbackError): + sync = {"status": "pending", "last_error": "local_sync_unavailable"} + return {**accepted, "sync": sync} + + @property + def is_sync_configured(self) -> bool: + return self.sync_config is not None or self._sync_configuration_error + + def _destination_hash(self) -> str: + return _digest(self.sync_config.url) if self.sync_config else "" + + def _backfill_outbox(self, db): + if not self._feedback_sync_enabled or db.execute( + "SELECT 1 FROM feedback_sync_meta WHERE name='initial_backfill'").fetchone(): + return + rows = db.execute("SELECT r.task_id,r.target_id,r.delivery_id FROM feedback_ratings r " + "LEFT JOIN feedback_outbox o ON r.task_id=o.task_id AND r.target_id=o.target_id " + "WHERE o.feedback_id IS NULL").fetchall() + for row in rows: + db.execute("INSERT OR IGNORE INTO feedback_outbox " + "(feedback_id,task_id,target_id,delivery_id) VALUES (?,?,?,?)", + (_digest([row["task_id"], row["target_id"]]), row["task_id"], + row["target_id"], row["delivery_id"])) + db.execute("INSERT OR IGNORE INTO feedback_sync_meta VALUES ('initial_backfill','1')") + + def sync_status(self) -> dict: + """Return durable queue counts without contacting the collector.""" + try: + self._require_agreement("feedback_status") + except AgreementRequiredError: + return self._agreement_blocked_status() + destination = self._destination_hash() + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + self._backfill_outbox(db) + total = db.execute("SELECT COUNT(*) FROM feedback_outbox").fetchone()[0] + acknowledged = db.execute("SELECT COUNT(*) FROM feedback_outbox " + "WHERE acknowledged=1 AND destination_hash=?", + (destination,)).fetchone()[0] if destination else 0 + last = db.execute("SELECT last_error FROM feedback_outbox WHERE last_error IS NOT NULL " + "ORDER BY last_attempt DESC LIMIT 1").fetchone() + pending = total - acknowledged + status = ("configuration_error" if self._sync_configuration_error else "disabled" + if not self.sync_config else "pending" if pending else "acknowledged") + result = {"status": status, "configured": self.is_sync_configured, + "pending_count": pending, "acknowledged_count": acknowledged} + if last: + result["last_error"] = last[0] + return result + + def sync_pending(self, limit=100) -> dict: + """Best-effort bounded replay; failures never remove accepted feedback.""" + from .feedback_sync import FeedbackSyncClient, FeedbackSyncError + + try: + self._require_agreement("feedback_sync") + except AgreementRequiredError: + return self._agreement_blocked_status() + if type(limit) is not int or not 1 <= limit <= 1000: + raise FeedbackError("sync limit must be between 1 and 1000") + if not self.sync_config: + return self.sync_status() + destination = self._destination_hash() + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + self._backfill_outbox(db) + rows = db.execute("SELECT * FROM feedback_outbox WHERE acknowledged=0 OR destination_hash<>? " + "ORDER BY COALESCE(last_attempt,0),feedback_id LIMIT ?", + (destination, limit)).fetchall() + client = FeedbackSyncClient(self.sync_config, state_dir=self.state_dir) + attempted = succeeded = 0 + # One flush has a wall-time budget as well as an event-count limit. + deadline = time.monotonic() + 30 + for event in rows: + if time.monotonic() >= deadline: + break + try: + self._require_agreement("feedback_sync") + except AgreementRequiredError: + return {**self._agreement_blocked_status(), "attempted_count": attempted, + "acknowledged_this_run": succeeded} + attempted += 1 + error = None + try: + with self._db() as db: + rating = db.execute("SELECT * FROM feedback_ratings WHERE task_id=? AND target_id=?", + (event["task_id"], event["target_id"])).fetchone() + delivery = db.execute("SELECT * FROM feedback_deliveries WHERE id=?", + (event["delivery_id"],)).fetchone() + if (not rating or not delivery or rating["delivery_id"] != event["delivery_id"] + or delivery["task_id"] != event["task_id"]): + raise FeedbackError("invalid local feedback event") + receipt = json.loads(delivery["payload"]) + body = {key: value for key, value in receipt.items() if key != "delivery_id"} + canonical, target = json.loads(rating["rating"]), json.loads(rating["target"]) + if (receipt.get("delivery_id") != event["delivery_id"] + or _digest(body) != event["delivery_id"] + or receipt.get("task_id") != event["task_id"] + or target not in receipt.get("targets", []) + or canonical.get("target_id") != event["target_id"] + or _digest([event["task_id"], event["target_id"]]) != event["feedback_id"]): + raise FeedbackError("invalid local feedback event") + client.send(receipt=receipt, rating=canonical, target=target, + feedback_id=event["feedback_id"]) + succeeded += 1 + except AgreementRequiredError: + return {**self._agreement_blocked_status(), "attempted_count": attempted, + "acknowledged_this_run": succeeded} + except FeedbackSyncError as exc: + error = (str(exc) if str(exc) in {"privacy_blocked", "feedback_conflict", "authentication_failed"} + else "collector_unavailable") + except (OSError, sqlite3.Error, ValueError, TypeError, KeyError): + error = "invalid_local_event" + with self._db() as db: + if error is None: + db.execute("UPDATE feedback_outbox SET destination_hash=?,acknowledged=1," + "attempts=attempts+1,last_attempt=?,acknowledged_at=?,last_error=NULL " + "WHERE feedback_id=?", + (destination, time.time(), time.time(), event["feedback_id"])) + else: + # A failed concurrent attempt cannot revoke a valid ack. + db.execute("UPDATE feedback_outbox SET " + "destination_hash=CASE WHEN acknowledged=1 THEN destination_hash ELSE ? END," + "attempts=attempts+1,last_attempt=?," + "last_error=CASE WHEN acknowledged=1 AND destination_hash=? " + "THEN last_error ELSE ? END WHERE feedback_id=?", + (destination, time.time(), destination, error, event["feedback_id"])) + return {**self.sync_status(), "attempted_count": attempted, + "acknowledged_this_run": succeeded} + + def central_report(self, repository="", limit=100) -> dict: + from .feedback_sync import FeedbackSyncClient, FeedbackSyncError + + self._require_agreement("feedback_report") + if not isinstance(repository, str) or type(limit) is not int or not 1 <= limit <= 1000: + raise FeedbackError("report requires a repository string and limit between 1 and 1000") + if not self.sync_config: + raise FeedbackError("knowledge feedback collector is not configured correctly") + try: + return {**FeedbackSyncClient(self.sync_config, state_dir=self.state_dir).report(repository=repository.strip(), limit=limit), + "scope": "central"} + except FeedbackSyncError: + raise FeedbackError("knowledge feedback collector report is unavailable") from None + + def report_for_scope(self, repository="", limit=100, scope="auto") -> dict: + """A configured but unavailable collector must never appear as local totals.""" + if scope not in {"auto", "local", "central"}: + raise FeedbackError("report scope must be auto, local, or central") + if scope == "central" or (scope == "auto" and self.is_sync_configured): + return self.central_report(repository=repository, limit=limit) + return {**self.report(repository=repository, limit=limit), "scope": "local"} + + def report(self, repository="", limit=100) -> dict: + if not isinstance(repository, str) or type(limit) is not int or not 1 <= limit <= 1000: + raise FeedbackError("report requires a repository string and limit between 1 and 1000") + repository = repository.strip() + rows = self._inspection_rows("SELECT * FROM feedback_ratings" + (" WHERE repository=?" if repository else ""), + (repository,) if repository else ()) + grouped = {} + for row in rows: + rating, target = json.loads(row["rating"]), json.loads(row["target"]) + item = grouped.setdefault(row["target_id"], {**target, "positive_count": 0, + "negative_count": 0, "rating_count": 0, "net_score": 0}) + item["positive_count" if rating["score"] > 0 else "negative_count"] += 1 + item["rating_count"] += 1 + item["net_score"] += rating["score"] + for item in grouped.values(): + item["mean_score"] = item["net_score"] / item["rating_count"] + item["distinct_tasks"] = item["rating_count"] + targets = sorted(grouped.values(), key=lambda row: (row["repository"], row["path"], + row["kind"], row.get("block_id", ""), row["target_id"])) + return {"protocol": PROTOCOL, "repository": repository, "total_targets": len(targets), + "total_ratings": len(rows), "targets": targets[:limit], "truncated": len(targets) > limit} + + +def from_env() -> KnowledgeFeedbackStore: + return KnowledgeFeedbackStore.from_env() diff --git a/src/infermatrix_copilot/knowledge_service/feedback_http.py b/src/infermatrix_copilot/knowledge_service/feedback_http.py new file mode 100644 index 000000000..dc2f9ecb7 --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/feedback_http.py @@ -0,0 +1,236 @@ +"""Bounded bearer-authenticated HTTP transport for trusted feedback providers.""" +from __future__ import annotations + +import hashlib +import hmac +import ipaddress +import json +import re +import socket +import sqlite3 +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from urllib.parse import parse_qs, urlsplit + +from .agreement import AgreementRequiredError +from .feedback import FeedbackError +from .feedback_hub import FeedbackConflict, FeedbackHubStore + +MAX_BODY_BYTES = 4 * 1024 * 1024 +REQUEST_TIMEOUT = 15 + + +class _HTTPError(Exception): + def __init__(self, status, code, message): + self.status, self.code, self.message = status, code, message + + +def _pairs(pairs): + result = {} + for key, value in pairs: + if key in result: + raise ValueError("duplicate JSON key") + result[key] = value + return result + + +def _constant(value): + raise ValueError("nonfinite JSON number") + + +def _loopback(host): + if host.lower() == "localhost": + return True + try: + return ipaddress.ip_address(host).is_loopback + except ValueError: + return False + + +class FeedbackRequestHandler(BaseHTTPRequestHandler): + server_version = "InferMatrixFeedback/1" + sys_version = "" + + def setup(self): + self.request.settimeout(REQUEST_TIMEOUT) + super().setup() + + def log_message(self, format, *args): + # Tokens, task identifiers, query strings and evidence are never logged. + pass + + def _json(self, result, status=200): + body = json.dumps(result, ensure_ascii=False, allow_nan=False).encode("utf-8") + self.send_response(status) + self.send_header("Content-Type", "application/json; charset=utf-8") + self.send_header("Content-Length", str(len(body))) + self.send_header("Cache-Control", "no-store") + self.send_header("X-Content-Type-Options", "nosniff") + self.send_header("Connection", "close") + if status == 401: + self.send_header("WWW-Authenticate", 'Bearer realm="knowledge-feedback"') + self.end_headers() + self.close_connection = True + if self.command != "HEAD": + self.wfile.write(body) + + def send_error(self, code, message=None, explain=None): + # BaseHTTPRequestHandler otherwise interpolates malformed request text. + self._json({"error": {"code": "invalid_request", "message": "Invalid HTTP request"}}, code) + + def _authenticate(self): + headers = self.headers.get_all("Authorization", []) + candidate = "" + if len(headers) == 1: + scheme, separator, token = headers[0].partition(" ") + if scheme.lower() == "bearer" and separator and 32 <= len(token) <= 4096: + candidate = token + digest = hashlib.sha256(candidate.encode("utf-8")).digest() + matched = False + for expected in self.server.token_digests: + matched |= hmac.compare_digest(digest, expected) + if not candidate or not matched: + raise _HTTPError(401, "unauthenticated", "A valid provider bearer token is required") + + def _path(self): + if len(self.path) > 4096: + raise _HTTPError(400, "invalid_request", "Invalid request target") + parts = urlsplit(self.path) + if parts.scheme or parts.netloc or parts.fragment: + raise _HTTPError(400, "invalid_request", "Invalid request target") + query = parse_qs(parts.query, keep_blank_values=True, max_num_fields=8) + if any(len(values) != 1 for values in query.values()): + raise _HTTPError(400, "invalid_request", "Query parameters must not repeat") + return parts.path, {key: values[0] for key, values in query.items()} + + def _body(self): + lengths = self.headers.get_all("Content-Length", []) + if self.headers.get_all("Transfer-Encoding", []): + raise _HTTPError(400, "invalid_request", "Transfer encoding is not supported") + if not lengths: + raise _HTTPError(411, "length_required", "Content length is required") + if len(lengths) != 1 or not re.fullmatch(r"[0-9]{1,10}", lengths[0]): + raise _HTTPError(400, "invalid_request", "Invalid content length") + length = int(lengths[0]) + if length > MAX_BODY_BYTES: + raise _HTTPError(413, "body_too_large", "Feedback event exceeds the transport limit") + if self.headers.get_content_type() != "application/json": + raise _HTTPError(415, "unsupported_media_type", "Send an application/json request body") + try: + body = self.rfile.read(length) + if len(body) != length: + raise ValueError("short body") + result = json.loads(body.decode("utf-8"), object_pairs_hook=_pairs, parse_constant=_constant) + except (ValueError, UnicodeError, RecursionError) as exc: + raise _HTTPError(400, "invalid_request", "Invalid JSON request body") from exc + if not isinstance(result, dict): + raise _HTTPError(400, "invalid_request", "Feedback event must be a JSON object") + return result + + def _get(self): + path, query = self._path() + if path == "/healthz" and not query: + self._json({"ok": True}) + return + self._authenticate() + if path != "/v1/feedback/report": + raise _HTTPError(404, "not_found", "Route not found") + if set(query) - {"repo", "limit"}: + raise _HTTPError(400, "invalid_request", "Unknown report parameter") + raw_limit = query.get("limit", "100") + if not re.fullmatch(r"[0-9]{1,4}", raw_limit): + raise _HTTPError(400, "invalid_request", "Invalid report limit") + self._json(self.server.store.report(repository=query.get("repo", ""), limit=int(raw_limit))) + + def _post(self): + self._authenticate() # Authenticate before reading or parsing any body. + path, query = self._path() + if path != "/v1/feedback/events": + raise _HTTPError(404, "not_found", "Route not found") + if query: + raise _HTTPError(400, "invalid_request", "Event endpoint does not accept query parameters") + event = self._body() + if set(event) == {"receipt", "ratings"}: + raise AgreementRequiredError() + if set(event) != {"receipt", "ratings", "agreement"}: + raise _HTTPError(400, "invalid_feedback", "Event requires exactly receipt, ratings and agreement") + self._json(self.server.store.ingest(receipt=event["receipt"], ratings=event["ratings"], + agreement=event["agreement"])) + + def _run(self, action): + try: + action() + except _HTTPError as exc: + self._json({"error": {"code": exc.code, "message": exc.message}}, exc.status) + except AgreementRequiredError: + self._json({"error": {"code": "agreement_required", "message": + "A trusted provider must attest current user acceptance before uploading feedback."}}, 428) + except FeedbackConflict: + self._json({"error": {"code": "feedback_conflict", "message": "Feedback identity conflicts with an immutable earlier event"}}, 409) + except (FeedbackError, ValueError, TypeError, RecursionError): + self._json({"error": {"code": "invalid_feedback", "message": "Invalid feedback metadata or rating"}}, 400) + except (BrokenPipeError, ConnectionResetError): + pass + except TimeoutError: + self._json({"error": {"code": "request_timeout", "message": "Request timed out"}}, 408) + except (sqlite3.Error, OSError): + self._json({"error": {"code": "storage_unavailable", "message": "Feedback storage is unavailable"}}, 503) + except Exception: # noqa: BLE001 - private provider state must never enter HTTP errors. + self._json({"error": {"code": "internal_error", "message": "The request could not be completed"}}, 500) + + def do_GET(self): + self._run(self._get) + + def do_HEAD(self): + self._run(self._get) + + def do_POST(self): + self._run(self._post) + + +def create_server(store: FeedbackHubStore, token: str | tuple[str, ...], host="127.0.0.1", port=0, + public_url: str | None = None) -> ThreadingHTTPServer: + """Create a listener; remote bindings require an explicit HTTPS proxy origin. + + ``public_url`` declares the TLS reverse proxy deployment. This listener + itself speaks HTTP and must be reachable only by that proxy or loopback. + Tokens identify trusted provider operators and can attest arbitrary receipts. + Multiple tokens share one ledger and support credential rotation. + """ + tokens = (token,) if isinstance(token, str) else token + if (not isinstance(tokens, tuple) or not tokens + or any(not isinstance(item, str) or not 32 <= len(item) <= 4096 + or any(ord(char) < 33 or ord(char) > 126 for char in item) for item in tokens)): + raise ValueError("Configure a provider token of 32 to 4096 printable nonspace ASCII characters") + if not isinstance(host, str) or not host or type(port) is not int or not 0 <= port <= 65535: + raise ValueError("Invalid feedback listener address") + if public_url is not None: + parts = urlsplit(public_url) + try: + _ = parts.port + except ValueError as exc: + raise ValueError("Invalid feedback public URL") from exc + if (parts.scheme != "https" or not parts.hostname or parts.username or parts.password + or parts.path not in {"", "/"} or parts.query or parts.fragment): + raise ValueError("Feedback public URL must be an HTTPS origin") + elif not _loopback(host): + raise ValueError("A non-loopback listener requires an HTTPS reverse proxy public URL") + + class FeedbackServer(ThreadingHTTPServer): + daemon_threads = True + request_queue_size = 128 + + def handle_error(self, request, client_address): + # The stdlib default prints tracebacks containing request state. + pass + + if ":" in host: + class IPv6FeedbackServer(FeedbackServer): + address_family = socket.AF_INET6 + + server_class = IPv6FeedbackServer + else: + server_class = FeedbackServer + server = server_class((host, port), FeedbackRequestHandler) + server.store = store + server.token_digests = tuple(hashlib.sha256(item.encode()).digest() for item in tokens) + return server diff --git a/src/infermatrix_copilot/knowledge_service/feedback_hub.py b/src/infermatrix_copilot/knowledge_service/feedback_hub.py new file mode 100644 index 000000000..aa7e5e5e7 --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/feedback_hub.py @@ -0,0 +1,238 @@ +"""Shared feedback ledger for authenticated, trusted knowledge providers. + +An imported receipt is a provider attestation, not an independent proof of +delivery. Only the authenticated transport may expose ``ingest``: end users +must continue rating receipts issued by their own provider. Hash checks bind +all metadata to the existing knowledge-feedback/1 identities without inventing +a second version or deduplication protocol. +""" +from __future__ import annotations + +import hashlib +import json +import re +from pathlib import PurePosixPath + +from .agreement import validate_upload_attestation +from .feedback import PROTOCOL, FeedbackError, KnowledgeFeedbackStore, _digest, _json + +MAX_RECEIPT_BYTES = 1_500_000 +MAX_TARGETS = 4096 +_SHA256 = re.compile(r"[0-9a-f]{64}\Z") +_PIN = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z") + + +class FeedbackConflict(FeedbackError): + """An immutable task/target vote or receipt identity was reused differently.""" + + +def _fields(value, expected, name): + if not isinstance(value, dict) or set(value) != set(expected): + raise FeedbackError(f"{name} has an invalid schema") + + +def _string(value, name, maximum=512, *, empty=False): + if (not isinstance(value, str) or len(value) > maximum + or (not empty and not value) or value != value.strip() + or any(ord(char) < 32 or ord(char) == 127 for char in value)): + raise FeedbackError(f"{name} is invalid") + return value + + +def _sha(value, name, *, empty=False): + if not isinstance(value, str) or not ((empty and value == "") or _SHA256.fullmatch(value)): + raise FeedbackError(f"{name} must be a lowercase SHA256 digest") + return value + + +def _path(value): + _string(value, "document path", 1024) + path = PurePosixPath(value) + if (path.is_absolute() or "\\" in value or ":" in value + or any(part in {"", ".", ".."} for part in value.split("/")) + or path.suffix.casefold() != ".md"): + raise FeedbackError("document path must be a normalized relative Markdown path") + return value + + +def validate_receipt(receipt: dict) -> dict: + """Validate hashes, exact schemas and all available provenance bindings. + + Source text is deliberately absent. The authenticated provider is responsible + for checking that complete rule sections really reached the host agent. + """ + _fields(receipt, {"protocol", "delivery_id", "task_id", "repository", "snapshot", + "tree_sha256", "documents", "targets"}, "receipt") + if receipt["protocol"] != PROTOCOL: + raise FeedbackError("unsupported feedback protocol") + _string(receipt["task_id"], "task_id") + _string(receipt["repository"], "repository", 256) + _string(receipt["snapshot"], "snapshot") + _sha(receipt["tree_sha256"], "tree_sha256", empty=True) + _sha(receipt["delivery_id"], "delivery_id") + if (not isinstance(receipt["documents"], list) or len(receipt["documents"]) > 256 + or not isinstance(receipt["targets"], list) or len(receipt["targets"]) > MAX_TARGETS): + raise FeedbackError("receipt contains too many documents or targets") + if len(_json(receipt).encode("utf-8")) > MAX_RECEIPT_BYTES: + raise FeedbackError("receipt metadata is too large") + body = {key: value for key, value in receipt.items() if key != "delivery_id"} + if _digest(body) != receipt["delivery_id"]: + raise FeedbackError("delivery identity does not match receipt metadata") + + pages, fragments = {}, set() + delivered_chars = 0 + for document in receipt["documents"]: + _fields(document, {"path", "page_sha256", "delivered_sha256", "delivered_chars"}, "document") + path = _path(document["path"]) + _sha(document["page_sha256"], "page_sha256") + _sha(document["delivered_sha256"], "delivered_sha256") + if type(document["delivered_chars"]) is not int or not 1 <= document["delivered_chars"] <= 16_000_000: + raise FeedbackError("delivered_chars is invalid") + delivered_chars += document["delivered_chars"] + if delivered_chars > 16_000_000: + raise FeedbackError("delivered fragments exceed the delivery limit") + if path in pages and pages[path] != document["page_sha256"]: + raise FeedbackError("a document has inconsistent page versions") + pages[path] = document["page_sha256"] + identity = _digest(document) + if identity in fragments: + raise FeedbackError("receipt cannot repeat a delivered fragment") + fragments.add(identity) + if receipt["documents"] != sorted(receipt["documents"], key=lambda row: (row["path"], row["delivered_sha256"])): + raise FeedbackError("delivered fragments must use provider canonical ordering") + + target_ids, document_targets = set(), set() + common = {"repository", "path", "kind", "content_sha256", "target_id", "page_sha256", "snapshot"} + for target in receipt["targets"]: + if not isinstance(target, dict) or target.get("kind") not in ("document", "rule"): + raise FeedbackError("target kind is invalid") + rule = target["kind"] == "rule" + _fields(target, common | ({"unit_id", "block_id", "upstream_pins"} if rule else set()), "target") + path = _path(target["path"]) + for field in ("target_id", "page_sha256", "content_sha256"): + _sha(target[field], field) + if (target["repository"] != receipt["repository"] or target["snapshot"] != receipt["snapshot"] + or pages.get(path) != target["page_sha256"]): + raise FeedbackError("target provenance does not match its delivery") + version = {key: target[key] for key in ("repository", "path", "kind", "content_sha256")} + if rule: + _sha(target["unit_id"], "unit_id") + _string(target["block_id"], "block_id") + pins = target["upstream_pins"] + if (not isinstance(pins, list) or len(pins) > 256 + or any(not isinstance(pin, str) or not _PIN.fullmatch(pin) for pin in pins) + or pins != sorted(set(pins))): + raise FeedbackError("upstream_pins must be sorted unique source digests") + parts = PurePosixPath(path).parts + owner_repo = parts[1] if len(parts) > 2 and parts[0] == "repos" else "general" + expected_unit = hashlib.sha256("\0".join((owner_repo, path, target["block_id"], "rule")).encode()).hexdigest() + if target["unit_id"] != expected_unit: + raise FeedbackError("rule identity does not match its owner and block") + version.update({key: target[key] for key in ("unit_id", "block_id", "upstream_pins")}) + else: + if target["content_sha256"] != target["page_sha256"]: + raise FeedbackError("document version does not match its page") + document_targets.add(path) + if _digest(version) != target["target_id"]: + raise FeedbackError("target identity does not match its content version") + if target["target_id"] in target_ids: + raise FeedbackError("receipt cannot repeat a target") + target_ids.add(target["target_id"]) + if document_targets != set(pages): + raise FeedbackError("each delivered document requires its document target") + if receipt["targets"] != sorted(receipt["targets"], key=lambda row: ( + row["path"], row["kind"], row.get("block_id", ""), row["target_id"])): + raise FeedbackError("targets must use provider canonical ordering") + # Return an owned copy so caller mutation cannot race persistence. + return json.loads(_json(receipt)) + + +class FeedbackHubStore(KnowledgeFeedbackStore): + """One durable team ledger, with global (task_id, target_id) deduplication.""" + + _feedback_sync_enabled = False + + def ingest(self, *, receipt: dict, ratings: list[dict], agreement: dict | None = None) -> dict: + agreement = validate_upload_attestation(agreement) + receipt = validate_receipt(receipt) + if not isinstance(ratings, list) or len(ratings) > 256: + raise FeedbackError("ratings must be a list of at most 256 entries") + for rating in ratings: + _fields(rating, {"target_id", "score", "used", "reason", "evidence"}, "rating") + if len(_json(ratings).encode("utf-8")) > 3_000_000: + raise FeedbackError("rating metadata is too large") + from .learning_privacy import LearningPrivacyError, validate_distilled_text + + try: + validate_distilled_text(receipt) + validate_distilled_text(ratings) + except LearningPrivacyError as exc: + raise FeedbackError("feedback metadata requires redaction before upload") from exc + # A trusted, structurally valid receipt can remain after an invalid batch; + # record() applies every vote in a separate single atomic transaction. + encoded = _json(receipt) + with self._db() as db: + db.executescript(""" + CREATE TABLE IF NOT EXISTS feedback_agreements ( + acceptance_id TEXT PRIMARY KEY, attestation TEXT NOT NULL); + CREATE TABLE IF NOT EXISTS feedback_delivery_agreements ( + delivery_id TEXT NOT NULL, acceptance_id TEXT NOT NULL, + PRIMARY KEY(delivery_id, acceptance_id)); + """) + db.execute("BEGIN IMMEDIATE") + attestation = _json(agreement) + prior = db.execute("SELECT attestation FROM feedback_agreements WHERE acceptance_id=?", + (agreement["acceptance_id"],)).fetchone() + if prior and prior["attestation"] != attestation: + raise FeedbackConflict("agreement identity conflicts with its earlier attestation") + row = db.execute("SELECT payload FROM feedback_deliveries WHERE id=?", (receipt["delivery_id"],)).fetchone() + if row and row["payload"] != encoded: + raise FeedbackConflict("delivery identity conflicts with its earlier receipt") + db.execute("INSERT OR IGNORE INTO feedback_agreements VALUES (?,?)", + (agreement["acceptance_id"], attestation)) + db.execute("INSERT OR IGNORE INTO feedback_deliveries VALUES (?,?,?,?)", + (receipt["delivery_id"], receipt["task_id"], receipt["repository"], encoded)) + db.execute("INSERT OR IGNORE INTO feedback_delivery_agreements VALUES (?,?)", + (receipt["delivery_id"], agreement["acceptance_id"])) + try: + return self.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], ratings=ratings) + except FeedbackError as exc: + if str(exc) == "feedback for this task and content version is immutable": + raise FeedbackConflict(str(exc)) from exc + raise + + def report(self, repository="", limit=100) -> dict: + if not isinstance(repository, str) or type(limit) is not int or not 1 <= limit <= 1000: + raise FeedbackError("report requires a repository string and limit between 1 and 1000") + repository = repository.strip() + _string(repository, "repository", 256, empty=True) + where, parameters = (" WHERE repository=?", (repository,)) if repository else ("", ()) + with self._db() as db: + db.execute("BEGIN") + counts = db.execute("SELECT COUNT(*) AS ratings, COUNT(DISTINCT target_id) AS targets " + "FROM feedback_ratings" + where, parameters).fetchone() + rows = db.execute(""" + WITH grouped AS ( + SELECT target_id, MIN(rowid) AS representative, + COUNT(*) AS rating_count, + SUM(CASE WHEN json_extract(rating,'$.score')=1 THEN 1 ELSE 0 END) AS positive_count, + SUM(CASE WHEN json_extract(rating,'$.score')=-1 THEN 1 ELSE 0 END) AS negative_count, + SUM(json_extract(rating,'$.score')) AS net_score + FROM feedback_ratings + """ + where + """ + GROUP BY target_id + ) + SELECT r.target, g.rating_count, g.positive_count, g.negative_count, g.net_score + FROM grouped g JOIN feedback_ratings r ON r.rowid=g.representative + ORDER BY r.repository, json_extract(r.target,'$.path'), json_extract(r.target,'$.kind'), + COALESCE(json_extract(r.target,'$.block_id'),''), r.target_id + LIMIT ? + """, (*parameters, limit)).fetchall() + targets = [] + for row in rows: + item = json.loads(row["target"]) + item.update({key: row[key] for key in ("rating_count", "positive_count", "negative_count", "net_score")}) + item.update(mean_score=row["net_score"] / row["rating_count"], distinct_tasks=row["rating_count"]) + targets.append(item) + return {"protocol": PROTOCOL, "repository": repository, "total_targets": counts["targets"], + "total_ratings": counts["ratings"], "targets": targets, "truncated": counts["targets"] > limit} diff --git a/src/infermatrix_copilot/knowledge_service/feedback_server_cli.py b/src/infermatrix_copilot/knowledge_service/feedback_server_cli.py new file mode 100644 index 000000000..99cd7fd76 --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/feedback_server_cli.py @@ -0,0 +1,46 @@ +"""Standalone shared feedback service, without model or knowledge dependencies.""" +from __future__ import annotations + +import argparse +import json +import os +import sqlite3 +import sys +from pathlib import Path + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(prog="infermatrix-feedback", description="Serve the shared trusted-provider knowledge feedback ledger") + parser.add_argument("--host", default="127.0.0.1") + parser.add_argument("--port", type=int, default=8788) + parser.add_argument("--state-dir", default=os.environ.get("KNOWLEDGE_FEEDBACK_SERVER_STATE_DIR", "")) + parser.add_argument("--public-url", help="HTTPS reverse proxy origin; required for non-loopback bindings") + args = parser.parse_args(argv) + from .feedback_http import create_server + from .feedback_hub import FeedbackHubStore + + server = None + try: + state = Path(args.state_dir).expanduser() if args.state_dir else Path.home() / ".infermatrix-copilot" / "feedback-server" + store = FeedbackHubStore(state) + server = create_server(store, token=os.environ.get("KNOWLEDGE_FEEDBACK_SERVER_TOKEN", ""), + host=args.host, port=args.port, public_url=args.public_url) + # Fail startup on storage errors, before reporting readiness. + store.report(limit=1) + print(json.dumps({"service": "knowledge-feedback/1", "host": args.host, + "port": server.server_address[1]}), flush=True) + server.serve_forever(poll_interval=0.25) + return 0 + except KeyboardInterrupt: + return 0 + except (ValueError, OSError, sqlite3.Error): + # Configuration errors never include environment values or credentials. + print(json.dumps({"error": {"code": "startup_failed", "message": "Check feedback token, listener and state configuration"}}), file=sys.stderr) + return 2 + finally: + if server is not None: + server.server_close() + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/infermatrix_copilot/knowledge_service/feedback_sync.py b/src/infermatrix_copilot/knowledge_service/feedback_sync.py new file mode 100644 index 000000000..c5824d95c --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/feedback_sync.py @@ -0,0 +1,273 @@ +"""Bounded, authenticated transport for the knowledge feedback collector. + +Credentials are operator configuration, never part of receipts or the outbox. +The caller commits local feedback before using this transport. +""" +from __future__ import annotations + +import hashlib +import ipaddress +import json +import math +import re +import socket +import time +from dataclasses import dataclass, field +from urllib.error import HTTPError +from urllib.parse import urlencode, urlsplit +from urllib.request import HTTPRedirectHandler, ProxyHandler, Request, build_opener + +from .agreement import AgreementRequiredError, AgreementStore + +MAX_MESSAGE_BYTES = 4 * 1024 * 1024 + + +class FeedbackSyncError(ValueError): + """A deliberately sanitized transport or configuration failure.""" + + +class _NoRedirect(HTTPRedirectHandler): + def redirect_request(self, req, fp, code, msg, headers, newurl): + return None + + +def _loopback(host: str) -> bool: + try: + return ipaddress.ip_address(host).is_loopback + except ValueError: + return host == "localhost" + + +@dataclass(frozen=True) +class FeedbackSyncConfig: + url: str + token: str = field(repr=False) + timeout_seconds: float = 5.0 + + def __post_init__(self): + try: + parts = urlsplit(self.url) + if (parts.scheme not in {"https", "http"} or not parts.hostname + or parts.username is not None or parts.password is not None + or parts.query or parts.fragment or "?" in self.url or "#" in self.url + or any(char.isspace() for char in self.url) or "\\" in self.url + or "%" in parts.hostname or parts.port == 0 + or (parts.scheme == "http" and not _loopback(parts.hostname))): + raise ValueError + if (not isinstance(self.token, str) or not 32 <= len(self.token) <= 4096 + or any(not 33 <= ord(char) <= 126 for char in self.token)): + raise ValueError + if (isinstance(self.timeout_seconds, bool) + or not math.isfinite(float(self.timeout_seconds)) + or not 0.1 <= float(self.timeout_seconds) <= 30): + raise ValueError + except (ValueError, TypeError, AttributeError) as exc: + raise FeedbackSyncError("invalid knowledge feedback collector configuration") from exc + object.__setattr__(self, "url", self.url.rstrip("/")) + object.__setattr__(self, "timeout_seconds", float(self.timeout_seconds)) + + @classmethod + def from_environment(cls, environ: dict[str, str]): + url = environ.get("KNOWLEDGE_FEEDBACK_URL", "").strip() + token = environ.get("KNOWLEDGE_FEEDBACK_TOKEN", "") + if not url and not token: + return None + return cls(url, token, environ.get("KNOWLEDGE_FEEDBACK_TIMEOUT_SECONDS", "5")) + + +def _no_duplicate_keys(pairs): + result = {} + for key, value in pairs: + if key in result: + raise ValueError("duplicate JSON key") + result[key] = value + return result + + +def _encoded(value) -> bytes: + return json.dumps(value, sort_keys=True, separators=(",", ":"), + ensure_ascii=False, allow_nan=False).encode("utf-8") + + +class FeedbackSyncClient: + def __init__(self, config: FeedbackSyncConfig, *, state_dir=None): + self.config = config + self.state_dir = state_dir + + def _agreement(self): + return AgreementStore.from_env(state_dir=self.state_dir, feedback_url=self.config.url) + + def _request(self, path: str, payload=None) -> dict: + agreement = self._agreement() + agreement.require("feedback_sync" if payload is not None else "feedback_report") + if payload is not None: + from .learning_privacy import LearningPrivacyError, validate_distilled_text + + payload = {**payload, "agreement": agreement.attestation()} + try: + validate_distilled_text(payload) + except LearningPrivacyError: + raise FeedbackSyncError("privacy_blocked") from None + config = self.config + try: + parts = urlsplit(config.url) + # Do not permit an HTTP localhost alias to resolve off the machine. + if parts.scheme == "http" and parts.hostname == "localhost": + addresses = socket.getaddrinfo("localhost", parts.port or 80, + type=socket.SOCK_STREAM) + if not addresses or any(not ipaddress.ip_address(row[4][0]).is_loopback + for row in addresses): + raise ValueError + data = None if payload is None else _encoded(payload) + if data is not None and len(data) > MAX_MESSAGE_BYTES: + raise ValueError + destination_url = config.url + if parts.scheme == "http" and parts.hostname == "localhost": + # Connect to the already checked literal address, avoiding a + # second DNS resolution between validation and connection. + address = addresses[0][4][0] + host = "[" + address + "]" if ":" in address else address + authority = host + (":" + str(parts.port) if parts.port else "") + destination_url = parts._replace(netloc=authority).geturl() + request = Request(destination_url + path, data=data, + headers={"Authorization": "Bearer " + config.token, + "Accept": "application/json", + "Content-Type": "application/json"}, + method="GET" if data is None else "POST") + # Disallow environment proxy routing and all redirects, so the token + # is delivered only to the configured origin. HTTPS uses normal + # stdlib certificate and hostname verification. + opener = build_opener(ProxyHandler({}), _NoRedirect()) + deadline = time.monotonic() + config.timeout_seconds + with opener.open(request, timeout=config.timeout_seconds) as response: + if response.status != 200: + raise ValueError + content_type = response.headers.get_content_type() + if content_type != "application/json": + raise ValueError + length = response.headers.get("Content-Length") + if length is not None and (int(length) < 0 or int(length) > MAX_MESSAGE_BYTES): + raise ValueError + chunks, size = [], 0 + while True: + if time.monotonic() >= deadline: + raise TimeoutError + chunk = response.read1(min(65536, MAX_MESSAGE_BYTES + 1 - size)) + if not chunk: + break + size += len(chunk) + if size > MAX_MESSAGE_BYTES: + raise ValueError + chunks.append(chunk) + result = json.loads(b"".join(chunks).decode("utf-8"), + object_pairs_hook=_no_duplicate_keys, + parse_constant=lambda _: (_ for _ in ()).throw(ValueError())) + if not isinstance(result, dict): + raise TypeError + return result + except HTTPError as exc: + status = exc.code + exc.close() + if status == 409: + raise FeedbackSyncError("feedback_conflict") from None + if status in (401, 403): + raise FeedbackSyncError("authentication_failed") from None + if status == 428: + raise AgreementRequiredError() from None + raise FeedbackSyncError("knowledge feedback collector request failed") from None + except Exception: # noqa: BLE001 - transport errors must never echo private endpoint data + # URLs, response bodies and exception details may contain secrets. + raise FeedbackSyncError("knowledge feedback collector request failed") from None + + def send(self, *, receipt: dict, rating: dict, target: dict, feedback_id: str) -> None: + from .learning_privacy import LearningPrivacyError, validate_distilled_text + + agreement = self._agreement() + agreement.require("feedback_sync") + event = {"receipt": receipt, "ratings": [rating], "agreement": agreement.attestation()} + try: + validate_distilled_text(event) + except LearningPrivacyError: + raise FeedbackSyncError("privacy_blocked") from None + actual = self._request("/v1/feedback/events", event) + expected = {"task_id": receipt["task_id"], "delivery_id": receipt["delivery_id"], + "ratings": [{**rating, "feedback_id": feedback_id, "target": target}]} + try: + # A global duplicate can retain the first provider's page/snapshot + # provenance. All identity/version fields and the canonical vote + # must still agree exactly; provenance need not match that provider. + actual_ratings = actual["ratings"] + if len(actual_ratings) != 1 or not isinstance(actual_ratings[0], dict): + raise ValueError + actual_target = actual_ratings[0]["target"] + version_fields = ("target_id", "repository", "path", "kind", "content_sha256", + "unit_id", "block_id", "upstream_pins") + wanted_target = {key: target[key] for key in version_fields if key in target} + returned_target = {key: actual_target[key] for key in version_fields if key in actual_target} + normalized = {"task_id": actual["task_id"], "delivery_id": actual["delivery_id"], + "ratings": [{**actual_ratings[0], "target": returned_target}]} + expected["ratings"][0]["target"] = wanted_target + matches = _encoded(normalized) == _encoded(expected) + except (TypeError, ValueError, KeyError): + matches = False + if not matches: + raise FeedbackSyncError("knowledge feedback collector acknowledgement did not match") + + def report(self, *, repository: str, limit: int) -> dict: + result = self._request("/v1/feedback/report?" + urlencode({"repo": repository, "limit": limit})) + # Never treat an error or arbitrary response as an empty team report. + if (result.get("protocol") != "knowledge-feedback/1" + or result.get("repository") != repository + or type(result.get("total_targets")) is not int or result["total_targets"] < 0 + or type(result.get("total_ratings")) is not int or result["total_ratings"] < 0 + or not isinstance(result.get("targets"), list) or len(result["targets"]) > limit + or type(result.get("truncated")) is not bool): + raise FeedbackSyncError("knowledge feedback collector report is invalid") + try: + targets = result["targets"] + total_targets, total_ratings = result["total_targets"], result["total_ratings"] + if (len(targets) != min(total_targets, limit) + or result["truncated"] != (total_targets > limit)): + raise ValueError + seen, counted = set(), 0 + for target in targets: + if not isinstance(target, dict): + raise TypeError + for key in ("repository", "path", "content_sha256", "target_id"): + if not isinstance(target.get(key), str) or not target[key]: + raise ValueError + if (repository and target["repository"] != repository + or target["target_id"] in seen + or not re.fullmatch(r"[0-9a-f]{64}", target["content_sha256"]) + or target.get("kind") not in {"rule", "document"}): + raise ValueError + version = {key: target[key] for key in ("repository", "path", "kind", "content_sha256")} + if target["kind"] == "rule": + for key in ("unit_id", "block_id"): + if not isinstance(target.get(key), str) or not target[key]: + raise ValueError + version[key] = target[key] + pins = target["upstream_pins"] + if not isinstance(pins, list) or any(not isinstance(pin, str) for pin in pins) or pins != sorted(pins): + raise ValueError + version["upstream_pins"] = pins + if hashlib.sha256(_encoded(version)).hexdigest() != target["target_id"]: + raise ValueError + seen.add(target["target_id"]) + for key in ("positive_count", "negative_count", "rating_count", "distinct_tasks"): + if type(target.get(key)) is not int or target[key] < 0: + raise ValueError + positive, negative, count = target["positive_count"], target["negative_count"], target["rating_count"] + if (count <= 0 or count != positive + negative or target["distinct_tasks"] != count + or type(target.get("net_score")) is not int or target["net_score"] != positive - negative + or type(target.get("mean_score")) not in (int, float) + or not math.isfinite(target["mean_score"]) + or not math.isclose(target["mean_score"], (positive - negative) / count, + rel_tol=1e-12, abs_tol=1e-12)): + raise ValueError + counted += count + if counted > total_ratings or (not result["truncated"] and counted != total_ratings): + raise ValueError + except (ValueError, TypeError, KeyError, OverflowError): + raise FeedbackSyncError("knowledge feedback collector report is invalid") from None + return result diff --git a/src/infermatrix_copilot/knowledge_service/learning.py b/src/infermatrix_copilot/knowledge_service/learning.py new file mode 100644 index 000000000..f06f3bbee --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/learning.py @@ -0,0 +1,512 @@ +"""Durable host-model task learning; raw chat is never an API input. + +The host distills its own local conversation into bounded positive/negative +lessons. This service freezes owner pages, validates the host's rule proposal, +and applies it only in a provider-owned worktree. It never calls a model. +""" + +from __future__ import annotations + +import hashlib +import json +import os +import re +import sqlite3 +import subprocess +from contextlib import contextmanager +from datetime import UTC, datetime +from pathlib import Path, PurePosixPath + +from ..sdk.v1.models import ( + KnowledgeEvidenceBatch, + KnowledgeEvidenceEvent, + RepositoryRef, +) +from .curation import KnowledgeCurator, KnowledgeValidatorError +from .learning_publication import LearningPublicationError, LearningPublisher +from .lifecycle import Page + + +def _json(value): + return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + + +def _digest(value): + return hashlib.sha256(_json(value).encode()).hexdigest() + + +class TaskLearningError(ValueError): + """The task identity, input, or frozen knowledge packet is invalid.""" + + +class TaskLearningService: + MAX_LESSONS = 20 + + def __init__(self, state_dir, workspace_root=None): + self.state_dir = Path(state_dir).expanduser().resolve() + from .learning_config import learning_environment + + configured = workspace_root or learning_environment().get("KNOWLEDGE_LEARNING_WORKSPACE") + # A source checkout fallback is allowed; installed package data is not + # a writable canonical knowledge authority. + self.workspace_root = Path(configured).expanduser().resolve() if configured else Path(__file__).resolve().parents[3] + if self.state_dir.is_relative_to(self.workspace_root / "knowledge"): + raise TaskLearningError("learning runtime state must live outside the knowledge tree") + self.database = self.state_dir / "task-learning.sqlite" + + def _require_agreement(self, action): + from .agreement import AgreementStore + + return AgreementStore.from_env(state_dir=self.state_dir).require(action) + + @classmethod + def from_env(cls, workspace_root=None): + from .learning_config import learning_environment + + state = learning_environment().get("KNOWLEDGE_LEARNING_STATE_DIR") + return cls(Path(state) if state else Path.home() / ".infermatrix-copilot/learning", + workspace_root=workspace_root) + + @contextmanager + def _db(self): + self.state_dir.mkdir(parents=True, exist_ok=True, mode=0o700) + db = sqlite3.connect(self.database, timeout=60) + try: + self.database.chmod(0o600) + db.execute("PRAGMA busy_timeout=60000") + with db: + db.execute("CREATE TABLE IF NOT EXISTS learning_tasks (task_key TEXT PRIMARY KEY, packet TEXT NOT NULL, " + "packet_digest TEXT NOT NULL, proposals TEXT, proposals_digest TEXT, result TEXT NOT NULL)") + yield db + finally: + db.close() + + @contextmanager + def _task_lock(self, key): + """Serialize one task across processes without blocking other tasks. + + The OS releases this lock on interruption. Durable preparation and + application receipts remain the authority when the next caller resumes. + Lock files are never unlinked, which would let waiters lock different + inodes for the same task. + """ + from ..trace_store import file_lock + + with file_lock(self.state_dir / "locks" / f"task-{key}.lock", timeout=60) as held: + if not held: + raise TaskLearningError("learning task is busy; retry the same task") + yield + + @staticmethod + def _task(task_id): + if not isinstance(task_id, str) or not task_id.strip() or len(task_id) > 256: + raise TaskLearningError("task_id must contain 1..256 characters") + return _digest(task_id) + + @staticmethod + def _git(root, *args): + try: + done = subprocess.run(["git", "-C", str(root), *args], text=True, capture_output=True, + timeout=120, check=False) + except (OSError, subprocess.TimeoutExpired) as exc: + raise TaskLearningError(f"learning workspace Git unavailable ({type(exc).__name__})") from exc + if done.returncode: + raise TaskLearningError(f"learning workspace Git {args[0]} failed") + return done.stdout.strip() + + def _source(self): + root = self.workspace_root + if self._git(root, "rev-parse", "--show-toplevel") != str(root): + raise TaskLearningError("learning workspace must be the root of a governed Git checkout") + if not (root / "knowledge/AGENTS.md").is_file(): + raise TaskLearningError("learning workspace has no governed knowledge tree") + if self.state_dir.is_relative_to(root / "knowledge"): + raise TaskLearningError("learning runtime state must live outside the knowledge tree") + return root + + def _verify_repository(self, source, base, repository): + """Check the committed slice before persisting a new task identity.""" + try: + kind = self._git(source, "cat-file", "-t", f"{base}:knowledge/repos/{repository}") + except TaskLearningError as exc: + raise TaskLearningError("repository has no verified knowledge slice") from exc + if kind != "tree": + raise TaskLearningError("repository has no verified knowledge slice") + + def _correct_invalid_repository(self, packet, result, row, identity): + """Recover only the exact invalid-slice preparation left by old versions. + + A repository typo used to be detected after persisting identity and + creating a worktree. Reuse that worktree only when no proposal or + application exists and it still proves to be the pristine frozen base. + """ + old_identity = packet.get("identity", {}) + old_repository = old_identity.get("repository") + if (result != {"status": "preparing"} or packet.get("packet_digest") != "" + or row[2] is not None or row[3] is not None or row[4] != "" + or not isinstance(old_repository, str) + or not re.fullmatch(r"[a-z0-9][a-z0-9._-]*", old_repository) + or {**old_identity, "repository": identity["repository"]} != identity + or packet.get("repository") != old_repository + or packet.get("task_key") != identity["task_key"] + or packet.get("source_pin") != identity["source_pin"] + or packet.get("lessons") != identity["lessons"] + or any(packet.get(field) for field in ("page_hashes", "existing_rules", "prompt"))): + return None + base = packet.get("base_sha", "") + if not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", base): + return None + source = self._source() + if packet.get("source_workspace") != str(source): + return None + # ls-tree distinguishes a genuinely absent path from a Git failure; + # transient failures must never authorize replacing task identity. + if self._git(source, "ls-tree", base, "--", f"knowledge/repos/{old_repository}"): + return None + self._verify_repository(source, base, identity["repository"]) + checkout = self._checkout(identity["task_key"]) + if checkout.parent.is_symlink() or (checkout.parent.exists() and ( + not checkout.parent.is_dir() or any(path.name != "checkout" for path in checkout.parent.iterdir()))): + raise TaskLearningError("interrupted preparation has unknown files; preserve it for inspection") + if checkout.exists() or checkout.is_symlink(): + self._verify_preparing_checkout(packet, checkout) + return {**packet, "repository": identity["repository"], "identity": identity} + + @classmethod + def _lessons(cls, lessons): + if not isinstance(lessons, list) or len(lessons) > cls.MAX_LESSONS: + raise TaskLearningError(f"lessons must be a list of at most {cls.MAX_LESSONS} distilled lessons") + result = [] + for item in lessons: + if not isinstance(item, dict) or set(item) - {"outcome", "summary", "evidence", "changed_paths", "title"}: + raise TaskLearningError("lesson fields must contain distilled outcomes, never a transcript") + outcome, summary = item.get("outcome"), item.get("summary") + if not isinstance(outcome, str) or outcome not in {"positive", "negative"} or not isinstance(summary, str) or not 1 <= len(summary.strip()) <= 4000: + raise TaskLearningError("each lesson needs a positive/negative outcome and a bounded summary") + evidence, paths = item.get("evidence", []), item.get("changed_paths", []) + title = item.get("title", "Task maintenance lesson") + if not isinstance(title, str) or not 1 <= len(title.strip()) <= 200: + raise TaskLearningError("lesson title must contain 1..200 characters") + if not isinstance(evidence, list) or len(evidence) > 10 or any(not isinstance(v, str) or not 1 <= len(v) <= 1000 for v in evidence): + raise TaskLearningError("lesson evidence must contain at most ten bounded references") + if not isinstance(paths, list) or len(paths) > 30: + raise TaskLearningError("changed_paths must be a bounded list") + for value in paths: + if (not isinstance(value, str) or not value or len(value) > 500 or "\\" in value + or PurePosixPath(value).is_absolute() or ".." in PurePosixPath(value).parts + or re.match(r"^[A-Za-z]:", value) or "\0" in value): + raise TaskLearningError("changed_paths must be repository-relative") + result.append({"outcome": outcome, "summary": summary.strip(), "evidence": evidence, + "changed_paths": paths, "title": title.strip()}) + return result + + def _checkout(self, key): + return self.state_dir / "tasks" / key / "checkout" + + @staticmethod + def _save(path, value): + temporary = path.with_suffix(".tmp") + with temporary.open("w", encoding="utf-8") as handle: + handle.write(_json(value)) + handle.flush() + os.fsync(handle.fileno()) + temporary.replace(path) + + def _clean(self, checkout): + return not self._git(checkout, "status", "--porcelain", "--untracked-files=all") + + def _batch(self, packet): + events = tuple(KnowledgeEvidenceEvent(event_id=f"lesson-{i}", source_kind="host_task_learning", + source_reference=packet["source_references"][i], title=lesson["title"], + summary=lesson["summary"], changed_paths=tuple(lesson["changed_paths"]), + attributes={"outcome": lesson["outcome"], "evidence": lesson["evidence"], + "source_pin": packet["source_pin"]}) for i, lesson in enumerate(packet["lessons"])) + return KnowledgeEvidenceBatch(batch_id="chat-" + packet["task_key"][:32], + repository=RepositoryRef(packet["repository"]), events=events) + + @staticmethod + def _existing_rules(curator, repository): + """Summaries aid host semantic comparison; they are not duplicate proofs.""" + remaining, documents = 24000, [] + for document in curator.catalog(repository): + text = curator._document_path(document).read_text(encoding="utf-8") + rules = Page.parse(text).rules() + summaries, spent = [], 0 + for rule in rules: + summary = rule.body_without_footer[:400] + cost = len(summary) + if spent + cost > 2400 or cost > remaining: + break + summaries.append({"rule_id": rule.rule_id, "summary": summary, + "truncated": len(summary) < len(rule.body_without_footer)}) + spent += cost + remaining -= cost + documents.append({"document_id": document, "sha256": hashlib.sha256(text.encode()).hexdigest(), + "rules": summaries, "total_rules": len(rules), + "truncated": len(summaries) < len(rules)}) + return documents + + def prepare(self, task_id, repository, source_pin, lessons): + self._require_agreement("learning_prepare") + key, lessons = self._task(task_id), self._lessons(lessons) + from .learning_privacy import validate_distilled_text + validate_distilled_text(lessons) + if not isinstance(repository, str) or not re.fullmatch(r"[a-z0-9][a-z0-9._-]*", repository): + raise TaskLearningError("repository must be one verified knowledge repository slug") + if not isinstance(source_pin, str) or not re.fullmatch(r"(?:[0-9a-f]{40}|[0-9a-f]{64})", source_pin): + raise TaskLearningError("source_pin must be a full lowercase Git commit") + identity = {"task_key": key, "repository": repository, "source_pin": source_pin, "lessons": lessons} + with self._task_lock(key): + self._require_agreement("learning_prepare") + with self._db() as db: + row = db.execute("SELECT packet,result,proposals,proposals_digest,packet_digest " + "FROM learning_tasks WHERE task_key=?", (key,)).fetchone() + if row: + packet, result = json.loads(row[0]), json.loads(row[1]) + if packet["identity"] != identity: + packet = self._correct_invalid_repository(packet, result, row, identity) + if packet is None: + raise TaskLearningError("task already has a different learning packet") + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + db.execute("UPDATE learning_tasks SET packet=? WHERE task_key=?", (_json(packet), key)) + if result["status"] != "preparing": + return self._public(packet, result) + else: + packet = {**identity, "task_id": task_id, "identity": identity, "source_references": [ + f"chat-task:{key[:24]}:{i}" for i in range(len(lessons))], + "base_sha": "", "page_hashes": {}, "existing_rules": [], "prompt": "", "packet_digest": ""} + if lessons: + source = self._source() + base = self._git(source, "rev-parse", "HEAD") + self._git(source, "cat-file", "-e", f"{base}:knowledge/AGENTS.md") + self._verify_repository(source, base, repository) + packet.update(base_sha=base, source_workspace=str(source)) + # Persist intent before creating the worktree; an interrupted + # prepare can reuse only this exact pristine detached checkout. + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + db.execute("INSERT INTO learning_tasks VALUES (?,?,?,?,?,?)", + (key, _json(packet), "", None, None, _json({"status": "preparing"}))) + if lessons: + self._verify_repository(Path(packet["source_workspace"]), packet["base_sha"], repository) + self._finish_prepare(packet) + packet.pop("packet_digest") + packet["packet_digest"] = _digest(packet) + result = {"status": "prepared" if lessons else "no_op"} + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + db.execute("UPDATE learning_tasks SET packet=?,packet_digest=?,result=? WHERE task_key=?", + (_json(packet), packet["packet_digest"], _json(result), key)) + return self._public(packet, result) + + def _finish_prepare(self, packet): + self._require_agreement("learning_prepare") + checkout = self._checkout(packet["task_key"]) + source, base = Path(packet["source_workspace"]), packet["base_sha"] + checkout.parent.mkdir(parents=True, exist_ok=True, mode=0o700) + if not checkout.exists(): + self._git(source, "worktree", "add", "--detach", str(checkout), base) + self._verify_preparing_checkout(packet, checkout) + if not (checkout / "knowledge/repos" / packet["repository"]).is_dir(): + raise TaskLearningError("repository has no verified knowledge slice") + curator = KnowledgeCurator(checkout) + batch = self._batch(packet) + existing = self._existing_rules(curator, batch.repository) + packet.update(page_hashes={page: hashlib.sha256((checkout / page).read_bytes()).hexdigest() + for page in curator.catalog(batch.repository)}, + existing_rules=existing, + prompt=curator.build_prompt(batch) + "\nFrozen existing owner rules (bounded summaries):\n" + + _json(existing) + "\nCompare meanings and reuse existing rules; propose no duplicate. " + "Truncation is explicit: if omitted context leaves a possible duplicate unresolved, return no rule. " + "These summaries do not mechanically prove semantic uniqueness.\n" + "Preserve positive practices as well as lessons from failures. " + "Return executable owner rules only. Never quote local chat, paths, secrets, or personal data. " + "Cite only the opaque source_reference values; evidence is private drafting context.\n") + + def _verify_preparing_checkout(self, packet, checkout): + source, base = Path(packet["source_workspace"]), packet["base_sha"] + expected_common = self._git(source, "rev-parse", "--path-format=absolute", "--git-common-dir") + if (checkout.is_symlink() + or self._git(checkout, "rev-parse", "--show-toplevel") != str(checkout) + or self._git(checkout, "rev-parse", "--path-format=absolute", "--git-common-dir") != expected_common + or self._git(checkout, "rev-parse", "HEAD") != base + or self._git(checkout, "rev-parse", "--abbrev-ref", "HEAD") != "HEAD" + or not self._clean(checkout)): + raise TaskLearningError("interrupted preparation workspace differs; preserve it for inspection") + + def _public(self, packet, result): + return {"task_id": packet["task_id"], "task_key": packet["task_key"], "packet_digest": packet["packet_digest"], + "repository": packet["repository"], "source_pin": packet["source_pin"], + "source_references": packet["source_references"], "prompt": packet["prompt"], + "existing_rules": packet["existing_rules"], + "outcomes": {kind: sum(l["outcome"] == kind for l in packet["lessons"]) for kind in ("positive", "negative")}, + **result} + + def status(self, task_id): + if not self.database.exists(): + return {"status": "unknown"} + with self._db() as db: + row = db.execute("SELECT packet,result FROM learning_tasks WHERE task_key=?", (self._task(task_id),)).fetchone() + if not row: + return {"status": "unknown"} + return self._public(json.loads(row[0]), json.loads(row[1])) + + def submit(self, task_id, packet_digest, proposals): + self._require_agreement("learning_submit") + key = self._task(task_id) + if not isinstance(packet_digest, str) or not re.fullmatch(r"[0-9a-f]{64}", packet_digest): + raise TaskLearningError("packet_digest must identify a finished preparation") + if not isinstance(proposals, dict) or set(proposals) != {"rules"} or not isinstance(proposals["rules"], list): + raise TaskLearningError("host proposals must contain only a rules list") + if len(_json(proposals).encode()) > 160000: + raise TaskLearningError("host proposal batch is too large") + from .learning_privacy import validate_distilled_text + validate_distilled_text(proposals) + proposal_digest = _digest(proposals) + with self._task_lock(key): + self._require_agreement("learning_submit") + # Record exact host output before filesystem/publication effects, + # then release SQLite's database-wide writer lock. The task file + # lock alone protects its worktree, receipts and publication. + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + row = db.execute("SELECT packet,proposals_digest,result FROM learning_tasks WHERE task_key=?", (key,)).fetchone() + if not row or json.loads(row[0])["packet_digest"] != packet_digest: + raise TaskLearningError("unknown or changed learning packet") + packet, result = json.loads(row[0]), json.loads(row[2]) + if result["status"] == "preparing" or not packet["packet_digest"]: + raise TaskLearningError("learning preparation must finish before submission") + if row[1] and row[1] != proposal_digest: + raise TaskLearningError("task already has different host proposals") + db.execute("UPDATE learning_tasks SET proposals=?,proposals_digest=? WHERE task_key=?", (_json(proposals), proposal_digest, key)) + if result["status"] in {"draft_pr", "rejected", "stale"}: + return self._public(packet, result) + if not proposals["rules"]: + result = {"status": "no_op", "applied": 0} + elif not packet["lessons"]: + raise TaskLearningError("an empty lesson packet cannot support rules") + else: + result = self._submit(packet, proposals, proposal_digest, result) + with self._db() as db: + db.execute("BEGIN IMMEDIATE") + db.execute("UPDATE learning_tasks SET result=? WHERE task_key=?", (_json(result), key)) + return self._public(packet, result) + + def _submit(self, packet, proposals, proposal_digest, previous): + self._require_agreement("learning_submit") + checkout = self._checkout(packet["task_key"]) + if not checkout.is_dir() or self._git(checkout, "rev-parse", "--show-toplevel") != str(checkout): + raise TaskLearningError("provider-owned learning worktree is unavailable") + receipt_path = checkout.parent / "applied.json" + receipt = json.loads(receipt_path.read_text()) if receipt_path.exists() else None + if receipt: + if receipt.get("packet_digest") != packet["packet_digest"] or receipt.get("proposals_digest") != proposal_digest: + raise TaskLearningError("applied learning receipt does not match the task") + if self._git(checkout, "rev-parse", "HEAD") != receipt["head_sha"] or not self._clean(checkout): + return {"status": "stale", "reason": "applied task worktree changed"} + result = receipt["result"] + else: + result = self._apply_task(packet, proposals, proposal_digest, checkout) + if result["status"] != "local": + return result + receipt = {"packet_digest": packet["packet_digest"], "proposals_digest": proposal_digest, + "head_sha": result["head_sha"], "result": result} + self._save(receipt_path, receipt) + try: + publication = LearningPublisher(state_dir=self.state_dir).publish(checkout, task_digest=packet["task_key"], head=result["head_sha"], + packet_digest=packet["packet_digest"], rules=result["applied"], base_sha=packet["base_sha"], + source_pin=packet["source_pin"], source_repository=packet["repository"], + documents={page: hashlib.sha256((checkout / page).read_bytes()).hexdigest() for page in result["documents"]}, + outcomes={kind: sum(l["outcome"] == kind for l in packet["lessons"]) for kind in ("positive", "negative")}) + return {**result, "status": publication["status"], "publication": publication} + except LearningPublicationError as exc: + return {**result, "status": "publication_failed", "publication": {"status": "failed", "reason": str(exc)}} + + def _apply_task(self, packet, proposals, proposal_digest, checkout): + """Recover only exact provider-generated files/commits, never guess.""" + self._require_agreement("learning_apply") + intent_path = checkout.parent / "application-intent.json" + binding = {"packet_digest": packet["packet_digest"], "proposals_digest": proposal_digest, + "base_sha": packet["base_sha"]} + intent = json.loads(intent_path.read_text()) if intent_path.exists() else None + message = ("knowledge: retain host-distilled maintenance rules\n\n" + f"Chat-Learning-Packet: {packet['packet_digest']}\n" + f"Chat-Learning-Proposals: {proposal_digest}") + if intent and any(intent.get(k) != v for k, v in binding.items()): + raise TaskLearningError("application intent differs from this exact task") + head = self._git(checkout, "rev-parse", "HEAD") + if head != packet["base_sha"]: + if (not intent or not intent.get("tree") or not intent.get("validation") + or self._git(checkout, "rev-parse", "HEAD^") != packet["base_sha"] + or self._git(checkout, "rev-parse", "HEAD^{tree}") != intent["tree"] + or self._git(checkout, "log", "-1", "--format=%B") != message + or not self._clean(checkout)): + raise TaskLearningError("unrecorded task commit differs; preserve it for inspection") + return {"status": "local", "applied": intent["validation"]["applied"], "head_sha": head, + "documents": intent["documents"], "workspace": str(checkout), "validation": intent["validation"]} + if intent and not self._clean(checkout): + dirty = set(self._git(checkout, "diff", "--name-only", "HEAD").splitlines()) + untracked = self._git(checkout, "ls-files", "--others", "--exclude-standard") + if untracked or dirty - set(intent["documents"]): + return {"status": "stale", "reason": "unexpected files changed during interrupted application"} + for page in intent["documents"]: + path = checkout / page + allowed = {hashlib.sha256(intent["originals"][page].encode()).hexdigest(), intent["expected_hashes"][page]} + if not path.is_file() or hashlib.sha256(path.read_bytes()).hexdigest() not in allowed: + return {"status": "stale", "reason": "interrupted application has ambiguous owner edits"} + staged = self._git(checkout, "ls-files", "--stage", "--", page).split() + if (len(staged) < 3 or staged[2] != "0" + or [staged[0], staged[1]] not in intent.get("allowed_index", {}).get(page, [])): + return {"status": "stale", "reason": "interrupted application has ambiguous staged owner edits"} + # These bytes are proved to be either the frozen original or the + # exact attempted output. Rewind only these owned paths, then rerun + # the same curator/validators; unknown user changes are retained. + self._require_agreement("learning_apply") + self._git(checkout, "restore", "--source", packet["base_sha"], "--staged", "--worktree", "--", *intent["documents"]) + if not self._clean(checkout): + return {"status": "stale", "reason": "provider worktree contains unexpected edits or files"} + if self._git(Path(packet["source_workspace"]), "rev-parse", "HEAD") != packet["base_sha"]: + return {"status": "stale", "reason": "knowledge source advanced after the packet was frozen"} + for page, digest in packet["page_hashes"].items(): + if hashlib.sha256((checkout / page).read_bytes()).hexdigest() != digest: + return {"status": "stale", "reason": "owner page changed after packet preparation"} + curator = KnowledgeCurator(checkout) + validation = curator.validate_proposals(proposals, self._batch(packet)) + if validation.rejected: + return {"status": "rejected", "rejected": [r.to_dict() for r in validation.rejected], "applied": 0} + updated_on = intent["updated_on"] if intent else datetime.now(UTC).date().isoformat() + documents = sorted({p.page_document_id for p in validation.accepted}) + originals = {page: (checkout / page).read_text(encoding="utf-8") for page in documents} + expected = {page: curator._updated_page(originals[page], [ + p.section_markdown for p in validation.accepted if p.page_document_id == page], updated_on) for page in documents} + object_format = self._git(checkout, "rev-parse", "--show-object-format") + def blob_id(text): + data = text.encode() + return hashlib.new(object_format, b"blob " + str(len(data)).encode() + b"\0" + data).hexdigest() + intent = {**binding, "updated_on": updated_on, "documents": documents, "originals": originals, + "expected_hashes": {page: hashlib.sha256(text.encode()).hexdigest() for page, text in expected.items()}, + "allowed_index": {page: [[self._git(checkout, "ls-files", "--stage", "--", page).split()[0], + blob_id(text)] for text in (originals[page], expected[page])] for page in documents}} + self._require_agreement("learning_apply") + self._save(intent_path, intent) + try: + self._require_agreement("learning_apply") + applied = curator.apply(validation, updated_on=updated_on) + except KnowledgeValidatorError as exc: + return {"status": "validator_failed", "applied": 0, "validation": exc.result.to_dict()} + dirty = set(self._git(checkout, "diff", "--name-only", "HEAD").splitlines()) + if dirty != set(documents) or self._git(checkout, "ls-files", "--others", "--exclude-standard"): + return {"status": "stale", "reason": "validators changed files outside the approved rule pages"} + if any(hashlib.sha256((checkout / page).read_bytes()).hexdigest() != digest + for page, digest in intent["expected_hashes"].items()): + return {"status": "stale", "reason": "applied owner bytes differ from the frozen proposal"} + self._require_agreement("learning_apply") + self._git(checkout, "add", "--", *documents) + intent.update(tree=self._git(checkout, "write-tree"), validation=applied.to_dict()) + self._save(intent_path, intent) + self._require_agreement("learning_apply") + self._git(checkout, "-c", "user.name=Knowledge Learning", "-c", "user.email=knowledge-learning@localhost", + "-c", "commit.gpgsign=false", "-c", "core.hooksPath=/dev/null", "commit", "-m", message) + return {"status": "local", "applied": applied.applied, "head_sha": self._git(checkout, "rev-parse", "HEAD"), + "documents": documents, "workspace": str(checkout), "validation": applied.to_dict()} diff --git a/src/infermatrix_copilot/knowledge_service/learning_cli.py b/src/infermatrix_copilot/knowledge_service/learning_cli.py new file mode 100644 index 000000000..b0d5aa8b6 --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/learning_cli.py @@ -0,0 +1,176 @@ +"""Thin JSON CLI for host-distilled task learning and knowledge feedback.""" + +from __future__ import annotations + +import argparse +import json +import sys +from pathlib import Path +from typing import Any + +_MAX_INPUT_BYTES = 512 * 1024 + + +class _InputError(ValueError): + pass + + +class _Parser(argparse.ArgumentParser): + def error(self, message: str) -> None: + # argparse's default errors echo invalid values and unknown arguments. + # JSON input is the sole data boundary; never repeat stray credentials. + self.exit(2, "Invalid learning command; use --help for accepted arguments.\n") + + +def _read_input(path: str) -> dict[str, Any]: + try: + if path == "-": + content = sys.stdin.read(_MAX_INPUT_BYTES + 1) + if len(content.encode("utf-8")) > _MAX_INPUT_BYTES: + raise _InputError("Input exceeds the 512 KiB limit") + else: + with Path(path).open("rb") as stream: + raw = stream.read(_MAX_INPUT_BYTES + 1) + if len(raw) > _MAX_INPUT_BYTES: + raise _InputError("Input exceeds the 512 KiB limit") + content = raw.decode("utf-8") + value = json.loads(content) + except (OSError, UnicodeError, json.JSONDecodeError): + raise _InputError("Input must be a readable UTF-8 JSON object") from None + if not isinstance(value, dict): + raise _InputError("Input must be a JSON object") + return value + + +def _fields(value: dict[str, Any], allowed: set[str]) -> None: + if set(value) - allowed: + raise _InputError("Input contains unsupported fields") + + +def _text(value: dict[str, Any], field: str) -> str: + result = value.get(field) + if not isinstance(result, str) or not result.strip(): + raise _InputError(f"{field} must be a non-empty string") + return result + + +def _learning_service(): + from .learning import TaskLearningService + + return TaskLearningService.from_env() + + +def _feedback_store(): + from .feedback import KnowledgeFeedbackStore + + return KnowledgeFeedbackStore.from_env() + + +def _require_agreement(action: str) -> None: + from .agreement import AgreementStore + + AgreementStore.from_env().require(action) + + +def _dispatch(args: argparse.Namespace) -> Any: + if args.command == "status": + return _learning_service().status(args.task_id) + if args.command == "report": + if not 1 <= args.limit <= 1000: + raise _InputError("limit must be within 1..1000") + return _feedback_store().report_for_scope(repository=args.repo, limit=args.limit, scope=args.scope) + if args.command == "sync": + if not 1 <= args.limit <= 1000: + raise _InputError("limit must be within 1..1000") + _require_agreement("learning.sync") + return _feedback_store().sync_pending(limit=args.limit) + if args.command == "sync-status": + return _feedback_store().sync_status() + + value = _read_input(args.input) + if args.command == "prepare": + _fields(value, {"task_id", "repository", "repo", "source_pin", "lessons"}) + if "repo" in value and "repository" in value: + raise _InputError("Use repository or repo, not both") + if "repo" in value: + value["repository"] = value.pop("repo") + task_id = _text(value, "task_id") + repository = _text(value, "repository") + source_pin = _text(value, "source_pin") + lessons = value.get("lessons", []) + if not isinstance(lessons, list): + raise _InputError("lessons must be an array") + _require_agreement("learning.prepare") + return _learning_service().prepare( + task_id=task_id, repository=repository, source_pin=source_pin, + lessons=lessons, + ) + if args.command == "submit": + _fields(value, {"task_id", "packet_digest", "proposals"}) + task_id = _text(value, "task_id") + packet_digest = _text(value, "packet_digest") + if "proposals" not in value: + raise _InputError("proposals is required") + _require_agreement("learning.submit") + return _learning_service().submit( + task_id=task_id, packet_digest=packet_digest, + proposals=value["proposals"], + ) + _fields(value, {"task_id", "delivery_id", "ratings"}) + task_id = _text(value, "task_id") + delivery_id = _text(value, "delivery_id") + ratings = value.get("ratings") + if not isinstance(ratings, list): + raise _InputError("ratings must be an array") + _require_agreement("learning.feedback") + return _feedback_store().record( + task_id=task_id, delivery_id=delivery_id, ratings=ratings, + ) + + +def main(argv: list[str] | None = None) -> int: + arguments = list(sys.argv[1:] if argv is None else argv) + if arguments and arguments[0] == "agreement": + from .agreement_cli import main as agreement_main + + return agreement_main(arguments[1:]) + parser = _Parser(prog="infermatrix-copilot learning") + subcommands = parser.add_subparsers(dest="command", required=True) + subcommands.add_parser("agreement", help="show agreement, inspect status, accept interactively or revoke") + for command in ("prepare", "submit", "feedback"): + child = subcommands.add_parser(command) + child.add_argument("--input", required=True, help="JSON file, or - for stdin") + status = subcommands.add_parser("status") + status.add_argument("task_id") + report = subcommands.add_parser("report") + report.add_argument("--repo", default="") + report.add_argument("--limit", type=int, default=100) + report.add_argument("--scope", choices=("auto", "local", "central"), default="auto") + sync = subcommands.add_parser("sync", help="retry pending feedback uploads") + sync.add_argument("--limit", type=int, default=100) + subcommands.add_parser("sync-status", help="inspect the local feedback upload queue") + args = parser.parse_args(arguments) + try: + result = _dispatch(args) + if hasattr(result, "to_dict"): + result = result.to_dict() + output = json.dumps(result, ensure_ascii=False, indent=2) + except _InputError as exc: + print(json.dumps({"error": {"code": "invalid_input", "message": str(exc)}})) + return 2 + except Exception as exc: # noqa: BLE001 - the CLI must not echo private provider failures + if getattr(exc, "code", "") == "agreement_required": + print(json.dumps({"error": {"code": "agreement_required", "message": + "Human agreement required; inspect learning agreement show and sign interactively with learning agreement accept."}})) + return 3 + # Service/provider errors can contain paths, credentials or remote output. + # Preserve the local packet; a status request can report its safe state. + print(json.dumps({"error": {"code": "learning_failed", "message": + "Learning operation failed; retry with the same task ID or inspect its status."}})) + return 1 + print(output) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/infermatrix_copilot/knowledge_service/learning_config.py b/src/infermatrix_copilot/knowledge_service/learning_config.py new file mode 100644 index 000000000..6c67d610c --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/learning_config.py @@ -0,0 +1,36 @@ +"""Read learning options with the same .env precedence as Copilot settings.""" + +from __future__ import annotations + +import os +from pathlib import Path + +_OPTIONS = frozenset({ + "KNOWLEDGE_LEARNING_STATE_DIR", "KNOWLEDGE_LEARNING_WORKSPACE", + "KNOWLEDGE_LEARNING_REPOSITORY", "KNOWLEDGE_LEARNING_BASE", + "KNOWLEDGE_LEARNING_PUBLICATION", "ALLOW_PUSH", "ALLOW_POST", + "KNOWLEDGE_FEEDBACK_URL", "KNOWLEDGE_FEEDBACK_TOKEN", + "KNOWLEDGE_FEEDBACK_TIMEOUT_SECONDS", +}) + + +def learning_environment() -> dict[str, str]: + """Load only learning options; never export or return model credentials. + + Explicit environment values override source, user and cwd dotenv files. + Constructing this mapping does not instantiate a model or mutate os.environ. + """ + from dotenv import dotenv_values + + from ..config import Settings + + files = Settings.model_config.get("env_file") or () + if isinstance(files, (str, Path)): + files = (files,) + result = {} + for path in files: + for key, value in dotenv_values(path, interpolate=False).items(): + if key in _OPTIONS and value is not None: + result[key] = value + result.update({key: os.environ[key] for key in _OPTIONS if key in os.environ}) + return result diff --git a/src/infermatrix_copilot/knowledge_service/learning_privacy.py b/src/infermatrix_copilot/knowledge_service/learning_privacy.py new file mode 100644 index 000000000..9a606a49c --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/learning_privacy.py @@ -0,0 +1,40 @@ +"""Reject recognizable secrets and chat exports before automatic learning. + +This is a guard against accidental disclosure, not a claim to detect arbitrary +private information. The host must still select and redact distilled lessons. +""" + +from __future__ import annotations + +import re + + +class LearningPrivacyError(ValueError): + """A distilled payload needs redaction before it may be retained or sent.""" + + +_CREDENTIAL = re.compile( + r"(?:\bgh[pousr]_[A-Za-z0-9]{20,}\b|\bgithub_pat_[A-Za-z0-9_]{20,}\b|" + r"\bsk-(?:proj-|svcacct-)?[A-Za-z0-9_-]{20,}\b|\bAKIA[0-9A-Z]{16}\b|" + r"-----BEGIN (?:RSA |EC |DSA |OPENSSH |ENCRYPTED )?PRIVATE KEY-----|" + r"(?i:\bbearer\s+[A-Za-z0-9._~+/=-]{20,})|" + r"https?://[^\s/:@]+:[^\s/@]+@)" +) +_ROLE = re.compile(r'''["']role["']\s*:\s*["'](?:user|assistant|system)["']''', re.IGNORECASE) +_CHAT_LINE = re.compile(r"^\s*(?:user|assistant|system)\s*:\s*", re.IGNORECASE | re.MULTILINE) + + +def validate_distilled_text(value) -> None: + """Validate bounded structured lessons/proposals without echoing secrets.""" + if isinstance(value, dict): + for key, item in value.items(): + validate_distilled_text(key) + validate_distilled_text(item) + elif isinstance(value, (list, tuple)): + for item in value: + validate_distilled_text(item) + elif isinstance(value, str): + if _CREDENTIAL.search(value): + raise LearningPrivacyError("distilled knowledge contains credential-like material; redact it before retrying") + if len(value) > 400 and (len(_ROLE.findall(value)) > 1 or len(_CHAT_LINE.findall(value)) > 1): + raise LearningPrivacyError("send distilled lessons instead of a conversation export") diff --git a/src/infermatrix_copilot/knowledge_service/learning_publication.py b/src/infermatrix_copilot/knowledge_service/learning_publication.py new file mode 100644 index 000000000..382a23887 --- /dev/null +++ b/src/infermatrix_copilot/knowledge_service/learning_publication.py @@ -0,0 +1,155 @@ +"""Create-only draft PR publication for host-distilled knowledge tasks.""" + +from __future__ import annotations + +import hashlib +import json +import re +import subprocess +from pathlib import Path + +from ..push import PushPolicy, guard_push + + +class LearningPublicationError(ValueError): + pass + + +def _run(command, workspace): + try: + done = subprocess.run(command, cwd=workspace, text=True, capture_output=True, + timeout=120, check=False) + except (OSError, subprocess.TimeoutExpired) as exc: + raise LearningPublicationError(f"publication command unavailable ({type(exc).__name__})") from exc + if done.returncode: + # Tool output can contain authenticated remote URLs or private paths. + raise LearningPublicationError(f"publication {command[0]} {command[1]} failed") + return done.stdout.strip() + + +class LearningPublisher: + """The destination is host configuration, never model-supplied data.""" + + def __init__(self, environ=None, *, state_dir=None): + from .learning_config import learning_environment + + self.environ = dict(learning_environment() if environ is None else environ) + self.state_dir = state_dir + + def _require_agreement(self): + from .agreement import AgreementStore + + return AgreementStore.from_env(state_dir=self.state_dir, environ=self.environ).require("learning_publication") + + def publish(self, workspace: Path, *, task_digest: str, head: str, + packet_digest: str, rules: int, outcomes: dict, + base_sha: str = "", documents: dict | None = None, + source_pin: str = "", source_repository: str = "") -> dict: + mode = self.environ.get("KNOWLEDGE_LEARNING_PUBLICATION", "local") + branch = "knowledge/chat-" + task_digest[:24] + if mode == "local": + return {"status": "local", "branch": branch, "head_sha": head} + if mode != "draft_pr": + raise LearningPublicationError("KNOWLEDGE_LEARNING_PUBLICATION must be local or draft_pr") + self._require_agreement() + if source_pin and (not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", source_pin) + or not re.fullmatch(r"[a-z0-9][a-z0-9._-]*", source_repository)): + raise LearningPublicationError("publication source provenance is invalid") + repository = self.environ.get("KNOWLEDGE_LEARNING_REPOSITORY", "") + base = self.environ.get("KNOWLEDGE_LEARNING_BASE", "main") + if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repository): + raise LearningPublicationError("draft PR publication requires a fixed owner/repository") + if not base or base.startswith("-") or _run(["git", "check-ref-format", "--branch", base], workspace) != base: + raise LearningPublicationError("publication base branch is invalid") + if self.environ.get("ALLOW_PUSH") != "1" or self.environ.get("ALLOW_POST") != "1": + return {"status": "publication_blocked", "reason": "draft PR requires ALLOW_PUSH=1 and ALLOW_POST=1", + "branch": branch, "head_sha": head} + remote = f"https://github.com/{repository}.git" + documents = documents or {} + if (not re.fullmatch(r"[0-9a-f]{40}|[0-9a-f]{64}", base_sha) or not documents + or any(not re.fullmatch(r"knowledge/(?:repos/[a-z0-9._-]+|general)/.+/?rules(?:-[a-z0-9-]+)?\.md", p) + and not re.fullmatch(r"knowledge/repos/[a-z0-9._-]+/rules(?:-[a-z0-9-]+)?\.md", p) for p in documents)): + raise LearningPublicationError("publication requires an exact validated owner-document manifest") + if (_run(["git", "rev-parse", "HEAD"], workspace) != head + or _run(["git", "rev-parse", "HEAD^"], workspace) != base_sha + or _run(["git", "status", "--porcelain", "--untracked-files=all"], workspace) + or set(_run(["git", "diff", "--name-only", base_sha, head], workspace).splitlines()) != set(documents)): + raise LearningPublicationError("publication head differs from the isolated knowledge commit") + for page, expected in documents.items(): + path = workspace / page + if path.is_symlink() or not path.resolve().is_relative_to(workspace.resolve()) or hashlib.sha256(path.read_bytes()).hexdigest() != expected: + raise LearningPublicationError("publication document differs from the validated bytes") + # Verify the whole PR against the real configured destination, not only + # the last commit. A feature-branch source must never carry unrelated + # committed work into an otherwise narrow knowledge PR. + target_ref = "refs/infermatrix-learning/" + task_digest + "/publication-base" + self._require_agreement() + _run(["git", "fetch", "--no-tags", "--no-write-fetch-head", remote, + "refs/heads/" + base + ":" + target_ref], workspace) + if (_run(["git", "merge-base", base_sha, target_ref], workspace) != base_sha + or set(_run(["git", "diff", "--name-only", target_ref + "..." + head], workspace).splitlines()) != set(documents)): + raise LearningPublicationError("knowledge baseline carries work outside the destination base") + marker = f"" + command = ["gh", "pr", "list", "--repo", repository, "--head", branch, "--state", "all", + "--json", "url,headRefOid,baseRefName,body,isDraft,state"] + + def existing(): + self._require_agreement() + try: + rows = json.loads(_run(command, workspace)) + except (ValueError, TypeError) as exc: + raise LearningPublicationError("draft PR recovery returned invalid data") from exc + if not isinstance(rows, list) or len(rows) > 1: + raise LearningPublicationError("draft PR branch has ambiguous reviews") + if not rows: + return None + row = rows[0] + if (row.get("headRefOid") != head or row.get("baseRefName") != base + or marker not in row.get("body", "") or not row.get("url") + or row.get("isDraft") is not True): + raise LearningPublicationError("existing review does not match this exact draft") + return {"status": "draft_pr", "url": row["url"], "head_sha": head, "branch": branch, + "state": row.get("state", "OPEN")} + + prior = existing() + if prior: + return prior + self._require_agreement() + observed = _run(["git", "ls-remote", "--heads", remote, "refs/heads/" + branch], workspace) + if observed: + entries = [line.split() for line in observed.splitlines()] + if entries != [[head, "refs/heads/" + branch]]: + raise LearningPublicationError("remote learning branch already contains different work") + else: + decision = guard_push(PushPolicy(allowed=True, remote=remote, branch=branch, create_only=True), + [base, "main", "master"]) + if not decision.allowed: + raise LearningPublicationError(decision.reason) + self._require_agreement() + _run(list(decision.command), workspace) + # Recover before create as well as on retry: upload and review creation + # may each have succeeded before their command transport failed. + prior = existing() + if prior: + return prior + body = (f"Host-distilled maintenance rules: {rules} executable owner-scoped rules.\n\n" + f"Learning outcomes: {outcomes.get('positive', 0)} positive, {outcomes.get('negative', 0)} negative. " + "The local chat remains private. Existing knowledge review and quality gates apply.\n\n" + + (f"Host source repository: `{source_repository}`; source pin: `{source_pin}`.\n\n" + if source_pin else "") + marker + "\n") + body_file = workspace.parent / "pull-request-body.txt" + self._require_agreement() + body_file.write_text(body, encoding="utf-8") + try: + self._require_agreement() + _run(["gh", "pr", "create", "--repo", repository, "--base", base, "--head", branch, + "--draft", "--title", "knowledge: retain task maintenance lessons", "--body-file", str(body_file)], workspace) + except LearningPublicationError: + prior = existing() + if prior: + return prior + raise + prior = existing() + if prior is None: + raise LearningPublicationError("created draft PR could not be verified; retry to recover it") + return prior diff --git a/src/infermatrix_copilot/sdk/v1/__init__.py b/src/infermatrix_copilot/sdk/v1/__init__.py index a11deb931..5565b70e8 100644 --- a/src/infermatrix_copilot/sdk/v1/__init__.py +++ b/src/infermatrix_copilot/sdk/v1/__init__.py @@ -51,10 +51,14 @@ UnsupportedRepositoryError, ) from .strict import StrictRuntime +from .learning import KnowledgeAgreementClient, KnowledgeFeedbackClient, KnowledgeLearningClient from .rfc import RFC_API_VERSION, RFCClient, RFCClientError, Principal, SourceRef from ...trace_store import SCHEMA as TRACE_SCHEMA, TraceStore, redact, trace_context __all__ = [ + "KnowledgeAgreementClient", + "KnowledgeFeedbackClient", + "KnowledgeLearningClient", "RFC_API_VERSION", "RFCClient", "RFCClientError", diff --git a/src/infermatrix_copilot/sdk/v1/direct.py b/src/infermatrix_copilot/sdk/v1/direct.py index 78d47e8f0..b202b8f52 100644 --- a/src/infermatrix_copilot/sdk/v1/direct.py +++ b/src/infermatrix_copilot/sdk/v1/direct.py @@ -7,8 +7,9 @@ import json import re import threading +import uuid from collections import OrderedDict -from dataclasses import dataclass +from dataclasses import dataclass, replace from functools import lru_cache from pathlib import Path, PurePosixPath from typing import Any @@ -126,6 +127,8 @@ class _IssuedContext: carried_findings: tuple[dict, ...] = () knowledge_view: Any = None knowledge_usage: dict | None = None + task_id: str = "" + repository: str = "" class DirectClient: @@ -170,6 +173,46 @@ def _revision(self, knowledge: Path) -> str: def capabilities(self) -> Capabilities: return get_capabilities() + @staticmethod + def _feedback(view, task_id: str, repository: str, documents: list[dict]) -> dict: + import sqlite3 + + from ...knowledge_service.agreement import AgreementStore + from ...knowledge_service.feedback import KnowledgeFeedbackStore + + if AgreementStore.from_env().status()["status"] != "accepted": + return {"status": "agreement_required", "protocol": "knowledge-feedback/1", "targets": []} + + try: + return KnowledgeFeedbackStore.from_env().issue_delivery( + task_id=task_id, repository=repository, view=view, documents=documents) + except (OSError, sqlite3.Error): + return {"status": "unavailable", "error": "feedback_storage_unavailable"} + + def _task_repository(self, view, task_id: str) -> str | None: + """Reuse the task's delivery context, including across client restarts.""" + import sqlite3 + + from ...direct_routing import _normalize_repo + from ...knowledge_service.feedback import KnowledgeFeedbackStore + + with self._context_lock: + repositories = {issued.repository for issued in self._issued_contexts.values() + if issued.task_id == task_id and issued.repository} + unavailable = False + try: + repositories.update(KnowledgeFeedbackStore.from_env().repositories_for_task(task_id)) + except (OSError, sqlite3.Error): + # Feedback is optional. A failed lookup must not expose private paths + # or prevent delivering source when storage is unavailable. + unavailable = True + canonical = {_normalize_repo(repository, view) for repository in repositories} + if len(canonical) > 1: + raise InvalidRequestError( + "task_id has multiple repository contexts; supply repository or review_context_id" + ) + return next(iter(canonical), None if unavailable else "") + def _document_path(self, document_id: str, view=None) -> Path: view = view if view is not None else self._view() value = str(document_id).strip().replace("\\", "/") @@ -228,13 +271,18 @@ def read_document( offset: int = 0, max_bytes: int = _EXCERPT_BYTES, review_context_id: str = "", + task_id: str = "", + repository: str = "", ) -> DocumentPage: """Read one knowledge document page. With ``review_context_id`` the read (and every later page of it) comes from the knowledge tree that review's plan was issued from, so a snapshot activated mid-review cannot change what the reviewer reads. Without it, - the currently active tree is used. + the currently active tree is used. An explicit ``task_id`` reuses its + existing repository context for feedback. Before any plan has bound a + task, general documents require ``repository`` to avoid inventing a + second knowledge identity under the generic repository name. """ if offset < 0 or max_bytes < 1 or max_bytes > _EXCERPT_BYTES: raise InvalidRequestError( @@ -268,10 +316,48 @@ def read_document( session = issued.knowledge_usage.get("delivery_session") if context_id and issued.knowledge_usage else None if configuration()["enabled"] and not session: raise ContainmentError("enforced Direct document reads require a bound review delivery session") + from ...direct_routing import _normalize_repo + + if not isinstance(repository, str): + raise InvalidRequestError("repository must be a string") + explicit_repository = _normalize_repo(repository, view) if repository.strip() else "" + if explicit_repository and explicit_repository != "general": + from ...kb_service.repo_spec import resolve_snapshot_repo + + if resolve_snapshot_repo(view, explicit_repository) is None: + raise UnsupportedRepositoryError("repository must identify served knowledge") + if context_id: + bound_repository = issued.repository + if explicit_repository and explicit_repository != bound_repository: + raise InvalidRequestError("repository does not match review_context_id") + else: + from ...knowledge_service.agreement import AgreementStore + + agreement_accepted = AgreementStore.from_env().status()["status"] == "accepted" + bound_repository = (self._task_repository(view, task_id) + if agreement_accepted and task_id and not explicit_repository else "") + feedback_unavailable = bound_repository is None + repository = explicit_repository or bound_repository + if not repository: + if document_id.startswith("repos/"): + repository = _normalize_repo(document_id.split("/")[1], view) + elif task_id and not feedback_unavailable and (context_id or agreement_accepted): + raise InvalidRequestError( + "general document reads with task_id require repository or an existing review context" + ) + else: + repository = "general" + feedback = ({"status": "unavailable", "error": "feedback_storage_unavailable"} + if feedback_unavailable else self._feedback( + view, (issued.task_id if context_id else "") or task_id or f"task-{uuid.uuid4().hex}", + repository, ([{"path": document_id, "content": result.content}] + if PurePosixPath(document_id).suffix.casefold() == ".md" else []))) + result = replace(result, knowledge_feedback=feedback) _issue_usage(result.to_dict(), view=view, session_id=session) return result - def _request_values(self, request: DirectReviewRequest, *, allow_sha256: bool = False) -> tuple[str, list[str]]: + def _request_values(self, request: DirectReviewRequest, *, allow_sha256: bool = False, + view=None) -> tuple[str, list[str]]: alias = request.repository.alias.strip() if not request.review_id.strip(): raise InvalidRequestError("review_id must not be empty") @@ -279,10 +365,12 @@ def _request_values(self, request: DirectReviewRequest, *, allow_sha256: bool = raise InvalidRequestError("pr_number must be >= 0") if not alias: raise InvalidRequestError("repository alias must not be empty") - from ...kb_service.repo_spec import resolve_snapshot_repo - binding = resolve_snapshot_repo(self._view(), alias) + view = view if view is not None else self._view() + from ...direct_routing import _normalize_repo + from ...kb_service.repo_spec import list_snapshot_repos, resolve_snapshot_repo + binding = resolve_snapshot_repo(view, alias) if binding is None and alias.replace("_", "-").casefold() not in { - item.casefold() for item in self.capabilities().supported_repositories + item.repo_id.casefold() for item in list_snapshot_repos(view) }: raise UnsupportedRepositoryError(f"unsupported repository: {alias!r}") head = request.expected_head_sha.strip() @@ -300,14 +388,14 @@ def _request_values(self, request: DirectReviewRequest, *, allow_sha256: bool = f"changed path must be repository-relative: {item.path!r}" ) changed_files.append(path.as_posix()) - return alias, changed_files + return _normalize_repo(alias, view), changed_files @with_containment def open_knowledge_context(self, request: DirectReviewRequest, *, budget=None) -> dict: """Opt into the cumulative adaptive protocol; the v1 plan stays unchanged.""" from ...knowledge_context import KnowledgeContextService - alias, _ = self._request_values(request, allow_sha256=True) view = self._view() + alias, _ = self._request_values(request, allow_sha256=True, view=view) service = KnowledgeContextService(view, self._knowledge_context_path, allowed_repositories=self._allowed_knowledge_repositories, knowledge_maintenance=self._knowledge_maintenance) @@ -345,9 +433,9 @@ def _knowledge_context(self, session_id: str): def plan_adaptive(self, request: DirectReviewRequest, *, budget=None) -> dict: """Return one budgeted model packet, with references instead of SDK excerpts.""" from ...direct_routing import direct_review_plan - alias, changed = self._request_values(request, allow_sha256=True) status = self.open_knowledge_context(request, budget=budget) service, session_id = self._knowledge_context(status["session_id"]), status["session_id"] + alias, changed = self._request_values(request, allow_sha256=True, view=service.view) raw = direct_review_plan(alias, title=request.title, body=request.body, changed_files=changed, diff=request.diff, view=service.view) routes = [{"path": service.view.relative(row["path"]), "kind": "direct_map"} @@ -370,9 +458,14 @@ def plan_adaptive(self, request: DirectReviewRequest, *, budget=None) -> dict: "progress_update": raw["progress_update"], "completion_gate": raw["completion_gate"], "guidance": related.get("guidance", ""), "truncated": guide_packet["truncated"] or related["truncated"]} + from ...knowledge_service.feedback import model_content_documents + + packet["knowledge_feedback"] = self._feedback( + service.view, request.review_id, alias, model_content_documents(content)) usage = _issue_usage(packet, view=service.view, session_id=session_id) self._remember_context(context_id, request.expected_head_sha.casefold(), - tuple(row.to_dict() for row in request.carried_findings), service.view, usage) + tuple(row.to_dict() for row in request.carried_findings), service.view, usage, + task_id=request.review_id, repository=alias) return packet def read_knowledge_context(self, session_id: str, document_id: str, *, offset: int = 0, @@ -391,8 +484,11 @@ def expand_knowledge_context(self, session_id: str, *, target_tokens: int, reaso def _remember_context( self, context_id: str, expected_head_sha: str, carried=(), view=None, usage=None, + *, task_id: str = "", repository: str = "", ) -> None: view = view if view is not None else self._view() + from ...direct_routing import _normalize_repo + repository = _normalize_repo(repository, view) if repository else "" with self._context_lock: self._issued_contexts[context_id] = _IssuedContext( expected_head_sha=expected_head_sha, @@ -400,6 +496,8 @@ def _remember_context( carried_findings=tuple(carried), knowledge_view=view, knowledge_usage=usage, + task_id=task_id, + repository=repository, ) self._issued_contexts.move_to_end(context_id) while len(self._issued_contexts) > self._max_issued_contexts: @@ -415,9 +513,9 @@ def plan(self, request: DirectReviewRequest) -> DirectReviewPlan: carried = tuple(item.to_dict() for item in request.carried_findings) validate_carried(carried) - alias, changed_files = self._request_values(request) - expected_head = request.expected_head_sha.strip().casefold() view = self._view() + alias, changed_files = self._request_values(request, view=view) + expected_head = request.expected_head_sha.strip().casefold() revision = self._revision(view.root) raw = direct_review_plan( alias, @@ -506,8 +604,16 @@ def plan(self, request: DirectReviewRequest) -> DirectReviewPlan: untested_public_api=dict(raw.get("untested_public_api") or {}), related_knowledge=related, ) + references = [plan.knowledge_entry, *plan.mandatory_review_guides, *plan.document_maps, + *(route.document for route in plan.knowledge_routes)] + documents = [{"path": ref.document_id, "content": ref.excerpt} for ref in references] + documents.extend({"path": row["document"]["document_id"], + "content": row["document"]["excerpt"]} + for row in related.get("documents", []) if row.get("document")) + plan = replace(plan, knowledge_feedback=self._feedback(view, request.review_id, alias, documents)) usage = _issue_usage(plan.to_dict(), view=view, session_id=review_context_id.removeprefix("sha256:")) - self._remember_context(review_context_id, expected_head, carried, view, usage) + self._remember_context(review_context_id, expected_head, carried, view, usage, + task_id=request.review_id, repository=alias) return plan @with_containment diff --git a/src/infermatrix_copilot/sdk/v1/learning.py b/src/infermatrix_copilot/sdk/v1/learning.py new file mode 100644 index 000000000..2aa93e022 --- /dev/null +++ b/src/infermatrix_copilot/sdk/v1/learning.py @@ -0,0 +1,102 @@ +"""Host-model task learning and evidence-bound knowledge feedback. + +Imports are lazy: importing the SDK never creates a database, starts a server, +or resolves credentials. The host distills its own chat before submitting it. +""" + +from __future__ import annotations + +from pathlib import Path + + +def _require_agreement(action: str, state_dir: str | Path | None = None) -> None: + from ...knowledge_service.agreement import AgreementStore + + AgreementStore.from_env(state_dir=state_dir).require(action) + + +class KnowledgeAgreementClient: + """Inspect or revoke the human agreement; acceptance is never an SDK action.""" + + def __init__(self, *, state_dir: str | Path | None = None): + self._state_dir = state_dir + + def _store(self): + from ...knowledge_service.agreement import AgreementStore + + return AgreementStore.from_env(state_dir=self._state_dir) + + def document(self) -> dict: + return self._store().document() + + def status(self) -> dict: + return self._store().status() + + def revoke(self) -> dict: + return self._store().revoke() + + +class KnowledgeLearningClient: + """Use the same task-completion service as MCP and the learning CLI.""" + + def __init__(self, *, state_dir: str | Path | None = None, + workspace_root: str | Path | None = None): + self._state_dir = state_dir + self._workspace_root = workspace_root + self._service = None + + def _runtime(self): + if self._service is None: + from ...knowledge_service.learning import TaskLearningService + + self._service = (TaskLearningService(self._state_dir, self._workspace_root) + if self._state_dir is not None else + TaskLearningService.from_env(workspace_root=self._workspace_root)) + return self._service + + def prepare(self, *, task_id: str, repository: str, source_pin: str, + lessons: list[dict]) -> dict: + _require_agreement("knowledge_learning.prepare", self._state_dir) + return self._runtime().prepare(task_id, repository, source_pin, lessons) + + def submit(self, *, task_id: str, packet_digest: str, proposals: dict) -> dict: + _require_agreement("knowledge_learning.submit", self._state_dir) + return self._runtime().submit(task_id, packet_digest, proposals) + + def status(self, task_id: str) -> dict: + return self._runtime().status(task_id) + + +class KnowledgeFeedbackClient: + """Grade selected, actually used targets from provider-issued deliveries.""" + + def __init__(self, *, state_dir: str | Path | None = None): + self._state_dir = state_dir + + def _store(self): + from ...knowledge_service.feedback import KnowledgeFeedbackStore + + return (KnowledgeFeedbackStore.from_env(state_dir=self._state_dir) if self._state_dir is not None + else KnowledgeFeedbackStore.from_env()) + + def record(self, *, task_id: str, delivery_id: str, ratings: list[dict]) -> dict: + _require_agreement("knowledge_feedback.record", self._state_dir) + return self._store().record(task_id=task_id, delivery_id=delivery_id, ratings=ratings) + + def report(self, *, repository: str = "", limit: int = 100, + scope: str = "auto") -> dict: + """Read the configured team aggregate, or explicitly select local data. + + Auto selects central when configured. A central failure is an error; + it never presents a partial local ledger as the team aggregate. + """ + return self._store().report_for_scope(repository=repository, limit=limit, scope=scope) + + def sync(self, *, limit: int = 100) -> dict: + """Retry a bounded batch of durable feedback uploads.""" + _require_agreement("knowledge_feedback.sync", self._state_dir) + return self._store().sync_pending(limit=limit) + + def sync_status(self) -> dict: + """Inspect upload state without making a network request.""" + return self._store().sync_status() diff --git a/src/infermatrix_copilot/sdk/v1/models.py b/src/infermatrix_copilot/sdk/v1/models.py index 5bc92c8d9..ef6755a92 100644 --- a/src/infermatrix_copilot/sdk/v1/models.py +++ b/src/infermatrix_copilot/sdk/v1/models.py @@ -77,11 +77,14 @@ class DocumentPage(_Serializable): content: str next_offset: int | None review_context_id: str = "" + knowledge_feedback: dict[str, Any] = field(default_factory=dict) def to_dict(self) -> dict[str, Any]: result = super().to_dict() if not self.review_context_id: result.pop("review_context_id") + if not self.knowledge_feedback: + result.pop("knowledge_feedback") return result @@ -270,6 +273,7 @@ class DirectReviewPlan(_Serializable): # {"status": "no_diff"} when the request carried no diff untested_public_api: dict[str, Any] = field(default_factory=dict) related_knowledge: dict[str, Any] = field(default_factory=dict) + knowledge_feedback: dict[str, Any] = field(default_factory=dict) FeedbackStatus = Literal[ "checked", "disabled", "unavailable", "not_applicable" diff --git a/src/infermatrix_copilot/thin_mcp_server.py b/src/infermatrix_copilot/thin_mcp_server.py index bafbe954c..0baab7c9a 100644 --- a/src/infermatrix_copilot/thin_mcp_server.py +++ b/src/infermatrix_copilot/thin_mcp_server.py @@ -4,8 +4,10 @@ import re import signal +import sqlite3 import sys import time +import uuid from .config import Settings @@ -65,10 +67,16 @@ def _docs(repo: str, view: KnowledgeView | None = None) -> KnowledgeDocs: def _guard(fn): + from .sdk.v1.models import SDKError + try: return fn() except (KnowledgeDocsError, FileNotFoundError, PolicyError, TypeError, - ValueError) as exc: + ValueError, SDKError) as exc: + if getattr(exc, "code", "") == "agreement_required": + return {"status": "agreement_required", "error": str(exc), + "agreement_tool": "knowledge_agreement", + "human_command": "infermatrix-copilot learning agreement accept"} return {"error": str(exc)} @@ -80,26 +88,47 @@ def _model_context_delivery(packet: dict) -> dict: return packet -def _raw_document_delivery(result, receipt, session, view): - if session is None: - return result - from .knowledge_service.containment import _issue_usage - if result.get("path") or result.get("matches"): - receipt = _issue_usage({"session_id":session,"delivery":result}, view=view, session_id=session, injected=True) - return {**result, "knowledge_usage": receipt} +def _feedback_delivery(result, *, view, repository, task_id="", documents=None): + from .knowledge_service.feedback import KnowledgeFeedbackStore + + view = view or KnowledgeView.current() + documents = documents if documents is not None else ( + [{"path": result["path"], "content": result.get("content", "")}] + if result.get("path") else result.get("matches", [])) + try: + receipt = KnowledgeFeedbackStore.from_env().issue_delivery( + task_id=task_id or f"task-{uuid.uuid4().hex}", repository=repository, + view=view, documents=documents) + except (OSError, sqlite3.Error): + receipt = {"status": "unavailable", "error": "feedback_storage_unavailable"} + return {**result, "knowledge_feedback": receipt} -def _legacy_plan_delivery(plan): +def _raw_document_delivery(result, receipt, session, view, task_id=""): + if session is not None: + from .knowledge_service.containment import _issue_usage + if result.get("path") or result.get("matches"): + receipt = _issue_usage({"session_id":session,"delivery":result}, view=view, session_id=session, injected=True) + result = {**result, "knowledge_usage": receipt} + return _feedback_delivery(result, view=view, repository=result["repo"], task_id=task_id) + + +def _legacy_plan_delivery(plan, task_id="", repository="", view=None): from .knowledge_service.containment import configuration, _usage_session_view, _issue_usage, digest - if not configuration()["enabled"]: - return plan - session, view = _usage_session_view(plan["knowledge_usage"]) - context = {"raw_plan_sha256":digest(plan), - "documents":[{"document_id":row["path"]} for row in plan["knowledge_usage"]["pages"]], - "quick_maps":[{"path":view.relative(row["path"]),"content":row.get("quick_map","")} - for row in plan["knowledge_routes"]], - "related_knowledge":plan["related_knowledge"]} - return {**plan,"knowledge_usage":_issue_usage(context,view=view,session_id=session,injected=True)} + view = view or KnowledgeView.current() + if configuration()["enabled"]: + session, view = _usage_session_view(plan["knowledge_usage"]) + context = {"raw_plan_sha256":digest(plan), + "documents":[{"document_id":row["path"]} for row in plan["knowledge_usage"]["pages"]], + "quick_maps":[{"path":view.relative(row["path"]),"content":row.get("quick_map","")} + for row in plan["knowledge_routes"]], + "related_knowledge":plan["related_knowledge"]} + plan = {**plan,"knowledge_usage":_issue_usage(context,view=view,session_id=session,injected=True)} + documents = [{"path": row["path"], "content": row.get("quick_map", "")} + for row in plan.get("knowledge_routes", []) if row.get("quick_map")] + documents.extend(plan.get("related_knowledge", {}).get("documents", [])) + return _feedback_delivery(plan, view=view, repository=_normalize_repo(repository, view), + task_id=task_id, documents=documents) def _knowledge_entry(name: str) -> str: @@ -288,7 +317,31 @@ def build_mcp( "implicit. For Direct, pass post=true only when the user " "explicitly asks. Strict never posts and refuses post=true: exactly " "one publisher owns a PR's review marker and head gate, so read the " - "structured result from get_review_result and publish it yourself." + "structured result from get_review_result and publish it yourself. " + "At completion of each Copilot task, FIRST call knowledge_agreement " + "with action=status, before distilling lessons or grading knowledge. " + "Only status=accepted permits extra learning/grading tokens, feedback " + "uploads or knowledge contributions. Missing, revoked, unavailable " + "or renewal_required agreement means skip those activities and finish " + "the requested task normally. Offer the actual agreement document " + "through knowledge_agreement action=show and the human signing command " + "infermatrix-copilot learning agreement accept once; do not repeat " + "the reminder on every task. Never sign or accept on the user's behalf. " + "Operator publication/write configuration is not human consent. " + "After accepted status, distill reusable positive and negative lessons " + "locally from the current chat. Never send raw chat histories or credentials. Use " + "knowledge_learning prepare then submit for evidenced owner-scoped " + "rules; no reusable lesson is a valid empty result. Grade only " + "actually used targets from knowledge_feedback delivery receipts " + "with score -1 or +1, used=true, a reason and outcome evidence. " + "Leave unused or uncertain knowledge ungraded. Reuse one task_id " + "through review, follow-up reads, learning and feedback; task IDs " + "must be globally unique, for example the host chat UUID. Retries " + "reuse the exact packet. With accepted agreement, configured draft PR " + "publication runs automatically within its existing operator write gates; retain " + "and report pending work if publication is unavailable. Configured " + "central feedback sync follows local recording automatically; pending " + "uploads remain durable and can be retried with knowledge_feedback_sync." ), ) @@ -310,6 +363,7 @@ def review( idempotency_key: str = "", diff: str = "", knowledge_profile: str = "legacy", + task_id: str = "", ) -> dict: """Begin a Direct or Strict review. @@ -348,19 +402,21 @@ def run() -> dict: if selected_mode == "direct": if knowledge_profile == "adaptive": from .sdk.v1.models import ChangedPath, DirectReviewRequest, RepositoryRef - request = DirectReviewRequest(idempotency_key or f"direct:{target}", RepositoryRef(repo), + request = DirectReviewRequest(task_id or idempotency_key or f"direct:{target}:{uuid.uuid4().hex}", RepositoryRef(repo), 0, expected_head_sha, title, body, tuple(ChangedPath(path) for path in changed_files or ()), diff=diff) return _model_context_delivery(context_client.plan_adaptive(request)) if knowledge_profile != "legacy": raise ValueError("knowledge_profile must be legacy or adaptive") + view = KnowledgeView.current() return _legacy_plan_delivery(direct_review_plan( repo, title=title, body=body, changed_files=changed_files, diff=diff, - )) + view=view, + ), task_id=task_id or idempotency_key, repository=repo, view=view) if post: # Refused at the surface as well as in the policy, so the @@ -487,11 +543,13 @@ def doc_search( repo: str = "vllm-omni", limit: int = 20, knowledge_usage: dict | None = None, + task_id: str = "", ) -> dict: """Search knowledge; enforced reads require the review plan's knowledge_usage receipt.""" def run() -> dict: from .knowledge_service.containment import _usage_session_view session, view = _usage_session_view(knowledge_usage) + view = view or KnowledgeView.current() selected_repo = _normalize_repo(repo, view) if selected_repo not in _supported_repos(view): supported = ", ".join(_supported_repos(view)) or "(none)" @@ -512,7 +570,7 @@ def run() -> dict: "knowledge_entry." )} if not matches else {}), } - return _raw_document_delivery(result, knowledge_usage, session, view) + return _raw_document_delivery(result, knowledge_usage, session, view, task_id) return _guard(run) @@ -522,18 +580,125 @@ def doc_read( repo: str = "vllm-omni", offset: int = 0, knowledge_usage: dict | None = None, + task_id: str = "", ) -> dict: """Read a doc_search page; enforced reads require the review plan's knowledge_usage receipt.""" def run() -> dict: from .knowledge_service.containment import _usage_session_view session, view = _usage_session_view(knowledge_usage) + view = view or KnowledgeView.current() selected_repo = _normalize_repo(repo, view) result = { "repo": selected_repo, **_docs(selected_repo, view).read(path, offset=offset), } - return _raw_document_delivery(result, knowledge_usage, session, view) + return _raw_document_delivery(result, knowledge_usage, session, view, task_id) + + return _guard(run) + + @mcp.tool(annotations=ToolAnnotations( + title="Inspect or revoke the knowledge learning agreement", readOnlyHint=False, + destructiveHint=False, idempotentHint=True, openWorldHint=False)) + def knowledge_agreement(action: str = "status") -> dict: + """Read status/show the actual terms, or revoke consent using local state. + + Status and show do not sign or create acceptance. Acceptance is a human + interactive CLI action, never an MCP action. This tool accepts no signer, + credential, endpoint, attestation or acceptance flag. + """ + from .sdk.v1.learning import KnowledgeAgreementClient + + def run(): + if action not in {"status", "show", "revoke"}: + raise ValueError("knowledge_agreement action must be status, show or revoke") + client = KnowledgeAgreementClient() + if action == "status": + return client.status() + if action == "show": + return client.document() + return client.revoke() + return _guard(run) + + @mcp.tool(annotations=ToolAnnotations( + title="Distill task lessons into knowledge proposals", readOnlyHint=False, + destructiveHint=False, idempotentHint=True, openWorldHint=True)) + def knowledge_learning(action: str, task_id: str, repo: str = "", + source_pin: str = "", lessons: list[dict] | None = None, + packet_digest: str = "", proposals: dict | None = None) -> dict: + """At task completion prepare then submit locally distilled positive/negative lessons. + + First inspect knowledge_agreement(status); accepted agreement is required + before spending extra learning tokens. The host model uses the returned owner catalog and prompt. Send reusable + lessons and verification references, never a raw transcript. Draft PRs + require accepted human agreement, configured publication and the existing push/post gates. Empty + lessons are valid. Reuse task_id and the exact prepared packet on retries. + """ + from .sdk.v1.learning import KnowledgeLearningClient + + def run(): + client = KnowledgeLearningClient() + if action == "prepare": + return client.prepare(task_id=task_id, repository=repo, + source_pin=source_pin, lessons=lessons or []) + if action == "submit": + return client.submit(task_id=task_id, packet_digest=packet_digest, + proposals=proposals if proposals is not None else {"rules": []}) + if action == "status": + return client.status(task_id) + raise ValueError("knowledge_learning action must be prepare, submit or status") + return _guard(run) + + @mcp.tool(annotations=ToolAnnotations( + title="Grade knowledge actually used in a task", readOnlyHint=False, + destructiveHint=False, idempotentHint=True, openWorldHint=True)) + def knowledge_feedback(task_id: str, delivery_id: str, ratings: list[dict]) -> dict: + """Record -1/+1 only for issued targets with used=true, reason and evidence. + + Require accepted human agreement before grading. Omit unused or + inconclusive targets. Scores measure observed utility; + they do not authorize rule edits, retirement, merges or suppression. + Configured team sync runs after local persistence; pending is not an + acknowledged upload. Credentials and destination are host configuration. + """ + from .sdk.v1.learning import KnowledgeFeedbackClient + + return _guard(lambda: KnowledgeFeedbackClient().record( + task_id=task_id, delivery_id=delivery_id, ratings=ratings)) + @mcp.tool(annotations=ToolAnnotations( + title="Read knowledge quality counts", readOnlyHint=True, + destructiveHint=False, idempotentHint=True, openWorldHint=True)) + def knowledge_feedback_report(repo: str = "", limit: int = 100, + scope: str = "auto") -> dict: + """Read exact-version quality counts; auto uses configured team aggregation. + + Scope may be auto, local or central. Central failures are errors, never + a silent local fallback that understates the team's actual usage. + """ + from .sdk.v1.learning import KnowledgeFeedbackClient + + return _guard(lambda: KnowledgeFeedbackClient().report( + repository=repo, limit=limit, scope=scope)) + + @mcp.tool(annotations=ToolAnnotations( + title="Retry knowledge feedback uploads", readOnlyHint=False, + destructiveHint=False, idempotentHint=True, openWorldHint=True)) + def knowledge_feedback_sync(action: str = "flush", limit: int = 100) -> dict: + """Retry pending uploads or inspect status using configured destination only. + + Actions are flush and status. Status makes no network request. Reusing + original task/version identities makes retries safe after an uncertain + response. Neither action edits knowledge or creates another vote. + """ + from .sdk.v1.learning import KnowledgeFeedbackClient + + def run(): + client = KnowledgeFeedbackClient() + if action == "flush": + return client.sync(limit=limit) + if action == "status": + return client.sync_status() + raise ValueError("knowledge_feedback_sync action must be flush or status") return _guard(run) def rfc_call(action: str, payload: dict | None = None) -> dict: diff --git a/test/conftest.py b/test/conftest.py index 157bcf00c..713f36d17 100644 --- a/test/conftest.py +++ b/test/conftest.py @@ -1,4 +1,6 @@ +import os import subprocess +from functools import wraps from pathlib import Path import pytest @@ -94,5 +96,66 @@ def git(*args: str) -> None: @pytest.fixture(autouse=True) def _no_real_run_roots(tmp_path, monkeypatch): """Snapshot pruning looks for runs that pin a snapshot; tests never read - the real ~/.infermatrix-copilot/runs.""" + the real ~/.infermatrix-copilot/runs. Feedback tests also never write a + user's ledger or contact a configured team collector unless opted in.""" monkeypatch.setenv("KB_RUN_ROOTS", str(tmp_path / "no-runs")) + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "learning-state")) + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_URL", "") + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_TOKEN", "") + + +@pytest.fixture +def accept_learning_agreement(tmp_path): + """Simulate a named signature only inside this test's private directory.""" + from infermatrix_copilot.knowledge_service.agreement import AgreementStore + + def accept(state_dir=None, *, environ=None, feedback_url=None): + store = AgreementStore.from_env(state_dir=state_dir, environ=environ, feedback_url=feedback_url) + assert store.state_dir.resolve().is_relative_to(tmp_path.resolve()), "never sign real user state" + if store.status()["status"] != "accepted": + document = store.document() + store._accept("Synthetic Test User", version=document["version"], + agreement_sha256=document["sha256"], context_sha256=document["context_sha256"], + confirmation="I AGREE") + return store + return accept + + +@pytest.fixture +def accepted_learning_feature(monkeypatch, accept_learning_agreement): + """Legacy feature suites opt in; agreement tests exercise the closed default. + + These constructors still run production gates. The fixture only supplies + synthetic, destination-specific signatures in tmp_path, like a signed-in + test-user fixture; it never changes production checks or environment policy. + """ + from infermatrix_copilot.knowledge_service.agreement import AgreementRequiredError + from infermatrix_copilot.knowledge_service.feedback import KnowledgeFeedbackStore + from infermatrix_copilot.knowledge_service.learning import TaskLearningService + from infermatrix_copilot.knowledge_service.learning_publication import ( + LearningPublisher, + ) + + accept_learning_agreement() + for cls in (KnowledgeFeedbackStore, TaskLearningService, LearningPublisher): + original = cls.__init__ + + def wrap(original, cls): + @wraps(original) + def initialize(self, *args, **kwargs): + if cls is LearningPublisher and kwargs.get("state_dir") is None: + kwargs["state_dir"] = os.environ["KNOWLEDGE_LEARNING_STATE_DIR"] + original(self, *args, **kwargs) + if cls is KnowledgeFeedbackStore and not self._feedback_sync_enabled: + return + options = {"environ": self.environ} if cls is LearningPublisher else {} + if cls is KnowledgeFeedbackStore and self.sync_config is not None: + options["feedback_url"] = self.sync_config.url + try: + accept_learning_agreement(getattr(self, "state_dir", None), **options) + except AgreementRequiredError: + # Invalid deployment destinations cannot be consented to. + # Configuration-error tests still exercise that closed path. + return + return initialize + monkeypatch.setattr(cls, "__init__", wrap(original, cls)) diff --git a/test/test_chat_knowledge_learning.py b/test/test_chat_knowledge_learning.py new file mode 100644 index 000000000..052862e43 --- /dev/null +++ b/test/test_chat_knowledge_learning.py @@ -0,0 +1,343 @@ +"""Host-distilled task learning uses private state and an isolated checkout.""" + +from __future__ import annotations + +import hashlib +import json +import subprocess +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +from infermatrix_copilot.knowledge_service.learning import ( + TaskLearningError, + TaskLearningService, +) +from infermatrix_copilot.knowledge_service.learning_publication import ( + LearningPublicationError, + LearningPublisher, +) + +PAGE = "knowledge/repos/x/rules.md" +PAGE_TEXT = """--- +title: x rules +created: 2026-08-01 +updated: 2026-08-01 +type: rule +tags: [review] +sources: [] +--- + +# x rules + +## X-1 — existing rule + +- Trigger: existing behavior changes. +- Required: preserve the current behavior. +""" + + +def git(root, *args): + return subprocess.run(["git", "-C", str(root), *args], capture_output=True, + text=True, check=True).stdout.strip() + + +@pytest.fixture +def source(tmp_path): + root = tmp_path / "source" + (root / "knowledge/repos/x").mkdir(parents=True) + (root / "knowledge/tools").mkdir() + (root / "knowledge/AGENTS.md").write_text("Governed knowledge\n") + (root / PAGE).write_text(PAGE_TEXT) + for name in ("check_knowledge_tree.py", "check_wiki_lint.py"): + (root / "knowledge/tools" / name).write_text("raise SystemExit(0)\n") + git(root, "init", "-q", "-b", "main") + git(root, "config", "user.name", "Test") + git(root, "config", "user.email", "test@example.com") + git(root, "add", ".") + git(root, "commit", "-qm", "initial") + return root + + +def lessons(): + return [{"outcome": "positive", "summary": "A precise source comparison preserved the API behavior.", + "evidence": ["source comparison passed"], "changed_paths": ["src/api.py"]}, + {"outcome": "negative", "summary": "An empty request exposed a missing boundary check.", + "evidence": ["empty-input regression failed before the fix"], "changed_paths": ["src/api.py"]}] + + +def proposal(packet, rule="X-2"): + citation = packet["source_references"][0] + return {"rules": [{"page": PAGE, "rule_id": rule, + "section_markdown": f"## {rule} — preserve API boundary behavior\n\n" + "- Trigger: a patch changes API request boundary handling.\n" + f"- Required: compare boundary results and preserve the verified public contract. ^[{citation}]", + "sources": [citation]}]} + + +def prepared(source, tmp_path): + service = TaskLearningService(tmp_path / "state", source) + return service, service.prepare("private-chat-123", "x", "a" * 40, lessons()) + + +def test_positive_negative_host_prompt_and_private_isolated_apply(source, tmp_path): + original_head = git(source, "rev-parse", "HEAD") + (source / PAGE).write_text(PAGE_TEXT + "\nUser's unfinished edit\n") + (source / "private-untracked.txt").write_text("user data") + service, packet = prepared(source, tmp_path) + assert packet["outcomes"] == {"positive": 1, "negative": 1} + events = json.loads(packet["prompt"].split('\n')[1].split("")[0]) + assert [json.loads(event["attributes_json"])["outcome"] for event in events] == ["positive", "negative"] + assert "private-chat-123" not in packet["prompt"] + assert packet["source_pin"] == "a" * 40 + assert all(len(ref) <= 60 for ref in packet["source_references"]) + result = service.submit("private-chat-123", packet["packet_digest"], proposal(packet)) + assert result["status"] == "local" and result["applied"] == 1 + checkout = Path(result["workspace"]) + assert checkout != source and "## X-2" in (checkout / PAGE).read_text() + assert "User's unfinished edit" not in (checkout / PAGE).read_text() + assert "User's unfinished edit" in (source / PAGE).read_text() + assert (source / "private-untracked.txt").read_text() == "user data" + assert git(source, "rev-parse", "HEAD") == original_head + assert git(checkout, "show", "--pretty=", "--name-only", "HEAD") == PAGE + + +@pytest.mark.parametrize("bad", [ + [{"outcome": "positive", "summary": "x", "transcript": "raw local chat"}], + [{"outcome": "positive", "summary": "x", "messages": []}], + [{"outcome": "neutral", "summary": "x"}], + [{"outcome": "negative", "summary": "x", "changed_paths": ["../outside"]}], + [{"outcome": "negative", "summary": "x", "evidence": ["x" * 1001]}], +]) +def test_no_transcript_or_unbounded_lesson_inputs(source, tmp_path, bad): + service = TaskLearningService(tmp_path / "state", source) + with pytest.raises(TaskLearningError): + service.prepare("task", "x", "a" * 40, bad) + + +def test_empty_lessons_and_empty_host_proposals_are_noop_without_workspace(tmp_path): + service = TaskLearningService(tmp_path / "state", tmp_path / "not-a-checkout") + packet = service.prepare("empty", "x", "a" * 40, []) + assert packet["status"] == "no_op" and packet["prompt"] == "" + assert service.submit("empty", packet["packet_digest"], {"rules": []})["applied"] == 0 + assert not (tmp_path / "state/tasks").exists() + + +def test_interrupted_prepare_cannot_submit_empty_digest_or_change_phase(source, tmp_path, monkeypatch): + service = TaskLearningService(tmp_path / "state", source) + original = service._git + def interrupt(root, *args): + result = original(root, *args) + if args[:2] == ("worktree", "add"): + raise RuntimeError("interrupted after workspace creation") + return result + monkeypatch.setattr(service, "_git", interrupt) + with pytest.raises(RuntimeError, match="interrupted"): + service.prepare("interrupted", "x", "a" * 40, lessons()) + restarted = TaskLearningService(tmp_path / "state", source) + assert restarted.status("interrupted")["status"] == "preparing" + with pytest.raises(TaskLearningError, match="finished preparation"): + restarted.submit("interrupted", "", {"rules": []}) + with pytest.raises(TaskLearningError): + restarted.submit("interrupted", "b" * 64, {"rules": []}) + assert restarted.status("interrupted")["status"] == "preparing" + assert restarted.prepare("interrupted", "x", "a" * 40, lessons())["status"] == "prepared" + + +def test_exact_retry_restart_and_concurrent_submit_create_one_commit(source, tmp_path): + service, packet = prepared(source, tmp_path) + document = proposal(packet) + def submit(_): + return TaskLearningService(tmp_path / "state", source).submit("private-chat-123", packet["packet_digest"], document) + with ThreadPoolExecutor(max_workers=4) as pool: + results = list(pool.map(submit, range(4))) + assert len({r["head_sha"] for r in results}) == 1 + assert all(r["status"] == "local" for r in results) + checkout = Path(results[0]["workspace"]) + assert git(checkout, "rev-list", "--count", "HEAD") == "2" + assert service.prepare("private-chat-123", "x", "a" * 40, lessons())["packet_digest"] == packet["packet_digest"] + assert TaskLearningService(tmp_path / "state", source).status("private-chat-123")["head_sha"] == results[0]["head_sha"] + with pytest.raises(TaskLearningError, match="different host proposals"): + service.submit("private-chat-123", packet["packet_digest"], proposal(packet, "X-3")) + with pytest.raises(TaskLearningError, match="different learning packet"): + service.prepare("private-chat-123", "x", "b" * 40, lessons()) + + +def test_rejection_preserves_packet_and_never_applies_partial_rules(source, tmp_path): + service, packet = prepared(source, tmp_path) + document = proposal(packet) + document["rules"].append({**document["rules"][0], "page": "knowledge/repos/y/rules.md"}) + result = service.submit("private-chat-123", packet["packet_digest"], document) + assert result["status"] == "rejected" and result["applied"] == 0 + assert service.status("private-chat-123")["prompt"] == packet["prompt"] + assert git(service._checkout(service._task("private-chat-123")), "rev-list", "--count", "HEAD") == "1" + + +def test_knowledge_source_advance_and_owner_page_drift_are_stale(source, tmp_path): + service, packet = prepared(source, tmp_path) + git(source, "commit", "--allow-empty", "-qm", "another knowledge baseline") + assert service.submit("private-chat-123", packet["packet_digest"], proposal(packet))["status"] == "stale" + + +def test_changed_frozen_page_is_not_overwritten(source, tmp_path): + service, packet = prepared(source, tmp_path) + page = service._checkout(packet["task_key"]) / PAGE + page.write_text(page.read_text() + "\nUnexpected page edit\n") + assert service.submit(packet["task_id"], packet["packet_digest"], proposal(packet))["status"] == "stale" + assert "Unexpected page edit" in page.read_text() + + +def test_sha256_source_pin_and_unknown_repository(source, tmp_path): + service = TaskLearningService(tmp_path / "state", source) + packet = service.prepare("sha256-task", "x", "d" * 64, lessons()) + assert packet["source_pin"] == "d" * 64 and all(len(ref) <= 60 for ref in packet["source_references"]) + assert service.submit(packet["task_id"], packet["packet_digest"], proposal(packet))["status"] == "local" + with pytest.raises(TaskLearningError, match="verified knowledge slice"): + service.prepare("other-task", "unknown", "a" * 40, lessons()) + + +def test_validator_failure_rolls_back_and_retains_packet(source, tmp_path): + (source / "knowledge/tools/check_wiki_lint.py").write_text("raise SystemExit(1)\n") + git(source, "add", ".") + git(source, "commit", "-qm", "failing validator") + service, packet = prepared(source, tmp_path) + result = service.submit("private-chat-123", packet["packet_digest"], proposal(packet)) + assert result["status"] == "validator_failed" and result["validation"]["rolled_back"] + assert service.status("private-chat-123")["packet_digest"] == packet["packet_digest"] + checkout = service._checkout(service._task("private-chat-123")) + assert (checkout / PAGE).read_text() == PAGE_TEXT + + +def test_publication_requires_optin_and_both_flags(source, monkeypatch): + def unavailable(*_): + raise AssertionError("publication must not call the network") + monkeypatch.setattr("infermatrix_copilot.knowledge_service.learning_publication._run", unavailable) + local = LearningPublisher({}).publish(source, task_digest="a" * 64, head="b" * 40, + packet_digest="c" * 64, rules=1, outcomes={}) + assert local["status"] == "local" + monkeypatch.setattr("infermatrix_copilot.knowledge_service.learning_publication._run", lambda command, workspace: "main") + for flags in ({}, {"ALLOW_PUSH": "1"}, {"ALLOW_POST": "1"}): + result = LearningPublisher({"KNOWLEDGE_LEARNING_PUBLICATION": "draft_pr", + "KNOWLEDGE_LEARNING_REPOSITORY": "owner/knowledge", **flags}).publish(source, + task_digest="a" * 64, head="b" * 40, packet_digest="c" * 64, rules=1, outcomes={}) + assert result["status"] == "publication_blocked" + + +def test_failed_upload_retained_and_retry_reuses_applied_commit(source, tmp_path, monkeypatch): + service, packet = prepared(source, tmp_path) + def fail(*_args, **_kwargs): + raise LearningPublicationError("upload failed") + monkeypatch.setattr(LearningPublisher, "publish", fail) + result = service.submit("private-chat-123", packet["packet_digest"], proposal(packet)) + assert result["status"] == "publication_failed" and result["applied"] == 1 + head = result["head_sha"] + monkeypatch.setattr(LearningPublisher, "publish", lambda *_args, **_kwargs: + {"status": "draft_pr", "url": "https://github.com/owner/knowledge/pull/3"}) + retried = TaskLearningService(tmp_path / "state", source).submit("private-chat-123", packet["packet_digest"], proposal(packet)) + assert retried["status"] == "draft_pr" and retried["head_sha"] == head + assert git(Path(result["workspace"]), "rev-list", "--count", "HEAD") == "2" + + +def test_publisher_create_only_push_and_pr_recovery_do_not_publish_private_context(source, monkeypatch): + calls, reviews = [], [] + head, digest = "b" * 40, "c" * 64 + def run(command, workspace): + calls.append(command) + if command[:3] == ["git", "check-ref-format", "--branch"]: + return "main" + if command[:3] == ["gh", "pr", "list"]: + return json.dumps(reviews) + if command[:3] == ["git", "rev-parse", "HEAD"]: + return head + if command[:3] == ["git", "rev-parse", "HEAD^"]: + return "d" * 40 + if command[:2] == ["git", "diff"]: + return PAGE + if command[:2] == ["git", "merge-base"]: + return "d" * 40 + if command[:3] == ["gh", "pr", "create"]: + body = Path(command[-1]).read_text() + assert "positive" in body and "negative" in body + assert "source pin: `" + "e" * 40 + "`" in body + assert "private-chat-123" not in body and str(source) not in body + reviews.append({"url": "https://github.com/owner/knowledge/pull/4", "headRefOid": head, + "baseRefName": "main", "body": body, "isDraft": True, "state": "OPEN"}) + raise LearningPublicationError("response lost after PR creation") + return "" + monkeypatch.setattr("infermatrix_copilot.knowledge_service.learning_publication._run", run) + publisher = LearningPublisher({"KNOWLEDGE_LEARNING_PUBLICATION": "draft_pr", + "KNOWLEDGE_LEARNING_REPOSITORY": "owner/knowledge", "ALLOW_PUSH": "1", "ALLOW_POST": "1"}) + options = {"task_digest": "a" * 64, "head": head, "packet_digest": digest, "rules": 1, + "source_pin": "e" * 40, "source_repository": "x", + "outcomes": {"positive": 1, "negative": 1}, "base_sha": "d" * 40, + "documents": {PAGE: hashlib.sha256((source / PAGE).read_bytes()).hexdigest()}} + first = publisher.publish(source, **options) + assert first["status"] == "draft_pr" + assert publisher.publish(source, **options) == first + pushes = [c for c in calls if c[:2] == ["git", "push"]] + assert len(pushes) == 1 + assert pushes[0][-1] == "--force-with-lease=knowledge/chat-" + "a" * 24 + ":" + assert len([c for c in calls if c[:3] == ["gh", "pr", "create"]]) == 1 + + +def test_existing_remote_branch_cannot_be_overwritten(source, monkeypatch): + calls = [] + def run(command, workspace): + calls.append(command) + if command[:3] == ["git", "check-ref-format", "--branch"]: + return "main" + if command[:3] == ["gh", "pr", "list"]: + return "[]" + if command[:3] == ["git", "rev-parse", "HEAD"]: + return "b" * 40 + if command[:3] == ["git", "rev-parse", "HEAD^"]: + return "d" * 40 + if command[:2] == ["git", "status"] or command[:2] == ["git", "fetch"]: + return "" + if command[:2] == ["git", "diff"]: + return PAGE + if command[:2] == ["git", "merge-base"]: + return "d" * 40 + if command[:2] == ["git", "ls-remote"]: + return "e" * 40 + "\trefs/heads/knowledge/chat-" + "a" * 24 + raise AssertionError("conflicting branch must never be pushed or reviewed") + monkeypatch.setattr("infermatrix_copilot.knowledge_service.learning_publication._run", run) + publisher = LearningPublisher({"KNOWLEDGE_LEARNING_PUBLICATION": "draft_pr", + "KNOWLEDGE_LEARNING_REPOSITORY": "owner/knowledge", "ALLOW_PUSH": "1", "ALLOW_POST": "1"}) + with pytest.raises(LearningPublicationError, match="different work"): + publisher.publish(source, task_digest="a" * 64, head="b" * 40, packet_digest="c" * 64, rules=1, outcomes={}, + base_sha="d" * 40, documents={PAGE: hashlib.sha256((source / PAGE).read_bytes()).hexdigest()}) + assert not any(command[:2] == ["git", "push"] for command in calls) + + +def test_feature_branch_ancestry_never_enters_a_knowledge_pr(source, tmp_path, monkeypatch): + destination_base = git(source, "rev-parse", "HEAD") + (source / "unrelated-feature.py").write_text("unrelated = True\n") + git(source, "add", ".") + git(source, "commit", "-qm", "unfinished user feature") + feature_base = git(source, "rev-parse", "HEAD") + service, packet = prepared(source, tmp_path) + result = service.submit(packet["task_id"], packet["packet_digest"], proposal(packet)) + checkout = Path(result["workspace"]) + from infermatrix_copilot.knowledge_service import learning_publication + original = learning_publication._run + calls = [] + def run(command, workspace): + calls.append(command) + if command[:2] == ["git", "fetch"]: + git(workspace, "update-ref", command[-1].split(":", 1)[1], destination_base) + return "" + if command[0] == "gh" or command[:2] == ["git", "push"]: + raise AssertionError("unrelated ancestry must fail before any review or push") + return original(command, workspace) + monkeypatch.setattr(learning_publication, "_run", run) + publisher = LearningPublisher({"KNOWLEDGE_LEARNING_PUBLICATION": "draft_pr", + "KNOWLEDGE_LEARNING_REPOSITORY": "owner/knowledge", "ALLOW_PUSH": "1", "ALLOW_POST": "1"}) + with pytest.raises(LearningPublicationError, match="outside the destination"): + publisher.publish(checkout, task_digest=packet["task_key"], head=result["head_sha"], + packet_digest=packet["packet_digest"], rules=1, outcomes={}, base_sha=feature_base, + documents={PAGE: hashlib.sha256((checkout / PAGE).read_bytes()).hexdigest()}) + assert not any(command[:2] == ["git", "push"] for command in calls) diff --git a/test/test_chat_learning_review.py b/test/test_chat_learning_review.py new file mode 100644 index 000000000..0f600cd0c --- /dev/null +++ b/test/test_chat_learning_review.py @@ -0,0 +1,123 @@ +"""Fault-injection regressions for task-learning restart boundaries.""" + +from pathlib import Path + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") +from test_chat_knowledge_learning import ( + git, + lessons, + prepared, + proposal, +) +from test_chat_knowledge_learning import ( + source as _source_fixture, +) + +from infermatrix_copilot.knowledge_service.learning import ( + TaskLearningError, + TaskLearningService, +) + +source = _source_fixture + + +class InterruptedLearning(RuntimeError): + pass + + +def test_prepare_recovers_after_worktree_creation_before_database_completion(source, tmp_path, monkeypatch): + state = tmp_path / "state" + service = TaskLearningService(state, source) + original = service._git + + def interrupt(root, *args): + result = original(root, *args) + if args[:2] == ("worktree", "add"): + raise InterruptedLearning("transport lost after worktree creation") + return result + + monkeypatch.setattr(service, "_git", interrupt) + with pytest.raises(InterruptedLearning): + service.prepare("interrupted-prepare", "x", "a" * 40, lessons()) + restarted = TaskLearningService(state, source) + packet = restarted.prepare("interrupted-prepare", "x", "a" * 40, lessons()) + assert packet["status"] == "prepared" + checkout = restarted._checkout(packet["task_key"]) + assert checkout.is_dir() + assert git(checkout, "rev-parse", "HEAD") == git(source, "rev-parse", "HEAD") + assert git(checkout, "status", "--porcelain") == "" + + +@pytest.mark.parametrize("boundary", ["after_add", "after_commit"]) +def test_submit_recovers_exact_application_after_git_side_effect(source, tmp_path, monkeypatch, boundary): + service, packet = prepared(source, tmp_path) + rules = proposal(packet) + original = service._git + + def interrupt(root, *args): + result = original(root, *args) + matched = args[0] == "add" if boundary == "after_add" else "commit" in args and "-m" in args + if matched: + raise InterruptedLearning("transport lost after " + boundary) + return result + + monkeypatch.setattr(service, "_git", interrupt) + with pytest.raises(InterruptedLearning): + service.submit(packet["task_id"], packet["packet_digest"], rules) + checkout = service._checkout(packet["task_key"]) + committed = git(checkout, "rev-parse", "HEAD") if boundary == "after_commit" else None + restarted = TaskLearningService(tmp_path / "state", source) + result = restarted.submit(packet["task_id"], packet["packet_digest"], rules) + assert result["status"] == "local" + assert git(Path(result["workspace"]), "rev-list", "--count", "HEAD") == "2" + assert git(checkout, "status", "--porcelain") == "" + if committed: + assert result["head_sha"] == committed + + +def test_modified_validator_and_staged_source_work_cannot_run_or_enter_learning_commit(source, tmp_path): + service, packet = prepared(source, tmp_path) + checkout = service._checkout(packet["task_key"]) + executed = tmp_path / "modified-validator-executed" + validator = checkout / "knowledge/tools/check_wiki_lint.py" + validator.write_text(f"from pathlib import Path\nPath({str(executed)!r}).write_text('executed')\n") + git(checkout, "add", "knowledge/tools/check_wiki_lint.py") + try: + result = service.submit(packet["task_id"], packet["packet_digest"], proposal(packet)) + except TaskLearningError: + result = None + assert not executed.exists(), "changed validator code must be refused before execution" + if result is not None: + assert result["status"] in {"stale", "rejected"} + + +def test_interrupted_recovery_preserves_unknown_staged_owner_page(source, tmp_path, monkeypatch): + service, packet = prepared(source, tmp_path) + rules = proposal(packet) + original = service._git + + def interrupt(root, *args): + result = original(root, *args) + if args[0] == "add": + raise InterruptedLearning("transport lost after staging generated rules") + return result + + monkeypatch.setattr(service, "_git", interrupt) + with pytest.raises(InterruptedLearning): + service.submit(packet["task_id"], packet["packet_digest"], rules) + checkout = service._checkout(packet["task_key"]) + page = checkout / "knowledge/repos/x/rules.md" + generated = page.read_text() + page.write_text(generated + "\nUnknown user version retained only in the index.\n") + git(checkout, "add", "--", "knowledge/repos/x/rules.md") + staged_before = git(checkout, "rev-parse", ":knowledge/repos/x/rules.md") + # The working tree alone still matches the exact attempted generation. + page.write_text(generated) + restarted = TaskLearningService(tmp_path / "state", source) + result = restarted.submit(packet["task_id"], packet["packet_digest"], rules) + assert result["status"] == "stale" + assert git(checkout, "rev-parse", ":knowledge/repos/x/rules.md") == staged_before + assert "Unknown user version retained only in the index" in git(checkout, "show", ":knowledge/repos/x/rules.md") + assert page.read_text() == generated diff --git a/test/test_feedback_collection_integration.py b/test/test_feedback_collection_integration.py new file mode 100644 index 000000000..076f78233 --- /dev/null +++ b/test/test_feedback_collection_integration.py @@ -0,0 +1,189 @@ +"""Real HTTP collector exercised through provider, SDK, CLI and MCP entry points.""" + +from contextlib import contextmanager +from threading import Thread + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +from infermatrix_copilot.knowledge_service.feedback import ( + FeedbackError, + KnowledgeFeedbackStore, +) +from infermatrix_copilot.knowledge_service.feedback_http import create_server +from infermatrix_copilot.knowledge_service.feedback_hub import FeedbackHubStore +from infermatrix_copilot.knowledge_service.feedback_sync import ( + FeedbackSyncClient, + FeedbackSyncConfig, + FeedbackSyncError, +) +from infermatrix_copilot.knowledge_view import KnowledgeView +from infermatrix_copilot.sdk.v1 import DirectClient, KnowledgeFeedbackClient + +TOKEN = "collector-integration-secret-1234567890" +RULE = "## CONTRACT-1a — Verify the result\n\nCheck the result before accepting the task outcome.\n" +PATH = "repos/demo/rules.md" + + +@contextmanager +def running_collector(state): + store = FeedbackHubStore(state) + server = create_server(store, TOKEN) + thread = Thread(target=server.serve_forever, kwargs={"poll_interval": 0.01}, daemon=True) + thread.start() + try: + yield store, f"http://127.0.0.1:{server.server_address[1]}" + finally: + server.shutdown() + server.server_close() + thread.join(timeout=5) + + +@pytest.fixture +def knowledge(tmp_path, monkeypatch): + root = tmp_path / "knowledge" + (root / "repos/demo").mkdir(parents=True) + (root / "repos/demo/_index.md").write_text("# Demo\n") + (root / PATH).write_text("# Rules\n\n" + RULE) + view = KnowledgeView(root, "integration-snapshot") + monkeypatch.setenv("KNOWLEDGE_MAINTENANCE_ENABLED", "0") + monkeypatch.setattr(KnowledgeView, "current", classmethod(lambda cls: view)) + return view + + +def issue(store, view, task): + return store.issue_delivery(task_id=task, repository="demo", view=view, + documents=[{"path": PATH, "content": view.read_text(PATH)}]) + + +def grade(receipt, score=1): + target = next(row for row in receipt["targets"] if row["kind"] == "rule") + return {"target_id": target["target_id"], "score": score, "used": True, + "reason": "The result check determined the task outcome.", + "evidence": "tests/test_contract.py::test_result passed"} + + +def test_two_hosts_retry_same_task_then_aggregate_new_tasks_and_versions(tmp_path, knowledge): + with running_collector(tmp_path / "hub") as (hub, url): + config = FeedbackSyncConfig(url, TOKEN) + first = KnowledgeFeedbackStore(tmp_path / "host-a", sync_config=config) + second = KnowledgeFeedbackStore(tmp_path / "host-b", sync_config=config) + receipt = issue(first, knowledge, "chat-uuid-shared-task") + first.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], ratings=[grade(receipt)]) + + # Same unchanged rule, different page/snapshot provenance on another host. + (knowledge.root / PATH).write_text("# Revised navigation\n\n" + RULE) + newer_view = KnowledgeView(knowledge.root, "new-navigation-snapshot") + duplicate = issue(second, newer_view, receipt["task_id"]) + assert duplicate["delivery_id"] != receipt["delivery_id"] + assert grade(duplicate)["target_id"] == grade(receipt)["target_id"] + result = second.record(task_id=duplicate["task_id"], delivery_id=duplicate["delivery_id"], + ratings=[grade(duplicate)]) + assert result["sync"]["status"] == "acknowledged" + assert hub.report()["total_ratings"] == 1 + + negative = issue(second, newer_view, "another-chat-uuid") + second.record(task_id=negative["task_id"], delivery_id=negative["delivery_id"], + ratings=[grade(negative, -1)]) + report = first.report_for_scope(repository="demo") + assert report["scope"] == "central" + assert report["total_ratings"] == 2 + target = report["targets"][0] + assert (target["positive_count"], target["negative_count"], target["distinct_tasks"]) == (1, 1, 2) + assert target["net_score"] == target["mean_score"] == 0 + + (knowledge.root / PATH).write_text("# Rules\n\n" + RULE.replace("Check the result", "Validate both results")) + changed = issue(second, newer_view, "changed-version-task-uuid") + assert grade(changed)["target_id"] != grade(receipt)["target_id"] + second.record(task_id=changed["task_id"], delivery_id=changed["delivery_id"], ratings=[grade(changed)]) + assert hub.report()["total_targets"] == 2 + assert hub.report()["total_ratings"] == 3 + # The service itself never queues feedback back to another collector. + with hub._db() as db: + assert db.execute("SELECT COUNT(*) FROM feedback_outbox").fetchone()[0] == 0 + + +def test_auth_failure_restart_and_lost_ack_do_not_lose_or_duplicate_grades(tmp_path, knowledge, monkeypatch): + with running_collector(tmp_path / "hub") as (hub, url): + state = tmp_path / "host" + wrong = KnowledgeFeedbackStore(state, sync_config=FeedbackSyncConfig(url, "wrong-secret-" * 4)) + receipt = issue(wrong, knowledge, "retry-chat-uuid") + result = wrong.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], ratings=[grade(receipt)]) + assert result["sync"]["status"] == "pending" + assert wrong.report()["total_ratings"] == 1 + assert hub.report()["total_ratings"] == 0 + + restarted = KnowledgeFeedbackStore(state, sync_config=FeedbackSyncConfig(url, TOKEN)) + request = FeedbackSyncClient._request + + def lose_ack(self, path, payload=None): + result = request(self, path, payload) + if payload is not None: + raise FeedbackSyncError("simulated response loss after server commit") + return result + + monkeypatch.setattr(FeedbackSyncClient, "_request", lose_ack) + assert restarted.sync_pending()["status"] == "pending" + assert hub.report()["total_ratings"] == 1 + monkeypatch.setattr(FeedbackSyncClient, "_request", request) + assert restarted.sync_pending()["status"] == "acknowledged" + assert restarted.sync_pending()["attempted_count"] == 0 + assert hub.report()["total_ratings"] == 1 + + # A failed team query must never masquerade as the successful local report. + with pytest.raises(FeedbackError, match="unavailable"): + restarted.report_for_scope() + assert restarted.report_for_scope(scope="local")["total_ratings"] == 1 + assert FeedbackHubStore(tmp_path / "hub").report()["total_ratings"] == 1 + + +def test_live_collector_routes_sdk_mcp_and_learning_cli(tmp_path, knowledge, monkeypatch, capsys, accept_learning_agreement): + from test_thin_mcp_server import _fake_mcp + + from infermatrix_copilot.cli.entry import main + + with running_collector(tmp_path / "hub") as (hub, url): + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_URL", url) + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_TOKEN", TOKEN) + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "sdk-host")) + accept_learning_agreement() + receipt = DirectClient().read_document(PATH, task_id="sdk-chat-uuid").knowledge_feedback + client = KnowledgeFeedbackClient() + result = client.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], ratings=[grade(receipt)]) + assert result["sync"]["status"] == "acknowledged" + assert client.report()["scope"] == "central" + explicit = KnowledgeFeedbackClient(state_dir=tmp_path / "sdk-host") + assert explicit.report()["scope"] == "central" + assert explicit.sync_status()["status"] == "acknowledged" + + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "mcp-host")) + accept_learning_agreement() + mcp, _ = _fake_mcp(monkeypatch) + packet = mcp.tools["doc_read"](path=PATH, repo="demo", task_id="mcp-chat-uuid") + receipt = packet["knowledge_feedback"] + result = mcp.tools["knowledge_feedback"](task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], + ratings=[grade(receipt, -1)]) + assert result["sync"]["status"] == "acknowledged" + assert mcp.tools["knowledge_feedback_report"](repo="demo")["total_ratings"] == 2 + assert mcp.tools["knowledge_feedback_report"](repo="demo", scope="local")["total_ratings"] == 1 + assert mcp.tools["knowledge_feedback_sync"](action="status")["pending_count"] == 0 + assert mcp.tools["knowledge_feedback_sync"]()["attempted_count"] == 0 + + assert main(["learning", "report", "--scope", "central", "--repo", "demo"]) == 0 + assert '"total_ratings": 2' in capsys.readouterr().out + assert main(["learning", "sync-status"]) == 0 + assert '"acknowledged"' in capsys.readouterr().out + assert hub.report()["total_ratings"] == 2 + + +def test_credential_in_evidence_key_is_blocked_before_automatic_upload(tmp_path, knowledge): + with running_collector(tmp_path / "hub") as (hub, url): + store = KnowledgeFeedbackStore(tmp_path / "host", sync_config=FeedbackSyncConfig(url, TOKEN)) + receipt = issue(store, knowledge, "privacy-chat-uuid") + rating = {**grade(receipt), "evidence": {"ghp_" + "A" * 30: "test passed"}} + result = store.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], ratings=[rating]) + assert result["sync"]["status"] == "pending" + assert result["sync"]["last_error"] == "privacy_blocked" + assert store.report()["total_ratings"] == 1 + assert hub.report()["total_ratings"] == 0 diff --git a/test/test_feedback_http.py b/test/test_feedback_http.py new file mode 100644 index 000000000..c5c0543bd --- /dev/null +++ b/test/test_feedback_http.py @@ -0,0 +1,190 @@ +import copy +import http.client +import json +import socket +import threading + +import pytest + +from infermatrix_copilot.knowledge_service.agreement import AgreementStore +from infermatrix_copilot.knowledge_service.feedback import KnowledgeFeedbackStore +from infermatrix_copilot.knowledge_service.feedback_http import ( + MAX_BODY_BYTES, + create_server, +) +from infermatrix_copilot.knowledge_service.feedback_hub import FeedbackHubStore +from infermatrix_copilot.knowledge_service.feedback_server_cli import main +from infermatrix_copilot.knowledge_view import KnowledgeView + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +TOKEN = "provider-a-" + "a" * 40 +ROTATED_TOKEN = "provider-b-" + "b" * 40 +PAGE = "# Rules\n\n## FIRST-1a — Preserve contracts\n\nKeep the source contract intact when modifying the call.\n" +DOCUMENT = "repos/r/rules.md" + + +@pytest.fixture +def running(tmp_path): + root = tmp_path / "knowledge" + (root / "repos/r").mkdir(parents=True) + (root / DOCUMENT).write_text(PAGE) + provider = KnowledgeFeedbackStore(tmp_path / "provider") + receipt = provider.issue_delivery(task_id="host-a:task-1", repository="r", view=KnowledgeView(root, "snapshot-1"), + documents=[{"path": DOCUMENT, "content": PAGE}]) + hub = FeedbackHubStore(tmp_path / "hub") + server = create_server(hub, token=(TOKEN, ROTATED_TOKEN)) + server.test_agreement = AgreementStore.from_env(state_dir=provider.state_dir).attestation() + thread = threading.Thread(target=server.serve_forever, kwargs={"poll_interval": 0.01}, daemon=True) + thread.start() + try: + yield server, hub, receipt, provider, root + finally: + server.shutdown() + server.server_close() + thread.join(timeout=3) + + +def vote(target, **kwargs): + return {"target_id": target["target_id"], "score": 1, "used": True, + "reason": "The rule guided the verified fix.", "evidence": ["Focused source contract test passed."], **kwargs} + + +def request(server, method="GET", path="/v1/feedback/report", payload=None, token=TOKEN, headers=None): + supplied = {"Authorization": "Bearer " + token} if token else {} + if payload is not None: + supplied["Content-Type"] = "application/json" + if isinstance(payload, dict) and {"receipt", "ratings"} <= set(payload): + payload = {"agreement": server.test_agreement, **payload} + supplied.update(headers or {}) + body = json.dumps(payload).encode() if isinstance(payload, dict) else payload + connection = http.client.HTTPConnection(*server.server_address, timeout=3) + try: + connection.request(method, path, body=body, headers=supplied) + response = connection.getresponse() + body = response.read() + return response.status, json.loads(body) if body else None, dict(response.getheaders()) + finally: + connection.close() + + +def raw_request(server, body): + with socket.create_connection(server.server_address, timeout=3) as connection: + connection.sendall(body) + connection.shutdown(socket.SHUT_WR) + chunks = [] + while chunk := connection.recv(65536): + chunks.append(chunk) + header, body = b"".join(chunks).split(b"\r\n\r\n", 1) + return int(header.split(b" ")[1]), json.loads(body) + + +def test_authenticated_shared_delivery_vote_report_and_global_rotation_dedup(running): + server, hub, receipt, provider, root = running + target = receipt["targets"][0] + event = {"receipt": receipt, "ratings": [vote(target)]} + status, result, headers = request(server, "POST", "/v1/feedback/events", event) + assert status == 200 and set(result) == {"task_id", "delivery_id", "ratings"} + assert headers["Cache-Control"] == "no-store" + assert request(server, "POST", "/v1/feedback/events", event, token=ROTATED_TOKEN)[1] == result + another = provider.issue_delivery(task_id=receipt["task_id"], repository="r", view=KnowledgeView(root, "snapshot-1"), + documents=[{"path": DOCUMENT, "content": "Wrapper\n" + PAGE}]) + assert request(server, "POST", "/v1/feedback/events", {"receipt": another, "ratings": [vote(target)]}, token=ROTATED_TOKEN)[0] == 200 + status, report, _ = request(server, path="/v1/feedback/report?repo=r&limit=1") + assert status == 200 and report["total_ratings"] == 1 + assert report == hub.report(repository="r", limit=1) + + +def test_conflict_is_409_and_new_votes_in_same_batch_are_rolled_back(running): + server, hub, receipt, *_ = running + first, second = receipt["targets"][:2] + assert request(server, "POST", "/v1/feedback/events", {"receipt": receipt, "ratings": [vote(first)]})[0] == 200 + status, response, _ = request(server, "POST", "/v1/feedback/events", { + "receipt": receipt, "ratings": [vote(second), vote(first, score=-1)]}) + assert status == 409 and response["error"]["code"] == "feedback_conflict" + assert hub.report()["total_ratings"] == 1 + + +def test_authentication_precedes_body_read_and_parse_and_health_has_no_data(running, capsys): + server, hub, *_ = running + status, _, headers = request(server, "POST", "/v1/feedback/events", b"not-json", token="private-invalid-token") + assert status == 401 and headers["WWW-Authenticate"].startswith("Bearer") + # A client that never sends the declared large body must still get 401 now. + status, _ = raw_request(server, b"POST /v1/feedback/events HTTP/1.1\r\nHost: localhost\r\nContent-Length: 999999\r\n\r\n") + assert status == 401 + assert request(server, token="")[0] == 401 + assert request(server, path="/healthz", token="")[1] == {"ok": True} + assert not hub.path.exists() + assert "private-invalid-token" not in capsys.readouterr().err + + +@pytest.mark.parametrize("body", [b'{"receipt":null,"receipt":{},"ratings":[]}', b'{"receipt":NaN,"ratings":[]}', b'[]', b'\xff', b'{']) +def test_malformed_json_is_rejected_without_storage(running, body): + server, hub, *_ = running + assert request(server, "POST", "/v1/feedback/events", body, headers={"Content-Type": "application/json"})[0] == 400 + assert not hub.path.exists() + + +def test_transport_bounds_and_framing_are_enforced_before_ingest(running): + server, hub, *_ = running + prefix = b"POST /v1/feedback/events HTTP/1.1\r\nHost: localhost\r\nAuthorization: Bearer " + TOKEN.encode() + b"\r\nContent-Type: application/json\r\n" + cases = [ + (b"Content-Length: " + str(MAX_BODY_BYTES + 1).encode() + b"\r\n\r\n", 413), + (b"Content-Length: 2\r\nContent-Length: 2\r\n\r\n{}", 400), + (b"Content-Length: -1\r\n\r\n", 400), + (b"Transfer-Encoding: chunked\r\n\r\n0\r\n\r\n", 400), + (b"\r\n", 411), + (b"Content-Length: 100\r\n\r\n{}", 400), + ] + for suffix, expected in cases: + assert raw_request(server, prefix + suffix)[0] == expected + assert request(server, "POST", "/v1/feedback/events", b"{}", headers={"Content-Type": "text/plain"})[0] == 415 + assert not hub.path.exists() + + +def test_tampered_receipt_strict_rating_schema_and_private_evidence_are_400(running): + server, hub, receipt, *_ = running + target = receipt["targets"][0] + tampered = copy.deepcopy(receipt) + tampered["task_id"] = "another-task" + cases = [ + {"receipt": tampered, "ratings": [vote(target)]}, + {"receipt": receipt, "ratings": [vote(target, score=True)]}, + {"receipt": receipt, "ratings": [vote(target, transcript="raw")]}, + {"receipt": receipt, "ratings": [vote(target, evidence="ghp_" + "a" * 30)]}, + {"receipt": receipt, "ratings": [vote(target)], "workspace": "/private/path"}, + ] + for event in cases: + status, body, _ = request(server, "POST", "/v1/feedback/events", event) + assert status == 400 + assert "ghp_" not in json.dumps(body) + assert hub.report()["total_ratings"] == 0 + + +@pytest.mark.parametrize("path", ["/v1/feedback/report?limit=0", "/v1/feedback/report?limit=true", "/v1/feedback/report?repo=a&repo=b", "/v1/feedback/report?unknown=x"]) +def test_report_query_validation(running, path): + assert request(running[0], path=path)[0] == 400 + + +def test_unknown_routes_cannot_register_receipts_and_no_redirects(running): + server, hub, receipt, *_ = running + assert request(server, "POST", "/v1/feedback/deliveries", {"receipt": receipt})[0] == 404 + assert request(server, path="/v1/feedback/report/")[0] == 404 + assert request(server, "POST", "/v1/feedback/events?next=https://example.test", {"receipt": receipt, "ratings": []})[0] == 400 + assert not hub.path.exists() + + +def test_safe_server_configuration_and_cli_startup_failure(tmp_path, monkeypatch, capsys): + store = FeedbackHubStore(tmp_path / "hub") + for kwargs in ({"token": "short"}, {"token": TOKEN, "host": "0.0.0.0"}, + {"token": TOKEN, "public_url": "http://example.test"}, + {"token": TOKEN, "public_url": "https://user:secret@example.test"}): + with pytest.raises(ValueError): + create_server(store, **kwargs) + server = create_server(store, TOKEN, host="0.0.0.0", public_url="https://feedback.example.test") + server.server_close() + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_SERVER_TOKEN", "private-short-token") + assert main(["--state-dir", str(tmp_path / "cli")]) == 2 + output = capsys.readouterr() + assert "startup_failed" in output.err and "private-short-token" not in output.err + assert not (tmp_path / "cli").exists() diff --git a/test/test_feedback_hub.py b/test/test_feedback_hub.py new file mode 100644 index 000000000..573a81d71 --- /dev/null +++ b/test/test_feedback_hub.py @@ -0,0 +1,186 @@ +import copy +import sqlite3 +from concurrent.futures import ThreadPoolExecutor + +import pytest + +from infermatrix_copilot.knowledge_service.agreement import AgreementStore +from infermatrix_copilot.knowledge_service.feedback import ( + FeedbackError, + KnowledgeFeedbackStore, + _digest, +) +from infermatrix_copilot.knowledge_service.feedback_hub import ( + FeedbackConflict, + FeedbackHubStore, + validate_receipt, +) +from infermatrix_copilot.knowledge_view import KnowledgeView, build_manifest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +FIRST = "## FIRST-1a — Preserve the source contract\n\nKeep the source contract intact when modifying the call.\n\n" +SECOND = "## SECOND-1a — Preserve the independent contract\n\nKeep the independent contract intact when changing the return.\n" +PAGE = "# Rules\n\n" + FIRST + SECOND +DOCUMENT = "repos/r/rules.md" + + +@pytest.fixture +def provider(tmp_path): + root = tmp_path / "knowledge" + (root / "repos/r").mkdir(parents=True) + (root / DOCUMENT).write_text(PAGE) + return KnowledgeFeedbackStore(tmp_path / "provider"), KnowledgeView(root, "snapshot-1") + + +@pytest.fixture +def agreement(provider): + return AgreementStore.from_env(state_dir=provider[0].state_dir).attestation() + + +def issue(provider, task="task-1", content=PAGE): + store, view = provider + return store.issue_delivery(task_id=task, repository="r", view=view, + documents=[{"path": DOCUMENT, "content": content}]) + + +def vote(target, **kwargs): + return {"target_id": target["target_id"], "score": 1, "used": True, + "reason": "The rule guided the verified fix.", "evidence": ["Focused source contract test passed."], **kwargs} + + +def redigest(receipt): + receipt["delivery_id"] = _digest({key: value for key, value in receipt.items() if key != "delivery_id"}) + return receipt + + +def test_shared_import_uses_existing_identity_and_is_durable(provider, tmp_path, agreement): + receipt = issue(provider) + hub = FeedbackHubStore(tmp_path / "hub") + target = next(target for target in receipt["targets"] if target["kind"] == "rule") + result = hub.ingest(receipt=receipt, ratings=[vote(target)], agreement=agreement) + assert result["ratings"][0]["feedback_id"] == _digest(["task-1", target["target_id"]]) + restarted = FeedbackHubStore(hub.state_dir) + assert restarted.ingest(receipt=receipt, ratings=[vote(target)], agreement=agreement) == result + second = issue(provider, content="Presentation wrapper\n" + PAGE) + assert second["delivery_id"] != receipt["delivery_id"] + restarted.ingest(receipt=second, ratings=[vote(target)], agreement=agreement) + assert restarted.report()["total_ratings"] == 1 + with sqlite3.connect(hub.path) as db: + assert db.execute("SELECT COUNT(*) FROM feedback_outbox").fetchone()[0] == 0 + assert FIRST.encode() not in hub.path.read_bytes() + assert not (hub.path.stat().st_mode & 0o077) + + +def test_multiple_tasks_and_versions_aggregate_like_local_report(provider, tmp_path, agreement): + hub = FeedbackHubStore(tmp_path / "hub") + local = provider[0] + for task, score in (("host-a:task-1", 1), ("host-b:task-2", -1), ("host-a:task-3", 1)): + receipt = issue(provider, task=task) + targets = [target for target in receipt["targets"] if target.get("block_id") == "FIRST-1a"] + ratings = [vote(targets[0], score=score)] + local.record(task_id=task, delivery_id=receipt["delivery_id"], ratings=ratings) + hub.ingest(receipt=receipt, ratings=ratings, agreement=agreement) + changed = FIRST.replace("Keep the source", "Always preserve the source") + (provider[1].root / DOCUMENT).write_text("# Rules\n\n" + changed + SECOND) + receipt = issue(provider, task="host-c:task-4", content=changed) + target = next(target for target in receipt["targets"] if target["kind"] == "rule") + local.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], ratings=[vote(target)]) + hub.ingest(receipt=receipt, ratings=[vote(target)], agreement=agreement) + for repo, limit in (("", 100), ("r", 1), ("another", 100)): + assert hub.report(repository=repo, limit=limit) == local.report(repository=repo, limit=limit) + row = next(target for target in hub.report()["targets"] if target["rating_count"] == 3) + assert (row["positive_count"], row["negative_count"], row["distinct_tasks"], row["mean_score"]) == (2, 1, 3, pytest.approx(1 / 3)) + + +def test_concurrent_shared_imports_deduplicate_and_conflict_atomically(provider, tmp_path, agreement): + receipt = issue(provider) + target, another = receipt["targets"][:2] + hub = FeedbackHubStore(tmp_path / "hub") + def ingest(_): + return FeedbackHubStore(hub.state_dir).ingest(receipt=receipt, ratings=[vote(target)], agreement=agreement) + with ThreadPoolExecutor(max_workers=6) as pool: + results = list(pool.map(ingest, range(12))) + assert all(result == results[0] for result in results) + with pytest.raises(FeedbackConflict, match="immutable"): + hub.ingest(receipt=receipt, ratings=[vote(another), vote(target, score=-1)], agreement=agreement) + assert hub.report()["total_ratings"] == 1 + + +@pytest.mark.parametrize("change", [ + lambda r: r.update(protocol="feedback/other"), + lambda r: r.update(task_id=" task "), + lambda r: r.update(tree_sha256="f" * 40), + lambda r: r.update(delivery_id="0" * 64), + lambda r: r.update(transcript="private chat"), + lambda r: r["documents"][0].update(path="../outside.md"), + lambda r: r["documents"][0].update(path="C:/outside.md"), + lambda r: r["documents"][0].update(delivered_chars=True), + lambda r: r["documents"].append(copy.deepcopy(r["documents"][0])), + lambda r: r["targets"][0].update(repository="another"), + lambda r: r["targets"][0].update(snapshot="another"), + lambda r: r["targets"][0].update(page_sha256="b" * 64), + lambda r: r["targets"][0].update(content_sha256="b" * 64), + lambda r: r["targets"][1].update(unit_id="b" * 64), + lambda r: r["targets"][1].update(block_id="OTHER-1a"), + lambda r: r["targets"][1].update(upstream_pins=["b" * 40, "a" * 40]), + lambda r: r["targets"][1].update(target_id="b" * 64), + lambda r: r["targets"][1].update(kind=[]), + lambda r: r["targets"].append(copy.deepcopy(r["targets"][0])), + lambda r: r["targets"].pop(0), +]) +def test_receipt_metadata_cannot_be_rebound_even_with_recomputed_envelope(provider, tmp_path, change, agreement): + receipt = copy.deepcopy(issue(provider)) + change(receipt) + if receipt.get("delivery_id") != "0" * 64: + redigest(receipt) + hub = FeedbackHubStore(tmp_path / "hub") + with pytest.raises(FeedbackError): + hub.ingest(receipt=receipt, ratings=[], agreement=agreement) + assert not hub.path.exists() + + +def test_receipt_cannot_grant_undelivered_sibling(provider, tmp_path, agreement): + full = issue(provider) + partial = issue(provider, content=FIRST) + sibling = next(target for target in full["targets"] if target.get("block_id") == "SECOND-1a") + hub = FeedbackHubStore(tmp_path / "hub") + with pytest.raises(FeedbackError, match="not delivered"): + hub.ingest(receipt=partial, ratings=[vote(sibling)], agreement=agreement) + assert hub.report()["total_ratings"] == 0 + + +def test_verified_manifest_receipt_and_source_pins_keep_existing_protocol(provider): + store, view = provider + pinned = "---\nsources: [https://example.test/r/blob/" + "a" * 40 + "/api.py]\n---\n" + PAGE + (view.root / DOCUMENT).write_text(pinned) + manifest = build_manifest(view.root, "activated") + verified = KnowledgeView(view.root, "activated", manifest["files"]) + receipt = issue((store, verified), content=pinned) + assert validate_receipt(receipt) == receipt + assert receipt["tree_sha256"] + assert next(target for target in receipt["targets"] if target["kind"] == "rule")["upstream_pins"] == ["a" * 40] + + +def test_private_or_noncanonical_ratings_rejected_without_partial_votes(provider, tmp_path, agreement): + receipt = issue(provider) + target = receipt["targets"][0] + hub = FeedbackHubStore(tmp_path / "hub") + for change in ({"transcript": "raw"}, {"evidence": "ghp_" + "A" * 30}, {"score": True}): + with pytest.raises(FeedbackError): + hub.ingest(receipt=receipt, ratings=[vote(target, **change)], agreement=agreement) + assert hub.report()["total_ratings"] == 0 + + +def test_noop_and_limits_and_unknown_task_delivery(provider, tmp_path, agreement): + store, view = provider + empty = store.issue_delivery(task_id="empty", repository="r", view=view, documents=[]) + hub = FeedbackHubStore(tmp_path / "hub") + assert hub.ingest(receipt=empty, ratings=[], agreement=agreement)["ratings"] == [] + for limit in (True, 0, 1001, "100"): + with pytest.raises(FeedbackError): + hub.report(limit=limit) + with pytest.raises(FeedbackError, match="not issued"): + hub.record(task_id="unknown", delivery_id=empty["delivery_id"], ratings=[]) + with sqlite3.connect(hub.path) as db: + assert db.execute("SELECT COUNT(*) FROM feedback_ratings").fetchone()[0] == 0 diff --git a/test/test_feedback_identity.py b/test/test_feedback_identity.py new file mode 100644 index 000000000..bef5e8549 --- /dev/null +++ b/test/test_feedback_identity.py @@ -0,0 +1,203 @@ +"""Public SDK deliveries retain one feedback identity across aliases and reads.""" +import shutil +import sqlite3 +from contextlib import contextmanager +from threading import Thread + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") +import yaml + +from infermatrix_copilot.kb_service.repo_spec import RepoSpec +from infermatrix_copilot.knowledge_service.feedback import KnowledgeFeedbackStore +from infermatrix_copilot.knowledge_service.feedback_http import create_server +from infermatrix_copilot.knowledge_service.feedback_hub import FeedbackHubStore +from infermatrix_copilot.knowledge_view import KnowledgeView +from infermatrix_copilot.sdk.v1 import ( + ChangedPath, + DirectClient, + DirectReviewRequest, + InvalidRequestError, + KnowledgeFeedbackClient, + RepositoryRef, + UnsupportedRepositoryError, +) + +RULE_PATH = "repos/demo-repo/rules.md" +GUIDE_PATH = "general/review/guides/simplification-audit.md" +RULE = "## CONTRACT-1a — Check the result\n\nCheck the result before accepting the task outcome.\n" +GUIDE = "## REVIEW-1a — Verify the source\n\nVerify the source before publishing a conclusion.\n" + + +@pytest.fixture +def knowledge(tmp_path, monkeypatch): + root = tmp_path / "knowledge" + files = { + "AGENTS.md": "# Knowledge navigation\n", + "README.md": "# Knowledge\n", + "general/_index.md": "# General\n", + "repos/_index.md": "# Repositories\n", + "repos/demo-repo/_index.md": "# Demo repository\n", + RULE_PATH: "# Rules\n\n" + RULE, + GUIDE_PATH: "# Review\n\n" + GUIDE, + } + spec = RepoSpec("demo-repo", aliases=("demo_repo", "owner/demo-repo"), source_pin="a" * 40) + files["_repositories.yaml"] = yaml.safe_dump({"schema_version": 1, "repos": {"demo-repo": spec.to_dict()}}) + files["repos/demo-repo/_routes.yaml"] = yaml.safe_dump({"schema_version": 1, "owners": [{ + "owner": "contract", "path": RULE_PATH, "signals": ["contract"], "scope_prefixes": ["pkg/"]}]}) + for name, content in files.items(): + path = root / name + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(content, encoding="utf-8") + view = KnowledgeView(root, "identity-snapshot") + monkeypatch.setattr(KnowledgeView, "current", classmethod(lambda cls: view)) + monkeypatch.setenv("KNOWLEDGE_MAINTENANCE_ENABLED", "0") + return view + + +def request(alias="demo-repo", task_id="identity-task"): + return DirectReviewRequest(task_id, RepositoryRef(alias), 1, "a" * 40, + "Review contract", "", (ChangedPath("pkg/contract.py"),)) + + +def target(receipt, path=RULE_PATH): + return next(row for row in receipt["targets"] if row["kind"] == "rule" and row["path"] == path) + + +def record(client, receipt, path=RULE_PATH): + return client.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], ratings=[{ + "target_id": target(receipt, path)["target_id"], "score": 1, "used": True, + "reason": "The result check determined the task outcome.", + "evidence": "tests/test_contract.py::test_result passed", + }]) + + +@contextmanager +def collector(tmp_path, monkeypatch): + hub = FeedbackHubStore(tmp_path / "hub") + token = "identity-test-provider-secret-1234567890" + server = create_server(hub, token) + thread = Thread(target=server.serve_forever, kwargs={"poll_interval": 0.01}, daemon=True) + thread.start() + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_URL", f"http://127.0.0.1:{server.server_address[1]}") + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_TOKEN", token) + try: + yield hub + finally: + server.shutdown() + server.server_close() + thread.join(timeout=5) + + +def test_supported_aliases_keep_one_public_sdk_and_central_vote(knowledge, tmp_path, monkeypatch, accept_learning_agreement): + with collector(tmp_path, monkeypatch) as hub: + accept_learning_agreement() + sdk = DirectClient() + receipts = [sdk.plan(request(alias)).knowledge_feedback + for alias in ("demo-repo", "demo_repo", "owner/demo-repo")] + assert {receipt["repository"] for receipt in receipts} == {"demo-repo"} + assert len({target(receipt)["target_id"] for receipt in receipts}) == 1 + feedback = KnowledgeFeedbackClient() + for receipt in receipts: + assert record(feedback, receipt)["sync"]["status"] == "acknowledged" + assert feedback.report(scope="local")["total_ratings"] == 1 + assert feedback.report(scope="central")["total_ratings"] == 1 + assert hub.report()["total_targets"] == 1 + # Frozen knowledge-feedback/1 canonical identifier, independent of aliases. + assert target(receipts[0])["target_id"] == "7574eb3b1441d00b21ff43c8e24df88d6d2e7805edf8486748328a00bc7f37ee" + + +def test_general_task_read_reuses_plan_repository_across_clients(knowledge): + sdk = DirectClient() + plan = sdk.plan(request()) + receipts = [plan.knowledge_feedback, + sdk.read_document(GUIDE_PATH, task_id="identity-task").knowledge_feedback, + DirectClient().read_document(GUIDE_PATH, task_id="identity-task").knowledge_feedback, + sdk.read_document(GUIDE_PATH, review_context_id=plan.review_context_id).knowledge_feedback] + assert {receipt["repository"] for receipt in receipts} == {"demo-repo"} + assert len({target(receipt, GUIDE_PATH)["target_id"] for receipt in receipts}) == 1 + feedback = KnowledgeFeedbackClient() + for receipt in receipts: + record(feedback, receipt, GUIDE_PATH) + assert feedback.report(scope="local")["total_ratings"] == 1 + + +def test_general_read_before_plan_requires_explicit_task_repository(knowledge): + sdk = DirectClient() + with pytest.raises(InvalidRequestError, match="require repository"): + sdk.read_document(GUIDE_PATH, task_id="identity-task") + with pytest.raises(UnsupportedRepositoryError, match="served knowledge"): + sdk.read_document(GUIDE_PATH, task_id="identity-task", repository="unserved-arbitrary-namespace") + first = sdk.read_document(GUIDE_PATH, task_id="identity-task", repository="demo_repo").knowledge_feedback + planned = sdk.plan(request()).knowledge_feedback + assert target(first, GUIDE_PATH)["target_id"] == target(planned, GUIDE_PATH)["target_id"] + assert sdk.read_document(GUIDE_PATH).knowledge_feedback["repository"] == "general" + + +def test_ambiguous_task_repository_requires_explicit_context(knowledge): + sdk = DirectClient() + plan = sdk.plan(request()) + sdk.read_document(GUIDE_PATH, task_id="identity-task", repository="general") + with pytest.raises(InvalidRequestError, match="multiple repository contexts"): + DirectClient().read_document(GUIDE_PATH, task_id="identity-task") + explicit = DirectClient().read_document(GUIDE_PATH, task_id="identity-task", repository="demo_repo") + assert target(explicit.knowledge_feedback, GUIDE_PATH)["target_id"] == target(plan.knowledge_feedback, GUIDE_PATH)["target_id"] + with pytest.raises(InvalidRequestError, match="does not match"): + sdk.read_document(GUIDE_PATH, review_context_id=plan.review_context_id, repository="general") + + +def test_alias_resolution_and_context_reads_pin_one_snapshot(knowledge, tmp_path, monkeypatch): + replacement_root = tmp_path / "replacement" + shutil.copytree(knowledge.root, replacement_root) + (replacement_root / RULE_PATH).write_text("# Rules\n\n" + RULE.replace("Check the result", "Check both results")) + replacement = KnowledgeView(replacement_root, "replacement-snapshot") + calls = [] + + def activate(cls): + calls.append(True) + return knowledge if len(calls) == 1 else replacement + + monkeypatch.setattr(KnowledgeView, "current", classmethod(activate)) + sdk = DirectClient() + plan = sdk.plan(request("demo_repo")) + assert len(calls) == 1 + original = sdk.read_document(RULE_PATH, review_context_id=plan.review_context_id, repository="demo_repo") + assert len(calls) == 1 + assert original.knowledge_feedback["snapshot"] == "identity-snapshot" + assert target(original.knowledge_feedback)["target_id"] == target(plan.knowledge_feedback)["target_id"] + current = sdk.read_document(RULE_PATH, task_id="identity-task", repository="demo_repo") + assert current.knowledge_feedback["snapshot"] == "replacement-snapshot" + assert target(current.knowledge_feedback)["target_id"] != target(original.knowledge_feedback)["target_id"] + + +def test_adaptive_plan_aliases_and_followup_share_repository(knowledge, tmp_path): + receipts = [] + initial = [] + for index, alias in enumerate(("demo-repo", "demo_repo")): + sdk = DirectClient(knowledge_context_path=tmp_path / f"context-{index}.sqlite") + plan = sdk.plan_adaptive(request(alias)) + initial.append(plan["knowledge_feedback"]) + followup = sdk.read_document(RULE_PATH, review_context_id=plan["review_context_id"]) + assert followup.knowledge_feedback["repository"] == "demo-repo" + receipts.append(followup.knowledge_feedback) + assert {receipt["repository"] for receipt in initial} == {"demo-repo"} + assert {row["target_id"] for row in initial[0]["targets"]} == { + row["target_id"] for row in initial[1]["targets"]} + assert {receipt["repository"] for receipt in receipts} == {"demo-repo"} + assert len({target(receipt)["target_id"] for receipt in receipts}) == 1 + + +@pytest.mark.parametrize("failure", [OSError, sqlite3.OperationalError]) +def test_unavailable_task_lookup_and_issuance_keep_source_private(knowledge, monkeypatch, failure): + def unavailable(self): + raise failure("private/token-file and authenticated database endpoint") + + monkeypatch.setattr(KnowledgeFeedbackStore, "_db", unavailable) + monkeypatch.setattr(KnowledgeFeedbackStore, "_inspection_rows", lambda self, *_args: unavailable(self)) + sdk = DirectClient() + pages = [sdk.read_document(GUIDE_PATH, task_id="unknown-task"), + sdk.read_document(GUIDE_PATH)] + for page in pages: + assert "Verify the source" in page.content + assert page.knowledge_feedback == {"status": "unavailable", "error": "feedback_storage_unavailable"} diff --git a/test/test_feedback_recovery.py b/test/test_feedback_recovery.py new file mode 100644 index 000000000..17a33619b --- /dev/null +++ b/test/test_feedback_recovery.py @@ -0,0 +1,212 @@ +"""Storage recovery repairs feedback for the exact original adaptive delivery.""" + +from __future__ import annotations + +import hashlib +import json +import sqlite3 + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") +import test_kb_adaptive_containment as containment_helpers +from test_thin_mcp_server import _fake_mcp + +from infermatrix_copilot.knowledge_context import ( + ContextBudget, + ContextError, + KnowledgeContextService, +) +from infermatrix_copilot.knowledge_service.containment import ( + knowledge_availability_check, + knowledge_usage_record, +) +from infermatrix_copilot.knowledge_service.feedback import ( + KnowledgeFeedbackStore, + model_content_documents, +) +from infermatrix_copilot.knowledge_view import KnowledgeView, build_manifest +from infermatrix_copilot.sdk.v1 import DirectClient + +PIN = "a" * 40 +DOCUMENT = "repos/r/rules.md" +FIRST = ( + "## FIRST-1a — Preserve the input ownership contract\n\n" + + "Compare the verified input ownership and preserve the successful source contract before publishing the result. " * 6 + + "\n\n" +) +SECOND = ( + "## SECOND-1a — Preserve the undisclosed sibling contract\n\n" + "UNDISCLOSED_SIBLING requires a different independently verified downstream boundary.\n" +) +PAGE = "# Rules\n\n" + FIRST + SECOND +UNAVAILABLE = {"status": "unavailable", "error": "feedback_storage_unavailable"} + + +@pytest.fixture +def recovery(tmp_path, monkeypatch): + root = tmp_path / "snapshot" / "knowledge" + (root / "repos/r").mkdir(parents=True) + (root / DOCUMENT).write_text(PAGE) + manifest = build_manifest(root, "recovery-snapshot") + view = KnowledgeView(root, "recovery-snapshot", manifest["files"]) + binding = {"repo_id": "r", "knowledge_slice": "repos/r", "source_pin": PIN, + "catalog_hash": "b" * 64, "policy_hash": "c" * 64} + monkeypatch.setenv("KNOWLEDGE_MAINTENANCE_ENABLED", "0") + monkeypatch.setattr(KnowledgeView, "current", classmethod(lambda cls: view)) + state_path = tmp_path / "context.sqlite" + + def service(): + return KnowledgeContextService(view, state_path, resolver=lambda _view, _repo: binding) + + return service, state_path, view + + +def unavailable(*_args, **_kwargs): + raise sqlite3.OperationalError("private SQLite failure at /private/operator/path; bearer credential_value_123456789") + + +def read_session(service, *, initial_tokens=4000): + return service.open_session("r", source_pin=PIN, review_id="feedback-recovery-task", + budget=ContextBudget(initial_tokens=initial_tokens))["session_id"] + + +def without_feedback(packet): + return {key: value for key, value in packet.items() if key != "knowledge_feedback"} + + +@pytest.mark.parametrize("delivery", ["budget_partial", "complete_first_rule"]) +def test_cached_feedback_recovers_exact_original_fragments_after_restart(recovery, monkeypatch, delivery): + factory, _state_path, _view = recovery + service = factory() + session = read_session(service, initial_tokens=500 if delivery == "budget_partial" else 4000) + parameters = {"limit": 65536 if delivery == "budget_partial" else len(("# Rules\n\n" + FIRST).encode())} + issue_delivery = KnowledgeFeedbackStore.issue_delivery + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", unavailable) + original = service.read(session, DOCUMENT, **parameters) + assert original["knowledge_feedback"] == UNAVAILABLE + original_status = service.status(session) + fragments = model_content_documents(original["model_content"]) + assert fragments and "UNDISCLOSED_SIBLING" not in fragments[0]["content"] + if delivery == "budget_partial": + assert original["truncated"] and FIRST.strip() not in fragments[0]["content"] + else: + assert FIRST.strip() in fragments[0]["content"] + + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", issue_delivery) + restarted = factory() + recovered = restarted.read(session, DOCUMENT, **parameters) + assert without_feedback(recovered) == without_feedback(original) + assert restarted.status(session) == original_status + receipt = recovered["knowledge_feedback"] + assert receipt["protocol"] == "knowledge-feedback/1" + assert receipt["task_id"] == "feedback-recovery-task" + assert receipt["repository"] == "r" + assert receipt["documents"] == [{ + "path": DOCUMENT, + "page_sha256": hashlib.sha256(PAGE.encode()).hexdigest(), + "delivered_sha256": hashlib.sha256(fragments[0]["content"].encode()).hexdigest(), + "delivered_chars": len(fragments[0]["content"]), + }] + assert {target.get("block_id") for target in receipt["targets"] if target["kind"] == "rule"} == ( + set() if delivery == "budget_partial" else {"FIRST-1a"}) + # Persistence must update the cached integrity digest, rather than only the + # returned object: a second restart verifies and returns that exact packet. + again = factory() + assert again.read(session, DOCUMENT, **parameters) == recovered + assert again.status(session) == original_status + + +def test_repeated_storage_failure_keeps_source_deliverable_and_error_private(recovery, monkeypatch): + factory, _state_path, _view = recovery + service = factory() + session = read_session(service) + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", unavailable) + first = service.read(session, DOCUMENT) + cached = factory().read(session, DOCUMENT) + assert cached == first + assert cached["knowledge_feedback"] == UNAVAILABLE + assert "Preserve the input ownership" in cached["model_content"] + assert "/private/operator/path" not in json.dumps(cached) + assert "credential_value_123456789" not in json.dumps(cached) + assert factory().status(session)["consumed_tokens"] == first["consumed_tokens"] + + +def test_tampered_cached_content_is_rejected_before_feedback_reissue(recovery, monkeypatch): + factory, state_path, _view = recovery + service = factory() + session = read_session(service) + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", unavailable) + service.read(session, DOCUMENT) + with sqlite3.connect(state_path) as db: + state = json.loads(db.execute("SELECT state FROM sessions WHERE id=?", (session,)).fetchone()[0]) + next(iter(state["requests"].values()))["result"]["model_content"] += "Injected undisclosed sibling text." + db.execute("UPDATE sessions SET state=? WHERE id=?", (json.dumps(state), session)) + attempts = [] + + def forbidden_reissue(*args, **kwargs): + attempts.append((args, kwargs)) + raise AssertionError("tampered cached context reached feedback issuance") + + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", forbidden_reissue) + with pytest.raises(ContextError, match="integrity"): + factory().read(session, DOCUMENT) + assert attempts == [] + + +@pytest.mark.parametrize("surface", ["sdk", "mcp"]) +def test_document_delivery_surfaces_hide_storage_exception_details(recovery, monkeypatch, surface): + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", unavailable) + if surface == "sdk": + result = DirectClient().read_document(DOCUMENT, task_id="safe-failure-task").to_dict() + else: + mcp, _ = _fake_mcp(monkeypatch) + result = mcp.tools["doc_read"](path=DOCUMENT, repo="r", task_id="safe-failure-task") + assert result["knowledge_feedback"] == UNAVAILABLE + assert "Preserve the input ownership" in result["content"] + assert "credential_value_123456789" not in json.dumps(result) + assert "/private/operator/path" not in json.dumps(result) + + +@pytest.fixture +def contained(tmp_path, monkeypatch): + return containment_helpers.adaptive.__wrapped__(tmp_path, monkeypatch) + + +def test_repaired_cached_packet_keeps_prior_containment_receipts_valid(contained, monkeypatch): + fixture = contained + + def service(): + return KnowledgeContextService(fixture.view, fixture.context_path, + knowledge_maintenance=fixture.cfg) + + initial = service() + session = initial.open_session("r", source_pin=PIN, review_id="contained-feedback-recovery")["session_id"] + issue_delivery = KnowledgeFeedbackStore.issue_delivery + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", unavailable) + original = initial.read(session, containment_helpers.FOLLOWUP) + assert original["knowledge_feedback"] == UNAVAILABLE + old_receipt = knowledge_usage_record(original, injected=True, config=fixture.cfg) + assert knowledge_availability_check(old_receipt, config=fixture.cfg)["allowed"] + original_status = initial.status(session) + + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", issue_delivery) + restarted = service() + recovered = restarted.read(session, containment_helpers.FOLLOWUP) + assert recovered["knowledge_feedback"]["protocol"] == "knowledge-feedback/1" + assert without_feedback(recovered) == without_feedback(original) + assert restarted.status(session) == original_status + updated_receipt = knowledge_usage_record(recovered, injected=True, config=fixture.cfg) + assert updated_receipt["context_sha256"] != old_receipt["context_sha256"] + assert updated_receipt["pages"] == old_receipt["pages"] + assert updated_receipt["injected_units"] == old_receipt["injected_units"] + assert updated_receipt["delivery_session"] == old_receipt["delivery_session"] == session + assert knowledge_availability_check(old_receipt, config=fixture.cfg)["allowed"] + assert knowledge_availability_check(updated_receipt, config=fixture.cfg)["allowed"] + assert service().read(session, containment_helpers.FOLLOWUP) == recovered + assert knowledge_usage_record(recovered, injected=True, config=fixture.cfg) == updated_receipt + # A later hold still affects both the original and repaired packet. Recovery + # cannot detach the delivery from the session's publication dependencies. + containment_helpers.hold_followup(fixture) + assert not knowledge_availability_check(old_receipt, config=fixture.cfg)["allowed"] + assert not knowledge_availability_check(updated_receipt, config=fixture.cfg)["allowed"] diff --git a/test/test_feedback_sync.py b/test/test_feedback_sync.py new file mode 100644 index 000000000..b1c0b9106 --- /dev/null +++ b/test/test_feedback_sync.py @@ -0,0 +1,409 @@ +import copy +import hashlib +import json +import os +import sqlite3 +import threading +from concurrent.futures import ThreadPoolExecutor +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +from infermatrix_copilot.knowledge_service.feedback import ( + FeedbackError, + KnowledgeFeedbackStore, +) +from infermatrix_copilot.knowledge_service.feedback_sync import ( + MAX_MESSAGE_BYTES, + FeedbackSyncConfig, + FeedbackSyncError, +) +from infermatrix_copilot.knowledge_view import KnowledgeView + +PAGE = "# Rules\n\n## SOURCE-1a — Preserve the source\n\nKeep the executable source contract.\n" +DOCUMENT = "repos/r/rules.md" +TOKEN = "test-provider-token-" + "z" * 32 + + +def digest(value): + return hashlib.sha256(json.dumps(value, sort_keys=True, separators=(",", ":"), + ensure_ascii=False).encode()).hexdigest() + + +@pytest.fixture +def collector(): + state = {"mode": "ok", "events": [], "unique": {}, "headers": [], "on_post": None} + + class Handler(BaseHTTPRequestHandler): + def log_message(self, *_args): + pass + + def send_json(self, value, status=200): + data = json.dumps(value).encode() + self.send_response(status) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(len(data))) + self.end_headers() + self.wfile.write(data) + + def do_POST(self): + state["headers"].append(dict(self.headers)) + event = json.loads(self.rfile.read(int(self.headers["Content-Length"]))) + state["events"].append(event) + if state["on_post"]: + state["on_post"]() + if state["mode"] == "fail": + self.send_json({"error": TOKEN}, status=503) + return + if state["mode"] in ("conflict", "unauthorized"): + self.send_json({"error": TOKEN}, status=409 if state["mode"] == "conflict" else 401) + return + if state["mode"] == "redirect": + self.send_response(307) + self.send_header("Location", state["url"] + "/stolen") + self.end_headers() + return + receipt = event["receipt"] + votes = [] + for rating in event["ratings"]: + target = next(t for t in receipt["targets"] if t["target_id"] == rating["target_id"]) + key = (receipt["task_id"], rating["target_id"]) + previous = state["unique"].get(key) + vote = {**rating, "feedback_id": digest(list(key)), "target": target} + if previous is not None: + vote["target"] = previous["target"] + state["unique"][key] = copy.deepcopy(vote) + votes.append(vote) + response = {"task_id": receipt["task_id"], "delivery_id": receipt["delivery_id"], + "ratings": votes} + if state["mode"] == "wrong_ack": + response["ratings"][0]["score"] *= -1 + elif state["mode"] == "wrong_version": + response["ratings"][0]["target"]["content_sha256"] = "f" * 64 + elif state["mode"] == "other_provenance": + response["ratings"][0]["target"]["snapshot"] = "first-provider-snapshot" + response["ratings"][0]["target"]["page_sha256"] = "f" * 64 + self.send_json(response) + + def do_GET(self): + state["headers"].append(dict(self.headers)) + if state["mode"] == "fail": + self.send_json({"error": TOKEN}, status=503) + elif state["mode"] == "large": + self.send_response(200) + self.send_header("Content-Type", "application/json") + self.send_header("Content-Length", str(MAX_MESSAGE_BYTES + 1)) + self.end_headers() + elif state["mode"] == "wrong_report": + self.send_json({"error": TOKEN}) + elif state["mode"] == "malformed_target": + self.send_json({"protocol": "knowledge-feedback/1", "repository": "r", + "total_targets": 1, "total_ratings": 1, + "targets": [{}], "truncated": False}) + else: + self.send_json({"protocol": "knowledge-feedback/1", "repository": "r", + "total_targets": 0, "total_ratings": 0, + "targets": [], "truncated": False}) + + server = ThreadingHTTPServer(("127.0.0.1", 0), Handler) + state["url"] = f"http://127.0.0.1:{server.server_port}" + thread = threading.Thread(target=server.serve_forever, daemon=True) + thread.start() + try: + yield state + finally: + server.shutdown() + server.server_close() + thread.join(timeout=5) + + +@pytest.fixture +def world(tmp_path, collector): + root = tmp_path / "knowledge" + (root / "repos/r").mkdir(parents=True) + (root / DOCUMENT).write_text(PAGE) + config = FeedbackSyncConfig(collector["url"], TOKEN, 1) + return KnowledgeFeedbackStore(tmp_path / "state", sync_config=config), KnowledgeView(root, "snapshot-1") + + +def issue(world, task="global-task-1", content=PAGE): + store, view = world + return store.issue_delivery(task_id=task, repository="r", view=view, + documents=[{"path": DOCUMENT, "content": content}]) + + +def vote(receipt, **overrides): + target = next(t for t in receipt["targets"] if t["kind"] == "rule") + return {"target_id": target["target_id"], "score": 1, "used": True, + "reason": "The rule guided a successful fix.", + "evidence": ["Focused source contract test passed."], **overrides} + + +def record(world, receipt=None, **overrides): + receipt = receipt or issue(world) + return world[0].record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], + ratings=[vote(receipt, **overrides)]) + + +def test_auto_upload_reuses_identity_and_does_not_store_token(world, collector): + receipt = issue(world) + first = record(world, receipt) + assert first["sync"]["status"] == "acknowledged" + assert first["sync"]["pending_count"] == 0 + assert collector["events"] == [{"receipt": receipt, "ratings": [vote(receipt)], + "agreement": world[0]._agreement().attestation()}] + assert collector["headers"][0]["Authorization"] == "Bearer " + TOKEN + assert record(world, receipt)["ratings"] == first["ratings"] + assert len(collector["events"]) == 1 + assert TOKEN not in repr(world[0].sync_config) + assert TOKEN.encode() not in world[0].path.read_bytes() + assert world[0].report()["total_ratings"] == 1 + + +def test_network_outage_persists_then_restart_replays_without_double_count(world, collector): + collector["mode"] = "fail" + result = record(world) + assert result["sync"]["status"] == "pending" + assert result["sync"]["last_error"] == "collector_unavailable" + assert TOKEN not in json.dumps(result) + assert world[0].report()["total_ratings"] == 1 + restarted = KnowledgeFeedbackStore(world[0].state_dir, sync_config=world[0].sync_config) + collector["mode"] = "ok" + assert restarted.sync_pending()["status"] == "acknowledged" + assert len(collector["unique"]) == 1 + assert restarted.sync_pending()["attempted_count"] == 0 + + +@pytest.mark.parametrize("mode", ["wrong_ack", "wrong_version", "redirect"]) +def test_wrong_ack_and_redirect_never_claim_synced(world, collector, mode): + collector["mode"] = mode + result = record(world) + assert result["sync"]["status"] == "pending" + assert result["sync"]["acknowledged_count"] == 0 + assert len(collector["events"]) == 1 + collector["mode"] = "ok" + assert world[0].sync_pending()["status"] == "acknowledged" + assert len(collector["unique"]) == 1 + + +def test_global_duplicate_accepts_first_receipt_provenance(world, collector): + collector["mode"] = "other_provenance" + assert record(world)["sync"]["status"] == "acknowledged" + + +def test_new_receipt_retry_keeps_original_immutable_delivery(world, collector): + first = issue(world) + collector["mode"] = "fail" + record(world, first) + second = issue(world, content="Wrapper\n" + PAGE) + collector["mode"] = "ok" + result = record(world, second) + assert result["sync"]["status"] == "acknowledged" + assert collector["events"][-1]["receipt"]["delivery_id"] == first["delivery_id"] + assert result["delivery_id"] == second["delivery_id"] + + +def test_pre_sync_local_ratings_backfill_and_disabled_record_survive(world, collector, accept_learning_agreement): + store, view = world + local = KnowledgeFeedbackStore(store.state_dir) + local_world = local, view + receipt = issue(local_world) + assert record(local_world, receipt)["sync"]["status"] == "disabled" + # Simulate a database created before the outbox table existed. + with sqlite3.connect(store.path) as db: + db.execute("DROP TABLE feedback_outbox") + db.execute("DROP TABLE feedback_sync_meta") + accept_learning_agreement(store.state_dir, feedback_url=store.sync_config.url) + assert store.sync_pending()["status"] == "acknowledged" + assert len(collector["unique"]) == 1 + assert store.sync_pending()["attempted_count"] == 0 + + +def test_outbox_commit_is_atomic_and_network_holds_no_local_transaction(world, collector): + store, _ = world + + def inspect(): + with sqlite3.connect(store.path, timeout=0.2) as db: + db.execute("BEGIN IMMEDIATE") + assert db.execute("SELECT COUNT(*) FROM feedback_outbox").fetchone()[0] == 1 + assert db.execute("SELECT COUNT(*) FROM feedback_ratings").fetchone()[0] == 1 + collector["on_post"] = inspect + assert record(world)["sync"]["status"] == "acknowledged" + + +def test_conflicting_feedback_is_not_queued_or_sent(world, collector): + receipt = issue(world) + record(world, receipt) + with pytest.raises(FeedbackError, match="immutable"): + record(world, receipt, score=-1) + assert len(collector["events"]) == 1 + assert world[0].sync_status()["acknowledged_count"] == 1 + + +def test_secret_shaped_evidence_stays_local_and_pending(world, collector): + result = record(world, evidence=["ghp_" + "a" * 30]) + assert result["sync"]["status"] == "pending" + assert result["sync"]["last_error"] == "privacy_blocked" + assert collector["events"] == [] + assert KnowledgeFeedbackStore(world[0].state_dir, + sync_config=world[0].sync_config).sync_pending()["pending_count"] == 1 + assert world[0].report()["total_ratings"] == 1 + + +@pytest.mark.parametrize("mode,code", [("conflict", "feedback_conflict"), + ("unauthorized", "authentication_failed")]) +def test_safe_permanent_failure_codes_do_not_echo_response(world, collector, mode, code): + collector["mode"] = mode + result = record(world) + assert result["sync"]["status"] == "pending" + assert result["sync"]["last_error"] == code + assert TOKEN not in json.dumps(result) + + +def test_report_auto_scope_does_not_silently_return_local_on_failure(world, collector): + store, _ = world + record(world) + assert store.report_for_scope(repository="r")["scope"] == "central" + assert store.report_for_scope(repository="r", scope="local")["total_ratings"] == 1 + for mode in ("fail", "large", "wrong_report", "malformed_target"): + collector["mode"] = mode + with pytest.raises(FeedbackError, match="unavailable") as exc: + store.report_for_scope(repository="r") + assert TOKEN not in str(exc.value) + assert KnowledgeFeedbackStore(store.state_dir).report_for_scope(repository="r")["scope"] == "local" + + +def test_concurrent_flushes_global_dedup(world, collector): + collector["mode"] = "fail" + record(world) + collector["mode"] = "ok" + with ThreadPoolExecutor(max_workers=4) as pool: + list(pool.map(lambda _: world[0].sync_pending(), range(4))) + assert len(collector["unique"]) == 1 + assert world[0].sync_status()["acknowledged_count"] == 1 + + +def test_configuration_from_env_keeps_invalid_destination_local(monkeypatch, tmp_path): + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "state")) + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_URL", "http://remote.invalid") + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_TOKEN", TOKEN) + store = KnowledgeFeedbackStore.from_env() + assert store.sync_status()["status"] == "agreement_required" + from infermatrix_copilot.knowledge_service.agreement import AgreementRequiredError + + with pytest.raises(AgreementRequiredError): + store.report_for_scope() + assert store.report_for_scope(scope="local")["total_ratings"] == 0 + + +@pytest.mark.parametrize("url", [ + "http://example.org", "https://user:password@example.org", "https://example.org?token=x", + "https://example.org#x", "https://example.org?", "https://example.org#", + "ftp://127.0.0.1", "https://example.org:0", "https://example.org:65536", + "https://example.org\\@evil.invalid", "https://example.org/ bad", +]) +def test_unsafe_urls_rejected_without_echo(url): + with pytest.raises(FeedbackSyncError) as exc: + FeedbackSyncConfig(url, TOKEN) + assert url not in str(exc.value) + assert TOKEN not in str(exc.value) + + +@pytest.mark.parametrize("token", ["short", "x" * 31, "x" * 32 + "\n", "x" * 32 + " "]) +def test_invalid_tokens_rejected(token): + with pytest.raises(FeedbackSyncError): + FeedbackSyncConfig("https://collector.example", token) + + +@pytest.mark.parametrize("timeout", [0, -1, True, 31, "nan", "inf", "bad"]) +def test_invalid_timeouts_rejected(timeout): + with pytest.raises(FeedbackSyncError): + FeedbackSyncConfig("https://collector.example", TOKEN, timeout) + + +def test_valid_loopback_and_https_configuration(): + for url in ("http://127.0.0.1:8888/", "http://[::1]:8888", "http://localhost:8888", + "https://collector.example/feedback/"): + assert FeedbackSyncConfig(url, TOKEN).url == url.rstrip("/") + + +def test_configured_endpoint_change_replays_to_new_aggregate(world, collector): + record(world) + previous = world[0].sync_config + # The new service can share an origin behind a distinct configured prefix. + next_config = FeedbackSyncConfig(previous.url + "/new-service", TOKEN) + next_store = KnowledgeFeedbackStore(world[0].state_dir, sync_config=next_config) + assert next_store.sync_status()["pending_count"] == 1 + assert next_store.sync_pending()["status"] == "acknowledged" + assert len(collector["events"]) == 2 + + +def test_existing_public_state_directory_never_exposes_database_sidecars(tmp_path): + directory = tmp_path / "existing-state" + directory.mkdir(mode=0o755) + store = KnowledgeFeedbackStore(directory) + with store._db() as db: + db.execute("INSERT INTO feedback_sync_meta VALUES ('permission-test','1')") + for path in (store.path, Path(str(store.path) + "-wal"), Path(str(store.path) + "-shm")): + assert path.exists() + assert path.stat().st_mode & 0o077 == 0 + + +def test_explicit_state_directory_retains_transport_from_environment(monkeypatch, collector, tmp_path): + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "default")) + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_URL", collector["url"]) + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_TOKEN", TOKEN) + store = KnowledgeFeedbackStore.from_env(state_dir=tmp_path / "override") + assert store.state_dir == tmp_path / "override" + assert store.sync_config.url == collector["url"] + assert store.sync_config.token == TOKEN + + +def test_database_supports_platform_without_fchmod_or_nofollow(monkeypatch, tmp_path): + monkeypatch.delattr(os, "fchmod") + monkeypatch.delattr(os, "O_NOFOLLOW") + store = KnowledgeFeedbackStore(tmp_path / "state") + assert store.report()["total_ratings"] == 0 + + +def test_failed_concurrent_flush_cannot_revoke_successful_ack(world, collector, monkeypatch): + from infermatrix_copilot.knowledge_service.feedback_sync import FeedbackSyncClient + + collector["mode"] = "fail" + record(world) + second_started, success_finished = threading.Event(), threading.Event() + original = FeedbackSyncClient.send + + def send(client, **kwargs): + if threading.current_thread().name == "failed-upload": + second_started.set() + assert success_finished.wait(5) + raise FeedbackSyncError("collector request failed") + assert second_started.wait(5) + return original(client, **kwargs) + + monkeypatch.setattr(FeedbackSyncClient, "send", send) + collector["mode"] = "ok" + errors = [] + + def failed_upload(): + try: + world[0].sync_pending() + except (OSError, sqlite3.Error, ValueError, AssertionError) as exc: + errors.append(exc) + + thread = threading.Thread(target=failed_upload, name="failed-upload") + thread.start() + try: + assert second_started.wait(5) + assert world[0].sync_pending()["status"] == "acknowledged" + finally: + success_finished.set() + thread.join(timeout=5) + assert not thread.is_alive() + assert errors == [] + assert world[0].sync_status()["status"] == "acknowledged" + assert "last_error" not in world[0].sync_status() diff --git a/test/test_knowledge_feedback.py b/test/test_knowledge_feedback.py new file mode 100644 index 000000000..107defdfc --- /dev/null +++ b/test/test_knowledge_feedback.py @@ -0,0 +1,229 @@ +import hashlib +import json +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +from infermatrix_copilot.knowledge_service.feedback import ( + FeedbackError, + KnowledgeFeedbackStore, + from_env, + model_content_documents, +) +from infermatrix_copilot.knowledge_view import KnowledgeView, build_manifest + +FIRST = "## FIRST-1a — Preserve the source contract\n\nKeep the first executable contract intact when modifying the call.\n\n" +SECOND = "## SECOND-1a — Preserve the independent contract\n\nKeep the second independent source contract intact when changing the return.\n" +PAGE = "# Rules\n\n" + FIRST + SECOND +DOCUMENT = "repos/r/rules.md" + + +@pytest.fixture +def world(tmp_path): + root = tmp_path / "knowledge" + (root / "repos/r").mkdir(parents=True) + (root / DOCUMENT).write_text(PAGE) + return KnowledgeFeedbackStore(tmp_path / "learning"), KnowledgeView(root, "snapshot-1") + + +def issue(world, task="task-1", content=PAGE, **kwargs): + store, view = world + return store.issue_delivery(task_id=task, repository="r", view=view, + documents=[{"path": DOCUMENT, "content": content}], **kwargs) + + +def vote(target, **kwargs): + return {"target_id": target["target_id"], "score": 1, "used": True, + "reason": "The contract guided the successful fix.", + "evidence": ["Focused test run: source contract passed."], **kwargs} + + +def test_delivery_is_provider_bound_hash_only_and_works_without_containment(world, monkeypatch): + monkeypatch.delenv("KNOWLEDGE_MAINTENANCE_ENABLED", raising=False) + store, view = world + receipt = issue(world) + assert receipt["task_id"] == "task-1" + assert {target["kind"] for target in receipt["targets"]} == {"document", "rule"} + assert {target.get("block_id") for target in receipt["targets"] if target["kind"] == "rule"} == {"FIRST-1a", "SECOND-1a"} + assert receipt["documents"][0]["page_sha256"] == hashlib.sha256(PAGE.encode()).hexdigest() + assert receipt["documents"][0]["delivered_sha256"] == hashlib.sha256(PAGE.encode()).hexdigest() + stored = store.path.read_bytes() + assert FIRST.encode() not in stored + assert str(view.root) not in json.dumps(receipt) + assert issue(world) == receipt + + +def test_only_complete_delivered_rules_are_eligible(world): + receipt = issue(world, content="Provider wrapper\n" + FIRST.strip() + "\nEnd wrapper") + assert [target["block_id"] for target in receipt["targets"] if target["kind"] == "rule"] == ["FIRST-1a"] + partial = issue(world, content=FIRST[:65]) + assert [target["kind"] for target in partial["targets"]] == ["document"] + + +def test_empty_delivery_does_not_invent_targets(world): + store, view = world + receipt = store.issue_delivery(task_id="empty", repository="r", view=view, documents=[]) + assert receipt["targets"] == [] + assert store.record(task_id="empty", delivery_id=receipt["delivery_id"], ratings=[])["ratings"] == [] + with pytest.raises(FeedbackError, match="not delivered"): + store.record(task_id="empty", delivery_id=receipt["delivery_id"], ratings=[vote({"target_id": "a" * 64})]) + + +@pytest.mark.parametrize("document", ["../outside.md", "/tmp/unrelated.md", "repos/r/nonmarkdown.txt"]) +def test_document_path_and_markdown_containment(world, document): + store, view = world + (view.root / "repos/r/nonmarkdown.txt").write_text("not Markdown") + with pytest.raises(FeedbackError, match="knowledge document"): + store.issue_delivery(task_id="task", repository="r", view=view, + documents=[{"path": document, "content": "delivered"}]) + + +def test_symlink_escape_and_state_inside_knowledge_are_refused(world, tmp_path): + store, view = world + outside = tmp_path / "outside.md" + outside.write_text(PAGE) + (view.root / "repos/r/escape.md").symlink_to(outside) + with pytest.raises(FeedbackError, match="knowledge document"): + store.issue_delivery(task_id="task", repository="r", view=view, + documents=[{"path": "repos/r/escape.md", "content": PAGE}]) + inside = KnowledgeFeedbackStore(view.root / "learning") + with pytest.raises(FeedbackError, match="outside the knowledge tree"): + issue((inside, view)) + assert not inside.path.exists() + + +def test_verified_view_rejects_manifest_tampering(world): + store, view = world + manifest = build_manifest(view.root, "verified") + verified = KnowledgeView(view.root, "verified", manifest["files"]) + (view.root / DOCUMENT).write_text("changed source") + with pytest.raises(FeedbackError, match="knowledge document"): + issue((store, verified)) + + +@pytest.mark.parametrize("change", [ + {"score": True}, {"score": False}, {"score": 0}, {"score": 1.0}, {"score": "1"}, + {"used": False}, {"used": 1}, {"reason": " "}, {"evidence": []}, {"evidence": {}}, + {"evidence": [""]}, {"evidence": None}, {"target_id": "unknown"}, +]) +def test_rating_requires_eligible_used_target_strict_score_reason_and_evidence(world, change): + store, _ = world + receipt = issue(world) + with pytest.raises(FeedbackError): + store.record(task_id="task-1", delivery_id=receipt["delivery_id"], ratings=[vote(receipt["targets"][0], **change)]) + assert store.report()["total_ratings"] == 0 + + +def test_task_binding_unknown_delivery_and_unread_sibling_are_refused(world): + store, _ = world + all_targets = issue(world) + partial = issue(world, content=FIRST) + second = next(target for target in all_targets["targets"] if target.get("block_id") == "SECOND-1a") + with pytest.raises(FeedbackError, match="not delivered"): + store.record(task_id="task-1", delivery_id=partial["delivery_id"], ratings=[vote(second)]) + for task_id, delivery_id in (("another-task", partial["delivery_id"]), ("task-1", "a" * 64)): + with pytest.raises(FeedbackError, match="not issued"): + store.record(task_id=task_id, delivery_id=delivery_id, ratings=[]) + + +def test_feedback_is_immutable_idempotent_across_restart_and_repeat_deliveries(world): + store, view = world + receipt = issue(world) + rating = vote(receipt["targets"][0]) + first = store.record(task_id="task-1", delivery_id=receipt["delivery_id"], ratings=[rating]) + restarted = KnowledgeFeedbackStore(store.state_dir) + assert restarted.record(task_id="task-1", delivery_id=receipt["delivery_id"], ratings=[rating]) == first + second_receipt = issue((restarted, view), content="Wrapped\n" + PAGE) + restarted.record(task_id="task-1", delivery_id=second_receipt["delivery_id"], ratings=[rating]) + assert restarted.report()["total_ratings"] == 1 + with pytest.raises(FeedbackError, match="immutable"): + restarted.record(task_id="task-1", delivery_id=receipt["delivery_id"], ratings=[{**rating, "score": -1}]) + + +def test_feedback_batch_is_atomic_on_conflict(world): + store, _ = world + receipt = issue(world) + first, second = receipt["targets"][:2] + store.record(task_id="task-1", delivery_id=receipt["delivery_id"], ratings=[vote(second)]) + with pytest.raises(FeedbackError, match="immutable"): + store.record(task_id="task-1", delivery_id=receipt["delivery_id"], + ratings=[vote(first), vote(second, score=-1)]) + assert store.report()["total_ratings"] == 1 + + +def test_concurrent_retries_count_only_one_vote(world): + store, _ = world + receipt = issue(world) + rating = vote(receipt["targets"][0], score=-1) + def record(_): + return KnowledgeFeedbackStore(store.state_dir).record( + task_id="task-1", delivery_id=receipt["delivery_id"], ratings=[rating]) + with ThreadPoolExecutor(max_workers=6) as pool: + results = list(pool.map(record, range(12))) + assert all(result == results[0] for result in results) + assert store.report()["total_ratings"] == 1 + + +def test_report_groups_exact_content_versions_and_distinct_tasks(world): + store, view = world + receipt = issue(world) + rule = next(target for target in receipt["targets"] if target.get("block_id") == "FIRST-1a") + for task, score in (("task-1", 1), ("task-2", -1), ("task-3", 1)): + delivered = issue(world, task=task) + store.record(task_id=task, delivery_id=delivered["delivery_id"], ratings=[vote(rule, score=score)]) + # An unrelated sibling edit preserves this rule's identity; its own edit does not. + (view.root / DOCUMENT).write_text("# Different preamble\n\n" + FIRST + SECOND + "Additional sibling text.\n") + unchanged = issue(world, task="task-4", content=FIRST) + assert next(target for target in unchanged["targets"] if target["kind"] == "rule")["target_id"] == rule["target_id"] + changed = FIRST.replace("Keep the first", "Always preserve the first") + (view.root / DOCUMENT).write_text("# Rules\n\n" + changed + SECOND) + newer = issue(world, task="task-4", content=changed) + new_rule = next(target for target in newer["targets"] if target["kind"] == "rule") + assert new_rule["target_id"] != rule["target_id"] + store.record(task_id="task-4", delivery_id=newer["delivery_id"], ratings=[vote(new_rule, score=-1)]) + report = store.report(repository="r") + old = next(target for target in report["targets"] if target["target_id"] == rule["target_id"]) + assert (old["positive_count"], old["negative_count"], old["net_score"], old["rating_count"], old["distinct_tasks"]) == (2, 1, 1, 3, 3) + assert old["mean_score"] == pytest.approx(1 / 3) + assert report["total_targets"] == 2 + assert store.report(repository="another")["total_ratings"] == 0 + assert store.report(limit=1)["truncated"] + + +def test_document_version_changes_with_page_and_rule_version_with_upstream_pin(world): + first = issue(world) + _store, view = world + pinned = f"---\nsources: [https://example.test/r/blob/{'a' * 40}/api.py]\n---\n" + PAGE + (view.root / DOCUMENT).write_text(pinned) + second = issue(world, content=pinned) + changed_pin = pinned.replace("a" * 40, "b" * 40) + (view.root / DOCUMENT).write_text(changed_pin) + third = issue(world, content=changed_pin) + assert {target["target_id"] for target in first["targets"]}.isdisjoint( + target["target_id"] for target in second["targets"]) + assert {target["target_id"] for target in second["targets"]}.isdisjoint( + target["target_id"] for target in third["targets"]) + + +def test_environment_and_default_state_path(monkeypatch, tmp_path): + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "chosen")) + assert from_env().path == tmp_path / "chosen/feedback.sqlite3" + assert KnowledgeFeedbackStore.from_env().path == from_env().path + monkeypatch.delenv("KNOWLEDGE_LEARNING_STATE_DIR") + monkeypatch.setattr(Path, "home", lambda: tmp_path) + assert from_env().path == tmp_path / ".infermatrix-copilot/learning/feedback.sqlite3" + + +def test_adaptive_fragments_extract_only_actual_json_deliveries(): + def render(path, content): + return "\n\n" + json.dumps({"path": path, "content": content}).replace("<", "\\u003c") + "\n\n" + content = FIRST + "\n\nquoted, not a new delivery\n\n" + rendered = render(DOCUMENT, content) + render("general/api.md", "Additional actual context") + assert model_content_documents(rendered) == [ + {"path": DOCUMENT, "content": content}, + {"path": "general/api.md", "content": "Additional actual context"}, + ] + assert model_content_documents("Plain text is not an adaptive source delivery") == [] diff --git a/test/test_knowledge_learning_hosts.py b/test/test_knowledge_learning_hosts.py new file mode 100644 index 000000000..5bbecf214 --- /dev/null +++ b/test/test_knowledge_learning_hosts.py @@ -0,0 +1,203 @@ +"""Installed completion routing and the JSON CLI's service boundary.""" + +import importlib.util +import io +import json +import re +import sys +from pathlib import Path +from types import ModuleType, SimpleNamespace + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +from infermatrix_copilot.knowledge_service import learning_cli + +ROOT = Path(__file__).resolve().parents[1] +SKILLS = ROOT / "plugins" / "infermatrix-copilot" / "skills" + + +def _installer(): + spec = importlib.util.spec_from_file_location( + "learning_hosts_installer", ROOT / "scripts" / "install_mcp.py" + ) + assert spec is not None and spec.loader is not None + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +@pytest.mark.parametrize("host_root", [".agents", ".claude", ".cursor"]) +def test_installed_workflows_resolve_one_completion_contract(tmp_path, host_root): + destination = tmp_path / host_root / "skills" + _installer()._install_skills(destination) + workflows = sorted(SKILLS.glob("im*/SKILL.md")) + assert {p.parent.name for p in workflows} >= { + "imreview", "imcoding", "imcifix", "imdesign", "imrfc", "imupdate", "imkbinit", "imlearn", + } + for source in workflows: + installed = destination / source.parent.name / "SKILL.md" + text = installed.read_text(encoding="utf-8") + match = re.search(r"\[task completion learning\]\(([^)]+)\)", text) + assert match is not None, f"{source.parent.name} has no completion route" + contract = (installed.parent / match[1]).resolve() + assert contract.is_relative_to(destination.resolve()) + assert contract.read_bytes() == ( + SKILLS / "imlearn" / "references" / "task-completion.md" + ).read_bytes() + assert "$imlearn" in (destination / "imlearn" / "SKILL.md").read_text(encoding="utf-8") + + +@pytest.fixture +def services(monkeypatch): + calls = [] + + def operation(name): + def execute(*args, **kwargs): + calls.append((name, args, kwargs)) + return {"operation": name, "status": "retained"} + return execute + + learning = SimpleNamespace(**{name: operation(name) for name in ("prepare", "submit", "status")}) + feedback = SimpleNamespace(**{name: operation(name) for name in ( + "record", "report_for_scope", "sync_pending", "sync_status")}) + for module_name, class_name, service in ( + ("learning", "TaskLearningService", learning), + ("feedback", "KnowledgeFeedbackStore", feedback), + ): + module = ModuleType(f"infermatrix_copilot.knowledge_service.{module_name}") + setattr(module, class_name, SimpleNamespace(from_env=lambda service=service: service)) + monkeypatch.setitem(sys.modules, module.__name__, module) + return calls, learning, feedback + + +def _input(monkeypatch, tmp_path, value, stdin): + text = json.dumps(value) + if stdin: + monkeypatch.setattr(sys, "stdin", io.StringIO(text)) + return "-" + path = tmp_path / "input.json" + path.write_text(text, encoding="utf-8") + return str(path) + + +@pytest.mark.parametrize("stdin", [False, True]) +def test_prepare_delegates_bound_packet_with_empty_lessons( + monkeypatch, tmp_path, capsys, services, stdin +): + path = _input(monkeypatch, tmp_path, { + "task_id": "task-1", "repo": "vllm-omni", "source_pin": "a" * 40, "lessons": [], + }, stdin) + assert learning_cli.main(["prepare", "--input", path]) == 0 + assert services[0] == [("prepare", (), { + "task_id": "task-1", "repository": "vllm-omni", "source_pin": "a" * 40, "lessons": [], + })] + assert json.loads(capsys.readouterr().out)["operation"] == "prepare" + + +def test_submit_preserves_the_prepared_identity(monkeypatch, tmp_path, services): + proposals = {"rules": []} + path = _input(monkeypatch, tmp_path, { + "task_id": "task-1", "packet_digest": "b" * 64, "proposals": proposals, + }, False) + assert learning_cli.main(["submit", "--input", path]) == 0 + assert services[0] == [("submit", (), { + "task_id": "task-1", "packet_digest": "b" * 64, "proposals": proposals, + })] + + +def test_feedback_preserves_receipt_targets_and_evidence(monkeypatch, tmp_path, services): + ratings = [{"target_id": "rule-1", "score": -1, "used": True, + "reason": "stale API", "evidence": "test pin"}] + path = _input(monkeypatch, tmp_path, { + "task_id": "task-1", "delivery_id": "delivery-1", "ratings": ratings, + }, True) + assert learning_cli.main(["feedback", "--input", path]) == 0 + assert services[0] == [("record", (), { + "task_id": "task-1", "delivery_id": "delivery-1", "ratings": ratings, + })] + + +def test_status_and_report_delegate_without_starting_learning(services): + assert learning_cli.main(["status", "task-1"]) == 0 + assert learning_cli.main(["report", "--repo", "vllm-omni", "--limit", "7"]) == 0 + assert services[0] == [ + ("status", ("task-1",), {}), + ("report_for_scope", (), {"repository": "vllm-omni", "limit": 7, "scope": "auto"}), + ] + + +def test_feedback_retry_status_and_explicit_report_scope(services): + assert learning_cli.main(["sync", "--limit", "5"]) == 0 + assert learning_cli.main(["sync-status"]) == 0 + assert learning_cli.main(["report", "--scope", "local"]) == 0 + assert services[0] == [ + ("sync_pending", (), {"limit": 5}), + ("sync_status", (), {}), + ("report_for_scope", (), {"repository": "", "limit": 100, "scope": "local"}), + ] + + +@pytest.mark.parametrize("extra", ["transcript", "token", "workspace", "service_url"]) +def test_cli_rejects_unscoped_input_before_service_access( + monkeypatch, tmp_path, services, capsys, extra +): + path = _input(monkeypatch, tmp_path, { + "task_id": "task-1", "repository": "vllm-omni", "source_pin": "a" * 40, + "lessons": [], extra: "private-secret", + }, False) + assert learning_cli.main(["prepare", "--input", path]) == 2 + assert services[0] == [] + result = capsys.readouterr().out + assert "private-secret" not in result + assert json.loads(result)["error"]["code"] == "invalid_input" + + +def test_service_error_never_echoes_provider_details(monkeypatch, services, capsys): + def fail(task_id): + raise RuntimeError("token=private-secret from provider output") + services[1].status = fail + assert learning_cli.main(["status", "task-1"]) == 1 + output = capsys.readouterr().out + assert "private-secret" not in output + assert json.loads(output)["error"]["code"] == "learning_failed" + + +@pytest.mark.parametrize("raw", ['{"lessons": "private-secret"', '["private-secret"]']) +def test_malformed_input_is_bounded_and_does_not_echo_content(monkeypatch, services, capsys, raw): + monkeypatch.setattr(sys, "stdin", io.StringIO(raw)) + assert learning_cli.main(["prepare", "--input", "-"]) == 2 + assert services[0] == [] + assert "private-secret" not in capsys.readouterr().out + + +def test_oversized_input_is_rejected_before_service_access(monkeypatch, services, capsys): + monkeypatch.setattr(sys, "stdin", io.StringIO(" " * (learning_cli._MAX_INPUT_BYTES + 1))) + assert learning_cli.main(["prepare", "--input", "-"]) == 2 + assert services[0] == [] + assert json.loads(capsys.readouterr().out)["error"]["code"] == "invalid_input" + + +def test_argument_errors_do_not_echo_unexpected_credentials(capsys): + with pytest.raises(SystemExit) as exc: + learning_cli.main(["report", "--token", "private-secret"]) + assert exc.value.code == 2 + assert "private-secret" not in capsys.readouterr().err + + +def test_cli_empty_task_round_trips_through_real_service(monkeypatch, tmp_path, capsys, accept_learning_agreement): + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "state")) + accept_learning_agreement() + payload = tmp_path / "task.json" + payload.write_text(json.dumps({ + "task_id": "completed-with-no-new-lesson", "repository": "vllm-omni", + "source_pin": "a" * 40, "lessons": [], + }), encoding="utf-8") + assert learning_cli.main(["prepare", "--input", str(payload)]) == 0 + prepared = json.loads(capsys.readouterr().out) + assert prepared["status"] == "no_op" + assert learning_cli.main(["status", "completed-with-no-new-lesson"]) == 0 + restored = json.loads(capsys.readouterr().out) + assert restored["packet_digest"] == prepared["packet_digest"] + assert restored["status"] == "no_op" diff --git a/test/test_knowledge_learning_integration.py b/test/test_knowledge_learning_integration.py new file mode 100644 index 000000000..af6c834b2 --- /dev/null +++ b/test/test_knowledge_learning_integration.py @@ -0,0 +1,152 @@ +"""Task learning is reachable from real delivery and public entry points.""" + +import hashlib +import sqlite3 +from concurrent.futures import ThreadPoolExecutor + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") +from test_thin_mcp_server import _fake_mcp + +from infermatrix_copilot.knowledge_context import ContextBudget, KnowledgeContextService +from infermatrix_copilot.knowledge_view import KnowledgeView +from infermatrix_copilot.sdk.v1 import ( + DirectClient, + KnowledgeFeedbackClient, + KnowledgeLearningClient, +) + + +@pytest.fixture +def delivery(tmp_path, monkeypatch, accept_learning_agreement): + root = tmp_path / "knowledge" + owner = root / "repos" / "demo" + owner.mkdir(parents=True) + (owner / "_index.md").write_text("# Demo\n") + path = owner / "guide.md" + path.write_text("# Runtime guide\n\nCheck the output contract before retrying.\n") + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(tmp_path / "state")) + accept_learning_agreement() + monkeypatch.setenv("KNOWLEDGE_MAINTENANCE_ENABLED", "0") + view = KnowledgeView(root, "unverified") + monkeypatch.setattr(KnowledgeView, "current", classmethod(lambda cls: view)) + return view, path + + +def grade(receipt, score=1): + target = next(row for row in receipt["targets"] if row["kind"] == "document") + return {"target_id": target["target_id"], "score": score, "used": True, + "reason": "The output-contract check established the retry result.", + "evidence": ["tests/test_runtime.py::test_output_contract passed"]} + + +def test_mcp_read_to_grade_to_report_without_containment(delivery, monkeypatch): + mcp, _ = _fake_mcp(monkeypatch) + packet = mcp.tools["doc_read"](path="repos/demo/guide.md", repo="demo", task_id="host-task") + assert packet["content"].endswith("before retrying.\n") + receipt = packet["knowledge_feedback"] + assert receipt["task_id"] == "host-task" + rating = grade(receipt, -1) + call = lambda: mcp.tools["knowledge_feedback"]( + task_id="host-task", delivery_id=receipt["delivery_id"], ratings=[rating]) + with ThreadPoolExecutor(max_workers=4) as pool: + replies = list(pool.map(lambda _: call(), range(4))) + assert all(reply == replies[0] for reply in replies) + report = mcp.tools["knowledge_feedback_report"](repo="demo") + assert report["total_ratings"] == 1 + assert report["targets"][0]["mean_score"] == -1 + assert "error" in mcp.tools["knowledge_feedback"]( + task_id="another-task", delivery_id=receipt["delivery_id"], ratings=[rating]) + + +def test_sdk_reads_and_feedback_share_the_public_store(delivery): + client = DirectClient() + page = client.read_document("repos/demo/guide.md", task_id="sdk-task") + receipt = page.to_dict()["knowledge_feedback"] + feedback = KnowledgeFeedbackClient() + feedback.record(task_id="sdk-task", delivery_id=receipt["delivery_id"], ratings=[grade(receipt)]) + assert feedback.report(repository="demo")["targets"][0]["positive_count"] == 1 + + +def test_sdk_metadata_reads_stay_available_without_ratable_rules(delivery): + view, _ = delivery + (view.root / "repos/demo/_routes.yaml").write_text("owners: []\n") + page = DirectClient().read_document("repos/demo/_routes.yaml", task_id="metadata-task") + assert page.content == "owners: []\n" + assert page.knowledge_feedback["targets"] == [] + + +def test_unavailable_feedback_storage_does_not_break_source_delivery(delivery, monkeypatch): + from infermatrix_copilot.knowledge_service.feedback import KnowledgeFeedbackStore + + def unavailable(*_args, **_kwargs): + raise sqlite3.OperationalError("feedback database unavailable") + + monkeypatch.setattr(KnowledgeFeedbackStore, "issue_delivery", unavailable) + mcp, _ = _fake_mcp(monkeypatch) + packet = mcp.tools["doc_read"](path="repos/demo/guide.md", repo="demo", task_id="storage-task") + assert "before retrying" in packet["content"] + assert packet["knowledge_feedback"]["status"] == "unavailable" + page = DirectClient().read_document("repos/demo/guide.md", task_id="storage-task") + assert "before retrying" in page.content + assert page.knowledge_feedback["status"] == "unavailable" + + +def test_raw_mcp_feedback_pins_the_same_view_as_delivered_content(delivery, tmp_path, monkeypatch): + view, path = delivery + mcp, _ = _fake_mcp(monkeypatch) + new_root = tmp_path / "new-knowledge" + (new_root / "repos/demo").mkdir(parents=True) + (new_root / "repos/demo/_index.md").write_text("# New demo\n") + (new_root / "repos/demo/guide.md").write_text("A replacement rule with different behavior.\n") + replacement = KnowledgeView(new_root, "replacement") + resolutions = [] + + def activate_between_resolutions(cls): + resolutions.append(True) + return view if len(resolutions) == 1 else replacement + + monkeypatch.setattr(KnowledgeView, "current", classmethod(activate_between_resolutions)) + packet = mcp.tools["doc_read"](path="repos/demo/guide.md", repo="demo", task_id="activation-task") + target = next(t for t in packet["knowledge_feedback"]["targets"] if t["kind"] == "document") + assert "before retrying" in packet["content"] + assert target["page_sha256"] == hashlib.sha256(path.read_bytes()).hexdigest() + assert len(resolutions) == 1 + + +def test_adaptive_delivery_receipt_persists_and_exposes_only_delivered_content(delivery, tmp_path): + view, _ = delivery + resolver = lambda _view, _repo: {"repo_id": "demo", "knowledge_slice": "repos/demo", + "source_pin": "a" * 40, "catalog_hash": "", "policy_hash": ""} + service = KnowledgeContextService(view, tmp_path / "context.sqlite", resolver=resolver) + session = service.open_session("demo", source_pin="a" * 40, review_id="adaptive-task", + budget=ContextBudget(initial_tokens=500)) + packet = service.read(session["session_id"], "repos/demo/guide.md") + receipt = packet["knowledge_feedback"] + assert receipt["task_id"] == "adaptive-task" + assert len(receipt["documents"]) == 1 + assert service.read(session["session_id"], "repos/demo/guide.md") == packet + KnowledgeFeedbackClient().record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], + ratings=[grade(receipt)]) + assert KnowledgeFeedbackClient().report(repository="demo")["total_ratings"] == 1 + + +def test_mcp_and_sdk_share_empty_completion_state(delivery, monkeypatch): + mcp, _ = _fake_mcp(monkeypatch) + packet = mcp.tools["knowledge_learning"](action="prepare", task_id="no-lesson", repo="demo", + source_pin="a" * 40, lessons=[]) + assert packet["status"] == "no_op" + client = KnowledgeLearningClient() + assert client.status("no-lesson")["packet_digest"] == packet["packet_digest"] + submitted = client.submit(task_id="no-lesson", packet_digest=packet["packet_digest"], + proposals={"rules": []}) + assert submitted["status"] == "no_op" + assert "error" in mcp.tools["knowledge_learning"](action="execute", task_id="no-lesson") + + +def test_learning_cli_dispatch_requires_no_model_or_mcp(delivery, capsys): + from infermatrix_copilot.cli.entry import main + + assert main(["learning", "report", "--repo", "demo"]) == 0 + assert '"total_ratings": 0' in capsys.readouterr().out diff --git a/test/test_learning_agreement.py b/test/test_learning_agreement.py new file mode 100644 index 000000000..2e2ee1706 --- /dev/null +++ b/test/test_learning_agreement.py @@ -0,0 +1,334 @@ +import io +import json +import os +from datetime import UTC, datetime, timedelta + +import pytest + +from infermatrix_copilot.knowledge_service import agreement, agreement_cli +from infermatrix_copilot.knowledge_service.agreement import ( + AGREEMENT_SHA256, + AGREEMENT_TEXT, + AGREEMENT_VERSION, + AgreementRequiredError, + AgreementStore, + validate_upload_attestation, +) + + +def accept(store, name="Synthetic Test User"): + document = store.document() + return store._accept(name, version=document["version"], agreement_sha256=document["sha256"], + context_sha256=document["context_sha256"], confirmation="I AGREE") + + +@pytest.fixture +def store(tmp_path): + return AgreementStore(tmp_path / "state") + + +def test_read_only_status_and_document_do_not_create_state(store, monkeypatch): + monkeypatch.setenv("KNOWLEDGE_LEARNING_AGREEMENT_ACCEPTED", "1") + document = store.document() + assert (document["version"], document["text"], document["sha256"]) == (AGREEMENT_VERSION, AGREEMENT_TEXT, AGREEMENT_SHA256) + assert store.status()["status"] == "required" + with pytest.raises(AgreementRequiredError) as error: + store.require("learn") + assert error.value.code == "agreement_required" + assert not store.state_dir.exists() + + +def test_terms_disclose_cost_data_destinations_and_revocation(): + for required in ("tokens", "execution time", "paid", "personal", "proprietary", "private local", + "public repository", "collector", "reasons", "task identifiers", "raw chat", + "perfect redaction", "in flight", "does not erase", "legal"): + assert required in AGREEMENT_TEXT.lower() + + +def test_named_acceptance_is_private_exact_and_status_is_minimal(store): + result = accept(store) + assert result["status"] == "accepted" + assert "signer" not in result and "Synthetic Test User" not in json.dumps(result) + record = json.loads(store.path.read_text()) + accepted = record["acceptance"] + assert accepted["signer"] == "Synthetic Test User" + assert accepted["agreement_text"] == AGREEMENT_TEXT + assert accepted["agreement_sha256"] == AGREEMENT_SHA256 + assert accepted["context"] == store.document()["context"] + assert accepted["confirmation"] == "I AGREE" + assert record["audit"][0]["acceptance"] == accepted + if hasattr(os, "getuid"): + assert accepted["owner_uid"] == os.getuid() + if os.name != "nt": + assert store.directory.stat().st_mode & 0o777 == 0o700 + assert store.path.stat().st_mode & 0o777 == 0o600 + minimal = store.require("feedback_grade") + assert set(minimal) == {"version", "agreement_sha256", "context_sha256", "acceptance_id", "accepted_at"} + assert AgreementStore(store.state_dir).status() == result + + +@pytest.mark.parametrize("change", [ + {"version": "old"}, {"agreement_sha256": "0" * 64}, {"context_sha256": "0" * 64}, + {"confirmation": "yes"}, {"confirmation": "I AGREE "}, {"signer": " "}, {"signer": "A\nB"}, + {"signer": "ghp_" + "A" * 30}, +]) +def test_acceptance_requires_name_and_exact_displayed_terms_and_destinations(store, change): + document = store.document() + arguments = {"signer": "Synthetic Test User", "version": document["version"], + "agreement_sha256": document["sha256"], "context_sha256": document["context_sha256"], + "confirmation": "I AGREE", **change} + with pytest.raises(AgreementRequiredError): + store._accept(**arguments) + assert store.status()["status"] == "required" + + +def test_revocation_keeps_private_audit_and_new_acceptance_gets_new_identity(store): + first = accept(store) + assert store.revoke()["status"] == "revoked" + with pytest.raises(AgreementRequiredError): + store.attestation() + revoked = json.loads(store.path.read_text()) + assert revoked["acceptance"]["acceptance_id"] == first["acceptance_id"] + second = accept(store) + assert second["acceptance_id"] != first["acceptance_id"] + assert [event["action"] for event in json.loads(store.path.read_text())["audit"]] == ["accepted", "revoked", "accepted"] + + +def test_revoke_without_acceptance_remains_disabled(store): + assert store.revoke()["status"] == "revoked" + assert json.loads(store.path.read_text())["acceptance"] is None + with pytest.raises(AgreementRequiredError): + store.require("feedback_upload") + + +def test_context_changes_require_new_acceptance_but_token_rotation_does_not(tmp_path): + environ = {"KNOWLEDGE_LEARNING_STATE_DIR": str(tmp_path / "state"), + "KNOWLEDGE_LEARNING_PUBLICATION": "draft_pr", "KNOWLEDGE_LEARNING_REPOSITORY": "owner/knowledge", + "KNOWLEDGE_LEARNING_BASE": "main", "KNOWLEDGE_FEEDBACK_URL": "https://feedback.example.test", + "KNOWLEDGE_FEEDBACK_TOKEN": "original-token"} + first = AgreementStore.from_env(environ=environ) + accept(first) + rotated = AgreementStore.from_env(environ={**environ, "KNOWLEDGE_FEEDBACK_TOKEN": "replacement-token"}) + assert rotated.status()["status"] == "accepted" + for key, value in (("KNOWLEDGE_LEARNING_PUBLICATION", "local"), + ("KNOWLEDGE_LEARNING_REPOSITORY", "other/knowledge"), + ("KNOWLEDGE_LEARNING_BASE", "release"), + ("KNOWLEDGE_FEEDBACK_URL", "https://other.example.test")): + changed = AgreementStore.from_env(environ={**environ, key: value}) + assert changed.status()["status"] == "renewal_required" + with pytest.raises(AgreementRequiredError): + changed.require("learn") + override = AgreementStore.from_env(environ=environ, feedback_url="http://127.0.0.1:8787") + assert override.document()["context"]["feedback_url"] == "http://127.0.0.1:8787" + assert override.status()["status"] == "renewal_required" + assert "token" not in json.dumps(first.document()["context"]).lower() + + +def test_terms_version_change_requires_renewal(store, monkeypatch): + accept(store) + monkeypatch.setattr(agreement, "AGREEMENT_VERSION", "next") + assert store.status()["status"] == "renewal_required" + with pytest.raises(AgreementRequiredError): + store.require("learn") + + +@pytest.mark.parametrize("raw", ["not json", "{}", '{"protocol":"x","protocol":"y"}', "[]"]) +def test_corrupt_records_fail_closed(store, raw): + accept(store) + store.path.write_text(raw) + assert store.status()["status"] == "unavailable" + with pytest.raises(AgreementRequiredError): + store.require("learn") + + +def test_owner_and_permission_mismatch_fail_closed(store): + accept(store) + if hasattr(os, "getuid"): + record = json.loads(store.path.read_text()) + record["acceptance"]["owner_uid"] = os.getuid() + 1 + store.path.write_text(json.dumps(record)) + assert store.status()["status"] == "unavailable" + if os.name != "nt": + store.path.chmod(0o644) + assert store.status()["status"] == "unavailable" + + +def test_symlink_state_or_record_cannot_authorize_or_be_overwritten(tmp_path, store): + target = tmp_path / "target" + target.mkdir() + linked = tmp_path / "linked" + try: + linked.symlink_to(target, target_is_directory=True) + except OSError: + pytest.skip("symlinks unavailable") + unsafe = AgreementStore(linked) + assert unsafe.status()["status"] == "unavailable" + with pytest.raises(AgreementRequiredError): + accept(unsafe) + assert not (target / "agreement").exists() + accept(store) + original = store.path.read_text() + copied = tmp_path / "copied.json" + copied.write_text(original) + store.path.unlink() + store.path.symlink_to(copied) + assert store.status()["status"] == "unavailable" + with pytest.raises(AgreementRequiredError): + store.revoke() + assert copied.read_text() == original + + +def test_interrupted_atomic_write_preserves_prior_acknowledgement(store, monkeypatch): + first = accept(store) + monkeypatch.setattr(agreement.os, "replace", lambda *_: (_ for _ in ()).throw(OSError("private failure"))) + with pytest.raises(AgreementRequiredError): + store.revoke() + assert store.status() == first + assert not list(store.directory.glob(".acceptance-*.tmp")) + + +def test_feedback_attestation_minimal_current_and_pure(store): + accept(store) + attestation = store.attestation() + assert attestation["purpose"] == "feedback_upload" + assert "signer" not in attestation and "agreement_text" not in attestation and "context" not in attestation + assert validate_upload_attestation(attestation) == attestation + assert validate_upload_attestation(attestation) is not attestation + for field, value in (("purpose", "learn"), ("version", "old"), ("agreement_sha256", "0" * 64), + ("acceptance_id", "not-id"), ("context_sha256", "bad"), + ("accepted_at", "yesterday"), ("signer", "unexpected")): + with pytest.raises(AgreementRequiredError): + validate_upload_attestation({**attestation, field: value}) + future = (datetime.now(UTC) + timedelta(days=1)).isoformat().replace("+00:00", "Z") + with pytest.raises(AgreementRequiredError): + validate_upload_attestation({**attestation, "accepted_at": future}) + + +def test_cli_default_show_and_status_do_not_sign(store, monkeypatch, capsys): + monkeypatch.setattr(AgreementStore, "from_env", classmethod(lambda cls: store)) + assert agreement_cli.main([]) == 0 + assert AGREEMENT_TEXT in capsys.readouterr().out + assert agreement_cli.main(["status"]) == 0 + assert json.loads(capsys.readouterr().out)["status"] == "required" + assert not store.state_dir.exists() + + +def test_cli_piped_acceptance_cannot_sign(store, monkeypatch, capsys): + monkeypatch.setattr(AgreementStore, "from_env", classmethod(lambda cls: store)) + monkeypatch.setattr(agreement_cli.sys, "stdin", io.StringIO("Synthetic Test User\nI AGREE\n")) + assert agreement_cli.main(["accept"]) == 2 + assert json.loads(capsys.readouterr().out)["error"]["code"] == "interactive_required" + assert not store.state_dir.exists() + + +def terminal(monkeypatch): + monkeypatch.setattr(agreement_cli.sys.stdin, "isatty", lambda: True) + monkeypatch.setattr(agreement_cli.sys.stdout, "isatty", lambda: True) + + +def test_cli_interactive_acceptance_displays_terms_before_named_confirmation(store, monkeypatch, capsys): + monkeypatch.setattr(AgreementStore, "from_env", classmethod(lambda cls: store)) + terminal(monkeypatch) + answers = iter(["Synthetic Test User", "I AGREE"]) + shown = [] + def respond(prompt): + shown.append(capsys.readouterr().out) + return next(answers) + monkeypatch.setattr("builtins.input", respond) + assert agreement_cli.main(["accept"]) == 0 + assert AGREEMENT_TEXT in shown[0] + assert store.status()["status"] == "accepted" + assert agreement_cli.main(["revoke"]) == 0 + assert store.status()["status"] == "revoked" + + +@pytest.mark.parametrize("answer", ["yes", "I agree", "I AGREE ", ""]) +def test_cli_cancel_or_inexact_confirmation_cannot_sign(store, monkeypatch, capsys, answer): + monkeypatch.setattr(AgreementStore, "from_env", classmethod(lambda cls: store)) + terminal(monkeypatch) + answers = iter(["Synthetic Test User", answer]) + monkeypatch.setattr("builtins.input", lambda _: next(answers)) + assert agreement_cli.main(["accept"]) == 2 + assert "not accepted" in capsys.readouterr().out + assert not store.state_dir.exists() + + +def test_cli_changed_destination_during_prompt_requires_reading_again(store, monkeypatch, capsys): + changed = AgreementStore(store.state_dir, context={**store.context, "feedback_url": "https://changed.example.test"}) + stores = iter([store, changed]) + monkeypatch.setattr(AgreementStore, "from_env", classmethod(lambda cls: next(stores))) + terminal(monkeypatch) + answers = iter(["Synthetic Test User", "I AGREE"]) + monkeypatch.setattr("builtins.input", lambda _: next(answers)) + assert agreement_cli.main(["accept"]) == 2 + assert "agreement_changed" in capsys.readouterr().out + assert not store.state_dir.exists() + + +def test_cli_has_no_yes_flag_or_sensitive_argument_echo(capsys): + with pytest.raises(SystemExit) as error: + agreement_cli.main(["accept", "--yes", "private-token"]) + assert error.value.code == 2 + assert "private-token" not in capsys.readouterr().err + + +def test_dynamic_environment_rechecked_on_existing_store(tmp_path, monkeypatch): + values = {"KNOWLEDGE_LEARNING_STATE_DIR": str(tmp_path / "state")} + monkeypatch.setattr("infermatrix_copilot.knowledge_service.learning_config.learning_environment", lambda: dict(values)) + store = AgreementStore.from_env() + accept(store) + values["KNOWLEDGE_FEEDBACK_URL"] = "https://new.example.test" + assert store.status()["status"] == "renewal_required" + assert "KNOWLEDGE_FEEDBACK_TOKEN" not in store.document()["context"] + + +def test_invalid_destination_never_echoes_secret_or_creates_state(tmp_path): + store = AgreementStore.from_env(state_dir=tmp_path / "state", environ={"KNOWLEDGE_FEEDBACK_URL": "https://name:secret@example.test"}) + assert store.status()["status"] == "unavailable" + assert "secret" not in json.dumps(store.status()) + assert not store.state_dir.exists() + with pytest.raises(AgreementRequiredError): + store.require("feedback_upload") + + +def test_symlinked_home_parent_matches_canonical_runtime_state(tmp_path, monkeypatch): + physical = tmp_path / "physical-home" + physical.mkdir() + alias = tmp_path / "home-alias" + try: + alias.symlink_to(physical, target_is_directory=True) + except OSError: + pytest.skip("symlinks unavailable") + monkeypatch.setattr(agreement.Path, "home", classmethod(lambda cls: alias)) + store = AgreementStore.from_env(environ={}) + assert store.state_dir == physical / ".infermatrix-copilot" / "learning" + accepted = accept(store) + assert AgreementStore(physical / ".infermatrix-copilot" / "learning").status() == accepted + + +def test_symlink_resolution_loop_fails_closed_without_constructor_error(tmp_path): + loop = tmp_path / "loop" + try: + loop.symlink_to(loop, target_is_directory=True) + except OSError: + pytest.skip("symlinks unavailable") + for path in (loop, loop / "nested-state"): + store = AgreementStore(path) + assert store.status()["status"] == "unavailable" + with pytest.raises(AgreementRequiredError): + store.require("feedback_delivery") + with pytest.raises(AgreementRequiredError): + accept(store) + assert not list(tmp_path.glob("acceptance*")) + + +def test_bounded_recent_audit_never_blocks_revocation(store, monkeypatch): + accept(store) + record = json.loads(store.path.read_text()) + record["audit"] = record["audit"] * 32 + store.path.write_text(agreement._json(record) + "\n") + monkeypatch.setattr(agreement, "_MAX_RECORD_BYTES", len((agreement._json(record) + "\n").encode()) + 10) + assert store.revoke()["status"] == "revoked" + current = json.loads(store.path.read_text()) + assert current["audit"][-1]["action"] == "revoked" + assert len(current["audit"]) <= 32 diff --git a/test/test_learning_agreement_collection.py b/test/test_learning_agreement_collection.py new file mode 100644 index 000000000..99435e475 --- /dev/null +++ b/test/test_learning_agreement_collection.py @@ -0,0 +1,147 @@ +"""The collector requires a current provider attestation before persistence.""" +from __future__ import annotations + +import copy +import http.client +import json +import sqlite3 +import threading + +import pytest + +from infermatrix_copilot.knowledge_service.agreement import ( + AgreementRequiredError, + AgreementStore, +) +from infermatrix_copilot.knowledge_service.feedback import ( + KnowledgeFeedbackStore, + _digest, +) +from infermatrix_copilot.knowledge_service.feedback_http import create_server +from infermatrix_copilot.knowledge_service.feedback_hub import FeedbackHubStore +from infermatrix_copilot.knowledge_view import KnowledgeView + +TOKEN = "test-provider-" + "x" * 40 +PAGE = "repos/r/rules.md" +CONTENT = "# Rules\n\n## SOURCE-1a — Preserve contracts\n\nKeep the executable source contract.\n" +PRIVATE_SIGNER = "Synthetic Private Collection Test User" + + +@pytest.fixture +def provider_event(tmp_path): + provider = KnowledgeFeedbackStore(tmp_path / "provider") + agreement = AgreementStore.from_env(state_dir=provider.state_dir) + document = agreement.document() + agreement._accept(PRIVATE_SIGNER, version=document["version"], agreement_sha256=document["sha256"], + context_sha256=document["context_sha256"], confirmation="I AGREE") + root = tmp_path / "knowledge" + (root / PAGE).parent.mkdir(parents=True) + (root / PAGE).write_text(CONTENT) + receipt = provider.issue_delivery(task_id="globally-unique-task-1", repository="r", + view=KnowledgeView(root, "snapshot-1"), + documents=[{"path": PAGE, "content": CONTENT}]) + rating = {"target_id": receipt["targets"][0]["target_id"], "score": 1, "used": True, + "reason": "The rule guided the verified fix.", "evidence": ["Focused contract test passed."]} + return {"receipt": receipt, "ratings": [rating], "agreement": agreement.attestation()} + + +@pytest.fixture +def collector(tmp_path): + hub = FeedbackHubStore(tmp_path / "collector") + server = create_server(hub, TOKEN) + thread = threading.Thread(target=server.serve_forever, kwargs={"poll_interval": 0.01}, daemon=True) + thread.start() + try: + yield hub, server + finally: + server.shutdown() + server.server_close() + thread.join(timeout=3) + + +def post(server, event): + connection = http.client.HTTPConnection(*server.server_address, timeout=3) + try: + connection.request("POST", "/v1/feedback/events", json.dumps(event).encode(), + {"Content-Type": "application/json", "Authorization": "Bearer " + TOKEN}) + response = connection.getresponse() + return response.status, json.loads(response.read()) + finally: + connection.close() + + +def invalid_event(event, kind): + event = copy.deepcopy(event) + if kind == "missing": + event.pop("agreement") + elif kind == "stale_version": + event["agreement"]["version"] = "old-disclosure-version" + elif kind == "stale_text": + event["agreement"]["agreement_sha256"] = "0" * 64 + elif kind == "malformed_context": + event["agreement"]["context_sha256"] = "invalid" + elif kind == "wrong_purpose": + event["agreement"]["purpose"] = "arbitrary-data-upload" + elif kind == "future_timestamp": + event["agreement"]["accepted_at"] = "2999-01-01T00:00:00Z" + elif kind == "signer_included": + event["agreement"]["signer"] = PRIVATE_SIGNER + elif kind == "malformed_identity": + event["agreement"]["acceptance_id"] = True + elif kind == "not_an_attestation": + event["agreement"] = True + else: + raise AssertionError("unknown test case") + return event + + +INVALID = ("missing", "stale_version", "stale_text", "malformed_context", "wrong_purpose", + "future_timestamp", "signer_included", "malformed_identity", "not_an_attestation") + + +@pytest.mark.parametrize("kind", INVALID) +def test_hub_rejects_missing_stale_or_malformed_attestation_before_database(provider_event, tmp_path, kind): + event = invalid_event(provider_event, kind) + hub = FeedbackHubStore(tmp_path / "hub") + with pytest.raises(AgreementRequiredError) as error: + hub.ingest(receipt=event["receipt"], ratings=event["ratings"], agreement=event.get("agreement")) + assert error.value.code == "agreement_required" + assert PRIVATE_SIGNER not in str(error.value) + assert not hub.state_dir.exists() + + +@pytest.mark.parametrize("kind", INVALID) +def test_http_rejects_missing_stale_or_malformed_attestation_without_storage(provider_event, collector, capsys, kind): + hub, server = collector + status, response = post(server, invalid_event(provider_event, kind)) + assert status == 428 + assert response["error"]["code"] == "agreement_required" + assert PRIVATE_SIGNER not in json.dumps(response) + assert not hub.state_dir.exists() + captured = capsys.readouterr() + assert PRIVATE_SIGNER not in captured.out + captured.err + assert TOKEN not in captured.out + captured.err + + +def test_current_attestation_deduplicates_and_audits_without_signer(provider_event, collector): + hub, server = collector + # The collector operator has no local user acceptance; provider attestation + # is what authorizes this authenticated ingestion boundary. + assert AgreementStore.from_env(state_dir=hub.state_dir).status()["status"] == "required" + status, result = post(server, provider_event) + assert status == 200 + assert post(server, provider_event) == (status, result) + receipt = provider_event["receipt"] + rating = provider_event["ratings"][0] + assert result["ratings"][0]["feedback_id"] == _digest([receipt["task_id"], rating["target_id"]]) + assert hub.report()["total_ratings"] == 1 + with sqlite3.connect(hub.path) as db: + rows = db.execute("SELECT acceptance_id,attestation FROM feedback_agreements").fetchall() + assert len(rows) == 1 + assert rows[0][0] == provider_event["agreement"]["acceptance_id"] + assert json.loads(rows[0][1]) == provider_event["agreement"] + assert db.execute("SELECT COUNT(*) FROM feedback_delivery_agreements").fetchone()[0] == 1 + assert db.execute("SELECT COUNT(*) FROM feedback_outbox").fetchone()[0] == 0 + assert PRIVATE_SIGNER.encode() not in hub.path.read_bytes() + assert "signer" not in json.dumps(result) + assert not (hub.state_dir / "agreement").exists() diff --git a/test/test_learning_agreement_hosts.py b/test/test_learning_agreement_hosts.py new file mode 100644 index 000000000..b2784d57f --- /dev/null +++ b/test/test_learning_agreement_hosts.py @@ -0,0 +1,161 @@ +"""The host must inspect consent before optional learning, never sign it.""" + +import inspect +import io +import json +from pathlib import Path +from types import SimpleNamespace + +import pytest +from test_thin_mcp_server import _fake_mcp + +from infermatrix_copilot.knowledge_service import learning_cli +from infermatrix_copilot.knowledge_service.agreement import ( + AgreementRequiredError, + AgreementStore, +) +from infermatrix_copilot.sdk.v1 import ( + KnowledgeAgreementClient, + KnowledgeFeedbackClient, + KnowledgeLearningClient, +) + +ROOT = Path(__file__).resolve().parents[1] +SKILLS = ROOT / "plugins/infermatrix-copilot/skills" + + +@pytest.fixture +def unsigned_state(monkeypatch, tmp_path): + state = tmp_path / "unsigned-learning" + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(state)) + return state + + +def test_sdk_agreement_is_inspection_only_and_default_status_has_no_side_effects(unsigned_state): + client = KnowledgeAgreementClient() + assert not unsigned_state.exists() + status = client.status() + document = client.document() + assert status["status"] == "required" + assert status["agreement_sha256"] == document["sha256"] + assert document["text"] + assert not unsigned_state.exists() + assert {name for name in dir(client) if not name.startswith("_")} == {"document", "status", "revoke"} + for operation in (client.document, client.status, client.revoke): + assert not inspect.signature(operation).parameters + + +@pytest.mark.parametrize("operation", ["prepare", "submit", "record", "sync"]) +def test_sdk_refuses_optional_work_before_constructing_runtime(unsigned_state, monkeypatch, operation): + def forbidden(): + pytest.fail("An unsigned optional operation constructed its runtime") + learning = KnowledgeLearningClient() + feedback = KnowledgeFeedbackClient() + monkeypatch.setattr(learning, "_runtime", forbidden) + monkeypatch.setattr(feedback, "_store", forbidden) + calls = { + "prepare": lambda: learning.prepare(task_id="task", repository="demo", source_pin="a" * 40, lessons=[]), + "submit": lambda: learning.submit(task_id="task", packet_digest="b" * 64, proposals={"rules": []}), + "record": lambda: feedback.record(task_id="task", delivery_id="delivery", ratings=[]), + "sync": feedback.sync, + } + with pytest.raises(AgreementRequiredError): + calls[operation]() + assert not unsigned_state.exists() + + +def test_sdk_local_inspection_remains_available_without_consent(unsigned_state, monkeypatch): + learning = KnowledgeLearningClient() + feedback = KnowledgeFeedbackClient() + monkeypatch.setattr(learning, "_runtime", lambda: SimpleNamespace(status=lambda task: {"status": "unknown", "task_id": task})) + monkeypatch.setattr(feedback, "_store", lambda: SimpleNamespace( + report_for_scope=lambda **kwargs: {"targets": [], **kwargs}, + sync_status=lambda: {"pending": 0}, + )) + assert learning.status("task")["status"] == "unknown" + assert feedback.report(scope="local")["targets"] == [] + assert feedback.sync_status() == {"pending": 0} + assert not unsigned_state.exists() + + +def test_sdk_accepted_check_precedes_prepare(monkeypatch, tmp_path): + events = [] + fake = SimpleNamespace(require=lambda action: events.append(("require", action))) + monkeypatch.setattr(AgreementStore, "from_env", classmethod(lambda cls, **kwargs: fake)) + client = KnowledgeLearningClient(state_dir=tmp_path) + monkeypatch.setattr(client, "_runtime", lambda: SimpleNamespace( + prepare=lambda *args: events.append(("prepare", args)) or {"status": "prepared"}, + )) + assert client.prepare(task_id="task", repository="demo", source_pin="a" * 40, lessons=[])["status"] == "prepared" + assert [event[0] for event in events] == ["require", "prepare"] + + +def test_mcp_has_no_acceptance_or_signature_payload(unsigned_state, monkeypatch): + server, _ = _fake_mcp(monkeypatch) + tool = server.tools["knowledge_agreement"] + assert list(inspect.signature(tool).parameters) == ["action"] + assert tool()["status"] == "required" + assert tool(action="show")["text"] + assert not unsigned_state.exists() + assert "error" in tool(action="accept") + with pytest.raises(TypeError): + tool(action="status", signer="Agent", accepted=True) + assert not unsigned_state.exists() + annotations = server.tool_annotations["knowledge_agreement"] + assert annotations.readOnlyHint is False # revoke mutates local consent + assert annotations.openWorldHint is False + assert tool(action="revoke")["status"] == "revoked" + + +def test_mcp_learning_refuses_unsigned_request_without_runtime(unsigned_state, monkeypatch): + server, _ = _fake_mcp(monkeypatch) + monkeypatch.setattr(KnowledgeLearningClient, "_runtime", lambda self: pytest.fail("unsigned runtime")) + reply = server.tools["knowledge_learning"]( + action="prepare", task_id="task", repo="demo", source_pin="a" * 40, lessons=[], + ) + assert reply["status"] == "agreement_required" + assert reply["human_command"].endswith("learning agreement accept") + assert not unsigned_state.exists() + + +def test_cli_agreement_status_and_show_use_human_agreement_interface(unsigned_state, capsys): + assert learning_cli.main(["agreement", "status"]) == 0 + assert json.loads(capsys.readouterr().out)["status"] == "required" + assert learning_cli.main(["agreement", "show"]) == 0 + assert AgreementStore.from_env().document()["text"] in capsys.readouterr().out + assert not unsigned_state.exists() + + +def test_cli_will_not_sign_from_a_pipe_or_accept_flag(unsigned_state, monkeypatch, capsys): + monkeypatch.setattr("sys.stdin", io.StringIO("Agent\nI AGREE\n")) + monkeypatch.setattr(AgreementStore, "_accept", lambda *args, **kwargs: pytest.fail("agent signed")) + assert learning_cli.main(["agreement", "accept"]) == 2 + assert json.loads(capsys.readouterr().out)["error"]["code"] == "interactive_required" + with pytest.raises(SystemExit) as error: + learning_cli.main(["agreement", "accept", "--yes"]) + assert error.value.code == 2 + assert not unsigned_state.exists() + + +def test_cli_unsigned_prepare_reports_gate_without_creating_service(unsigned_state, monkeypatch, capsys): + monkeypatch.setattr("sys.stdin", io.StringIO(json.dumps({ + "task_id": "task", "repository": "demo", "source_pin": "a" * 40, "lessons": [], + }))) + monkeypatch.setattr(learning_cli, "_learning_service", lambda: pytest.fail("unsigned service")) + assert learning_cli.main(["prepare", "--input", "-"]) == 3 + assert json.loads(capsys.readouterr().out)["error"]["code"] == "agreement_required" + assert not unsigned_state.exists() + + +def test_every_host_completion_route_checks_agreement_before_learning(): + for skill in SKILLS.glob("im*/SKILL.md"): + text = skill.read_text(encoding="utf-8") + completion = text if skill.parent.name == "imlearn" else text.split("## Task completion learning", 1)[1] + assert completion.index('knowledge_agreement(action="status")') < completion.index("task completion learning](") + assert 'status="accepted"' in completion + assert "Never sign" in completion or "Never accept" in completion + shared = (SKILLS / "imlearn/references/task-completion.md").read_text(encoding="utf-8") + assert shared.index('knowledge_agreement(action="status")') < shared.index("## Distill locally") + assert "skip learning and grading" in shared + assert "Operator configuration alone is not consent" in shared + assert "Do not repeatedly remind" in " ".join(shared.split()) diff --git a/test/test_learning_agreement_retrieval.py b/test/test_learning_agreement_retrieval.py new file mode 100644 index 000000000..443ce450c --- /dev/null +++ b/test/test_learning_agreement_retrieval.py @@ -0,0 +1,71 @@ +"""Source retrieval stays available across optional learning consent changes.""" + +from __future__ import annotations + +import pytest +import test_feedback_recovery as helpers + +from infermatrix_copilot.knowledge_service.agreement import AgreementStore +from infermatrix_copilot.knowledge_view import KnowledgeView, build_manifest +from infermatrix_copilot.sdk.v1 import DirectClient + + +@pytest.fixture +def retrieval(tmp_path, monkeypatch): + return helpers.recovery.__wrapped__(tmp_path, monkeypatch) + + +def test_unsigned_general_source_read_does_not_require_feedback_repository( + retrieval, monkeypatch, +): + _factory, _state_path, view = retrieval + (view.root / "general").mkdir() + (view.root / "general/rules.md").write_text(helpers.PAGE) + manifest = build_manifest(view.root, "general-source") + active = KnowledgeView(view.root, "general-source", manifest["files"]) + monkeypatch.setattr(KnowledgeView, "current", classmethod(lambda cls: active)) + result = DirectClient().read_document("general/rules.md", task_id="ordinary-read") + assert "Preserve the input ownership" in result.content + assert result.knowledge_feedback["status"] == "agreement_required" + assert not AgreementStore.from_env().state_dir.exists() + + +def test_cached_source_receipt_tracks_signature_and_revocation_without_extra_tokens( + retrieval, accept_learning_agreement, +): + factory, _state_path, _view = retrieval + service = factory() + session = helpers.read_session(service) + unsigned = service.read(session, helpers.DOCUMENT) + assert unsigned["knowledge_feedback"]["status"] == "agreement_required" + assert not AgreementStore.from_env().state_dir.exists() + before = service.status(session) + + agreement = accept_learning_agreement() + signed = factory().read(session, helpers.DOCUMENT) + assert signed["knowledge_feedback"]["targets"] + assert helpers.without_feedback(signed) == helpers.without_feedback(unsigned) + assert factory().status(session) == before + assert factory().read(session, helpers.DOCUMENT) == signed + + agreement.revoke() + revoked = factory().read(session, helpers.DOCUMENT) + assert revoked["knowledge_feedback"]["status"] == "agreement_required" + assert helpers.without_feedback(revoked) == helpers.without_feedback(unsigned) + assert factory().status(session) == before + assert factory().read(session, helpers.DOCUMENT) == revoked + + accept_learning_agreement() + renewed = factory().read(session, helpers.DOCUMENT) + assert renewed == signed # the same delivered bytes keep their existing identity + assert factory().status(session) == before + + +def test_invalid_optional_state_keeps_normal_source_available(retrieval, monkeypatch, tmp_path): + _factory, _state_path, _view = retrieval + loop = tmp_path / "loop" + loop.symlink_to(loop) + monkeypatch.setenv("KNOWLEDGE_LEARNING_STATE_DIR", str(loop)) + result = DirectClient().read_document(helpers.DOCUMENT, task_id="ordinary-read") + assert "Preserve the input ownership" in result.content + assert result.knowledge_feedback["status"] == "agreement_required" diff --git a/test/test_learning_agreement_runtime.py b/test/test_learning_agreement_runtime.py new file mode 100644 index 000000000..f1712ded9 --- /dev/null +++ b/test/test_learning_agreement_runtime.py @@ -0,0 +1,354 @@ +"""Runtime consent gates precede data collection, grading, and publication.""" +from __future__ import annotations + +import hashlib +import io +import json +import sqlite3 +from urllib.error import HTTPError + +import pytest + +from infermatrix_copilot.knowledge_service.agreement import ( + AgreementRequiredError, + AgreementStore, +) +from infermatrix_copilot.knowledge_service.feedback import KnowledgeFeedbackStore +from infermatrix_copilot.knowledge_service.feedback_sync import ( + FeedbackSyncClient, + FeedbackSyncConfig, + FeedbackSyncError, +) +from infermatrix_copilot.knowledge_service.learning import TaskLearningService +from infermatrix_copilot.knowledge_service.learning_publication import LearningPublisher +from infermatrix_copilot.knowledge_view import KnowledgeView + +PAGE = "repos/r/rules.md" +CONTENT = "# Rules\n\n## SOURCE-1a — Preserve the source\n\nKeep the executable source contract.\n" + + +@pytest.fixture(autouse=True) +def isolated_environment(monkeypatch): + from infermatrix_copilot.config import Settings + + monkeypatch.setitem(Settings.model_config, "env_file", ()) + for name in ("KNOWLEDGE_FEEDBACK_URL", "KNOWLEDGE_FEEDBACK_TOKEN", + "KNOWLEDGE_LEARNING_STATE_DIR", "KNOWLEDGE_LEARNING_PUBLICATION", + "KNOWLEDGE_LEARNING_REPOSITORY", "KNOWLEDGE_LEARNING_BASE"): + monkeypatch.delenv(name, raising=False) + + +def accept(state_dir, *, feedback_url=None, environ=None): + """Create a synthetic acknowledgement exclusively in the test directory.""" + agreement = AgreementStore.from_env(state_dir=state_dir, feedback_url=feedback_url, environ=environ) + document = agreement.document() + agreement._accept("Synthetic Test User", version=document["version"], + agreement_sha256=document["sha256"], + context_sha256=document["context_sha256"], confirmation="I AGREE") + return agreement + + +@pytest.fixture +def world(tmp_path): + root = tmp_path / "knowledge" + (root / PAGE).parent.mkdir(parents=True) + (root / PAGE).write_text(CONTENT) + return KnowledgeFeedbackStore(tmp_path / "state"), KnowledgeView(root, "snapshot-1") + + +def issue(world, task="task-1"): + store, view = world + return store.issue_delivery(task_id=task, repository="r", view=view, + documents=[{"path": PAGE, "content": CONTENT}]) + + +def vote(receipt): + return {"target_id": receipt["targets"][0]["target_id"], "score": 1, "used": True, + "reason": "The rule guided a verified result.", "evidence": ["Focused contract test passed."]} + + +def record(store, receipt): + return store.record(task_id=receipt["task_id"], delivery_id=receipt["delivery_id"], + ratings=[vote(receipt)]) + + +def test_unsigned_learning_refuses_before_lesson_processing_or_runtime_creation(tmp_path, monkeypatch): + service = TaskLearningService(tmp_path / "state", tmp_path / "no-checkout") + + def never_process(_lessons): + raise AssertionError("unsigned lessons must not be processed") + + monkeypatch.setattr(service, "_lessons", never_process) + with pytest.raises(AgreementRequiredError): + service.prepare("task", "r", "a" * 40, []) + with pytest.raises(AgreementRequiredError): + service.submit("task", "invalid", {"rules": []}) + assert service.status("task") == {"status": "unknown"} + assert not service.state_dir.exists() + + +def test_unsigned_feedback_never_touches_content_or_creates_ledger(tmp_path): + class UnreadableView: + @property + def root(self): + raise AssertionError("unsigned delivery must not inspect knowledge") + + store = KnowledgeFeedbackStore(tmp_path / "state") + result = store.issue_delivery(task_id="task", repository="r", view=UnreadableView(), documents=None) + assert result == {"status": "agreement_required", "protocol": "knowledge-feedback/1", "targets": []} + with pytest.raises(AgreementRequiredError): + store.record(task_id="task", delivery_id="invalid", ratings=[]) + with pytest.raises(AgreementRequiredError): + store.central_report() + assert store.sync_pending()["status"] == "agreement_required" + assert store.sync_status()["pending_count"] == 0 + assert store.repositories_for_task("task") == () + assert store.report()["total_ratings"] == 0 + assert not store.state_dir.exists() + + +def test_acknowledgement_enables_grading_and_revocation_preserves_identity(world): + store, _view = world + agreement = accept(store.state_dir) + receipt = issue(world) + first = record(store, receipt) + assert first["sync"]["status"] == "disabled" + agreement.revoke() + assert issue(world)["status"] == "agreement_required" + with pytest.raises(AgreementRequiredError): + record(store, receipt) + assert store.sync_pending()["pending_count"] == 1 + assert store.report()["total_ratings"] == 1 + assert store.repositories_for_task("task-1") == ("r",) + accept(store.state_dir) + assert issue(world) == receipt + assert record(store, receipt)["ratings"] == first["ratings"] + assert store.report()["total_ratings"] == 1 + + +def test_changed_agreement_version_refuses_new_events(world, monkeypatch): + from infermatrix_copilot.knowledge_service import agreement as module + + store, _view = world + accept(store.state_dir) + receipt = issue(world) + monkeypatch.setattr(module, "AGREEMENT_VERSION", "future-version") + assert issue(world)["status"] == "agreement_required" + with pytest.raises(AgreementRequiredError): + record(store, receipt) + + +def test_real_constructor_destination_must_match_acknowledgement(world, monkeypatch): + original, view = world + first_url, second_url = "https://first.example", "https://second.example" + monkeypatch.setenv("KNOWLEDGE_FEEDBACK_URL", second_url) + # Signing a different configured URL cannot authorize the actual constructor URL. + accept(original.state_dir) + configured = KnowledgeFeedbackStore(original.state_dir, + sync_config=FeedbackSyncConfig(first_url, "x" * 32)) + assert issue((configured, view))["status"] == "agreement_required" + accept(original.state_dir, feedback_url=first_url) + assert "delivery_id" in issue((configured, view)) + configured.sync_config = FeedbackSyncConfig(second_url, "x" * 32) + assert issue((configured, view))["status"] == "agreement_required" + + +def test_revocation_blocks_legacy_backfill_and_preserves_queue(world): + store, _view = world + agreement = accept(store.state_dir) + receipt = issue(world) + record(store, receipt) + with sqlite3.connect(store.path) as db: + db.execute("DELETE FROM feedback_outbox") + db.execute("DELETE FROM feedback_sync_meta") + agreement.revoke() + assert store.sync_pending()["pending_count"] == 1 + with sqlite3.connect(store.path) as db: + assert db.execute("SELECT COUNT(*) FROM feedback_outbox").fetchone()[0] == 0 + assert db.execute("SELECT COUNT(*) FROM feedback_sync_meta").fetchone()[0] == 0 + accept(store.state_dir) + assert store.sync_pending()["pending_count"] == 1 + with sqlite3.connect(store.path) as db: + assert db.execute("SELECT COUNT(*) FROM feedback_outbox").fetchone()[0] == 1 + + +def test_transport_is_gated_even_when_called_directly(tmp_path, monkeypatch): + config = FeedbackSyncConfig("https://collector.example", "x" * 32) + client = FeedbackSyncClient(config, state_dir=tmp_path / "state") + + def never_network(*_args, **_kwargs): + raise AssertionError("unsigned transport must not open a network connection") + + monkeypatch.setattr("infermatrix_copilot.knowledge_service.feedback_sync.build_opener", never_network) + with pytest.raises(AgreementRequiredError): + client.send(receipt={}, rating={}, target={}, feedback_id="invalid") + with pytest.raises(AgreementRequiredError): + client._request("/v1/feedback/events", {}) + with pytest.raises(AgreementRequiredError): + client.report(repository="r", limit=100) + assert not client.state_dir.exists() + + +def test_transport_adds_minimal_attestation_and_rechecks_before_request(world, monkeypatch): + original, view = world + config = FeedbackSyncConfig("https://collector.example", "x" * 32) + store = KnowledgeFeedbackStore(original.state_dir, sync_config=config) + agreement = accept(store.state_dir, feedback_url=config.url) + receipt = issue((store, view)) + events = [] + + def inspect_event(client, path, payload): + events.append(payload) + agreement.revoke() + # Exercise the real transport gate after send's first check. + return original_request(client, path, payload) + + original_request = FeedbackSyncClient._request + monkeypatch.setattr(FeedbackSyncClient, "_request", inspect_event) + result = record(store, receipt) + assert result["sync"]["status"] == "agreement_required" + assert result["sync"]["pending_count"] == 1 + assert len(events) == 1 + attestation = events[0]["agreement"] + assert attestation["purpose"] == "feedback_upload" + assert "Synthetic Test User" not in json.dumps(attestation) + assert "signer" not in attestation + + +def test_flush_rechecks_between_events_without_dropping_pending_rows(world, monkeypatch): + original, view = world + config = FeedbackSyncConfig("https://collector.example", "x" * 32) + store = KnowledgeFeedbackStore(original.state_dir, sync_config=config) + agreement = accept(store.state_dir, feedback_url=config.url) + + def offline(*_args, **_kwargs): + raise FeedbackSyncError("offline") + + monkeypatch.setattr(FeedbackSyncClient, "send", offline) + for task in ("task-1", "task-2"): + receipt = issue((store, view), task=task) + record(store, receipt) + uploaded = [] + + def send_then_revoke(*_args, **kwargs): + uploaded.append(kwargs["feedback_id"]) + agreement.revoke() + + monkeypatch.setattr(FeedbackSyncClient, "send", send_then_revoke) + result = store.sync_pending() + assert result["status"] == "agreement_required" + assert result["pending_count"] == 1 + assert result["acknowledged_count"] == 1 + assert len(uploaded) == 1 + assert store.report()["total_ratings"] == 2 + + +def test_publisher_requires_explicit_agreement_before_any_command(tmp_path, monkeypatch): + def never_run(*_args, **_kwargs): + raise AssertionError("unsigned publication must not run commands") + + monkeypatch.setattr("infermatrix_copilot.knowledge_service.learning_publication._run", never_run) + publisher = LearningPublisher({"KNOWLEDGE_LEARNING_PUBLICATION": "draft_pr", + "KNOWLEDGE_LEARNING_REPOSITORY": "owner/knowledge", + "ALLOW_PUSH": "1", "ALLOW_POST": "1"}, state_dir=tmp_path / "state") + with pytest.raises(AgreementRequiredError): + publisher.publish(tmp_path, task_digest="a" * 64, head="b" * 40, + packet_digest="c" * 64, rules=1, outcomes={}) + assert not (tmp_path / "state").exists() + + +def test_learning_pending_submission_requires_current_agreement(tmp_path): + state = tmp_path / "state" + agreement = accept(state) + service = TaskLearningService(state, tmp_path / "no-checkout") + packet = service.prepare("empty", "r", "a" * 40, []) + agreement.revoke() + before = service.database.read_bytes() + with pytest.raises(AgreementRequiredError): + service.submit("empty", packet["packet_digest"], {"rules": []}) + assert service.database.read_bytes() == before + assert service.status("empty")["status"] == "no_op" + + +def test_publisher_rechecks_after_validation_before_remote_fetch(tmp_path, monkeypatch): + environ = {"KNOWLEDGE_LEARNING_PUBLICATION": "draft_pr", + "KNOWLEDGE_LEARNING_REPOSITORY": "owner/knowledge", + "ALLOW_PUSH": "1", "ALLOW_POST": "1"} + agreement = accept(tmp_path / "state", environ=environ) + workspace = tmp_path / "checkout" + document = "knowledge/repos/r/rules.md" + page = workspace / document + page.parent.mkdir(parents=True) + page.write_text(CONTENT) + head, base = "a" * 40, "b" * 40 + calls = [] + + def command(command, _workspace): + calls.append(command) + if command[1:3] == ["check-ref-format", "--branch"]: + return "main" + if command[1:] == ["rev-parse", "HEAD"]: + return head + if command[1:] == ["rev-parse", "HEAD^"]: + return base + if command[1] == "status": + return "" + if command[1] == "diff": + agreement.revoke() + return document + raise AssertionError("revoked publication must not perform remote commands") + + monkeypatch.setattr("infermatrix_copilot.knowledge_service.learning_publication._run", command) + with pytest.raises(AgreementRequiredError): + LearningPublisher(environ, state_dir=tmp_path / "state").publish( + workspace, task_digest="c" * 64, head=head, base_sha=base, + packet_digest="d" * 64, rules=1, outcomes={}, + documents={document: hashlib.sha256(CONTENT.encode()).hexdigest()}) + assert not any(command[1] == "fetch" for command in calls) + + +def test_changed_publication_destination_blocks_prepared_task(tmp_path, monkeypatch): + state = tmp_path / "state" + accept(state) + service = TaskLearningService(state, tmp_path / "no-checkout") + packet = service.prepare("empty", "r", "a" * 40, []) + monkeypatch.setenv("KNOWLEDGE_LEARNING_PUBLICATION", "draft_pr") + monkeypatch.setenv("KNOWLEDGE_LEARNING_REPOSITORY", "new-owner/knowledge") + with pytest.raises(AgreementRequiredError): + service.submit("empty", packet["packet_digest"], {"rules": []}) + assert service.status("empty")["status"] == "no_op" + + +def test_direct_transport_helper_still_blocks_secret_egress(tmp_path, monkeypatch): + state = tmp_path / "state" + url = "https://collector.example" + accept(state, feedback_url=url) + + def never_network(*_args, **_kwargs): + raise AssertionError("private outgoing material must not reach a network connection") + + monkeypatch.setattr("infermatrix_copilot.knowledge_service.feedback_sync.build_opener", never_network) + client = FeedbackSyncClient(FeedbackSyncConfig(url, "x" * 32), state_dir=state) + with pytest.raises(FeedbackSyncError, match="privacy_blocked"): + client._request("/v1/feedback/events", {"evidence": "ghp_" + "s" * 30}) + + +def test_collector_428_preserves_pending_event_and_reports_agreement_required(world, monkeypatch): + original, view = world + config = FeedbackSyncConfig("https://collector.example", "x" * 32) + accept(original.state_dir, feedback_url=config.url) + store = KnowledgeFeedbackStore(original.state_dir, sync_config=config) + receipt = issue((store, view)) + private_error = "private-collector-response" + + class RejectedByCollector: + def open(self, request, timeout): + raise HTTPError(request.full_url, 428, private_error, {}, io.BytesIO(private_error.encode())) + + monkeypatch.setattr("infermatrix_copilot.knowledge_service.feedback_sync.build_opener", + lambda *_args: RejectedByCollector()) + result = record(store, receipt) + assert result["sync"]["status"] == "agreement_required" + assert result["sync"]["pending_count"] == 1 + assert store.report()["total_ratings"] == 1 + assert private_error not in json.dumps(result) diff --git a/test/test_learning_config.py b/test/test_learning_config.py new file mode 100644 index 000000000..9e7170663 --- /dev/null +++ b/test/test_learning_config.py @@ -0,0 +1,30 @@ +from infermatrix_copilot.config import Settings +from infermatrix_copilot.knowledge_service.feedback import KnowledgeFeedbackStore +from infermatrix_copilot.knowledge_service.learning import TaskLearningService +from infermatrix_copilot.knowledge_service.learning_config import learning_environment +from infermatrix_copilot.knowledge_service.learning_publication import LearningPublisher + + +def test_dotenv_options_reach_services_without_exporting_credentials(tmp_path, monkeypatch): + first, second = tmp_path / "source.env", tmp_path / "user.env" + state = tmp_path / "learning-state" + workspace = tmp_path / "knowledge-checkout" + first.write_text("KNOWLEDGE_LEARNING_PUBLICATION=local\nALLOW_PUSH=0\n") + second.write_text(f"KNOWLEDGE_LEARNING_STATE_DIR={state}\n" + f"KNOWLEDGE_LEARNING_WORKSPACE={workspace}\n" + "KNOWLEDGE_LEARNING_PUBLICATION=draft_pr\nALLOW_PUSH=1\nALLOW_POST=1\n" + "ANTHROPIC_API_KEY=private-model-value\n") + monkeypatch.setattr(Settings, "model_config", {**Settings.model_config, "env_file": (str(first), str(second))}) + for key in ("KNOWLEDGE_LEARNING_STATE_DIR", "KNOWLEDGE_LEARNING_WORKSPACE", + "KNOWLEDGE_LEARNING_PUBLICATION", "ALLOW_PUSH", "ALLOW_POST"): + monkeypatch.delenv(key, raising=False) + options = learning_environment() + assert options["KNOWLEDGE_LEARNING_PUBLICATION"] == "draft_pr" + assert "ANTHROPIC_API_KEY" not in options + assert TaskLearningService.from_env().state_dir == state + assert TaskLearningService.from_env().workspace_root == workspace + assert KnowledgeFeedbackStore.from_env().state_dir == state + assert LearningPublisher().environ["ALLOW_PUSH"] == "1" + assert LearningPublisher({}).environ == {} + monkeypatch.setenv("KNOWLEDGE_LEARNING_PUBLICATION", "local") + assert learning_environment()["KNOWLEDGE_LEARNING_PUBLICATION"] == "local" diff --git a/test/test_learning_privacy.py b/test/test_learning_privacy.py new file mode 100644 index 000000000..f47f8a4ac --- /dev/null +++ b/test/test_learning_privacy.py @@ -0,0 +1,30 @@ +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") + +from infermatrix_copilot.knowledge_service.learning_privacy import ( + LearningPrivacyError, + validate_distilled_text, +) + + +@pytest.mark.parametrize("value", [ + "ghp_" + "a" * 36, + "github_pat_" + "a" * 55, + "sk-proj-" + "b" * 40, + "AKIA" + "1" * 16, + "-----BEGIN OPENSSH PRIVATE KEY-----", + "Bearer " + "a" * 32, + "https://user:secret@example.com/repo", +]) +def test_known_credentials_are_rejected_without_being_echoed(value): + with pytest.raises(LearningPrivacyError) as caught: + validate_distilled_text({"rules": [{"section_markdown": value}]}) + assert value not in str(caught.value) + + +def test_chat_export_is_rejected_but_protocol_examples_are_allowed(): + validate_distilled_text({"summary": 'Validate the {"role":"user"} message shape before dispatch.'}) + validate_distilled_text({"evidence": ["tests/test_api.py::test_empty_input passed"]}) + with pytest.raises(LearningPrivacyError, match="conversation export"): + validate_distilled_text("user: " + "private chat " * 40 + "\nassistant: another private response") diff --git a/test/test_learning_recovery.py b/test/test_learning_recovery.py new file mode 100644 index 000000000..a8127dc63 --- /dev/null +++ b/test/test_learning_recovery.py @@ -0,0 +1,265 @@ +"""Task isolation and rejected-preparation recovery through real services.""" + +from __future__ import annotations + +import json +import os +import sqlite3 +import subprocess +import sys +import threading +import time +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path + +import pytest + +pytestmark = pytest.mark.usefixtures("accepted_learning_feature") +from test_chat_knowledge_learning import git, lessons, proposal +from test_chat_knowledge_learning import source as _source_fixture + +from infermatrix_copilot.knowledge_service.learning import ( + TaskLearningError, + TaskLearningService, +) +from infermatrix_copilot.knowledge_service.learning_publication import LearningPublisher +from infermatrix_copilot.trace_store import file_lock + +source = _source_fixture + + +def _legacy_invalid_preparation(service, monkeypatch): + # Old versions had no committed-slice preflight: persist preparing intent, + # create the detached checkout, and only then discover the missing slice. + with monkeypatch.context() as old_version: + old_version.setattr(service, "_verify_repository", lambda *_args: None) + with pytest.raises(TaskLearningError, match="no verified knowledge slice"): + service.prepare("legacy-typo", "unknown", "a" * 40, lessons()) + packet = service.status("legacy-typo") + assert packet["status"] == "preparing" + checkout = service._checkout(packet["task_key"]) + assert checkout.is_dir() + return checkout + + +def test_corrected_repository_recovers_pristine_previously_poisoned_task(source, tmp_path, monkeypatch): + service = TaskLearningService(tmp_path / "state", source) + checkout = _legacy_invalid_preparation(service, monkeypatch) + original_inode = checkout.stat().st_ino + packet = service.prepare("legacy-typo", "x", "a" * 40, lessons()) + assert packet["status"] == "prepared" and packet["repository"] == "x" + assert checkout.stat().st_ino == original_inode, "reuse the proven pristine worktree" + assert git(source, "worktree", "list", "--porcelain").count("worktree ") == 2 + assert service.submit(packet["task_id"], packet["packet_digest"], proposal(packet))["status"] == "local" + + +def test_corrected_repository_recovers_legacy_intent_without_worktree(source, tmp_path, monkeypatch): + service = TaskLearningService(tmp_path / "state", source) + checkout = _legacy_invalid_preparation(service, monkeypatch) + # A prior interrupted/manual cleanup may leave just the durable intent. + git(source, "worktree", "remove", str(checkout)) + packet = service.prepare("legacy-typo", "x", "a" * 40, lessons()) + assert packet["status"] == "prepared" + assert checkout.is_dir() + + +def test_corrected_repository_preserves_dirty_legacy_worktree(source, tmp_path, monkeypatch): + service = TaskLearningService(tmp_path / "state", source) + checkout = _legacy_invalid_preparation(service, monkeypatch) + private = checkout / "unfinished-user-work.txt" + private.write_text("Preserve these unknown bytes.\n") + with pytest.raises(TaskLearningError, match="preserve it for inspection"): + service.prepare("legacy-typo", "x", "a" * 40, lessons()) + assert private.read_text() == "Preserve these unknown bytes.\n" + assert service.status("legacy-typo")["repository"] == "unknown" + assert service.status("legacy-typo")["status"] == "preparing" + + +@pytest.mark.parametrize("artifact", ["application-intent.json", "applied.json", "unknown-user-note.txt"]) +def test_corrected_repository_refuses_unknown_or_applied_legacy_artifacts(source, tmp_path, monkeypatch, artifact): + service = TaskLearningService(tmp_path / "state", source) + checkout = _legacy_invalid_preparation(service, monkeypatch) + retained = checkout.parent / artifact + retained.write_text("private state must survive\n") + with pytest.raises(TaskLearningError, match="preserve it for inspection"): + service.prepare("legacy-typo", "x", "a" * 40, lessons()) + assert retained.read_text() == "private state must survive\n" + assert service.status("legacy-typo")["repository"] == "unknown" + + +def test_legacy_repository_correction_cannot_change_source_or_lessons(source, tmp_path, monkeypatch): + service = TaskLearningService(tmp_path / "state", source) + _legacy_invalid_preparation(service, monkeypatch) + for source_pin, distilled in (("b" * 40, lessons()), ("a" * 40, lessons()[:1])): + with pytest.raises(TaskLearningError, match="different learning packet"): + service.prepare("legacy-typo", "x", source_pin, distilled) + assert service.status("legacy-typo")["repository"] == "unknown" + + +@pytest.mark.parametrize("slice_kind", ["missing", "untracked", "file"]) +def test_invalid_repository_does_not_reserve_task_or_create_worktree(source, tmp_path, slice_kind): + invalid_slice = source / "knowledge/repos/unknown" + if slice_kind == "untracked": + invalid_slice.mkdir() + elif slice_kind == "file": + invalid_slice.write_text("A file is not a repository slice.\n") + git(source, "add", ".") + git(source, "commit", "-qm", "non-directory slice") + service = TaskLearningService(tmp_path / "state", source) + task_id = "repository-typo" + + with pytest.raises(TaskLearningError, match="no verified knowledge slice"): + service.prepare(task_id, "unknown", "a" * 40, lessons()) + + assert service.status(task_id) == {"status": "unknown"} + assert not service._checkout(service._task(task_id)).exists() + assert git(source, "worktree", "list", "--porcelain").count("worktree ") == 1 + corrected = service.prepare(task_id, "x", "a" * 40, lessons()) + assert corrected["status"] == "prepared" + assert service.submit(task_id, corrected["packet_digest"], proposal(corrected))["status"] == "local" + + +def test_concurrent_same_task_prepare_reuses_one_frozen_worktree(source, tmp_path): + def prepare(_): + return TaskLearningService(tmp_path / "state", source).prepare("same-preparation", "x", "a" * 40, lessons()) + + with ThreadPoolExecutor(max_workers=4) as pool: + packets = list(pool.map(prepare, range(4))) + assert all(packet["status"] == "prepared" for packet in packets) + assert len({packet["packet_digest"] for packet in packets}) == 1 + assert git(source, "worktree", "list", "--porcelain").count("worktree ") == 2 + + +@pytest.mark.parametrize("boundary", ["prepare", "apply", "publish"]) +def test_slow_task_does_not_hold_sqlite_writer_lock_for_other_tasks(source, tmp_path, monkeypatch, boundary): + first = TaskLearningService(tmp_path / "state", source) + second = TaskLearningService(tmp_path / "state", source) + packet = first.prepare("slow-task", "x", "a" * 40, lessons()) if boundary != "prepare" else None + entered, release = threading.Event(), threading.Event() + + def wait(): + entered.set() + if not release.wait(10): + raise RuntimeError("test task did not release its gate") + + if boundary == "prepare": + original = first._finish_prepare + + def finish_prepare(*args): + wait() + return original(*args) + + monkeypatch.setattr(first, "_finish_prepare", finish_prepare) + operation = lambda: first.prepare("slow-task", "x", "a" * 40, lessons()) + elif boundary == "apply": + original = first._apply_task + + def apply(*args): + wait() + return original(*args) + + monkeypatch.setattr(first, "_apply_task", apply) + operation = lambda: first.submit(packet["task_id"], packet["packet_digest"], proposal(packet)) + else: + original = LearningPublisher.publish + + def publish(publisher, workspace, **kwargs): + if kwargs["task_digest"] == packet["task_key"]: + wait() + return original(publisher, workspace, **kwargs) + + monkeypatch.setattr(LearningPublisher, "publish", publish) + operation = lambda: first.submit(packet["task_id"], packet["packet_digest"], proposal(packet)) + + with ThreadPoolExecutor(max_workers=1) as pool: + pending = pool.submit(operation) + try: + assert entered.wait(5) + # Fail fast if the slow operation owns SQLite's global write lock, + # rather than waiting through the production 60-second timeout. + with sqlite3.connect(first.database, timeout=0.1) as writer: + writer.execute("BEGIN IMMEDIATE") + assert second.status("slow-task")["status"] == ("preparing" if boundary == "prepare" else "prepared") + other = second.prepare("independent-task", "x", "a" * 40, lessons()) + assert second.submit(other["task_id"], other["packet_digest"], proposal(other))["status"] == "local" + assert not pending.done(), "the unrelated task must finish while the slow task is blocked" + finally: + release.set() + assert pending.result(timeout=10)["status"] == ("prepared" if boundary == "prepare" else "local") + + +def _wait_for_file(path, process): + deadline = time.monotonic() + 10 + while not path.exists() and time.monotonic() < deadline: + if process.poll() is not None: + stdout, stderr = process.communicate() + pytest.fail(f"child exited before its checkpoint: {stdout}\n{stderr}") + time.sleep(0.02) + assert path.exists(), "child did not reach its checkpoint" + + +def test_same_task_submit_serializes_across_processes_and_publishes_once(source, tmp_path): + service = TaskLearningService(tmp_path / "state", source) + packet = service.prepare("shared-task", "x", "a" * 40, lessons()) + worker = tmp_path / "submit_worker.py" + worker.write_text('''import json, sys, time +from pathlib import Path +from infermatrix_copilot.knowledge_service.learning import TaskLearningService +from infermatrix_copilot.knowledge_service.learning_publication import LearningPublisher + +state, source, payload, signal_dir, name = sys.argv[1:] +signals = Path(signal_dir) +packet, proposals = json.loads(Path(payload).read_text()) +service = TaskLearningService(state, source) + +def publish(self, workspace, **kwargs): + with (signals / "publications").open("a") as output: + output.write(name + "\\n") + (signals / "publishing").touch() + deadline = time.monotonic() + 15 + while not (signals / "release").exists(): + if time.monotonic() > deadline: + raise RuntimeError("publication release timed out") + time.sleep(0.02) + return {"status": "draft_pr", "url": "https://github.com/example/knowledge/pull/1"} + +LearningPublisher.publish = publish +(signals / (name + "-started")).touch() +result = service.submit(packet["task_id"], packet["packet_digest"], proposals) +print(json.dumps(result)) +''') + payload = tmp_path / "submit.json" + payload.write_text(json.dumps([packet, proposal(packet)])) + signals = tmp_path / "signals" + signals.mkdir() + environment = dict(os.environ) + from infermatrix_copilot.knowledge_service import learning + environment["PYTHONPATH"] = str(Path(learning.__file__).parents[2]) + processes = [] + try: + for name in ("first", "second"): + process = subprocess.Popen( + [sys.executable, str(worker), str(service.state_dir), str(source), str(payload), str(signals), name], + env=environment, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, + ) + processes.append(process) + _wait_for_file(signals / ("publishing" if name == "first" else "second-started"), process) + with file_lock(service.state_dir / "locks" / f"task-{packet['task_key']}.lock", blocking=False) as held: + assert not held, "the publishing child must hold an OS lock visible to other processes" + (signals / "release").touch() + results = [] + for process in processes: + stdout, stderr = process.communicate(timeout=15) + assert process.returncode == 0, stderr + results.append(json.loads(stdout)) + finally: + (signals / "release").touch() + for process in processes: + if process.poll() is None: + process.kill() + process.communicate() + + assert all(result["status"] == "draft_pr" for result in results) + assert len({result["head_sha"] for result in results}) == 1 + assert (signals / "publications").read_text().splitlines() == ["first"] + assert git(service._checkout(packet["task_key"]), "rev-list", "--count", "HEAD") == "2" diff --git a/test/test_thin_mcp_server.py b/test/test_thin_mcp_server.py index 13ec8f15e..6b3c53c0a 100644 --- a/test/test_thin_mcp_server.py +++ b/test/test_thin_mcp_server.py @@ -108,6 +108,13 @@ def test_tool_annotations_mark_the_read_only_surface(monkeypatch): rfc_request = mcp.tool_annotations["rfc_request"] assert rfc_request.readOnlyHint is False and rfc_request.destructiveHint is True assert rfc_request.idempotentHint is False and rfc_request.openWorldHint is True + report = mcp.tool_annotations["knowledge_feedback_report"] + assert report.readOnlyHint is True and report.openWorldHint is True + for name in ("knowledge_learning", "knowledge_feedback", "knowledge_feedback_sync"): + hints = mcp.tool_annotations[name] + assert hints.readOnlyHint is False and hints.destructiveHint is False + assert hints.idempotentHint is True + assert hints.openWorldHint is True def test_direct_entrypoints_do_not_resolve_repo(monkeypatch): @@ -128,6 +135,11 @@ def test_direct_entrypoints_do_not_resolve_repo(monkeypatch): "search_knowledge_context", "expand_knowledge_context", "related_knowledge_context", + "knowledge_learning", + "knowledge_feedback", + "knowledge_feedback_report", + "knowledge_feedback_sync", + "knowledge_agreement", } review = mcp.tools["review"]( @@ -150,6 +162,7 @@ def test_direct_entrypoints_do_not_resolve_repo(monkeypatch): "progress_update", "completion_gate", "diagnostics", + "knowledge_feedback", } assert review["mode"] == "direct" assert review["untested_public_api"] == {"status": "no_diff"}