Skip to content

[Auto Advisor] Establish core Advisor and routing foundation #48

Closed

Description

@capyBearista

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-advisor using current repository V2 Promise-plugin conventions.
  • Initial compatibility baseline: @opencode/plugin@2.0.19 and @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:

  1. advisor.model
  2. routing.mode — off | observe | active
  3. routing.models
  4. routing.advisorWouldHelpThreshold
  5. routing.consequenceThreshold
  6. routing.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.model is 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, and active semantics.
  • Define materially new primary-dispatch routing opportunities at the session.context boundary.
  • 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 AdvisorRouter abstraction that contains no OpenCode Evaluation/System One types.
  • Provide fake/test router support.
  • Normalize router results to:
    • advisor_would_help probability;
    • 0-4 consequence score;
    • 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.maxConsultationsPerTurn as 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.
  • off must 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, and active domain 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

  1. changed the title [-][Auto Advisor] Establish V2 package and explicit Advisor path[/-] [+][Auto Advisor] Establish core Advisor and routing foundation[/+] on Sep 28, 2026
  2. capyBearista commented on Sep 29, 2026

    @capyBearista
    OwnerAuthor

    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-arg advisor() 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.

  3. capyBearista commented on Sep 29, 2026

    @capyBearista
    OwnerAuthor

    #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() omitted x-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:

    1. Assembled-request fidelity: the Executor called 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.
    2. Same-turn in-flight delta fidelity: the Executor emitted a glob tool call with a unique nonce plus advisor(); the nonce existed only in the sibling tool-call args; the Advisor recovered it exactly. Live session.context() state merges correctly with the captured request.

    Gates and review: typecheck / lint / test / build green 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions