Builder Report — R8: AI Provider-Agnostic Architecture

TL;DR

Status: IMPLEMENTED
Files changed: 5 new, 8 modified, 0 deleted
New files: bin/pos-ai (642 ln), lib/ai-providers/gemini.sh (59 ln), lib/ai-providers/openrouter.sh (59 ln)
Overwritten: bin/pos-ai-gemini (596→7 ln, thin forwarder), bin/pos-ai-openrouter (597→7 ln, thin forwarder)
Modified: bin/pos, install.sh, config/ai.env, DOC/howto/ai.md, DOC/POS.md, DOC/HOWTO.md, DOC/AGENT_Context_Project.md, completions/pos.bash, lib/pos-ai-hook.sh
Gates: bash -n OK, make gen OK, make check OK, make lint 0 FAIL / 0 WARN
Probes: 22/22 pass (all probes a–n verified)

Step 1: Provider adapters

[DONE] lib/ai-providers/gemini.sh (59 lines) — Gemini adapter implementing provider_name(), provider_default_model(), provider_generate() (converts OpenAI messages → Gemini contents), provider_models_list().

[DONE] lib/ai-providers/openrouter.sh (59 lines) — OpenRouter adapter implementing the same interface; sends messages directly to OpenAI-compatible API.

Step 2: Main tool

[DONE] bin/pos-ai (642 lines) — Provider-agnostic main tool with:

Unified # POS: header (ai ask, subcommands: ask/chat/sessions/capture/models/providers)
--provider flag + AI_PROVIDER env/config resolution
Unified AI_API_KEY with provider-specific fallback (AI_GEMINI_API_KEY → OPENROUTER_API_KEY)
Unified AI_MODEL with provider-specific fallback
AI_SYSTEM_PROMPT config support (between --system and built-in)
Universal session format (OpenAI messages) with auto-migration from old Gemini contents format
cmd_providers() — new subcommand listing providers + config status
All shared logic from both originals (render_markdown, machine_context, --last, capture, sessions)

Step 3: Backward compat forwarders

[DONE] bin/pos-ai-gemini (7 lines) — exec pos ai --provider gemini "$@" [DONE] bin/pos-ai-openrouter (7 lines) — exec pos ai --provider openrouter "$@"

Both include -h|--help passthrough for lint compliance.

Step 4: Install + dispatcher updates

[DONE] install.sh — Added ai-providers/ directory copy to /usr/local/bin/ai-providers/ [DONE] bin/pos — Added ai to INTERACTIVE_CMDS

Step 5: Config + doc updates

[DONE] config/ai.env — Updated template with unified + legacy keys [DONE] DOC/howto/ai.md — Full rewrite reflecting unified architecture [DONE] DOC/POS.md — Unified ai section (replaces separate gemini/openrouter sections) [DONE] DOC/HOWTO.md — Updated ai.env table row [DONE] DOC/AGENT_Context_Project.md — Updated ai.env description + Common Tasks row [DONE] completions/pos.bash — Regenerated (make gen) [DONE] lib/pos-ai-hook.sh — Updated comment references

Step 6: Gates

[DONE] bash -n — All 5 new/changed files pass [DONE] make gen — Idempotent (no drift) [DONE] make check — OK (check-sync passes) [DONE] make lint — 0 FAIL, 0 WARN

Step 7: Verification probes

[DONE] All 22 probes pass:

(a) gemini adapter calls correct API endpoint ✅
(b) openrouter adapter calls correct API + Bearer auth ✅
(c) --provider flag overrides AI_PROVIDER config ✅
(d,e) backward compat forwarders route correctly ✅
(f) --system overrides built-in; AI_SYSTEM_PROMPT from config; --system overrides config; --full drops all ✅
(g) AI_API_KEY precedence over provider-specific; fallback works; error on missing key ✅
(h) --model flag; AI_MODEL config; AI_GEMINI_MODEL legacy fallback; provider default model ✅
(i) Session migration: old contents format → messages format ✅
(k) Capture saves command output ✅
(l) pos ai providers lists both providers with status ✅
(n) Non-tty output is plain text (byte-compat) ✅

Step 8: AGENT_TODO

[DONE] Task is an Orchestrator assignment — no AGENT_TODO entry (ephemeral task, not project backlog).

Diff summary

New files:
  bin/pos-ai                         642 lines
  lib/ai-providers/gemini.sh          59 lines
  lib/ai-providers/openrouter.sh      59 lines

Overwritten (thinned):
  bin/pos-ai-gemini                 596→  7 lines (forwarder)
  bin/pos-ai-openrouter             597→  7 lines (forwarder)

Net: -1327 old lines removed, +189 modified lines, +760 new lines
     = 774 total new (vs ~1183 original combined)

REPORT_PATH: ./AgentsReport/builder/2026-08-25_r8-ai-plugin-arch.md

4.5 KiB Raw Blame History Unescape Escape