Skip to content

feat(server): expose read-only extraction diagnostics - #1796

Merged
PsiACE merged 12 commits into
masterfrom
codex/extraction-health
Oct 10, 2026
Merged

PsiACE merged 12 commits into
masterfrom
codex/extraction-health

Conversation

@PsiACE

@PsiACE PsiACE commented Sep 29, 2026 •

Copy link
Copy Markdown
Member

Which issue or RFC does this PR close?

Related: Artifact Processing Supervisor RFC.

Rationale for this change

A capability boolean cannot distinguish missing extraction configuration, model failures, and worker crashes.

What changes are included in this PR?

  • Expose independent extraction configuration, Supervisor state, and local observations in capabilities.
  • Retain failure evidence across later successes and classify errors without exposing provider messages.
  • Update OpenAPI, generated models, English/Chinese operating docs, and behavior tests.

Are there any user-facing changes?

GET /v1/capabilities adds a read-only extraction snapshot without model probes or diagnostic database queries. External configuration and execution state remain unknown. Observations start unverified and reset with the Runtime; historical success or failure is not a current health verdict. No migration.

How was this change tested?

  • make check
  • make contract-test (49 passed)
  • Extraction, Supervisor, composition, metrics, Server, and CLI regression suites (137 passed).
  • make e2e-test (316 passed, 64 skipped)
  • make docs-test

Tests cover missing configuration, model errors, worker crashes/timeouts, leader/standby roles, discovery failures, retained history, no-op flushes, and restart semantics. Model failures were injected; worker crash/timeout tests used real child processes. Lease-role tests used SQLite. No live model calls.

AI usage statement

Codex (GPT-6) assisted with implementation, tests, and PR preparation.

@PsiACE
PsiACE marked this pull request as draft September 29, 2026 10:18
@PsiACE PsiACE added the 1.3.0 label Sep 29, 2026
@PsiACE
PsiACE marked this pull request as ready for review October 5, 2026 15:56
@PsiACE

PsiACE commented Oct 9, 2026

Copy link
Copy Markdown
Member Author

Is this PR ready for review?

yep, let's move

PsiACE commented Oct 9, 2026

Copy link
Copy Markdown
Member Author

Capabilities exposes configuration, Supervisor state, and execution evidence as independent facts.

Runtime configuration ------+
memory.flush() outcomes ----+--> ExtractionDiagnostics --> /v1/capabilities
Supervisor/worker outcomes -+                                 |
                                                             `-- extraction
                                                                   +-- configuration
                                                                   +-- background
                                                                   `-- observation
  • configuration: pipeline assembled, absent, or unknown. Configuration does not verify model credentials or connectivity.
  • background: execution location, Supervisor role/state, and automatic scheduling. A standby Supervisor is normal; a worker crash can coexist with a running Supervisor that retries.
  • observation: observation-window start, latest success, and latest failure with a safe code, stage, and timestamp. Model timeouts and worker crashes remain distinguishable without exposing raw error messages.

Reads use in-memory state, with no model probes or diagnostic database queries. Existing execution boundaries record outcomes; scheduling and retry behavior are unchanged.

Observations start unverified and reset with the Runtime. Success never clears historical failure: Scope B succeeding does not prove Scope A recovered. Neither record is an overall health verdict, and success does not guarantee a new Memory was produced.

External worker configuration/state remain unknown. Queue depth stays in existing metrics, where ready, retrying, and unacknowledged work have explicit units.

@Zxf-xufeng Zxf-xufeng left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. [P2] Regenerate the Dify contract after changing OpenAPI

This PR updates openapi/powercontext.yaml but leaves integrations/dify/plugin/powercontext_dify/contract.json unchanged. Its stored openapi_sha256 therefore no longer matches the specification. I reproduced a failure of python -X utf8 integrations/dify/generate_contract.py --check on this PR, while the same check passes on the base commit. This check is part of make dify-test, so the dify-tools CI job cannot pass with the current generated artifact. Please regenerate and commit the Dify contract.

  1. [P2] Account for custom Memory workers in extraction configuration

At src/powercontext/builtin/runtime/composition.py:601, pipeline_configured only checks the parent process's contexts.memory_extraction. A custom Memory worker registered through artifact_processing_bindings can assemble its own extraction pipeline, yet diagnostics report configuration="unconfigured".

I reproduced this with a real spawned worker: it successfully created Memory revision 1 and durably acknowledged the invocation (1/1), while diagnostics still reported unconfigured alongside background.state="running" and a populated last_success_at. Please include registered local Memory bindings when determining the configuration status.

@PsiACE
PsiACE requested a review from yihong0618 as a code owner October 9, 2026 07:22
@PsiACE
PsiACE requested review from Teingi and Zxf-xufeng October 9, 2026 07:23
@PsiACE

PsiACE commented Oct 9, 2026

Copy link
Copy Markdown
Member Author

@Zxf-xufeng @Teingi Please re-review the fixes in commit 5f40ec5.

  • Regenerated the Dify contract fingerprint; the generator check now passes.
  • Extraction configuration now includes registered local Memory workers. The API role retains unknown external execution status.
  • Added regressions using real spawned workers in both global and dedicated modes. They verify readable Memory revision 1, durable requested/handled generations of 1/1, and configured diagnostics before and after execution. Other Family registrations do not configure Memory extraction.
  • Updated the English and Chinese configuration documentation.

Validation: 90 focused Python regression/contract tests passed, along with Python/JS generation checks, Ruff, formatting, and the affected ty check. Python dependencies were copied from the local cache at the exact uv.lock versions into an isolated Docker workspace. No remote model or OceanBase acceptance is claimed.

The full pre-commit hook run could not complete because isolated hook dependency installation failed; the existing regression and static checks passed, and CI still needs to confirm the full hook suite.

@PsiACE
PsiACE merged commit bfd1448 into master Oct 10, 2026
29 checks passed
@PsiACE
PsiACE deleted the codex/extraction-health branch October 21, 2026 07:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants