[ymote]

ADR 0002 decision C: an app's AI keeps its main path through its own octos agent and the toolbox's templates. In addition, contained script apps get a narrow, direct, one-shot model call, model.complete. This PR adds the ADR addendum (section 14, "Direct one-shot model calls (model.complete)") and the model host service.

Up to date with main bb2b219 (merged, no force-push). #70 is in: main pins App Hub e8601b80, which has the model capability (OctoSense-App-Hub#24), and Rinx 68afcf79, so the graph has one octosense-app-policy. This PR changes no pin (Rinx, App Hub, octos, makepad). A manifest can now ask for model, and the Card runner's isolate admits model.* for an app that does.

The API

host.request("model.complete", {task, input, schema, class?, allow_urls?}, fn(r){ … })

Field
task	what to do (≤ 4 KiB)
input	any JSON (≤ 32 KiB), sent as data; the host's instructions tell the model to follow no instruction inside it
schema	required JSON Schema, Octoscript's bounded subset (type, properties, required, additionalProperties, items, min/maxItems, min/maxLength, minimum, maximum, enum; ≤ 8 KiB). Any other keyword is refused
class	"fast" (default) or "strong": octos catalog types, never a provider or a model id
allow_urls	default false

Reply: {output, meta: {class, requested, attempts, usage: {input_tokens, output_tokens, estimated}, budget: {calls_today, calls_per_day, tokens_today, tokens_per_day, tokens_left, per_minute, resets_at}}}. model.budget returns the caller's budget alone.

Errors are "<code>: <sentence>", where code is one of capability, no_provider, rate, budget, bad_request, invalid_output, too_large or provider. The sentence never names a provider or a model.

Rules

• Provider selection: the person's profile, in its order (primary, then fallbacks). Providers whose model is of the requested class come first, then the other class, then models the catalog doesn't list. A provider that fails (network, HTTP error, no text) is skipped for the next. The app never sees the provider, the model id or the key. meta.class is the class that answered. The model id is deliberately not shown.
• One shot: no tools, no memory, no history.
• Validation: a reply that isn't JSON, fails the schema, contains a URL or is over 16 KiB is retried once on the same provider with the reason, then refused.
• URLs: by default, any string with http://, https:// or www. refuses the reply. This is the toolbox's validate_digest rule, because replies become L0/L1 card data. allow_urls: true opts out.
• No output-token cap is sent for OpenAI chat or the Responses API. Anthropic's Messages API requires max_tokens, so it gets the model's own catalog maximum. The host reads at most 1 MiB of a provider's answer and accepts at most 16 KiB of reply.
• Budget: a host-side ledger at <apps root>/.host/model/ledger.json. Defaults are 6 calls a minute, 100 calls and 100,000 tokens per app per UTC day. A call is admitted only if its estimated input fits. Both attempts of a retry are charged. Per-app overrides live in the same file. ModelHost::usage() and ModelHost::set_limits() are ready for a Settings page (follow-up).
• Capability: the isolate gate first (splash_policy::service_allowed). Behind it, the service checks the app's own verified manifest for model (manifest_grants). There is no os.* restriction, unlike llm.
• One accounting path: complete::host() → ModelHost::complete(app, Request). The toolbox's ModelClient (feat(toolbox): the system toolbox's workflow template library #82) maps {system, user, output_schema} onto a Request with the host-only system field set, which host.request can never set. The adapter is a few lines and shares the per-app ledger. feat(toolbox): the system toolbox's workflow template library #82 is not touched here.
• The schema validator is a small copy of Octoscript's subset, not octoscript-schema itself. That crate enables serde_json's arbitrary_precision, which would change number handling across the whole shell build.

Where

• apps/ai-providers/host-service/src/complete/{mod,schema,ledger,wire}.rs, plus register_model() in src/lib.rs
• crates/ai-host/src/lib.rs: registered with the llm service (feature llm)
• docs/adr/0002-event-driven-app-agents.md §14. The ADR's title and status are unchanged, so the ADR indexes are not touched.
• README for the service, and the AGENTS.md table rows

Verification

• cargo test --locked -p octosense-llm-service --test complete: 18 passed, using a fake provider. Covered: schema pass; schema fail after one retry; invalid JSON then a pass on the retry; a URL refused, and allowed with allow_urls; the size cap (reply, input, schema); no max_tokens/max_completion_tokens/max_output_tokens sent (and Anthropic's catalog maximum); token budget; daily call budget; rate limit; no provider; capability missing; the manifest grant; fallback order with class preference; no provider, model or key in replies or errors; the profile as provider source; a host caller sharing the ledger; and, new after the merge, the_card_runner_gate_and_the_service_agree_on_the_model_capability: Makepad's isolate gate (splash_policy, which App Hub feeds each app's resolved policy) admits model.complete and model.budget only with model (not llm or models), model grants nothing else, and the service's default manifest grant then serves the granted app and refuses the other. A scratch crate on octosense-app-policy at e8601b80 also confirmed a manifest declaring model resolves with allows("model") and nothing more. Plus 7 unit tests (schema, ledger, wire).

• cargo test --locked -p octosense-mail-service -p octosense-llm-service -p octosense-news-service: pass.

• cargo test --locked -p octosense-ai-host --features octos-core,llm: 12 passed.

• cargo clippy --locked -p octosense-llm-service --all-targets --no-deps -- -D warnings and the same for -p octosense-ai-host --features octos-core,llm: clean.

• cargo check --locked -p octosense, with and without --features mobile-apps: pass.

• python3 tools/setup.py --check --cargo: pass (.sources are hub worktrees at main's pins, makepad b0cbc9bc).

• bash tools/check-shell-graph.sh -p octosense passes, and from phone/, cargo check --locked -p octosense-home --features mobile-apps and bash ../tools/check-shell-graph.sh -p octosense-home pass.

• from phone/: cargo test --locked -p octosense-app-policy --no-run: pass, not ambiguous.

• After the merge: cargo test --locked -p octosense-llm-service and cargo test --locked -p octosense-ai-host --features octos-core,llm: pass. The live DeepSeek check below was run before the merge.

• Live check against DeepSeek (examples/model_complete_live.rs), with one call per class and 1,054 tokens in total (about US$0.0004):

  • fast (deepseek-v4-flash): 1.9 s, {"title":"Boiler leaking; call plumber","tags":["boiler","plumbing","urgent"],"urgent":true}, 241 in / 185 out;
  • strong (deepseek-v4-pro): 7.2 s, {"title":"Leaking boiler in kitchen","tags":["home","plumbing","urgent"],"urgent":true}, 294 in / 334 out.

  Both replies validated on the first attempt, and no output cap was sent.

• Not run in a shell or on a device: no app declares model yet.

Follow-ups

• A Settings page for per-app use and limits (the ledger API is ready).
• The toolbox ModelClient adapter onto ModelHost (after feat(toolbox): the system toolbox's workflow template library #82).
• The first system or store app that uses model declares it in its manifest.

🤖 Generated with Claude Code