@miller-tech/uap 2.19.5 → 2.20.0

package/docs/architecture/adr/0005-ollama-compatible-surface.md

@@ -0,0 +1,74 @@
+# ADR 0005: The Ollama-compatible surface — a third inbound dialect on a second port
+
+- Status: Accepted
+- Date: 2026-10-06 (branch `feature/340-ollama-compat-endpoint`)
+- Guide: `docs/guides/PROXY.md`
+
+## Context
+
+The anthropic proxy already serves two inbound dialects — Anthropic Messages
+(`/v1/messages`) and OpenAI Chat Completions (`/v1/chat/completions`) — both
+normalized through a single guarded Anthropic pipeline (admission control,
+rail semaphore, loop detection, tool narrowing, malformed-tool retry, context
+pruning). Ollama-native tooling is a third client family that auto-discovers
+`localhost:11434` and generally cannot be re-pointed at a path-prefixed
+alternative, so "just document the OpenAI surface" does not reach it.
+
+## Decision
+
+1. **Same process, second listener port.** The Ollama surface is served by the
+   SAME FastAPI app on `PROXY_OLLAMA_PORT` (default 11434; 0 disables). A
+   second process was rejected on a hard constraint, not taste: admission
+   control and the upstream rail semaphore are per-process in-memory state
+   (session admission limit=1, upstream slot limit=1), so a second process
+   would silently double the concurrency budget the backend was sized for and
+   break the rail. Path-prefixing on one port was rejected because Ollama
+   tooling cannot be pointed at it.
+
+2. **Translation only, through the shared guarded core.** Ollama requests are
+   translated to OpenAI shape and run through `_guarded_openai_completion` —
+   the same core the OpenAI route uses — then translated back to Ollama wire
+   shapes. This buys a parity guarantee: an Ollama client cannot drift from
+   the other surfaces in guardrail coverage, because there is only one
+   pipeline. The cost is double translation: only fields that survive BOTH
+   hops are mapped (see consequence 4).
+
+3. **Buffered streaming, same tradeoff as the OpenAI surface.** Streaming is
+   buffered through the guardrails, then emitted as Ollama NDJSON (one content
+   line plus a final `done: true` line) — not token-by-token from upstream.
+   Token-granular streaming would require bypassing the pipeline; correctness
+   of the guardrails was ranked above stream granularity. This is the same
+   call the OpenAI inbound already made; clients see their reply arrive at
+   once instead of incrementally.
+
+4. **Default on at 11434.** The surface's target audience auto-discovers that
+   port, so default-off would make the feature unreachable by its own users.
+   Blast radius is bounded: loopback bind by default, the same auth token
+   gates model-serving routes, a busy port disables the surface without
+   touching the Anthropic surface, and `PROXY_OLLAMA_PORT=0` is a config-only
+   rollback. The known asymmetry: if this proxy binds 11434 first, a
+   later-started real Ollama fails to bind and the error appears in Ollama's
+   logs, not ours.
+
+## Consequences
+
+- uvicorn serves one app on two ports via a companion listener that installs
+  no signal handlers (SIGTERM reaches it by mirroring the primary's exit) and
+  runs with `lifespan="off"` so app startup runs exactly once. The proxy
+  requires `uvicorn>=0.30.0` for the `capture_signals` override to be
+  honored.
+- A companion bind failure must never take the primary down: uvicorn signals
+  bind failure with `sys.exit(1)` inside `serve()`, and `SystemExit` is a
+  `BaseException` that `gather(return_exceptions=True)` does not contain —
+  the companion task is therefore wrapped in an explicit containment guard.
+- Option mapping is deliberately minimal (`temperature`, `top_p`, `top_k`,
+  `stop`, `num_predict`): Ollama's `format` (structured output),
+  `min_p`/`repeat_penalty`/`seed` and `num_ctx` are dropped honestly at the
+  boundary. Wiring `response_format` through the Anthropic pipeline is a
+  tracked contract change that deserves its own schema-diff pass.
+- The model card data (`/api/tags`, `/api/show`, `/api/ps`) mirrors only what
+  the backend actually exposes (llama.cpp `/props`), cached per model, and
+  never invents plausible-looking numbers a client would display as fact.
+- The Claude contract ids that `/v1/models` advertises for Anthropic-SDK
+  compatibility are protocol fictions and do NOT appear in `/api/tags` — an
+  Ollama client must only see ids the backend actually serves.

package/docs/guides/PROXY.md

@@ -41,6 +41,54 @@ the "keep a small model from wedging" logic lives.
 | `GET /health` | Liveness (probes the upstream; stays unauthenticated) |
 | `GET /v1/context` | Per-session token-usage / utilization / guardrail telemetry (dashboards & debug) |
 
+### Ollama-compatible surface (`PROXY_OLLAMA_PORT`, default 11434)
+
+The same proxy also serves the Ollama wire protocol on a **second port**
+(default `11434`, Ollama's well-known port — the one Ollama-native tooling
+auto-discovers and cannot be re-pointed). Set `PROXY_OLLAMA_PORT=0` to disable
+it (do that on a box running a real Ollama, which owns 11434); if the port is
+busy at startup the surface disables itself and the Anthropic/OpenAI surface
+carries on unaffected.
+
+| Route | Purpose |
+|---|---|
+| `GET /api/version` | Ollama discovery handshake |
+| `GET /api/tags` | Model list — backend-served ids only (the Anthropic-protocol Claude ids are not leaked here) |
+| `POST /api/show` | Model card (404s unknown ids like real Ollama) |
+| `GET /api/ps` | Running-model list (the backend stays loaded; capacity policy owns that) |
+| `POST /api/chat` | Chat — messages, options, tools (OpenAI tool schema) |
+| `POST /api/generate` | Text generation — prompt + optional system |
+
+Every request runs the **full guardrail path** (admission control, rail
+budgeting, loop detection, tool narrowing, malformed-tool retry, context
+pruning) — an Ollama client gets the same treatment an Anthropic client does.
+The tradeoff matches the OpenAI-compatible surface: streaming is buffered
+through the guardrails, then emitted as Ollama NDJSON (one content line plus a
+final `done: true` line), not token-by-token.
+
+Options map only where they survive both translation hops — `temperature`,
+`top_p`, `top_k`, `stop`, and `num_predict` → `max_tokens`. Everything else is
+dropped honestly rather than accepted and silently ignored: Ollama's
+`format` (structured output) is not carried by the underlying pipeline yet
+(wiring `response_format` through is a tracked contract change), `num_ctx`
+would fight the rail budget, and `min_p`/`repeat_penalty`/`seed` are not
+forwarded by the second hop. `keep_alive`/`raw`/`template` are lifecycle
+features with no local equivalent.
+
+Two auth behaviors to know about when `PROXY_AUTH_TOKEN` is set: the
+discovery routes above stay unauthenticated (Ollama clients probe them before
+any credential could be presented), but `POST /api/chat`, `POST /api/generate`
+and `POST /api/show` gate exactly like `/v1/messages` — and since most
+Ollama-native tooling has no way to configure a bearer token, auth-on
+realistically means Ollama clients stop at a 401. On the default loopback
+deployment (no token) everything works.
+
+If the port is busy at startup (typically a real Ollama), the surface
+disables itself and the Anthropic/OpenAI surface carries on unaffected — the
+error lands in this proxy's journal. The reverse ordering has the opposite
+signature: if this proxy binds 11434 first, a later-started real Ollama is the
+one that fails to bind, and its error shows up in Ollama's logs, not ours.
+
 ---
 
 ## Lifecycle: `uap proxy`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miller-tech/uap",
-  "version": "2.19.5",
+  "version": "2.20.0",
   "description": "Autonomous AI agent memory system with CLAUDE.md protocol enforcement",
   "type": "module",
   "main": "dist/index.js",
@@ -21,7 +21,7 @@
     "start": "node dist/bin/cli.js",
     "test": "vitest",
     "test:ci": "vitest run",
-    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_conditional_destructive_verbs tools.agents.tests.test_live_deliver_kill tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_schema_diff_inline tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_gate_evidence tools.agents.tests.test_repeat_call_guard tools.agents.tests.test_repeat_guard tools.agents.tests.test_gate_integrity tools.agents.tests.test_gate_failclosed_indirection tools.agents.tests.test_gate_failclosed_schema_diff tools.agents.tests.test_gate_failclosed_plane_admin tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_anthropic_proxy_tool_arg_types tools.agents.tests.test_anthropic_sse_schema tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_write_complexity tools.agents.tests.test_fastpath_config tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_count_tokens_scale_per_session tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_stuck_break_hard tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_plane_admin_protect tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_non_stream_resp_log tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core tools.agents.tests.test_models_context_window tools.agents.tests.test_thinking_template_kwargs tools.agents.tests.test_cycle_break_wait_poll tools.agents.tests.test_upstream_model_aliases tools.agents.tests.test_stream_thinking_deltas tools.agents.tests.test_verbatim_compact tools.agents.tests.test_tool_risk tools.agents.tests.test_lockstep_escalation",
+    "test:enforcers": "UAP_PROXY_ENV_AUTOLOAD=0 python3 -m unittest tools.agents.tests.test_enforcement_self_protect tools.agents.tests.test_conditional_destructive_verbs tools.agents.tests.test_live_deliver_kill tools.agents.tests.test_schema_diff_gate tools.agents.tests.test_schema_diff_inline tools.agents.tests.test_stream_telemetry tools.agents.tests.test_project_telemetry_events tools.agents.tests.test_workdir_scope_enforcer tools.agents.tests.test_gate_evidence tools.agents.tests.test_repeat_call_guard tools.agents.tests.test_repeat_guard tools.agents.tests.test_gate_integrity tools.agents.tests.test_gate_failclosed_indirection tools.agents.tests.test_gate_failclosed_schema_diff tools.agents.tests.test_gate_failclosed_plane_admin tools.agents.tests.test_expert_review_pr_scope tools.agents.tests.test_path_containment tools.agents.tests.test_path_normalizer_hardened tools.agents.tests.test_sandbox_tool_strip tools.agents.tests.test_proxy_env_loader tools.agents.tests.test_stream_required_tool tools.agents.tests.test_tool_call_wrapper_profiles tools.agents.tests.test_tool_convert_cache tools.agents.tests.test_doubling_break tools.agents.tests.test_error_loop_ignores_correctives tools.agents.tests.test_anthropic_proxy_tool_arg_types tools.agents.tests.test_anthropic_sse_schema tools.agents.tests.test_attractor_detection tools.agents.tests.test_client_disconnect tools.agents.tests.test_confidence_escalation tools.agents.tests.test_coordination_ban tools.agents.tests.test_coordination_early_ban tools.agents.tests.test_cycle_break_exploration tools.agents.tests.test_deferral_break tools.agents.tests.test_deliver_autoroute tools.agents.tests.test_delivery_enforcement_all_langs tools.agents.tests.test_delivery_enforcement_exemptions tools.agents.tests.test_delivery_enforcement_filepath tools.agents.tests.test_delivery_enforcement_write_complexity tools.agents.tests.test_fastpath_config tools.agents.tests.test_delivery_enforcement_web_and_bash tools.agents.tests.test_disconnect_watcher tools.agents.tests.test_empty_maxtokens_recovery tools.agents.tests.test_empty_tool_loop_break tools.agents.tests.test_enforcer_escape_hatches tools.agents.tests.test_error_loop_break tools.agents.tests.test_finalize_suppression tools.agents.tests.test_malformed_unclosed_think tools.agents.tests.test_mandate_beats_recon tools.agents.tests.test_mandate_deliver tools.agents.tests.test_overflow_truncate_count_tokens tools.agents.tests.test_count_tokens_scale_per_session tools.agents.tests.test_passthrough_oauth tools.agents.tests.test_project_telemetry tools.agents.tests.test_proxy_auth_headers tools.agents.tests.test_prune_preserve_force_write tools.agents.tests.test_recon_deliver_gate tools.agents.tests.test_session_admission tools.agents.tests.test_stream_heartbeat tools.agents.tests.test_stuck_break_reattach tools.agents.tests.test_stuck_break_hard tools.agents.tests.test_turn_count_breaker_periodic tools.agents.tests.test_upstream_chokepoint tools.agents.tests.test_vision_passthrough tools.agents.tests.test_worktree_required tools.agents.tests.test_plane_admin_protect tools.agents.tests.test_enforcer_suite_coverage tools.agents.tests.test_validate_plan_gate tools.agents.tests.test_validate_plan_inside_project tools.agents.tests.test_anthropic_proxy_streaming tools.agents.tests.test_non_stream_resp_log tools.agents.tests.test_delivery_enforcement_worktree tools.agents.tests.test_output_token_ceilings tools.agents.tests.test_tool_narrowing_core tools.agents.tests.test_models_context_window tools.agents.tests.test_thinking_template_kwargs tools.agents.tests.test_cycle_break_wait_poll tools.agents.tests.test_upstream_model_aliases tools.agents.tests.test_stream_thinking_deltas tools.agents.tests.test_verbatim_compact tools.agents.tests.test_tool_risk tools.agents.tests.test_lockstep_escalation tools.agents.tests.test_ollama_compat",
     "test:coverage": "vitest --coverage",
     "bench": "vitest --config vitest.bench.config.ts",
     "eval:routing": "tsx scripts/eval-routing.ts",