Tracking Issue: DSH reliability and cross-Agent PowerContext guidance #1450

Feature description

Make the DSH installation-to-recall journey diagnosable and make PowerContext tool/Skill routing consistent across maintained Agent integrations.

This is a focused follow-up tracker for a reported user journey: install the plugin, connect to a compatible Server, observe automatic recall/capture, and use natural-language Memory or Handoff requests correctly. It records independently deliverable work and acceptance criteria. Child Issues should own implementation and closure.

Problem and proposed solution

Reported user experience

A PowerContext 0.1.0 user reported that:

1. The DSH plugin loaded and exposed pc_* tools, but calls returned Error: PowerContext Server returned HTTP 404.
2. Automatic recall, capture, and injection were not apparent in the conversation, leading the user to suspect that the hook was not registered.
3. Tool descriptions and Skill discovery gave weak guidance. In the reported interaction, the Agent started with pc_memory_list as if listing stored entries were the normal way to restore context.

The user suggested a using-powercontext routing Skill with more focused domain Skills. This is useful as an additional guidance layer, while per-tool descriptions remain necessary because an Agent can call an exposed tool without loading a Skill.

Evidence boundary: these are reported symptoms, supplemented by source inspection. The original failing endpoint, response body, installed plugin revision, and exact DSH version have not been captured here. A wrong endpoint, proxy/base-path configuration, or mismatched Server/plugin revision are possibilities; the status code alone does not establish which occurred. An empty Memory store is also different from a missing HTTP route.

Verified current gaps

Source baseline: PowerContext master f0f288a, inspected on 2026-09-04. Released 0.1.0 and current master must be qualified separately.

Preserve the existing contracts

• Automatic hooks remain responsible for bounded recall and prompt capture. Manual tools supplement that path when the user explicitly requests an operation or needs additional retrieval. Guidance must not claim recall succeeded merely because a hook is configured.
• Explicit “remember/save this” and “search my memories” requests require the corresponding tool and honest reporting of its result. Automatic Source capture is not an explicit Memory write. Ordinary coding prompts must not trigger redundant remember, list, or search calls.
• Preserve the existing plugin diagnostics contract: typed classification, domain errors handled first, content-free diagnostics, bounded presentation, and the supported host channel. DSH currently uses the plugin logger. Diagnostic failures must not break normal Agent work.
• Do not inject a failure form: notice message into model context. That conflicts with the current diagnostics contract. Any additional DSH UI channel needs an explicit presentation decision and, if it changes that contract, design review first. Snapshot metadata may describe real recalled content; it must not fabricate successful recall.
• Diagnostic events and model-facing failures must not contain raw endpoint URLs, credentials, request/response bodies, or user content. An explicit local Doctor/status surface should identify the effective configuration through appropriately redacted output.
• Preserve Scope isolation, exact citations, untrusted historical evidence, and human-controlled candidate approval. Listing or generating a candidate does not approve, publish, install, or execute it.

Proposed child Issues

A–D and F have merged implementation PRs. E is tracked in #1620 and implemented in #1622, currently under review.
Each child owns its implementation and acceptance evidence. E unifies Skill entries as powercontext-project-context and uses package-local references or registered DSH domains; the broader generated distribution architecture remains owned by #1405 / #1410.

• bug(dsh): handle Scope failures at tool and command boundaries #1451 — A — bug(dsh): handle Scope failures at tool and command boundaries — delivered by fix(dsh): handle Scope failures at tool and command boundaries #1452
  First priority: normalize failures from Scope resolution and direct execution, preserve domain semantics, and make health/status commands usable when Scope resolution fails. Acceptance: a required-route 404, a valid resource/domain 404, authentication failure, timeout, and unresolved Scope produce distinct, actionable outcomes without an uncaught host exception or a false success. Do not create or change Scope bindings as a diagnostic side effect.

• bug(dsh): complete automatic-path diagnostics and recall presentation #1457 — B — bug(dsh): complete automatic-path diagnostics and recall presentation — delivered by fix(dsh): complete automatic-path diagnostics and recall presentation #1459
  First priority: connect the missing Scope failure exit to the existing diagnostic mechanism and verify where a DSH user can inspect it. Add supported structured snapshot metadata for actual recalled content. Acceptance: a failed automatic path continues normal Agent work and emits a bounded, content-free diagnostic; an empty result remains normal; successful recall is inspectable without injecting it twice. Preserve independent capture after a preparation failure when Scope is valid. A new diagnostic UI channel remains subject to the contract decision above.

