Skip to content

feat(opencode): move OpenCode install and entrypoint into an agent kit #485

Closed
Closed
feat(opencode): move OpenCode install and entrypoint into an agent kit#485

Description

@mogul
mogul
opened on Sep 16, 2026

Intent

Move OpenCode-specific install/start ownership out of core acq behavior and into an OpenCode agent kit, following ADR-0030's agent-install contract.

Parent: #473
ADR: #474

Scope

  • Provide an OpenCode agent kit with content-pinned installation.
  • Prefer nix profile install github:NixOS/nixpkgs/<rev>#<agent> when OpenCode is available through the selected nixpkgs rev.
  • Use a sha256-pinned release binary pattern if nixpkgs cannot supply the agent.
  • Declare the OpenCode entrypoint in the agent kit.
  • Remove or retire the unpinned npm install -g opencode-ai fallback as a contract path.
  • Ensure any agent-populated image is treated as an artifact derived from applying the kit, not as behavior source-of-truth.

Deferred Decisions

  • Exact image-building/caching automation can be deferred until after the kit path works from a generic devenv base.
  • Provider config rendering is tracked separately.

Acceptance Criteria

  • OpenCode can be installed from a generic devenv-enabled, agent-less base through the kit.
  • The installed OpenCode version is content-pinned.
  • Re-running create/run is idempotent.
  • Current acq run opencode . UX remains stable through the migration.
  • Tests or live verification cover a clean sandbox path without an OpenCode-populated base image.

Orchestration Notes

Implementation should be done by an authoring sub-agent and reviewed by an independent adversarial review sub-agent. Review findings must be addressed before the increment is accepted.

