Skip to content

docs(adr): Runtime dep philosophy — self-contain vs declare (V1 decisions) #948

Closed

Description

@omesser

What

Document V1 runtime-dependency philosophy: self-contain vs declare, with the locked calls from the #735 / #932 census.

Why now

Oded accepted the #932 spike recommendations (PR comment 2026-09-23). The framework and decisions need a durable home (ADR or equivalent docs) so future deps do not re-litigate V1 calls.

Scope

In

  1. ADR (or docs/ philosophy page) covering:
    • Prefer declare + loud failure over bundling when install cost is sane.
    • Locked V1 calls:
      • Node/npx — declare; graceful fail if missing; README lists as requirement for harnesses that need it. Do not bundle for V1 (spike(ship): Bundle Node runtime + pinned ACP adapters for self-contained Claude/Codex/Pi #928 closed not planned).
      • Harness CLIs — declare per preset; graceful fail; README lists PATH + auth requirements for that harness.
      • WebView — as recommended: graceful fail if missing; README (Tauri) — Windows handled; Linux declare; macOS nothing.
      • GStreamer — optional; README for Linux audio cues; nice-to-have; silent skip OK.
      • libfuse — AppImage only; when shipping AppImage, prefer type 2 with bundled runtime.
      • X11/Wayland — environment, not a dependency.
      • MCP stdio binary (AI_BUDDY_MCP_BIN) — do not bundle with main binary; challenge whether stdio path is still needed; optional download at best; HTTP+bearer remains primary.
  2. Point at research note docs/research/runtime-dependencies.md (spike(ship): Census of runtime deps beyond the binary #932) as the evidence census.
  3. Criteria for future deps: size, licenses, update cadence, user install base, required vs optional.

Out

Done when

Related

— Cursor agent (Architect), on @omesser's behalf.

Activity

  1. added this to the V1 milestone on Sep 23, 2026
  2. added
    researchDefining or executing a research into an aspect: tech, direction, decision
    on Sep 23, 2026
  3. omesser commented on Sep 23, 2026

    @omesser
    OwnerAuthor

    Cross-links: harness-connect UX #949, sticky inline missing-dep #950, Settings first-party vs npx #929, Goose #930. #928 closed not planned (no Node bundle for V1).

    — Cursor agent (Architect), on @omesser's behalf.

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

    harnessresearchDefining or executing a research into an aspect: tech, direction, decision

    Projects

    • Status
      Done

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions