feat(agent): add dynamic runtime context and domain plugin boundaries

[zhengdaqi]

Summary

This PR adds the generic Agent runtime foundations needed to adopt modern harness techniques in PilotDeck without embedding legal-domain behavior in Core. It introduces bounded, session-scoped dynamic prompt injection, mutable pre-model request hooks, reliable internal prompt arbitration, and artifact completion contracts. Legal or other specialized behavior can now activate through project/domain plugins, Skills, context pointers, and validators.

Architecture Boundary

• PilotDeck Core owns generic mechanics: context lifecycle, prompt budgets, model-request mutation, internal dispatch arbitration, artifact contracts, correction limits, cleanup, and trust boundaries.
• Domain plugins own specialized policy: task detection, Skill selection, context pointers, artifact requirements, and native validators.
• Domain activation runs only for user prompts. Synthetic/internal wake-up prompts cannot spoof a domain task or recursively reactivate domain policy.
• No legal rules, templates, terminology, or legal-specific validation logic are added to Core.

Changes

Dynamic context and model request lifecycle

• Add a session-scoped dynamic context store with stable source/id replacement, priority ordering, TTL expiry, per-entry and per-session prompt budgets, and explicit clear semantics.
• Use a two-phase peek/commit lifecycle so retries and request reconstruction cannot consume context before a model request is actually accepted.
• Inject dynamic context as transient, synthetic, model-only content rather than persisting it into the user transcript.
• Await PreModelRequest hooks and allow them to block a request, add current-request context/system instructions, or patch an allowlisted provider/model/token/temperature/metadata surface.
• Reapply hook effects after routing compaction/rebuild while preserving model hard token limits.

Internal prompt dispatch

• Add an authoritative, session-aware dispatch gate backed by SessionRouter busy state.
• Queue internal prompts FIFO with settle delay, semantic deduplication/coalescing, abort support, wait/turn timeouts, and shutdown handling.
• Make in-process submissions drain the full async turn and prevent WebSocket callers from spoofing internal/synthetic turns.

Artifact completion controls

• Add generic artifact contracts and validator registration with atomic duplicate protection and validator exception isolation.
• Resolve only workspace-relative paths and reject traversal and symlink escapes.
• Validate completion and allow at most two bounded correction turns before returning a failure.

Domain extension point

• Add DomainPlugin and DomainPluginRuntime contracts for project-specific task detection, Skills/context pointers, artifact contracts, and validators.
• Extend declarative project hook output to register dynamic context, restricted model patches, and artifact contracts without modifying Core.
• Ensure session-scoped context and contracts are cleared on normal completion, exceptions, and early async-generator termination.

QA & Evidence

• What was tested: pnpm run build before commit and again after atomic commit restructuring.

  • Observed result: production TypeScript build passed.
  • Artifact: .omo/evidence/20260722-pilotdeck-agent-runtime/README.md
  • Why sufficient: covers type and production assembly integrity.

• What was tested: 41 focused tests for context budgets/lifecycle, mutable request effects, domain activation, artifact correction, cleanup, dispatch ordering/deduplication/cancellation/timeouts/shutdown, and the WebSocket trust boundary.

  • Observed result: 41/41 passed.
  • Artifact: .omo/evidence/20260722-pilotdeck-agent-runtime/focused-tests.txt
  • Why sufficient: directly covers the new high-risk invariants and failure paths.

• What was tested: deterministic real local Gateway integration loading a temporary project command plugin from .pilotdeck/plugins.

  • Observed result: one-shot dynamic context reached only the first model request; maxOutputTokens was patched to 1234; missing final.xlsx triggered correction; completion succeeded only after the artifact was created.
  • Artifact: .omo/evidence/20260722-pilotdeck-agent-runtime/focused-tests.txt
  • Why sufficient: drives production plugin discovery, lifecycle parsing, request construction, model execution, validation, correction, transcript cleanup, and gateway disposal together without an external model.

• What was tested: full compiled test inventory excluding the independently reproduced baseline timer file.

  • Observed result: 154/154 passed.
  • Artifact: .omo/evidence/20260722-pilotdeck-agent-runtime/regression-suite.txt
  • Why sufficient: covers every other compiled repository test surface.

• What was tested: unmodified pnpm test plus a base-branch comparison of the affected timer source/tests.

  • Observed result: 153 passed, 7 cancelled, 0 assertion failures. All cancellations are confined to unchanged tests/network/fetch.spec.ts and reproduce on Node v22.22.0 because its only pending timers are unref()'d.
  • Artifact: .omo/evidence/20260722-pilotdeck-agent-runtime/baseline-known-failure.txt
  • Why sufficient: distinguishes a pre-existing runner/timer defect from this branch; git diff --exit-code origin/main -- src/network/fetch.ts tests/network/fetch.spec.ts passes.

Risks & Residuals

• Prompt inflation: mitigated by entry/session budgets, priority selection, TTL, dedupe, and transient injection.
• Hook privilege expansion: mitigated by an explicit model patch allowlist; hooks cannot replace messages or tools wholesale.
• Re-entrant internal turns: mitigated by authoritative busy state, FIFO arbitration, semantic coalescing, timeouts, and synthetic-turn trust enforcement.
• Unsafe artifact paths: mitigated by workspace containment and symlink escape checks.
• Infinite correction loops: mitigated by a hard maximum of two correction turns and existing turn limits.
• Domain leakage into Core: mitigated by the DomainPlugin boundary; this PR contains no legal-domain policy.
• Baseline network test cancellation: accepted as pre-existing and out of scope; source/tests are unchanged and the remainder of the suite passes.

Related Context

This implements the generic runtime half of the proposed PilotDeck architecture. Legal-domain behavior should be delivered separately as a project/plugin package containing Skills, domain context, artifact contracts, and validators built against these interfaces.

[zhengdaqi]

Verification gate record: CodeQL passed 4/4 on the current head. Cubic was SKIPPED because no Cubic review or comment appeared during the required 10-minute bounded wait, and repository history (30 recent PRs plus recent issue and inline comments) shows no Cubic integration activity. No code changed after the passing local QA evidence and CodeQL run.