Repository navigation
Closed
Labels
Description
Tracking issue: #47
Feature PR: #61
Plan: docs/plans/opencode-auto-advisor.md
Desired outcome
Establish the OpenCode V2 package, explicit Advisor path, configuration contract, and stable routing domain independently of any production Jev/System One provider implementation.
This issue absorbs the former routing-domain scope from #49.
Scope
Package and configuration
- Scaffold
@capybearista/opencode-auto-advisorusing current repository V2 Promise-plugin conventions. - Initial compatibility baseline:
@opencode/plugin@2.0.19and@opencode/ai@2.0.19. - Add optional sparse global
auto-advisor.json, resolved through OpenCode's platform-appropriate global config directory. - Use strict JSON and global-only Auto Advisor config in v1.
- Missing file/settings use defaults; invalid explicit values fail configuration clearly.
- Never store credentials/secrets in this file.
Six intended v1 knobs:
advisor.modelrouting.mode—off | observe | activerouting.modelsrouting.advisorWouldHelpThresholdrouting.consequenceThresholdrouting.maxConsultationsPerTurn
Explicit Advisor
- Register zero-argument
advisor(). - Give the Executor a clear tool description without requiring context/question arguments.
- Capture the actual relevant Executor context.
- Serialize roles and chronology faithfully for fresh Advisor inference.
- Preserve material text/reasoning/tool-call/tool-result context exposed by OpenCode.
- Represent unsupported media/file content explicitly with safe metadata/placeholders; do not silently drop it or claim the Advisor inspected the media.
- Implement one shared fresh/stateless Advisor service.
- If
advisor.modelis omitted, inherit the current Executor model. - Return concise plain-text advice as the genuine tool result.
- Make explicit consultation failures visible to the Executor.
- Add focused runtime validation proving same-turn content immediately before
advisor()is recoverable.
Stable routing domain
- Define
off,observe, andactivesemantics. - Define materially new primary-dispatch routing opportunities at the
session.contextboundary. - Build normalized routing state and deterministic state/context fingerprinting.
- Suppress equivalent/unchanged opportunities.
- Ensure plugin-injected advice does not recursively make a state appear new.
- Define an
AdvisorRouterabstraction that contains no OpenCode Evaluation/System One types. - Provide fake/test router support.
- Normalize router results to:
advisor_would_helpprobability;- 0-4
consequencescore; - optional adapter metadata.
- Keep model estimates separate from deterministic policy.
- Use AND policy semantics:
advisor_would_help >= threshold && consequence >= threshold. - Make both thresholds configurable.
- Define/configure
routing.maxConsultationsPerTurnas a positive integer, default 1. - Explicit
advisor()calls never consume the automatic budget. - Define deterministic budget accounting around automatic Advisor failures during implementation planning.
Non-goals
- production Zen/System One adapter;
- direct TypeSafe integration;
- OpenRouter/other routing providers;
- automatic Advisor invocation/delivery;
- telemetry persistence/RPC implementation;
- final threshold calibration;
- Advisor-model fallback chain;
- project-level Auto Advisor config.
Constraints
- OpenCode V2 only.
- The Executor must not author an Advisor context summary.
- No persistent private Advisor session.
- No Advisor tools in v1.
- Context serialization must not claim unsupported media was directly seen.
- Use supported V2 plugin/generation surfaces.
- OpenCode Evaluation/System One types must not leak into stable routing-domain interfaces.
offmust perform no automatic routing.- Explicit
advisor()remains available in every routing mode.
Acceptance criteria
- Package loads through its real package-root server entrypoint on OpenCode 2.0.19.
- Optional config file/default/validation behavior is independently tested.
advisor()has an empty object input schema.- Inherited and explicitly configured Advisor-model selection are tested.
- Advisor receives a faithful representation of actual parent context.
- Unsupported media is represented explicitly without false semantic-access claims.
- Same-turn content immediately preceding
advisor()is proven recoverable by focused runtime validation, or the durable plan is updated before proceeding. - Advice returns as a genuine tool result; explicit failures are visible.
off,observe, andactivedomain semantics are independently testable with a fake router.- Equivalent routing states are suppressed.
- Stable routing interfaces contain no Evaluation/System One-specific types.
- Threshold AND-policy behavior is deterministic and configurable.
- Automatic consultation budget defaults to 1, accepts valid positive integers, rejects invalid values, and does not count explicit consultations.
- Relevant unit/integration/runtime checks and repository gates pass.
Implementation authorization
Implementation is approved as of 2026-09-28. Work in this issue may proceed against the governing plan and #61.
No additional approval pause is required for work within the approved scope. Material changes to requirements, architecture, public interfaces, privacy/security behavior, configuration semantics, release strategy, or acceptance criteria require plan updates and explicit re-approval.
Activity
[-][Auto Advisor] Establish V2 package and explicit Advisor path[/-][+][Auto Advisor] Establish core Advisor and routing foundation[/+]capyBearista commentedon Sep 29, 2026
Phase 1 foundation is implemented on
feat/auto-advisor(2 local commits, PR #61 stays draft, unpushed). Contents: V2 server-only package, sparse global config with strict validation, zero-argadvisor()with model inheritance, canonical serialization with media placeholders, routing domain (modes, fingerprinting, AdvisorRouter seam + fake, AND policy 0.7/3, per-turn budget 1). Evidence: 92 pass/0 fail, typecheck+lint+test+build green, built-artifact smoke green, gate review PASS WITH FIXES with all fixes applied and re-verified. Notable rulings carried forward to #50: budget check stays after eval (preserve observe telemetry), router-error fails open without consuming, error-text failure channel, transcript sizing + turn-state bounds + advice origin-tagging deferred to #50. Zen adapter, telemetry storage/RPC, and active delivery remain #50 scope.feat(auto-advisor): establish core advisor and routing foundation
capyBearista commentedon Sep 29, 2026
#48 completion record — baseline 2.0.19, validation green
Compatibility baseline moved 2.0.18 → 2.0.19 (body updated). Reason: real-runtime probing exposed an upstream 2.0.18 limitation — stateless
ctx.generate.text()omittedx-opencode-session, breaking OpenCode-hosted model requests. 2.0.19 adds session attribution. No workaround was added for 2.0.18; the 2.0.18 probe is recorded as blocked upstream, not as a context-capture failure.Real 2.0.19 runtime validation (built package, package-root load) — both probes passed:
advisor()without reading repository files; the Advisor correctly recovered repository instructions absent from the user prompt (merge-commit merges, retain remote branch). Hook-time model-facing context reaches the Advisor through the captured request snapshot.globtool call with a unique nonce plusadvisor(); the nonce existed only in the sibling tool-call args; the Advisor recovered it exactly. Livesession.context()state merges correctly with the captured request.Gates and review:
typecheck/lint/test/buildgreen at repo root; package suite 181/0; built-artifact smoke green; code reviews (foundation + remediation + follow-ups) closed with no open findings.Closing #48 as complete. #50 work (Zen adapter, telemetry, active delivery) continues on the same branch and PR #61.