Activity

  1. mogul
    added a parent issue on Sep 16, 2026

  2. mogul commented on Sep 18, 2026

    @mogul
    mogul
    on Sep 18, 2026
    ContributorAuthor

    Implemented the quickstart-side validation/gating prep increment for the future OpenCode agent-kit cutover.

    Commit: 9be74d3 feat(agent-kits): validate built-in agent artifacts

    What landed:

    • Added static validation for built-in agent-kit artifacts without executing kit code.
    • Validation currently requires:
      • spec.yaml exists
      • schemaVersion: "hybrid/v1"
      • kind: mixin
      • top-level kit name matches the expected built-in kit name (opencode)
      • direct agent.name matches opencode
      • direct agent.entrypoint matches opencode
    • Added acq_agent_builtin_kit_ready, combining the existing enable flag with artifact validation.
    • Kept acq_agent_builtin_kit_enabled opencode false by default, so current behavior remains deferred until a real patterns-side artifact exists and the enablement policy changes.
    • Added a small readiness cache so enabled validation does not repeatedly fetch/check the same ref during one invocation.
    • Preserved explicit --kit suppression and shell no-agent-kit behavior.
    • Did not alter the MSB npm fallback install path.

    Review findings addressed before commit:

    • Avoided repeated validation/fetches by caching readiness results per agent/ref.
    • Fixed older enabled-path tests to use valid fixture artifacts.
    • Tightened the agent: parser to direct child fields only.
    • Added tests for wrong agent.name, wrong agent.entrypoint, and nested metadata that should not satisfy the contract.

    Verification:

    • PASS: ./test/vendor/bats-core/bin/bats test/bats/140-opencode-migration-gate.bats test/bats/85-kit-provenance.bats test/bats/50-kit-list-completeness.bats test/bats/30-dispatch-routing.bats (93/93)
    • PASS: bash -n acq acq.backends/common.sh acq.backends/agents.sh acq.backends/kit-translate.sh
    • PASS: focused ShellCheck on changed shell/test files
    • PASS: git diff --check

    Still deferred:

    • Actually publishing/consuming the real patterns-side OpenCode agent kit.
    • Flipping acq_agent_builtin_kit_enabled opencode on by default.
    • Removing/demoting the current MSB npm fallback install path.

  3. wz-gsa commented on Oct 1, 2026

    @wz-gsa
    wz-gsa
    on Oct 1, 2026
    Contributor

    AI-assisted (OpenCode). Opened the kit this issue scopes: GSA-TTS/agentic-coding-patterns#455 (depends on GSA-TTS/agentic-coding-patterns#454, a small prerequisite schema change adding the agent: block this issue's "declare the OpenCode entrypoint in the agent kit" acceptance criterion needs — acq_validate_agent_builtin_kit_dir/kit_spec_agent_field in this repo's acq.backends/common.sh parses that block).

    Scope checklist against what's in #455

    • "Prefer nix profile install ... if OpenCode is available through the selected nixpkgs rev" — checked, not just assumed: at this repo's devenv image's pinned NIXPKGS_REV, nixpkgs' own opencode package resolves to v0.3.112, built from the pre-rename upstream repo (sst/opencode) — roughly 70 releases stale. Verified by fetching that exact revision's own package.nix from the real nixpkgs tree. Installing via that pinned nixpkgs would downgrade users to an abandoned fork's ancient version, so this falls to the next line of the issue's own scope.
    • "Use a sha256-pinned release binary pattern if nixpkgs cannot supply the agent" — this is what fix(msb): point the --clone scratch's origin at the source checkout's remote #455 does: fetches the pinned GitHub Release tarball, verifies SHA-256 before extracting (fails CLOSED on a mismatch, unlike every other fail-soft kit in the family — see the kit's own docs/decisions/fail-closed-on-integrity.md), installs to /usr/local/bin.
    • "Declare the OpenCode entrypoint in the agent kit" — spec.yaml carries agent: {name: opencode, entrypoint: opencode} via the new schema field in fix(ci): bump js-yaml to 4.3.2 to clear a high-severity CPU-DoS advisory #454.
    • "Remove or retire the unpinned npm install -g opencode-ai fallback as a contract path" — not yet done in THIS PR; fix(msb): point the --clone scratch's origin at the source checkout's remote #455 adds the kit but doesn't touch acq.backends/msb.sh's _acq_msb_install_agent/ACQ_MSB_OPENCODE_PKG fallback path itself. That retirement is this repo's side of the migration, not the kit repo's — flagging here so it's tracked as the remaining half of this issue's acceptance criteria rather than assumed done.
    • "Ensure any agent-populated image is treated as an artifact derived from applying the kit, not as behavior source-of-truth" — the kit is self-contained (install script + SHA pins + spec), no image-baking assumption either way; this one seems satisfied by construction but worth a second look from whoever lands the retirement half.

    Also directly relevant: #480 (the migration gate)

    Commented there too — #480's scope needs a real kit to gate against, which didn't exist until now.

    Two independent adversarial reviews (security-focused, QA/accuracy-focused) ran against the kit before opening #455, per this issue's own "Orchestration Notes" requirement; every finding from both was fixed, not just logged — details in the PR description.

  4. basiliskus
    added a commit that references this issue on Oct 1, 2026

    feat(schema): add optional agent block to hybrid/v1 kit schema (#454)

    856c975
  5. mogul
    added 4 commits that reference this issue on Oct 2, 2026

    feat(acq-kits): add opencode agent-harness kit (SHA-pinned release bi…

    36038a6

    chore(kits): pin patterns v1.11.0

    d35f8c3

    chore(kits): pin patterns v1.11.0

    13ae3d6

    chore(kits): pin patterns v1.11.0

    122a849

  6. mogul commented on Oct 6, 2026

    @mogul
    mogul
    on Oct 6, 2026
    ContributorAuthor

    Implemented and shipped in v4.0.0 via #474 (with corrective #549). OpenCode install/entrypoint moved into the pinned opencode agent kit; native MSB npm fallback (ACQ_MSB_OPENCODE_PKG/opencode-ai) removed. The PR's Closes: footer did not auto-close this because the collapsed-stack squash merge dropped the closing keyword references; closing manually now that the work is on main and released.

  7. mogul
    closed this as completedon Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions