@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/docs/concepts/backends-and-tiers.md

@@ -5,32 +5,38 @@ title: Backends and Tiers
 id: backends-and-tiers
 aliases:
   - models
-  - claude codex gemini
+  - claude codex gemini opencode
   - heavy tier
   - light tier
+  - main backend
+  - fallback backend
 category: concepts
 summary: |
-  Aitne runs on three backends — Claude Code, Codex, Gemini CLI.
-  Each backend has a heavy and a light tier; the dispatcher picks the
-  binding for every ProcessKey based on operator configuration.
+  Aitne runs on four backends — Claude Code, Codex, Gemini CLI, OpenCode.
+  Each backend exposes light, medium, and high model tiers; the dispatcher
+  picks the binding for every ProcessKey based on operator configuration.
 section: backends
 tags:
   - core
   - backends
   - models
   - cost
+  - routing
 status: stable
 ask_examples:
   - Which model does my morning routine use?
   - How do I switch from Claude to Codex?
   - What is the difference between heavy and light tier?
+  - What is OpenCode and when should I use it?
+  - How does Aitne fail over when a backend hits its quota?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-28
 keywords:
   - claude
   - codex
   - gemini
+  - opencode
   - opus
   - sonnet
   - haiku
@@ -40,34 +46,73 @@ keywords:
   - vertex
   - foundry
   - azure-openai
+  - openrouter
+  - routing
+  - fallback
 related:
   - concepts/process-keys
   - concepts/costs-and-quotas
   - features/operations/backend-routing
-  - guides/use-cloud-providers
 ui_anchors:
   - /settings/models
+  - /analytics
+process_keys:
+  - message.dm
+  - dashboard.chat
+  - dashboard.docs_qa
+  - routine.morning_routine
+  - gmail_classify
+  - calendar.change
+  - delegated_task
+  - delegated_task_heavy
+config_keys:
+  - claudeExecutionPermissionMode
+  - codexExecutionPermissionMode
+  - geminiExecutionPermissionMode
+  - opencodeExecutionPermissionMode
+  - opencodeBaseUrl
+  - opencodeServerUsername
+  - delegatedTaskHeavyEnabled
 ---
 
 # Backends and Tiers
 
 ## TL;DR
 
-Three backends are supported: **Claude Code** (default),
-**Codex**, and **Gemini CLI**. Each backend exposes three classes of
-model used at install time:
-
-- **Main** (Sonnet 4.6 / GPT-5.4-mini / Gemini 3 Flash) — the default
-  for owner-facing work (DMs, daily / weekly / monthly review,
-  morning routine, dashboard chat, scheduled tasks).
-- **Delegated** (Haiku 4.5 on Claude; latest light tier on Codex /
-  Gemini) — cheaper model used for "simple" backend surfaces with no
-  owner in the loop: Gmail classification, GitHub event triage,
-  git-poll observers, calendar-change handlers, the
-  `delegated_task` invoker.
-- **Heavy** (Opus 4.7 / GPT-5.5 / Gemini 3 Pro) — registered but
-  *not* auto-selected. Operators opt in per-process from
-  `/settings/models`.
+Four backends are supported: **Claude Code** (default), **Codex**,
+**Gemini CLI**, and **OpenCode**. Each backend exposes three model
+tiers. The per-backend defaults seeded at install time are:
+
+| Tier | Claude | Codex | Gemini | OpenCode |
+|---|---|---|---|---|
+| **medium** (main) | Sonnet 4.6 | GPT-5.4 | Gemini 3.1 Pro (preview) | Sonnet 4.6 |
+| **lite** (delegated) | Haiku 4.5 | GPT-5.4 Mini | Gemini 3.1 Flash Lite (preview) | Haiku 4.5 |
+| **high** (heavy) | Opus 4.8 | GPT-5.4¹ | Gemini 3.1 Pro (preview)¹ | Opus 4.8 |
+
+¹ Codex and Gemini have no separately-seeded high model — their high
+tier collapses to the medium model via `SEED_HIGH_TIER_OVERRIDE`.
+Codex's flagship GPT-5.5 is Opus-priced and stays an opt-in; Gemini
+has no Opus-priced Google flagship worth defaulting to. Pin a higher
+model per row from `/settings/models` if you want it.
+
+What each tier is for:
+
+- **Medium / Main** — the default for owner-facing work: DMs and
+  mentions, dashboard chat, morning / evening / weekly / monthly
+  review, the hourly check, scheduled tasks.
+- **Lite / Delegated** — the cheaper model for "simple" backend
+  surfaces with no owner in the loop: Gmail classification, GitHub
+  event triage, git-poll observers, calendar-change handlers, the
+  routine pre-pass fetcher, the `delegated_task` invoker.
+- **High / Heavy** — registered but *not* auto-selected. After the
+  "no Opus by default" pass (2026-05-16), **no install-time-seeded
+  surface defaults to high.** The only `high`-tagged ProcessKey is
+  `delegated_task_heavy`, and it is opt-in (gated by the
+  `delegatedTaskHeavyEnabled` config flag). Operators can pin any
+  other ProcessKey to high per row from `/settings/models`. The
+  first morning routine after setup runs on **medium** tier with a
+  daemon-prepared `<roadmap_skeleton>` block instead of the retired
+  heavy `routine.morning_routine_initial`.
 
 Every ProcessKey resolves to a backend + model binding via
 `BackendRouter`. Aitne **does not store or read subscription-plan
@@ -79,11 +124,12 @@ install time and edited from `/settings/models`.
 Each backend authenticates via a provider API key registered on
 `/settings/models`. The provider dropdown picks one of:
 
-| Backend | Direct API key | Cloud provider options |
+| Backend | Direct API key | Cloud / aggregator options |
 |---|---|---|
 | `claude` | `anthropic` (`sk-ant-…`) | `bedrock` (Amazon Bedrock), `vertex` (Google Vertex AI), `foundry` (Microsoft Foundry) |
 | `codex` | `openai` (`sk-…`) | `azure-openai` (Codex CLI on Azure OpenAI; daemon writes a managed `config.toml` under `<dataDir>/codex-home/`) |
 | `gemini` | `google` (`AIza…`) | `gemini-vertex` (Gemini on Google Vertex AI) |
+| `opencode` | provider key forwarded to the OpenCode server (Anthropic / OpenAI / OpenRouter / …) | "Managed" mode runs a local `opencode` HTTP server on loopback; "Remote" mode points at a baseUrl you operate |
 
 API keys are the recommended and provider-supported auth method for
 headless agent use; if you skip the key the daemon falls back to the
@@ -92,18 +138,37 @@ officially support — Anthropic in particular currently prohibits the
 Claude Agent SDK on a Claude Pro / Max subscription. The dashboard
 surfaces a warning whenever a backend is on subscription auth.
 
-Cloud providers (Bedrock / Vertex / Foundry / Azure OpenAI /
-Gemini-Vertex) let teams reuse an existing enterprise contract,
-keep model traffic inside a private VPC, or take advantage of
-provider-side rate-limit pools. Aitne stores the credentials in the
-OS keychain and mirrors the corresponding env vars
-(`CLAUDE_CODE_USE_BEDROCK=1`, `CLAUDE_CODE_USE_VERTEX=1`,
-`CLAUDE_CODE_USE_FOUNDRY=1`, `GOOGLE_GENAI_USE_VERTEXAI=true`, …)
-into the backend subprocess. See
-[Use cloud providers](../guides/use-cloud-providers.md) for the
-end-to-end walkthrough and
-[Costs and Quotas](costs-and-quotas.md) for the cost shape of each
-path.
+Cloud / aggregator providers (Bedrock / Vertex / Foundry / Azure
+OpenAI / Gemini-Vertex / OpenRouter via OpenCode) let teams reuse
+an existing enterprise contract, keep model traffic inside a private
+VPC, or take advantage of provider-side rate-limit pools. Aitne
+stores the credentials in the OS keychain and mirrors the
+corresponding env vars (`CLAUDE_CODE_USE_BEDROCK=1`,
+`CLAUDE_CODE_USE_VERTEX=1`, `CLAUDE_CODE_USE_FOUNDRY=1`,
+`GOOGLE_GENAI_USE_VERTEXAI=true`, …) into the backend subprocess.
+See [Costs and Quotas](costs-and-quotas.md) for the cost shape of
+each path.
+
+## OpenCode (4th backend)
+
+OpenCode joined as a 4th backend in 2026-05. It is implemented on
+top of the `@opencode-ai/sdk` HTTP server and supports the same
+`ProcessKey` set as the other backends. Two operating modes:
+
+- **Managed** — the daemon spawns and supervises a local
+  `opencode` HTTP server on loopback (`127.0.0.1`, OS-picked port).
+  Per-session config (model, permissions, agent dir) is passed
+  inline to the server via the `OPENCODE_CONFIG_CONTENT` env var —
+  no config file is written to disk.
+- **Remote** — you point Aitne at an existing OpenCode server
+  baseUrl (your own cluster or a managed deployment), set via the
+  `opencodeBaseUrl` / `opencodeServerUsername` config keys.
+
+OpenCode is a runtime peer of Claude / Codex / Gemini for
+dispatching ProcessKeys, but it intentionally does **not** host
+native-mode integration connectors (Gmail / Calendar / Notion go
+through the daemon's polling path or another backend's MCP). See
+`docs/design/appendices/opencode-backend.md` for the full design.
 
 ## Why This Concept Exists
 
@@ -120,11 +185,15 @@ Claude's quota is exhausted, or use Gemini for cheap polling tasks.
 
 ## Definitions
 
-- **Backend**: the agent runtime. One of `claude`, `codex`, `gemini`.
-- **Tier**: `heavy` or `light`. Heavy maps to the strongest model
-  (Opus / GPT-5.5 / Gemini 3 Pro). Light is the operator's day-to-day
-  tier and split at install time into Sonnet (main) vs Haiku
-  (delegated/simple).
+- **Backend**: the agent runtime. One of `claude`, `codex`, `gemini`,
+  `opencode`.
+- **Tier**: `lite`, `medium`, or `high`. `high` maps to the strongest
+  model class (Opus-class — Opus 4.8 on Claude and OpenCode; on Codex
+  and Gemini the seeded high binding collapses to the medium model).
+  `medium` (Sonnet-class — Sonnet 4.6 and equivalents) is the
+  operator's day-to-day tier for owner-facing work; `lite`
+  (Haiku-class — Haiku 4.5 and equivalents) is reserved for
+  mechanical / delegated surfaces.
 - **Main / Fallback**: each ProcessKey has a `main` backend and a
   `fallback`. The router fails over on `BackendQuotaError` /
   `BackendDecisiveFailure`.
@@ -136,16 +205,16 @@ Claude's quota is exhausted, or use Gemini for cheap polling tasks.
 | `routine.morning_routine` | claude | Sonnet 4.6 |
 | `routine.evening_review` | claude | Sonnet 4.6 |
 | `routine.weekly_review` | claude | Sonnet 4.6 |
-| `routine.monthly_review` | claude | Sonnet 4.6 |
 | `routine.hourly_check` | claude | Sonnet 4.6 |
 | `message.dm` | claude | Sonnet 4.6 |
 | `dashboard.chat` | claude | Sonnet 4.6 |
-| `dashboard.docs_qa` | inherits from `message.dm` | Sonnet 4.6 (light forced) |
+| `dashboard.docs_qa` | inherits from `message.dm` | Sonnet 4.6 (locked to medium) |
 | `gmail_classify` | claude | Haiku 4.5 |
 | `github.*` | claude | Haiku 4.5 |
 | `git.push.detected` (and other git-poll keys) | claude | Haiku 4.5 |
 | `calendar.change` | claude | Haiku 4.5 |
 | `delegated_task` | claude | Haiku 4.5 |
+| `delegated_task_heavy` | claude | Opus 4.8 (high; opt-in, off by default) |
 
 ## Where You See It in the Dashboard
 

package/agent-assets/docs/concepts/costs-and-quotas.md

@@ -7,6 +7,9 @@ aliases:
   - cost
   - budget
   - quota
+  - daily cap
+  - cost cap
+  - per-token billing
 category: concepts
 summary: |
   How Aitne meters per-call costs and provider quotas, and where the
@@ -14,17 +17,21 @@ summary: |
   dashboard reports, it does not bill.
 section: cost
 tags:
+  - core
   - cost
   - quotas
-  - core
+  - backends
+  - operations
 status: stable
 ask_examples:
   - How do I see how much my agent is spending?
   - Why did the agent fail over from Claude to Codex?
   - What does the autonomous daily cost cap do?
+  - Does OpenCode billing differ from the other backends?
+  - How does Gemini's per-day quota work?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-28
 keywords:
   - cost
   - budget
@@ -33,16 +40,25 @@ keywords:
   - per-token billing
   - gemini quota
   - subscription fallback
+  - opencode
+  - openrouter
+  - daily cap
+  - monthly cap
+  - autonomous cap
 related:
   - concepts/backends-and-tiers
   - concepts/auth-health
   - features/operations/cost-tracking
-  - guides/use-cloud-providers
 ui_anchors:
   - /analytics
   - /settings/models
 config_keys:
   - autonomousDailyCostCapUsd
+  - autonomousMonthlyCostCapUsd
+process_keys:
+  - routine.morning_routine
+  - routine.fetch_window
+  - routine.hourly_check
 ---
 
 # Costs and Quotas
@@ -58,6 +74,12 @@ per-call against your provider account:
 - **Codex (via Codex CLI)** — per-token billing on `OPENAI_API_KEY`.
 - **Gemini (via Gemini CLI)** — per-token billing on `GEMINI_API_KEY`
   / `GOOGLE_API_KEY`; the free tier has per-day caps.
+- **OpenCode (via `@opencode-ai/sdk`)** — billing follows whichever
+  upstream provider the OpenCode server is configured against
+  (Anthropic / OpenAI / OpenRouter / …). Aitne reads cost telemetry
+  from the SDK's `session.info.cost` + `info.tokens` fields and
+  falls back to its local `MODEL_REGISTRY` pricing when the upstream
+  reports `cost === 0` against non-zero tokens.
 
 If you skip the API key, the daemon falls back to whatever
 subscription auth the CLI already has on your machine. That fallback
@@ -76,8 +98,13 @@ agent's problem to *avoid*: the dashboard shows you what each routine
 costs so you can re-pin tiers if a routine has gotten too expensive.
 
 The autonomous daily-cost cap (`autonomousDailyCostCapUsd`) is a
-bumper, not a budget — it pauses autonomous routines when crossed but
-does not interrupt reactive (in-the-loop) traffic.
+bumper, not a budget — once the day's autonomous spend crosses it the
+dispatcher starts shedding the *lowest-priority* routines first
+(hourly check), and only escalates to higher-priority ones as spend
+climbs further; the morning routine is the last to be cut. Reactive
+(in-the-loop) DMs and dashboard chat always pass through. A separate
+`autonomousMonthlyCostCapUsd` is a notifications-only soft cap — it
+fires an alert when crossed but never skips a session.
 
 ## Authentication policy
 