• feat(dsh): diagnose effective Server configuration and document matched setup #1493 — C — feat(dsh): diagnose the effective Server configuration and document matched setup — delivered by feat(dsh): diagnose effective Server configuration and matched setup #1494 (merged on 2026-09-09)
  First priority: complete the DSH-specific release/master setup and Server startup instructions on top of docs: separate released and unreleased install paths #1448. Extend diagnostics to distinguish registration, liveness, readiness, required-route compatibility, and Scope availability. Use the running plugin's resolved configuration for in-host checks; standalone CLI checks must report when they cannot observe the running host's overrides instead of claiming equivalence. Acceptance: a version-matched clean setup with a working Memory-processing configuration and a known fixture reaches usable recall; wrong-route, unreachable, unready, and unscoped cases identify the failing layer. A healthy Server without inference models may correctly return empty recall. Doctor remains read-only and reuses existing service/health diagnostics.

• feat(integrations): align PowerContext system guidance and tool routing #1520 — D — feat(integrations): align PowerContext system guidance and tool routing — delivered by feat(integrations): align agent guidance and tool routing #1522 (merged on 2026-09-15)
  Guidance priority: give each exposed operation concise product/domain context, positive triggers, relevant exclusions, and constraints. Distinguish list for inventory from search for relevant prior context; avoid routine per-turn calls while preserving explicit user requests. Define common semantics with host-specific names and capabilities. Coordinate canonical content and projections with Tracking Issue: deterministic Agent distributions from one canonical plugin #1405 / docs(rfc): define deterministic agent plugin distributions #1410; this child owns guidance behavior, not another distribution generator. Acceptance: DSH and each migrated host expose the intended guidance, unsupported operations are not advertised, and scenario evaluation shows correct routing with the Skill both loaded and unloaded.

• feat(integrations): add layered PowerContext Skill routing #1620 — E — feat(integrations): add layered PowerContext Skill routing — implemented in feat(integrations): add layered PowerContext Skill routing #1622; not merged
  Unify entry names, registration and installed paths as powercontext-project-context without compatibility aliases, and make English/Chinese intents visible in Skill descriptions. File-backed hosts use a small router with focused Scope/Memory, Handoff, and Review references, following MiniMax's organization. DSH registers independently loadable Memory/Handoff/Review runtime Skills alongside its powercontext-project-context router. OpenClaw packages a discoverable Memory/work Skill without advertising unavailable inventory or Review capabilities. OpenCode packages all references; WorkBuddy expands installed reference-file placeholders. Existing tools remain usable without mandatory Skill loading; Scope, exact references and approval boundaries remain authoritative. Tracking Issue: deterministic Agent distributions from one canonical plugin #1405 / docs(rfc): define deterministic agent plugin distributions #1410 retain ownership of the broader distribution architecture. Native loading, installation, archive, model and documentation evidence is linked from feat(integrations): add layered PowerContext Skill routing #1622.

• feat(dsh): expose bounded recall and capture status through /pc #1597 — F — feat(dsh): expose bounded recall and capture status through /pc — delivered by feat(dsh): expose observed recall and capture status through /pc #1600 (merged)
  The registered /pc now reports independent Scope, prepare, capture, flush and pre-step insertion observations for the current session/workspace. Each result identifies the attempt/turn, observation time, safe failure or skip reason and freshness. Retention is limited to the latest attempt for 64 session/workspace pairs; results become stale after five minutes or when their Scope cannot be verified or has changed. Late older completions cannot overwrite newer status. Source acceptance, processing progress and appended snapshots do not imply generated Memory or model consumption; unconfirmed writes remain explicitly unconfirmed. Status reads remain available during Scope failure and do not execute automatic work; Doctor probes do not overwrite real history. Reuses merged A–C and does not depend on D or E. feat(dsh): expose observed recall and capture status through /pc #1600 distinguishes rejected requests from unconfirmed writes and preserves observed HTTP rejection/request IDs through response-body failures. It includes registered-plugin, real HTTP and real DSH runtime regression evidence, with all 18 CI checks passing on head 16207938. The child acceptance checklist is verified in feat(dsh): expose bounded recall and capture status through /pc #1597 and the implementation is merged.

Sequence and existing ownership

A–D and F are merged on master. E (#1622) builds on master 0ed20c54, including D and F, and uses the shared powercontext-project-context entry while #1410 owns the broader distribution architecture. Merged master support does not establish availability in a released package. Delivery checkboxes record merged implementation; they do not claim universal model acceptance.

E validation: #1622 addresses naming, documentation, test-scope and domain-read evaluation review. Current head f4b56ab7: all 21 checks passed. Main CI, native Windows/macOS/Linux services, SQLite/OceanBase acceptance. E remains unchecked until its PR is merged.

Aggregate acceptance remains open. E's raw 400-observation record distinguishes native loading tests from controlled model evaluation. The main 320-case matrix had 289 original automated passes and 262 transcript-reviewed acceptance passes. Review rejected response wrappers, Scope drift, inactive inventory, unsupported substitutions, invalid evidence and misleading reporting; the evaluator now rejects wrapper carriers and non-Handoff Scope changes explicitly. Two 40-case reading probes remain unqualified observations. D's earlier model limitations also remain recorded. The workflow-aware rerun adds 80 observations: 53 routing passes (40/40 ordinary/current-context cases and 13/40 requested-reading probes), with semantic acceptance still unqualified. The evaluator rejects router-only, wrong-domain and late reads; the report identifies 15 historical routing false passes without altering the original records. A further 16-case DSH/OpenCode run after aligning Handoff/preview guidance recorded 15 routing passes and one output-budget truncation; semantic reporting remains unqualified. See #1622 and its standalone evaluation report. Do not mark these residual observations passed or close this tracker automatically when E merges; reconcile the accepted model/host scope and assign any remaining work explicitly.

Tool-count reduction, DSH/MCP parity, Handoff read/edit classification, and approval behavior without an interactive channel need separate design decisions. A settings card, DSH peer/type baseline updates, and release-version hygiene can become independent follow-ups after concrete gaps are verified; they do not block the reliability fixes. Public API, compatibility, or substantial architecture changes follow the RFC process.

Validation and completion

Children should protect observable behavior rather than exact prose, arbitrary keyword counts, internal call order, or a fixed number of tools.

Required acceptance evidence:

1. A clean, version-matched DSH setup captures a known Source. With the required Memory-processing configuration and a deterministic fixture, it produces Memory and recalls the expected context in a subsequent session using the same intended Scope. Verify capture, processing, and recall separately; a valid empty result remains a successful diagnosed state.
2. Route mismatch, domain absence, authentication failure, timeout, empty recall, and missing Scope remain distinguishable; diagnostics/status work during failure and never turn failure into saved Memory or injected context.
3. English and Chinese scenarios cover ordinary coding, continuing prior work, explicit remember/search, inventory, Handoff, candidate review, and unavailable tools. Record host/model/configuration, the baseline failure, actual calls/results, and evaluation limits. Description keywords alone do not establish reliable Agent behavior.
4. Exact citations, Scope isolation, explicit-write semantics, human Review boundaries, bounded injection, and diagnostic redaction remain intact.

Relevant commands for child work, as applicable:

pnpm --dir integrations/dsh/plugins/powercontext test
pnpm --dir integrations/dsh/plugins/powercontext run test:e2e
uv run pytest tests/test_dsh_cli.py tests/e2e/test_dsh_http_chain.py -q
make docs-test

Use each affected host's own checks. If the OpenAPI contract changes, edit openapi/powercontext.yaml, regenerate with make api-generate, and run make contract-test; do not hand-edit generated clients.

Close this tracker when A–F have linked delivery and acceptance evidence for their agreed host/version scope. Any deferred work must have an explicit disposition and an independent Issue where appropriate; it must not be marked delivered. Released and master-only support must remain distinguishable. Child PRs should close their child Issue and reference this tracker rather than close the entire tracker.

Alternatives considered

• Only expand tool descriptions: improves immediate selection but leaves failure diagnosis, workflow detail, and cross-host drift unresolved.
• Only add a router Skill: insufficient when a model calls an already-visible tool without loading the Skill.
• Only fix Server connectivity: necessary, but leaves redundant inventory/search and misleading explicit-memory acknowledgements possible.
• Combine everything in one implementation Issue/PR: couples urgent fixes to packaging and Skill design. Independent children keep acceptance and delivery bounded.

Additional context

This proposal is based on the reported user experience and current source/contract inspection. It does not claim an end-to-end reproduction of the original user's environment or completed Agent-routing evaluations. Child Issues should capture exact versions and sanitized reproduction evidence before asserting a specific deployment root cause.

AI assistance: OpenAI Codex assisted with source inspection, existing-Issue reconciliation, and preparation of this proposal.

Are you willing to contribute to this feature?

• Yes, I am willing to contribute code, docs, or design feedback.