@@ -121,13 +148,23 @@ register an API key on `/settings/models`.
   `codex login`, `gemini auth`). Used only when no API key is
   configured. Cost behaviour then matches whatever the subscription
   enforces (e.g. Claude's rolling 5-hour Opus window on a Max plan).
-- **Daily cost cap**: `autonomousDailyCostCapUsd` — autonomous routines
-  pause on the day they cross it. Reactive DMs / dashboard chat keep
-  running; you can always reach the agent.
+- **Daily cost cap**: `autonomousDailyCostCapUsd` (default unset) —
+  once the day's autonomous spend crosses it, lower-priority routines
+  are skipped first (hourly check at 100% of the cap, the morning
+  routine only at 200%). Reactive DMs / dashboard chat keep running;
+  you can always reach the agent. Distinct from the removed
+  `maxDailyCostUsd`, which used to blanket-block reactive traffic too.
+- **Monthly cost cap**: `autonomousMonthlyCostCapUsd` (default unset) —
+  a notifications-only soft threshold across the rolling agent month;
+  it raises an alert in the Notifications Center but never skips a
+  session.
 - **Per-process tier**: each ProcessKey has its own tier, max-turns,
   and max-budget USD. Configurable on `/settings/models`.
 - **Quota error**: `BackendQuotaError` thrown by an SDK / CLI tells
-  the router to fail over to the fallback backend.
+  the router to fail over to the fallback backend. Its sibling
+  `BackendDecisiveFailure` (e.g. an auth failure) triggers the same
+  failover — these two signals are why a routine that started on
+  Claude can finish on Codex.
 
 ## Concrete Examples
 
@@ -139,24 +176,42 @@ register an API key on `/settings/models`.
   cost reduction per fire).
 - Morning routine on Opus via `ANTHROPIC_API_KEY` = per-token billing
   on the Opus rate; pin only when Sonnet has failed the task. **No
-  recurring routine seeds on Opus by default** — only the one-shot
-  `routine.morning_routine_initial` runs heavy out of the box.
+  recurring routine seeds on Opus by default**, and after
+  morning-routine Phase 7 (2026-05-16) **no one-shot routine seeds
+  on Opus either** — `routine.morning_routine_initial` was retired
+  and the first-run branch runs on the parent
+  `routine.morning_routine` envelope (medium tier) with a
+  daemon-prepared `<roadmap_skeleton>` block.
 - Gemini hourly check on Flash via `GEMINI_API_KEY` = ~$0.0005 per
-  fire on the paid tier; free tier instead consumes a per-day quota
-  slot.
+  fire on the paid tier; the free tier instead consumes one of a
+  fixed per-day request budget (Aitne caps Gemini at 450 requests/day
+  to match Google's free-tier daily limit — this ceiling is
+  Gemini-only by design; Claude and Codex meter per-window and surface
+  exhaustion as a quota error).
 - Claude Code without an API key (subscription fallback on a Max20
   login) = covered by the subscription, but the daemon flags the
   fallback because it falls outside Anthropic's published policy.
 
-## Where You See It in the Dashboard
+## Where You See It
 
-- **Analytics** rolls today's cost by backend, by ProcessKey, and by
-  hour. When a backend is running on the subscription fallback,
-  remaining-window math is shown there too.
+In the dashboard:
+
+- **Analytics** (`/analytics`) rolls today's cost by backend, by
+  ProcessKey, and by hour. When a backend is running on the
+  subscription fallback, remaining-window math is shown there too.
 - **Sidebar footer** shows the day's running total.
 - **Activity** event details include the per-execute cost.
-- **Settings → Models** exposes the per-backend API-key panel and a
-  warning banner whenever a backend is running on subscription auth.
+- **Settings → Models** (`/settings/models`) exposes the per-backend
+  API-key panel and a warning banner whenever a backend is running on
+  subscription auth.
+
+From a DM or the terminal:
+
+- **`!cost`** (and `!cost claude` / `!cost codex` / `!cost gemini`)
+  DM the agent for trailing-7-day spend, broken down or per-backend.
+- **`aitne status`** prints today's action count and spend;
+  **`aitne audit`** lists the action log (filter with `--since`,
+  `--backend`, `--result`).
 
 ## Related