AI agents, models, tools, and skills

Frontend conversation ownership

features/agent owns chat composition, sessions, confirmations, message actions, and stream presentation. Its public entry exports AgentChat and the complete props contract. The application loads this entry dynamically; notebooks import the same component inside their optional route chunk. No caller reaches private chat modules or casts the component to a narrower type.

Context-reference arrays remain read-only through the UI and are copied only when constructing the existing HTTP request. This preserves source metadata, notebook scoping, payloads, stream replay, and persistence keys. Generic HTTP and NDJSON adapters remain under shared/api; composed feedback-and-transport tests belong to the agent feature so shared code does not depend on UI internals.

Capability model

Gnosi separates models, agents, skills, and tools:

• Model: a provider route with capabilities, limits, cost metadata, reliability, and credentials.
• Agent: instructions, model selection, memory/checkpoint policy, and assigned skills.
• Skill: a documented capability package that contributes instructions and constrains compatible tools.
• Tool: a callable operation classified by effect and origin.
• Context source: user-selected Vault, table, file, or external material added to a conversation with explicit containment and size behavior.

The Vault knowledge tool belt keeps LangChain StructuredTool objects at the registration boundary and unwraps their typed callables only for internal tool composition. Page creation registers through the canonical Vault owner, Vault search obtains its dedicated lazy store explicitly, and path/PDF reads retain their containment and server-owned size ceilings.

The Artificial Analysis feed is a typed, server-side comparison boundary. It keeps API credentials private, validates every paginated response, enriches only missing catalog metadata, preserves verified cached metrics, and falls back to stale cache or models.dev with explicit provenance.

Startup and request flow

sequenceDiagram
    participant Start as App lifespan
    participant MCP as MCP clients
    participant Catalog as Skill and tool catalog
    participant Graph as LangGraph workflow
    participant Chat as Chat endpoint
    participant Model as Selected model
    Start->>MCP: Connect and discover tools
    Start->>Catalog: Reconcile built-in, user, generated, and plugin entries
    Catalog->>Graph: Build allowed capability set
    Chat->>Graph: Message, agent, session, attachments, context
    Graph->>Model: Route prompt/tool cycle
    Graph->>Catalog: Validate tool effect and confirmation
    Graph-->>Chat: Ordered events and final response

Legacy Agent imports remain available through narrow compatibility facades, while the domain package owns context matching and storage, first-party tool dispatch, evidence and citation contracts, stream state, confirmations, sessions, and route composition. Agent catalog and governance routes use the same pattern under the configuration domain, preserving route order and operation identifiers.

The model router resolves provider/model combinations, context limits, tool support, spend caps, and fallback policy. Credentials are obtained from local secret storage or supported environment migration, not exposed to the frontend. Failure reasons are recorded separately from user-facing responses so operators can distinguish timeout, provider rejection, invalid credentials, context overflow, and tool incompatibility.

The legacy hybrid client remains available to social composition, mail drafting and older pipeline parsers through a strictly typed compatibility boundary. It narrows dynamic YAML provider maps, requires a concrete provider URL before any network call, validates OpenAI-compatible response envelopes, writes its prompt-hash cache atomically below the per-device data directory, and preserves the established primary-then-fallback behavior without exposing credentials.

Local Whisper transcription exposes a typed model protocol and result shape; audio remains on-device and its lazily downloaded model cache lives below the provider-neutral GNOSI_DATA_DIR. The optional untyped faster-whisper import is confined to this adapter. Currency conversion similarly narrows remote and cached JSON before budget arithmetic, retains stale-real and static fallbacks, and always returns a positive typed units-per-USD rate.

The router normalizes unknown registry metadata before iteration, compares token quotas and context windows as integers, and keeps its usage ledger behind typed atomic path/load/save boundaries. Monetary caps distinguish an absent cap from zero explicitly, preserving the existing near-cap and free-model fallback policy while making malformed persisted data recover to an empty ledger.

Agent observability, replay, stream journals, turn claims, reviewed quality, personal and semantic memory, model evaluations, capability audit and health are operational per-device state. Their SQLite/JSON stores resolve directly through GNOSI_DATA_DIR; they never derive a location from a Vault or cloud provider. Tests inject that same canonical resolver, and encrypted stream keys remain in the secrets child of the local data directory.

Profile execution uses pinned: exactly the configured provider and model. Legacy resilient, adaptive, and decision_engine: jev settings no longer select alternatives for profiles. The settings form saves one model with no fallbacks. Legacy strategy helpers remain covered in backend/tests/test_agent_model_decisions.py; profile editing is covered in frontend/src/features/settings/global-settings/AIAgentForm.test.tsx.

The stdio MCP client validates JSON-RPC object boundaries, types pending async requests explicitly, and routes tools through a cache that refreshes only on a miss. Malformed tool catalogs fail locally instead of leaking unchecked values into the agent runtime.

AI settings keep provider credentials, connection tombstones, model registry, budget and usage routes in a strictly typed compatibility facade. Editor generation and correction live in the configuration AI domain, while validated YAML mapping loads and explicit legacy response metadata preserve the existing HTTP and OpenAPI contracts exactly.

Tool governance

Tool descriptors declare read/write/external/destructive effects. Generated tools pass AST-based validation and execute in a restricted environment. The validator blocks dangerous capabilities such as unrestricted file writes, environment access, dynamic dunder traversal, and unsafe imports.

Actions requiring confirmation create durable pending records. Confirmation binds the user, session, tool, arguments, effect, and expiry; accepting a stale or altered action does not authorize a different invocation. Maintenance expires and removes records independently of chat traffic.

Versioned capability metadata is narrowed from model or mapping input before validation. Version 2 contracts fail closed unless timeout, idempotency, privacy, egress and durable-result policies are complete and valid; legacy version 1 descriptors remain compatible. Cooperative cancellation wraps any Python awaitable in a cancellable future, so coroutine and future based provider adapters share the same token semantics.

Skills and plugins

Built-in runtime skills live in pipeline/skills/. User and plugin packages are validated into a catalog while preserving origin, activation, compatibility, and managed-versus-user-owned fields. Plugin reconciliation is idempotent: disabling a plugin suspends its managed contribution without deleting user overrides.

Row and page translations use the shared translation operation. UI buttons select the Translation plugin's profile; actions within a conversation inherit the running agent's profile. That profile governs the model, policies and activity records. Translation settings link to this profile. Historical DeepL and Softcatalà arguments remain compatible but are ignored; there is no language-pair routing or placeholder provider fallback.

Plugin reconciliation can also run before FastAPI route composition. It derives the .gnosi directory from the canonical active-Vault context and reads state through backend/domains/configuration/plugin_state.py; it never imports a Vault route merely to resolve paths or configuration. Before the process-wide store exists, the same normalizer and atomic writer run behind a bootstrap lock; after composition, reconciliation reuses the shared store and mutation locks.

The legacy Chroma memory facade remains lazy and strictly typed for import compatibility. Importing it creates only the configured storage directory; it does not load embedding models. Missing embeddings degrade to empty reads and explicit failed writes, while canonical governed personal memory remains in the Agent domain's scoped SQLite service.

Context and memory

Conversation state is scoped by agent and session. UI message ordering uses stable identifiers rather than arrival time alone. Attachments and context sources validate paths, size, file type, and workspace/vault scope. Large external sources use searchable representations instead of injecting unlimited raw text into every turn.

The durable checkpoint remains the complete audit record, but provider prompts use a bounded projection. Earlier user and final assistant messages remain as conversation memory, while historical tool-call groups and raw tool payloads are omitted. The current turn retains complete call/result protocol groups, and the aggregate conversational projection has a hard character ceiling even when the selected model advertises a much larger context window.

Reviewed personal memory is a separate, explicit local store scoped by Vault and agent. Users can create, edit, disable, expire, and delete revisioned facts or preferences in Settings. Retrieval is lexical and bounded to five items; the prompt labels the result as data that cannot change policy, tools, or authorization. Conversation checkpoints and vocabulary associations retain their separate lifecycles.

Vault navigation contributes turn-scoped page, table, and active-view context. The server expands a dashboard with one embedded view to the canonical table view, reapplies its filters and sorting, and exposes an exact bounded row query with count and pagination. Exact page and table reads are server-authored tool calls; after a complete result, synthesis runs without tool bindings so a tool-eager model cannot repeat the call until the graph recursion limit.

The canonical self-authored Resources request is also server-routed. Gnosi executes the saved authorship view exactly once and formats its count and bounded record list directly from the governed result. This path performs no model call after the tool succeeds. Requests requiring interpretation or generation continue through normal model synthesis.

The same deterministic contract now applies to arbitrary attached-Vault inventories rather than individual topics or tables. Before tool selection, the server classifies the operation as conversation, lookup, inventory, analysis, or governed action. Inventory requests receive an exhaustive structured scan with exact count, canonical record ids, live registry type resolution, type grouping, selected provenance metadata, and offset pagination. The subject is query data: adding a topic or a new table does not add an intent branch. The first page and continuation pages are formatted directly from the governed tool result without a model call.

The request mode also prevents the default Knowledge attachment from hijacking unrelated work. Conversation mode performs no source read and binds no passive tools. Explicit mail, calendar, contacts, Reader, weather, web, Notion, or Zotero requests omit default Vault tools unless the same request also names a Vault object; the relevant assigned skill remains available.

Every request now carries an effective universal turn plan into the graph. The plan combines operation mode, explicit data domains, live runtime descriptors, required evidence, guarded grants, provider locality, execution strategy, and response strategy. It is request-scoped state that overwrites checkpoint data from previous turns. The Brain node intersects normal runtime selection with the plan's tool names, so the metadata shown to the user describes the actual tool surface rather than an advisory classifier.

Privacy is also request-scoped. The plan distinguishes local processing, private evidence processed by the configured remote model, external reads, and ordinary conversation. Attached Vault data does not count as used when an explicit Mail, Reader, Notion, web, or other domain excludes its tools. The UI reports only this posture and source counts; source bodies, prompts, secrets, and hidden reasoning never enter transparency metadata.

Final model responses pass through a deterministic verifier. It checks only current-turn tool results and effect policy, blocks claims that a governed action completed without a successful tool result, blocks source-dependent answers that skipped mandatory evidence, records tool failures as limitations, and emits evidence/tool counts. Inventory answers use the same verifier even though their text is server-rendered. Verification never invokes a second model.

Source-dependent responses also carry server-validated claim citations. Tool results define the only source ids valid for the current turn. Deterministic inventories map each listed line to its canonical Vault record and map aggregate count, grouping, pagination, and method statements to the exact tool-result manifest. Model synthesis may emit [[cite:SOURCE_ID]] markers; the verifier removes valid markers from visible prose, rejects ids absent from current-turn evidence, and marks incomplete grounding as a limitation. The chat renders the bounded claim/source mapping with safe Vault, Reader, or HTTP(S) links and never persists excerpts or filesystem paths as citation metadata. Every cited source also carries a short version fingerprint derived from its revision, etag, update timestamp, or exact current-turn tool manifest. The UI distinguishes exact from identity-only versions without exposing source bodies or connector secrets.

Vault search uses a deterministic hybrid rank: expanded multilingual lexical terms, exact-title boosts, index-role boosts, and the rebuildable vector score. Results are cached briefly by Brain/query/k only; the cache is bounded and does not retain prompts or unbounded source bodies. Returned excerpts are delimited as untrusted evidence and injection-like instructions are flagged; the Brain prompt treats every source, connector, attachment, and web result as data rather than an instruction.

Exhaustive inventories reuse the locally persisted parsed-document and link indexes. Relation ids are expanded to indexed target titles, so a record linked to a matching project or source remains discoverable without reopening every cloud-synced document. Normal Gnosi writes update these indexes; periodic index maintenance reconciles external edits. Records absent from the cache fall back to a direct bounded read. Semantic top-k search remains the evidence-discovery path for lookups and analyses and is never presented as a complete inventory.

Inventory payloads also report link-index build age, cache coverage, direct fallback reads, and stale-while-revalidate state. A stale or missing index requests a guarded background reconciliation without delaying the answer; the message retains the limitation instead of implying that the index was freshly rebuilt.

Whole-collection Reader analysis is admitted as a background operation through the provider-neutral capability-job facade. The server creates the job tool call deterministically, returns a namespaced reader: job id, and exposes status, result availability, resume after failure or interruption, and cooperative cancellation in message details. The same facade remains extensible to other source-owned durable providers; unsupported requests stay foreground and are never represented as durable work.

Reader agent tools require a concrete active Vault before analysis or page persistence, expose typed scope payloads and retain an identity decorator only for lean environments without LangChain. Article reads and mutations narrow legacy ORM descriptors at one boundary while preserving tool names, effects and serialized responses. Attached-Reader context tools apply the same guard and reuse one resolved Vault for status authorization and result retrieval, preventing cross-Vault context drift within a tool call. Untrusted-content wrapping and output bounds remain unchanged. Providers and queue dispatchers register versioned contracts declaring job kind, idempotency, lease, attempt and model-call budgets, result, resume, and cancellation behavior. Unknown job types fail visibly instead of entering a hard-coded worker branch.

Reader jobs persist a bounded recovery policy beside their checkpoints. A transient timeout, temporary network/service failure, or rate limit enters a cancelable retry-wait state with capped exponential backoff. Attempts and model calls consume separate persisted budgets before any new call is made. A daemon timer handles normal in-process retries; job list/status reconciliation starts an overdue retry after a backend restart. Permanent, cancelled, malformed, or budget-exhausted failures remain terminal and visible. Manual resume uses the same budgets and therefore cannot bypass the loop boundary.

Other read-only turns have an independent three-result budget: if the model keeps requesting tools, the next Brain invocation receives the accumulated evidence without tool bindings and must synthesize the response. The graph recursion ceiling therefore remains a final safety net rather than normal flow control.

The universal plan also carries an immutable operational budget for every turn: the HTTP timeout, maximum model calls, maximum tool calls, and maximum read results. Conversation turns receive a short no-tool budget; lookup and inventory turns receive bounded read budgets; analysis and governed actions receive a larger but finite budget. The graph enforces these values before the next provider or tool invocation, and the stream exposes the same values and whether a limit was reached. A zero tool budget is a mode declaration, not an authorization bypass: mandatory server-authored context reads still follow their explicit path. Dynamic context tools are not selected for a general question unless the user actually supplied a context source.

Capability automations persist scope, revision, schedule and per-run budgets in their own migrated SQLite database under the canonical local data directory. Run reservation is transactional, rejects overlapping or over-budget work, recovers stale leases, and records terminal status even when agent execution fails. Missing data configuration or a failed persistence round-trip aborts explicitly instead of reporting an automation that was not stored.

The ToolNode retains the complete active-skill runtime for execution and policy checks, while each model invocation binds only passive read tools plus guarded tools explicitly authorized by the current request. Legacy automatic profiles also narrow passive reads to multilingual request-domain matches and an exact required context operation, with a bounded maximum; explicitly scoped skills retain their already-small assigned read surface. Mandatory context reads bind only the required source tool for their first step. This per-turn binding is derived from request state and is never reused as cached authorization.

The chat measures each response from request dispatch through stream completion. A live whole-second counter is replaced by the saved elapsed time on the completed response. The stream also reports server setup, routing, tool, model, residual, and total durations together with model/tool call and token counts; message details retain this bounded diagnostic breakdown. Every visible message also exposes conversation rewind: after confirmation, the server truncates the scoped canonical checkpoint at the complete turn boundary and returns its public projection. Rewind changes conversation memory only; completed confirmations and external side effects are never presented as reversed.

During execution the stream emits a bounded phase marker for routing, model generation, or tool execution. The chat shows the active phase beside the elapsed seconds counter and resets it when the turn ends. Stable transient failure codes (agent_loop_exhausted, timeout, service-unavailable, and rate limit variants) include advisory recovery metadata. The client offers one deliberate retry of the original request after user review; the server never replays a failed turn automatically because a governed action may already have been prepared. Permanent configuration or authorization errors instead invite editing the request or runtime settings.

The stream owns an opaque cancellation token. The explicit Cancel action calls an authenticated stream-scoped endpoint and reaches the asynchronous provider cancellation bridge. An accidental browser or proxy disconnect does not cancel the accepted bounded turn: an independent producer continues and its events remain resumable. Cached workflows do not capture request-specific events, and tokens are released after the producer completes. Provider failures use a bounded process-local circuit breaker keyed by provider/model, while authentication and policy errors remain terminal. Tool descriptors additionally expose a cheap health status (healthy, unavailable, or temporarily quarantined) so missing ids, names, handlers, and repeatedly failing adapters cannot be advertised as runnable capabilities. Two failures inside the bounded health window quarantine a tool briefly; a successful later call clears the consecutive-failure record.

The newline-delimited transport is wrapped in protocol version 1. Each event carries an opaque stream id, event id, monotonic sequence, trace id, and optional turn id. A pending provider operation remains alive while a heartbeat is emitted, so a slow but healthy provider is not cancelled by transport keep-alive. The client ignores duplicate sequence numbers. Events are encrypted in a scope-bound local journal for at most one hour, and the browser resumes from its last sequence for the full turn timeout. Replay repeats no model/tool call or governed action; it reapplies the original event envelope only.

Long prompts retain the complete checkpoint as an audit record but add a bounded deterministic digest of dropped human/assistant turns to the provider projection. The digest contains short excerpts and opaque hashes only; raw tool payloads and unbounded source bodies are never carried forward.

Every streamed turn receives an opaque trace_id propagated through planning, model selection, runtime health, messages, errors, metrics, and completion events. This gives distributed logs and the UI one correlation key without persisting prompts, credentials, or source text. MCP readiness is cached briefly per server, and provider/connector snapshots are included in the runtime receipt.

Brain retrieval combines the rebuildable vector score with accent-normalized, multilingual lexical expansion, title/index boosts, bounded caching, and injection-marked evidence. Live table/trash HTTP tests are opt-in and run in CI against a throwaway Vault and separate port; the hermetic suite always points at a closed port so a developer's native backend cannot be mutated accidentally.

Editable model-registry rows are hydrated from the canonical catalog before they reach Settings or runtime routing. Partial budget/settings updates merge with existing capability, context-window, cost, and quality metadata. Provider or model changes invalidate cached graphs so tool support and credentials take effect on the next turn. The chat header reports the selected model, exact tool count, and actionable reasons for any degraded runtime.

Message details provide bounded operational explainability: mode, route, foreground/background execution, tools actually used, evidence count, privacy posture, verifier status, index freshness, durable job state when present, and timings. This is an execution receipt, not chain-of-thought.

The same receipt includes a redacted semantic interpretation (operation, confidence, concepts, and retrieval strategy), the capability broker decision (candidate and guarded tool counts), and the checkpoint scope. Query digests, source bodies, historical tool payloads, prompts, and hidden reasoning are excluded from the client metadata.

Turn metrics include a provider-catalog-based USD estimate alongside token and latency counts. The persistent spend ledger remains the source of truth; the estimate is bounded display metadata and is never used as authorization by itself. The deterministic evaluation suite also asserts that every plan stays within the 120-second latency ceiling.

The deterministic corpus under backend/agent/evals/ covers all request modes, all four UI languages, domain containment, private local and remote processing, governed actions, and durable Reader admission. It runs before the backend test suite on matching pull requests and every day; any failed case exits nonzero without calling a provider or spending tokens.

Production errors and assistant thumbs feedback feed a local, authenticated quality loop. POST /api/chat/feedback accepts bounded operational metadata only and explicitly rejects response content. Stream errors are recorded by the server with stable codes. The local SQLite store retains hashed turn/session/ agent identities, plan and verifier fields, tool names, and timing buckets; it has no prompt, response, source, title, path, URL, excerpt, attachment, or raw tool-payload columns. Negative feedback and errors deterministically upsert deduplicated synthetic evaluation candidates. Administrators list, accept, reject, reopen, and run these candidates through /api/ai/evals/candidates*. Accepted local cases remain separate from the versioned CI corpus until a maintainer deliberately promotes them.

Administrators may also run an explicit cost-bearing real-model evaluation for an agent's assigned primary model. It uses three synthetic multilingual/schema prompts and stores only route identity, score, latency, token counts, and stable failure codes. Prompts and responses are never persisted. Reviewed scores may influence adaptive ordering but cannot add an allowed model or capability.

Adaptive quality and capability discovery

Tool health survives backend restarts in a bounded local SQLite store. Each capability retains success/failure counters, a consecutive-failure window, temporary quarantine state, and aggregate invocation latency. Runtime catalog construction reads these rows in one short-lived cache snapshot rather than opening the database once per tool. A later successful invocation clears the quarantine but retains bounded service-level totals for diagnostics.

Vault inventory retrieval fuses exact phrases, normalized lexical tokens, conservative character similarity, metadata, cached body text, and canonical relations while preserving an exhaustive scan of the authorized scope. Users can add or remove reviewed vocabulary associations through /api/ai/semantic-associations. The local store hashes the Vault scope and contains only bounded term pairs and a hashed author identity; it never stores prompts, answers, source bodies, paths, credentials, or executable text.

The final deterministic verifier now publishes a response-quality score over visible output, required evidence, tool success, supported completion claims, citations, inventory pagination, and contradiction handling. Structured facts with the same record and field but incompatible current-turn values produce a bounded conflict receipt containing provenance names but not the private values. The visible answer receives a localized warning instead of silently merging the facts. A provider-free response corpus complements the routing corpus and exercises these final-answer contracts in CI.

Tool and attachment evidence is scanned for instruction override, authority spoofing, tool coercion, and secret-exfiltration markers. Only bounded taint categories reach response metadata; source text remains untrusted data and the receipt always records that authorization was unchanged. The adversarial response corpus asserts this boundary.

Each plan exposes a soft synthesis boundary before the hard turn timeout. Once the reserve is reached and required evidence is available, Brain removes tool bindings and synthesizes the best supported result; the stream emits a deadline stage so the client can show that transition. If required evidence is still missing, the evidence boundary remains authoritative rather than producing an unsupported answer.

Capability discovery is part of the enforced turn plan. For each explicit domain it reports a usable capability, an assigned but guarded capability, or a missing connection/skill. Discovery cannot install software, grant permission, or authorize a guarded action. Settings → AI → Quality displays metadata-only turn counts, latency buckets, verification outcomes, errors, evaluation candidates, persistent capability health, and the reversible vocabulary editor through /api/ai/quality/dashboard.

Capability contracts may opt into schema version 2 through descriptor metadata. Version 2 fails closed unless timeout, idempotency, privacy, egress, and durable result behavior are valid. Legacy version 1 tools and skills remain visible as legacy or partial in Settings while they migrate; conformance metadata never makes a handler executable.

LLM Wiki configuration

Knowledge uses its dedicated plugin profile. The historical agent_id setting is preserved but does not override the plugin profile. The old managed llm-wiki profile remains retired; the new profile retains migrated Knowledge companion instructions. Settings link to the plugin profile and its skills.

The secondary Brain tools menu lives in the Brain table header, including embedded tables. It offers deterministic review with an in-view report and AI connection proposals that refresh and open the existing connection inbox. Maintenance actions no longer appear in plugin settings.

backend/domains/configuration/llm_wiki.py validates the Brain table, source tables, categorical dimensions, file/URL fields, fixed values and relation targets before any schema mutation. It then provisions the canonical roles and source relations, revalidates eligible index fields, persists atomically and refreshes the system pages through late-bound facade ports. The per-Vault configuration facade narrows property, source and dimension mappings to typed objects while deliberately retaining late-bound path and reference-table callables from vault_routes; disposable-Vault tests and existing integrations can therefore replace those historical seams without duplicating their mutable state. Its HTTP boundary narrows the late-bound legacy router once to APIRouter, so Brain designation and LLM Wiki configuration endpoints remain strictly typed without altering permissions, payload schemas, route order or OpenAPI output. The route adapter imports the canonical configuration, schema and record services directly, avoiding partially initialized facade lookups during standalone Agent startup. Runtime-replaceable Vault operations remain explicit ports, including the typed VaultActionsPort used by Brain processing actions. The processing boundary uses the same typed router for durable ingestion, polling, evidence, maintenance, lint, suggestion review, dictation and glossary learning; late-bound services and recoverable HTTP errors remain unchanged. Brain planning retries transient provider failures, including HTTP 429, within five attempts per fragment, 120 seconds of cumulative waits and a 360-second overall call budget. Each request receives the remaining timeout (at most 240 seconds). Exponential backoff includes jitter and honors Retry-After seconds, HTTP dates and retry-after-ms; a cooldown beyond the budget stops the attempt instead of retrying early. Authentication, validation and explicit exhausted billing quotas are not retried, and no provider is switched automatically. Connection and timeout failures are recognized by their SDK types, including LangChain wrappers over OpenAI-compatible providers using httpx2. Each retry reserves its own cost within the existing reading budget; an earlier unknown charge remains reserved. SDK timeouts use the localized provider-timeout message. The durable job exposes phase: retrying during waits. The processing dialog keeps polling, explains rate limits and offers a retry when the job stops. Successful fragment plans are checkpointed with their exact prompt hash and source chunk. A non-forced retry of an error or partial job reuses only matching plans, copies them into the new job and continues at the remaining fragments. Changed source evidence or planning inputs invalidate cached fragments; explicit force processing bypasses all previous checkpoints. Interrupted jobs retain their actual progress and source notes are written only after planning completes. Every ingestion call explicitly selects the configured agent_id. A provider response with x-ratelimit-limit-req-minute: 0 stops automatic retries, because waiting cannot replenish a zero request limit; zero remaining capacity with a positive limit still receives normal retries. After a backend restart, status lookup reads the persisted job by its exact ID and checks the source table when supplied. Interrupted running jobs become phase: partial and retain their completed-fragment counts. The dialog allows one status request at a time, ignores cancelled responses and shows fragment progress; phase: idle for a tracked job ends polling with a recoverable error.

Settings loading allows up to 45 seconds for a slow local response. Failed HTTP responses are rejected before entering the shared configuration cache, so a retry can reach the recovered server. Empty server failures use the translated configuration error with a separate retry button. Loading these settings does not require an available model provider.

backend/domains/configuration/llm_wiki_schema.py separately owns idempotent Brain-field repair and consolidation of one canonical source relation, including legacy aliases, page metadata and contextual embedded views. backend/domains/configuration/llm_wiki_records.py normalizes existing managed notes, source labels and localized resource-index titles without owning HTTP routes. Source extraction is split between backend/domains/llm_wiki/documents.py for typed document and media adapters and origins.py for deterministic evidence identity, deduplication and chunking. The historical service remains a compact compatibility facade so notebook and plugin contracts keep their current symbols. Extractor inputs now carry explicit metadata/configuration mappings and cross legacy attachment and local-data helpers as concrete Path values. The optional yt-dlp import is the sole localized untyped third-party adapter; public-URL checks, fingerprints, source ordering and provenance remain stable. Processing is split further into planning.py for prompts, parsing and grounded plans, dimensions.py for fixed/source/AI field mapping, ingestion.py for the blocking workflow, and writing.py for idempotent persistence. index_rendering.py owns managed resource, dimension and general pages, while search_index.py owns rebuildable JSON, FTS5 and vector indexes. backend/services/llm_wiki.py and backend/services/llm_wiki_indices.py remain late-bound compatibility facades so existing imports and monkeypatch/plugin seams continue to resolve at call time. backend/domains/llm_wiki/legacy_ports.py narrows the path, table, page parsing and persistence collaborators without introducing eager route imports. The JSON writer remains exposed by the facade because it is a historical replaceable seam; rebuild and incremental upsert paths retain their cache invalidation behaviour. The same late-bound path port owns Vault, .gnosi and local-data resolution for the personal dictation glossary, connection queue and durable Brain jobs, snapshots, manifests and synchronized page sidecars. Queue and lint scans use the late-bound table-page port, preserving existing runtime replacements. That input port still returns dynamically typed pages; its metadata contract remains separate typing debt. The ingestion facade uses the same late-bound ports for Brain page enumeration, table lookup and processed-state updates. Runtime plugin replacement is preserved, but the broad Any annotations in these ports do not prove complete typing.

Deterministic Brain lint is split into bounded checks for orphan notes, stale reviews, missing cross-references, duplicate provenance keys, retained managed notes, broken evidence citations, reprocessing and resource-index drift. The report shape and finding limits remain stable and require no model provider.

backend/domains/llm_wiki/lint_contracts.py defines the normalized note projection, all eight finding categories, counts and complete report at their producer. These are ordinary dictionaries with precise static types, not runtime models or schemas asserted over arbitrary stored metadata. The HTTP route may add optional suggestion totals; pure lint does not emit them. Output order, date handling, citation decoding and truncation are unchanged. The legacy page-input boundary and route composition still require separate typing work.

Grounded PDF citations use a separate deterministic persistence boundary. It resolves quote geometry with one cached document handle per attachment, upserts stable managed highlights in one transaction, preserves manual annotations and removes only obsolete Gnosi-managed entries.

Failure and safety invariants

• Provider failure does not silently route to a more expensive or less private model outside the configured policy.
• A tool unavailable to the selected model/skill cannot be invoked by name alone.
• Destructive or external effects require their declared policy.
• Generated code cannot access secrets or unrestricted filesystem state.
• One failed MCP server does not remove healthy servers from the catalog.
• Partial model output is not presented as a completed confirmed action.
• Source-dependent output cannot pass verification without current-turn source evidence.
• Citation ids cannot resolve unless the same turn returned that exact source.
• Transparency metadata cannot contain source bodies, prompts, or raw tool payloads.
• Automatic and manual job recovery cannot exceed persisted attempt or model-call budgets.
• Quality telemetry cannot accept or retain prompt/response content.
• Stale index evidence is labeled and refreshed outside the foreground turn.
• Agent messages remain isolated by agent and session across reloads.
• Adaptive routing cannot escape the selected agent's explicit model allowlist or local/remote trust boundary.
• Evidence taint and personal memory cannot grant tools or change authorization.

Verification focus

Run model routing, provider deletion, reliability, timeouts, MCP retry and resilience, skill catalog/runtime/API, generated-tool validation, context containment, confirmation race/expiry, chat ordering, and browser chat flows.

Universal agent runtime

Gnosi routes every turn through a bounded, provider-neutral contract. Before capability selection, the semantic interpreter normalizes multilingual intent, records a confidence score and can abstain when a request has no subject. The result is included in the turn plan without storing the original prompt.

Background capabilities use the local SQLite durable queue. A job has an idempotency key, attempt budget, lease and heartbeat; an expired lease can be reclaimed after a process restart or when a second worker is active. Reader analysis retains its JSON snapshots and batch checkpoints, while the queue is the source of truth for orchestration.

Every model and tool operation emits a bounded span correlated by the turn trace_id. Span attribute names are allowlisted; callers must not place prompts, sources, arguments or raw provider output under those allowed names. This filter does not inspect arbitrary text for secrets. Tool calls also pass through argument-size validation, descriptor timeouts, output limits and the existing role/confirmation policy.

Brain search maintains its JSON compatibility cache plus an FTS5 sidecar. The sidecar narrows lexical candidates before deterministic vector hybrid ranking, and exposes freshness metadata for diagnostics. If the sidecar is unavailable, the JSON cache remains a safe fallback.

Explicit turn identifiers are claimed durably in the workspace/user/session scope. A duplicate request is rejected instead of executing the same action or background job twice. The NDJSON stream emits progress events with node, phase, elapsed time and bounded call counters so clients can render responsive progress without reading internal prompts.

Security boundaries remain conservative: generated tools are revalidated at load time, connector URLs can use the public-host egress policy, and common credentials are redacted before diagnostics or tool messages are persisted. The generated-tool registry declares its local SQLite path only through an idempotent initialization boundary; migrations and parent-directory creation complete before any search, approval, rejection or statistics query can open the database. Cloud-synced source files remain separate from this local state. Dry-run protection preserves wrapped callable signatures, generates collision- resistant pending identifiers and never invokes an external-write function before confirmation. Confirm and cancel consume only the addressed pending record; non-external operations retain normal execution.

The generated-tool runtime also keeps typed boundaries from registry records through loader caches, dynamic JSON schemas, learning-loop results and sandbox resource callbacks. Untrusted schema payloads are narrowed before Pydantic model creation; these annotations document the existing subprocess contract without weakening validation or moving execution into the application process. The approval-registry provider constructs validated ToolDescriptor instances directly and exposes a signature-preserving lazy callable, so catalog policy and runtime loading share one typed record boundary. Approval and rejection handlers likewise validate their mutation responses with Pydantic while keeping the historical dictionary and OpenAPI shapes unchanged. Third-party plugin contributions use the same descriptor contract after narrowing manifest schemas and resolving the active Vault through the typed domain adapter. Their handlers remain Node-sandbox callables with exactly the declared permission subset; typing does not import plugin Python into FastAPI. First-party Gnosi tool support similarly narrows the remaining legacy facade ports for frontmatter parsing, page versioning, index refresh and table-view revisions. These adapters keep confirmation snapshots and optimistic concurrency checks typed without changing their persisted formats. Vault-administration tools consume those ports through explicit registry, table-row, metadata-refresh and page-index call signatures. Table discovery, saved authorship views, deterministic filtering and contained page relocation therefore retain their existing JSON tool contract under strict typing. Contact tools bind each operation to a typed management session and workspace-scoped ContactsService. Duplicate detection, bounded updates and destructive merges still close the session deterministically, while a missing primary after a concurrent update now follows the existing error-result path. Provider-neutral job tools resolve a concrete active Vault before listing, estimating, reading, resuming or cancelling durable work. Missing request context fails at this adapter boundary, while namespaced job identifiers and all persisted result payloads remain unchanged. MCP tool construction narrows each third-party descriptor and JSON schema before creating its dynamic Pydantic argument model. Required and optional fields preserve their prior call semantics, malformed entries remain isolated, and server-qualified routing continues through the existing MCP client. Mail tools use the installed LangChain tool contract directly and type the bounded serialization boundary for exact messages, threads and folders. Remote read/star/reply/batch behavior, account confinement and confirmation effects are unchanged. The remaining governed adapters for translation, public-web context, calendar, social publishing, Notion cloning and project planning use concrete tool signatures and canonical domain routes. Web fetches also make the otherwise unreachable no-response state explicit after bounded redirect handling; SSRF checks, payload limits, account policy and confirmation effects remain unchanged. Agent context sources now expose a typed searchable-source protocol for BOE and require concrete active-Vault paths before opening Reader or planning state. Plugin state is read through the canonical Vault configuration domain, while the small LangGraph compatibility graph uses a secret-bearing API-key type without changing its fallback responses. Runtime support now types confirmation context tokens and requires the configured local-data directory before opening its audit database. Memory and Vault search use their explicit lazy-store accessors, while model-catalog JSON, model identifiers, reliability ranking and evaluation metadata are narrowed at their input boundaries without altering routing evidence. Notion integration boundaries now type hosted-MCP responses, Markdown trees, attachment localization callbacks and clone-verification configuration. An atomic, idempotent integration-key deletion primitive removes irrecoverably expired OAuth credentials instead of repeatedly retrying a dead token; clone schemas, page bodies, views and attachment markers retain their formats. Core AI workflow contributions use an internal typed specification for identity, activation, source requirements, tools, and instructions. Descriptor creation therefore cannot conflate string fields with source/tool sequences, while the published catalog schema and ordering remain unchanged. Attached-context readers now preserve the concrete string contracts of URL, external-source, and internal-record wrappers directly. No dynamic cast masks a provider mismatch at these untrusted-content boundaries. Inventory cache readers retain the legacy Vault monkeypatch seams through a narrow typed adapter. This preserves plugin and test compatibility without allowing dynamically re-exported callables to spread into the agent domain. Confirmed page and table dispatchers apply the same rule to Vault mutation seams: each dynamically re-exported handler is narrowed at the call site, while conflict detection, partial-result reporting, rollback, and background cleanup retain their historical behavior. Context storage and the built-in LLM Wiki catalog also narrow their legacy Vault readers locally. Plugin lifecycle verification binds a concrete active Vault, including in isolated tests, before resolving filesystem-backed configuration. Eligible MCP tools are materialized as validated ToolDescriptor instances at the contribution boundary, with an explicit MCP origin and normalized input schema. Read-only/destructive annotations still determine admission exactly as before. Reference evidence requires a concrete active Vault before resolving or reading paths, and its table-page seam is narrowed locally. Notebook evidence wrappers return their typed untrusted-content strings directly across search, exact-read, and whole-analysis operations. Built-in catalog registration keeps tool and skill descriptor variables separate, so static validation cannot carry a tool type into the subsequent skill loop; registration order and resulting catalog revision remain stable.

The runtime dispatcher now wakes the durable queue on application startup, so Reader work is recovered without a status request. Brain FTS updates are incremental and carry an explicit stale marker. Approved generated tools are loaded as subprocess-backed proxies with resource limits; descriptor JSON schemas are checked before and after execution, with optional reviewed compensators for partial failures. A metadata-only replay endpoint exposes bounded plan, error, timing, and verification events by trace id. Ambiguous requests stop at the semantic interpreter and ask for the missing subject in the request language instead of guessing a capability.

Verification uses the deterministic universal-turn corpus, focused phase-two tests, the full backend/tests suite and the documentation gate.

Local diagnostic span contracts

agent_observability.py accepts arbitrary attribute values and a mutable context holder. Its produced SpanRecord maps string keys to SpanValue primitives: strings, integers, floats and booleans. The contract is not a rigid event schema: allowed attributes can override status and duration. Typing preserves the existing value conversions, exception behavior and shared record identity.

The service examines the first 32 input entries before filtering by SAFE_KEYS. Strings are whitespace-normalized and limited to 240 characters; booleans and numeric values retain their existing representation. Unknown keys are dropped. Filtering by name is not content redaction: never hide private content under an allowed provider, model or status key.

The in-memory buffer holds at most 2,000 spans; a query returns at most 200 and shares the stored dictionaries. This is not a size or retention cap on the append-only agent_spans.jsonl file. An OSError during append does not block the operation or discard the in-memory record; other exceptions retain their normal propagation. Context-manager errors record the exception class, not its message.

Tests use disposable logs, controlled clocks and owned threads. The real policy wrapper is exercised with an inert model to verify response/exception identity and absence of synthetic prompt/error content in diagnostics. No provider call or real user log is required for these checks.

Resource catalogue and personalisation

Tool labels are keyed by exact operation identity; different operations no longer collapse to a generic verb and domain. Localised descriptions have an exact-key fallback to the original catalogue text. Executable instructions always show the actual stored content. Technical identifiers and schemas are available in expandable details; tool selection includes descriptions, origin, effects, availability and search filters.

Bundled skills remain immutable. Personalise opens an editable draft, with no write until Save. The server verifies the source revision and stores source identity, version, original instructions and tool selection in derived_from. Subsequent edits preserve this provenance, and catalogue updates are compared without overwriting the personal version.

Applying a personal skill to selected agents and automations is explicit. Assignments use freshly read revisions and retain required skills. Targets receive the new skill before selected automations are updated; successful partial changes are preserved and errors are reported. An original still used by an unselected automation remains assigned. Cancelling a draft changes neither the catalogue nor assignments.

Model comparison and verified parameter counts

The comparison shows the model and its multi-role assessment first, then estimated monthly cost and model maker, followed by intelligence, context, input/output prices, modes, parameter counts, speed, latency and specialist scores. Compact headings retain units and full tooltips; filters align with their fields, mode menus close on outside pointer input, and monthly token inputs use grouped thousands. The footer remains clear of the horizontal scrollbar.

Parameter counts are expressed in billions, distinguishing total and active MoE parameters. Filters support verified/undisclosed/pending status and total-size bounds. Selected modes use explicit AND (default) or OR matching. Static reviewed metadata remains available when the server does not provide enriched data.

backend/services/model_parameters.py enriches comparison responses from a local cache without network requests during rendering. The refresh_model_parameters task appears once in the control-center scheduler, enabled every 1440 minutes and gated by ai-platform. Each run checks at most 40 distinct model identities with a 120-second budget checked between models; request timeouts bound individual source calls. A persistent cursor resumes subsequent batches.

Only allowlisted official Hugging Face organizations, unambiguous model identities and explicit parameter fields are accepted. Verified entries retain source and check date. Unmatched or unavailable sources preserve earlier verified values; absence never automatically becomes “not published”. Unsupported and ambiguous models remain pending manual review. Cache replacement is atomic. Tests cover parsing, identity ambiguity, failed-source preservation, resumable batches, scheduler reconciliation, remote metadata and filter interactions.

Monetary columns, the maximum input-price filter and the monthly spending cap use the configured currency. Comparison prices and ledger spending originate in USD and use the supplied exchange rate for conversion before filtering or budget checks. The incomplete-model filter uses the shared application switch.

Application tool coverage

The September 2026 audit adds 29 assignable tools, reusing canonical feature services and their validation. Four domain skills group the new notebook, literature, media and activity tools; five planning tools extend the existing planning skill. These additions do not grant skills to existing agents.

Application area	Agent and skill coverage
Vault, tables, tags, comments, links and trash	Existing first-party tools cover discovery, reading and governed mutations.
Mail, contacts and calendar	Existing account-scoped tools cover reading and actions, including confirmations for external changes.
Reader and analysis jobs	Existing tools cover feeds, extraction, analysis, progress, cancellation and resumption.
Notebooks	10 new tools list/read notebooks and sources, search a fixed revision, read cited evidence, create private notebooks, add Resources, rename, refresh and cancel indexing. Attached-context tools remain constrained to their selected notebook sources.
Academic discovery and Resources	8 new tools list sources/searches, start a bounded search, read results, import one stored result with deduplication and inspect systematic reviews. Ordinary Resources records remain accessible through existing table tools.
Gallery	3 new tools list roots, search by name/type/tags and edit a file's tags and description. They do not edit file contents or expose native file pickers.
Control center	3 new tools inspect the user's automations and run results, plus system schedules in the personal workspace. They do not approve actions or create schedules.
Planning	5 new tools list baselines and create/update work calendars, resources and assignments, or delete an exact entity with confirmation and dependency checks. Existing schedule, allocation, variance, worklog and recurrence tools remain available.
Brain, memory, social publishing, translation and Notion	Existing built-in/plugin contributions remain the supported entry points.
Meetings, documents and graph	Existing internal-source readers, page/PDF tools and link operations expose recorded information. Live capture, native device access and graph layout stay in the interface.

The adapters require the server-bound user, workspace, role and active Vault; missing or mismatched context fails closed. Notebook ownership and revision checks remain authoritative. Reads require viewer access; writes require editor access and the normal runtime confirmation policy. Plugin availability is rechecked both when resolving skills and when executing tools. Disabled plugins leave catalogue entries visible but unavailable, including in custom skills.

Academic queries require explicit enabled, available source IDs and never fall back to searching every source. Source listings omit transport configuration and credentials. Import and review inspection currently require the personal primary Vault because their canonical services resolve Resources there. Other Vaults are rejected before access rather than silently redirected. Search and indexing responses report queued/running state; completion must be checked separately.

Names and actionable descriptions are provided in Catalan, English, Spanish and French. Administrators can compose custom skills from individual tools or assign the domain skills to agents. Credentials, permission grants, approval decisions, plugin installation and device access intentionally remain outside this tool expansion. No external searches or provider calls are made by the regression tests.

Principal assistant and optional profiles

Assigned skill names link to their expanded catalogue entries. Opening a skill preserves the assistant editor and its unsaved form values; returning to the Assistant tab resumes the same draft. Following the link does not toggle the skill assignment. Assignments use the shared accessible switches; required skills remain disabled, while unavailable assignments can still be removed.

Concurrent catalog readers wait for built-in plugin registration to finish. Recursive reads on the registering thread remain permitted to avoid import cycles; other threads cannot cache a partial catalog without Brain skills.

Conversation learning and editable memory

The private chat learning panel groups project instructions, selected sources and result references. Explicit requests such as “Remember that…” create traceable memories; quoted text and ambiguous references do not. Memories are isolated by vault, assistant and user, with additional project or skill scopes. Settings → AI → Memory supports search, filters, editing, activation, expiry and deletion. Updates reject stale revisions. Deleting a project unlinks its sessions and disables its scoped memories.

Conversation-to-skill extraction uses the saved private transcript and the selected assistant’s configured model. The user reviews the procedure, acceptance criteria, synthetic examples and text templates before saving to the existing skill catalog. Assignment remains an explicit administrator action. A second-case trial makes no tool calls: a separate model review reports evidence for each criterion, and the user decides whether to keep the example. It does not certify external actions or factual correctness.

Portable gnosi-skill-v1 JSON packages include instructions, tool dependencies, criteria, examples and text resources. Import validates size and resource names before review; it never automatically saves or assigns a skill. Export excludes personal memories and conversation history. Runtime instructions include the saved criteria and resources without expanding tool permissions. The additive personal_memory_0002 migration preserves existing memories and creates private project/session bindings.

Validation: backend/tests/test_agent_learning.py covers capture, ownership, scopes, expiry, stale revisions, package boundaries and trial failures. Frontend tests cover read-only memory management, scope-preserving changes, learning intent and replay-safe acknowledgements.

Contextual source reading

The source button and chat use the same durable processing job and the assigned plugin.llm-wiki.process-source skill. The job freezes the selected profile, model and effective instructions. A missing skill or disabled profile fails explicitly. The skill owns interpretation, attribution, evidence requests and review; the application enforces budgets, citations, persistence and indexes.

Reading follows structural fragments with neighbouring context, section maps and a hierarchical global map. Extraction and review can request distant original passages. Every primary fragment is accounted for, and proposed notes are reviewed against a joint overview before writing. Coverage and exact quotations establish provenance, not guaranteed semantic correctness. Checkpoints are reused only when their source and execution inputs match; legacy unreviewed write plans are invalidated. Progress and reading observations appear in the processing dialog.

Instruction language

Skill instructions are saved and executed exactly as authored, in any language. The catalogue displays the original text. Translate externally if needed and review the text before pasting it into the editor.

Settings show the latest personal version and place its assignments inside its card. Restore original requires confirmation and restores the original instructions, tools and activation before autosaving. Validate checks the definition and tool availability; it does not execute the skill or assess the quality of its output.

Principal Agent execution

Functional AI uses a shared executor with explicit profiles. Plugin buttons and schedules resolve the plugin profile; conversations use their selected profile. Skills, scoped memory, usage accounting, bounded format repair and phase checkpoints remain shared.

Activity exposes scoped execution IDs, cancellation and supported resumptions. The versioned migration backs up configuration, retires only the managed Brain profile, preserves personal profiles and moves Knowledge-specific instructions into a companion skill. Knowledge URLs and the historical routes share handlers and permissions; Notion remains optional.

Profiles and conversations

Create profiles under Additional profiles (advanced). In chat, open the selector at the assistant name and choose the Conversation profile. The change applies to subsequent requests and preserves history. Each conversation remembers its profile. Use as default in Settings selects the profile for new conversations; it does not change existing chats.

Each profile has exactly one LLM. To use another model, choose another profile or edit the profile model. There is no automatic model selection or fallback to alternative models. If a profile is deleted or its model becomes unavailable, choose another profile in chat. To delete the default profile, first set another default. Disable the AI plugin to turn off AI.

Conversation checkpoint ownership remains in agent_id and session_id. The optional profile_id selects the execution profile, and the browser persists it as profileId per conversation. Switching profiles leaves messages, attachments, stream recovery and rewind attached to the same checkpoint. Server-owned confirmation arguments retain the original execution profile. New conversations use the current default; scheduled plugin skills use their plugin profile. A missing or disabled selected profile fails explicitly.

Plugin profiles

Each AI plugin declares an editable profile and the skills its actions use. Settings → Plugins → AI → Assistants shows one list of personal and plugin profiles, with one primary profile selected on its card. An explicitly selected, enabled plugin profile can be primary while preserving plugin ownership and skill assignments. Existing conversations and plugin actions retain their own profiles. Disabled, suspended or retired profiles fail explicitly when selected as primary. Edit the single model, instructions, sources and skill assignments there. Initial profiles copy only the current default model; plugin updates preserve user edits. Disabling a plugin suspends its profile without deleting settings. A missing model or required skill fails explicitly instead of falling back to the personal default. New standalone actions and scheduled plugin skills resolve the plugin profile; existing jobs retain their frozen snapshot. A manually selected conversation profile still governs that conversation.

Indicative score — weighted_catalog_v1

Guidance, not certification: at least 60/100 and 60% data coverage, with role-specific requirements. Intelligence, coding and agentic benchmarks are ranked within the current catalog; context and speed saturate at 200,000 tokens and 100 tokens/s. Latency and price use 1/(1+x/2). Price uses a fixed mix of 4 input tokens per output token, not actual task cost. Context does not demonstrate citation fidelity, Catalan quality or reliability.

Role weights are defined in backend/services/model_role_suitability.py. Benchmarks use tie-aware relative ranks in the current unfiltered feed (a singleton receives 0.5); they are not absolute quality probabilities. Required evidence gates are intelligence/agentic/tools for director, intelligence/tools for allrounder, intelligence/context for documentalist (minimum 100k), intelligence for expert, intelligence/tools-or-structured for administrative, and text/price/speed for worker. Unknown inputs are excluded from normalization but reduce coverage; absent requirements prevent a recommendation. Explicit tool limitations override scores. Parameter count is not treated as a proxy for capability. The legacy profile is retained only for older consumers. Catalog refresh recalculates assessments on cached feeds as well as fresh responses.

The Use column shows only the selected role and its percentage; sorting compares that score with unknown values last. Estimated cost and Model maker follow it. Without a role filter, Use sorts by each model’s highest available score.

The comparison’s Role and strategy tests panel lets users select enabled agents and explicitly authorize each run with real usage. Role suites use 2–3 synthetic cases with deterministic validators. Strategy comparison applies the same three cases to an all-rounder, an always-on director and a director with direct routes; these include two known routes and conflicting-source resolution with dependencies. It compares valid contracts, calls, avoidable interventions and cost; missing values do not become zero. This isolated laboratory reuses economic selection without business tools. It does not comprehensively certify language, long-context retrieval or real tool use.

Each result records version, date, model, provider and per-case checks within its original user and Vault. Assessments with sufficient catalog evidence combine 50% catalog and 50% synthetic results; broader limitations and evidence gaps stay visible. Refresh comparison after reviewing results. The global cap is 24 calls, each capped at 512 output tokens; the three-strategy comparison makes 17 calls. These tests retain metadata-only traces. Cancel from Activity. Assigned models never change.

Retention proposals show reusable skills, coverage/model differences from existing agents and completed executions. Completion does not certify every task-specific acceptance criterion. Permanent instructions start from a registered-skill template without copying the assignment; users can review them. Acceptance can also add the personal profile to the team. An existing equivalent configuration prevents a duplicate proposal. Rejection prevents repeating the same proposal.

Implementation: backend/services/agent_role_evaluations.py · backend/services/agent_team_retention.py · frontend/src/features/settings/AI/AgentEvaluationLab.tsx

For an unresolved parameter count, select Pending verification in the Parameters column. Consult the official source attempts an exact-version match against supported manufacturer model cards. An unavailable source or no match leaves the value pending. You can instead record total and active billions, or a reviewed non-disclosure, with an HTTPS source and explicit confirmation that you checked the exact model. Manually reviewed values retain their provenance and date; merely failing to find a number never establishes non-disclosure. Supplied links are not fetched by the server.

Selecting a role sorts by estimated suitability. Candidates with insufficient evidence appear only with Include incomplete enabled; searching or changing other filters does not enable that option. Compare all candidates explicitly enables incomplete candidates while preserving the role and token budget. Choosing a model does not require running evaluations.

Provider pricing is independent of the benchmark price. The selected provider controls monthly estimates, input/output price columns, price filtering and price sorting. With all providers selected, distinct provider/tariff pairs are listed by increasing monthly token cost; unknown prices appear last. Cached comparison routes are refreshed from the current catalog. Missing tariffs and unverified legacy zeros are unknown, not free. Local token fees exclude hardware and energy; estimates exclude fixed charges and taxes. Speed and role suitability remain general model data.

Model matching preserves the plus variant and does not remove size suffixes such as mini or small when looking for a provider route.

Activation rejects unknown route tariffs before enabling the provider or saving the registry; refreshing the catalog can resolve missing prices.

Provider context and capabilities are displayed per route, including input/output modalities, tool use and reasoning. Unknown declarations stay unknown, including legacy default context values. Provider filters, context sorting and combined price/context/mode filters use route data; one route must satisfy all constraints. Context sorting uses the highest known matching-provider window, with unknowns last. The general benchmark and role assessments remain model-level evidence.

Registry matching uses exact provider/model routes, never names or substrings. Active-state filtering respects the selected provider. Director and all-rounder filters exclude routes declaring no tool support. Activation retains every distinct provider/model offer and probes the selected route. Comparison edits are serialized and re-read the persisted registry before saving, preserving intervening model and budget changes. Restoring cached metrics recalculates role assessments against the restored feed.

Comparison writes include an optimistic registry revision; a stale writer receives HTTP 409 instead of overwriting another window’s changes. Explicit Refresh bypasses the benchmark and provider catalog caches, retaining fallback provenance on failure. Benchmark variants sharing an executable route remain informative views of one offer: activation applies to the shared offer, and the setup explains that it does not configure reasoning options or reproduce benchmark conditions. Unrated means no numeric role score; known limitations and below-threshold scores retain distinct labels. Compact context previews show the largest window; each price preview shows the minimum for that column, matching sorting. Sort headers expose aria-sort, filtered result counts are announced, and parameter inspection prepopulates existing evidence without reporting a saved change.

Assistant settings and team participation

One always-visible card per profile contains its configuration, the explicit primary selection, and team participation. The primary coordinates the team; other profiles independently receive assignments, request help, do both, or work alone. Changing the primary transfers the existing team state and removes the new primary from executor routes. It does not create another agent or silently enable a disabled team.

Complete participation, direct-route and temporary-policy changes save automatically. Incomplete changes remain local, explain what is missing, and never replace the last complete saved configuration. Removing the last receiver disables collaboration and request permissions. Named independent switches support multiple model, skill and route selections; empty receiver lists explain how to add recipients. Coordination is added only while enabling a team. Profile editing merges the latest team state to avoid overwriting simultaneous participation changes.

The settings reading area accepts keyboard focus. Scrolling keys work from text and standalone toggles while editable fields, selectors and composite widgets retain their own keyboard interactions.

Model recommendations and plugin lifecycle

Each visible assistant card derives an advisory model role from its principal status, built-in plugin operations, known assigned skills (including customized derivatives), team specialties and explicit task routes. The most demanding recognized role wins; unknown tasks use All-rounder guidance. This never changes the assigned route, grants a capability or treats the recommendation as a measured model score. Labels and reasons use the four UI locales.

Plugin suspension remains authoritative on the server and blocks execution. A successful lifecycle mutation invalidates configuration caches and notifies settings and chat. Settings merge only plugin lifecycle fields and newly created owned profiles, preserving local instructions and model edits. Suspended plugin profiles are hidden rather than deleted; active team membership and routes are pruned and collaboration stops when the principal or last receiver is suspended. A suspended principal produces an explicit selection prompt, without silently replacing the configured principal or existing conversations. Late refreshes after closing settings or changing vaults are discarded.

Reasoning effort

Profiles persist optional reasoning_effort. The editor discovers exact OpenRouter model choices through GET /api/ai/model-reasoning; absent metadata exposes no choices, explicit null accepts the gateway effort set, and mandatory reasoning excludes none. Metadata is cached outside the vault, with a verified Luna fallback for offline first use. Settings validation rejects unsupported choices. The default-model and workflow factories forward effort only when the selected provider/model matches the profile. Explicit OpenRouter reasoning, and Luna’s default reasoning, use stateless Responses with store=false, full history and encrypted reasoning across tool calls. Other model defaults are unchanged.

Optional team help

Team permission no longer intercepts every workflow. The factory resolves the selected profile’s own model first, including its reasoning setting, then offers request_team_help as an optional control call in chat and structured operations. Native function calling and validated JSON transport use the same contract. Ordinary work adds no routing call. A handoff must be the only tool call and must precede tool execution; format repair cannot request help. The bounded coordinator reuses the current turn input, snapshots, confirmation grants, cancellation and total-call limits. Executors cannot request nested help or route an assignment back to its requester. Member specialties are included in the planning catalog. Repair and resumption enter team handling only when a saved handoff or plan exists; otherwise they retain the original assistant. No team permissions are enabled by migration.

Read-only reasoning metadata lives in backend/domains/configuration/ai/model_metadata_routes.py; the AI settings router includes it under the unchanged /api/ai/model-reasoning path and public contract. This keeps the main router within the project source-size guardrail.

Background resource progress

Closing the processing dialog leaves a compact, nonmodal progress card in the lower-right corner. It shows the resource title, phase, fragment count and available progress, and reopens details without starting a second job. The application-level task store owns pending starts and non-overlapping polling, so both table actions and open-resource actions survive page navigation. Completed or interrupted results remain until dismissed; retry resumes saved work. The monitor resets on Vault or account changes and ignores stale responses. This frontend session state is not persisted across application reloads.

Structured operation output

OpenRouter structured operations send their output contract to the provider, with strict schema mode for detailed contracts and JSON-object mode for generic objects. Routing requires parameter support and preserves existing provider preferences and reasoning settings. Optional native tools use strict function contracts; fallback JSON tools constrain their outer envelope and validate the extracted answer locally. Other providers retain local validation. Directed source reading forwards its action schema, including the explicit action type.

Provider acceptance is not proof of compliance: local schema and domain validation remain mandatory, with the existing bounded repair attempt. A complete JSON object or array followed only by one repeated root closing delimiter can be recovered without changing any field; extra values, prose, mismatched closers and incomplete content are rejected. Citation matching, source coverage and note validation are unchanged. Structural validity does not guarantee factual accuracy or identical wording between runs.

If an optional team planner rejects the context before any model call or assignment, a structured operation can continue on its original model within the same deadline and call limit. The full request and resolved help call are retained; the declined handoff remains auditable and does not redirect resumption into the failed team phase. Permission failures, cancellation and failures after a plan exists still stop execution. Resuming interrupted resource processing from the page toolbar uses saved progress, including after an application reload, rather than forcing a new run.

Team planning and replanning validate executors, ordered dependencies and the result task before completing the planning phase or starting assignments. Domain errors participate in the canonical repair loop, with at most two planning calls within the existing total budget. A second invalid response fails the phase without executing its assignments. Completed cached plans are also validated before reuse.

Directed reading constrains each action payload, including nested notes, coverage and citations. It validates source references, complete coverage and exact quotations before accepting or caching an action, so one bounded repair keeps the original evidence and rejected answer together. Validation previews do not modify reading state. Every step carries exact chunk identifiers and primary-segment counts, and a step identity prevents an identical response from being reused across distinct iterations.

Team phases inherit the enclosing operation timeout while remaining inside its existing deadline. A delegated repair receives the original input and data alongside the rejected output and validation error, so it can check evidence rather than repairing an isolated answer.

Reading validation reports independent coverage and citation errors together, identifying note and citation positions without echoing source text. The single permitted repair can therefore correct all known inconsistencies against the original evidence, rather than discovering only the next error after each attempt. Invalid plans never advance reading state.

Reference repairs for directed reading return a schema-constrained patch for rejected notes and coverage. The original request, global memory, affected notes and original reference passages remain available. Only enumerated reference fields can change; note titles, bodies, order and unrelated fields are copied unchanged from the draft. Duplicate, missing and unauthorized patch paths fail locally. The original profile performs this repair within the reading step’s limit of three model calls and its original deadline, without further delegation. The restored action must pass the original schema and complete evidence validation before it can be cached or saved.

Before any handoff work starts, invalid or repeated help calls in a structured operation are rejected together. Their tool-call records are resolved as unexecuted, and the original assistant can answer directly using the full request within the existing repair allowance and deadline. No team assignment or mixed tool call executes. A reading step also carries the read and saved status of each listed source chunk, including after resumption, so counts cannot hide which plans remain pending.

Long-source reading retains the longer bounded timeout during later action selection, recalled-plan review and resumption, even when the current request is short. The source size determines the work allowance; input context limits, finite retry budgets, cancellation and validation are unchanged.

Each directed reading step exposes the current saved-plan review flags and note counts, alongside the action and chunk that produced its last result. These persisted progress facts take precedence over conflicting claims in the model’s working memory; the memory itself remains unchanged and carries its recorded step when available. A review flag records the reader’s declaration, not semantic correctness. Older checkpoints remain resumable. Reading steps allow at most three model calls so a JSON syntax correction can still be followed by one reference-only repair, without extending the operation deadline or permitting another delegation. A failed reference patch can use the remaining call under the same immutable patch contract and deadline; exhaustion stops the step without saving the invalid plan.

Reading-note property rules remain in the Brain plugin configuration: copy a source field, use a fixed value, infer with AI, or leave empty. The skill classifies each note only against the supplied existing labels. Every AI-configured field is explicit in the provider action schema and must appear in each note; both reading paths reject omissions, unknown fields, invented values and multiple values in a single-value field before writing. An explicit empty list remains valid when evidence supports no category. The application resolves labels and applies source/fixed mappings. Installing this correction does not reclassify existing notes. Configured Tags ignore the legacy free-form tag list, including when classification explicitly abstains or a copied source value is empty.

Exact inventories, verified trials and error outcomes

Exact field predicates preserve the requested value in property_filters; command words are not used as a free-text search. Relation values resolve within authorized destination tables by ID or unique exact title. Ambiguous titles, inaccessible targets and incomplete inventories cannot produce a partial bulk_update_rows change. Assignments validate the actual field definition and allowed options, preserving numeric zero and boolean false. This path still uses the normal confirmation and permission checks.

Learning trials retain the original criterion and its order. Each returned excerpt must occur in the supplied input or output; malformed checks and invented excerpts are rejected. Missing trial inputs remain visible alongside the result. These checks establish excerpt provenance and contract validity; they do not prove that a model's judgement is correct.

Localized chat errors retain a stable code and content_language; private exception details are not presented as the answer. An unavailable service before workflow execution ends with has_response=false and message_count=0. The UI preserves the backend's language and effective timeout. Recovery remains an explicit manual action, with no automatic retry. One producer task owns the live source throughout its lifetime so execution context and cancellation cleanup survive heartbeat events. Settings show one current personalization per original skill, chosen by the latest package modification time. Editing saves into the same package; creating a second personalization of the same source returns a conflict instead of duplicating it. Restore original asks for confirmation before replacing instructions, tools and activation; it saves into the same personal skill and preserves its assignments.

Multi-provider usage and current-month spending

Settings → Plugins → AI → Consumption reports only Gnosi usage across all configured providers, with the last seven days selected initially. Date ranges, grouping and filters cover provider, model, agent, activity, origin and model profile. Charts, totals, paginated requests and CSV export share the same filters. Model identities include both provider and model ID; an agent's total includes its calls across routes.

backend/services/ai_usage_ledger.py stores request metadata in SQLite without prompts or responses. backend/services/ai_usage_transport.py captures usage before response validation or transformation across SDK, callback and streaming transports. Each call preserves the actual route, attribution, tokens, duration, status and price snapshot; later configuration changes do not rewrite historical costs. Reported provider cost takes precedence, including explicit zero; otherwise the route tariff is used to estimate cost. Missing prices remain unknown, while local models have zero monetary token cost. Call identifiers prevent duplicate accounting, including failed attempts and partially reported streams.

backend/services/ai_usage_dashboard.py serves /api/ai/usage/dashboard, /api/ai/usage/requests and /api/ai/usage/export under the existing workspace permissions. Decimal USD amounts are converted to the Settings currency with exchange-rate provenance. Unknown, partial and estimated consumption remain distinct from zero and load errors. Existing monthly JSON totals are backed up and imported once, preserving provider, model and amount without inventing request dates or agents. They appear only in intervals covering their complete month; detailed request history begins with ledger activation.

The current-month spending control uses the same ledger and sums all providers independently of dashboard dates and filters. It shows the configured cap, spent amount and remaining budget in the Settings currency. A zero or empty cap means unlimited. Agent and team guards reject new calls at the cap only when blocking is enabled. With blocking disabled, paid models and optional model-selection requests remain eligible above the cap. Automatic, adaptive, resilient and manual routes share this policy; zero or absent caps never block a selector. Availability, token quotas, context limits and individual reading budgets still apply. backend/tests/test_ai_consumption.py covers provider separation, cost quality, streaming, idempotency, migration, currency and current-month/filter consistency; agent and team tests cover blocking on and off.

Quoted equality filters keep the literal resource title in Catalan, Spanish, English, and French, including donde and où. Explicit field assignments such as set estat to "En revisió" or définis estat sur "En revisió" use the complete verified inventory and require confirmation before writing. Negated or explanatory wording does not authorize an update. These deterministic flows do not establish model suitability.

An explicit request not to use tools is enforced for the current turn in Catalan, Spanish, English and French. It removes required context reads, authorized write tools and team help from the effective plan and model tool bindings, including directed profiles. Quoted source material does not grant this restriction. Model answers still require independent factual review.

Requests to list a table’s properties or fields read its authorized schema, including types, options and relations, without searching records. Empty tables are supported.

Bounded book reading and reference repair

Directed source reading caps each work fragment at 4,096 estimated tokens. Its input budget includes the operation envelope, repeated output schema, serialized messages and system instructions. The default action allowance grows to at least four actions per fragment plus sixteen; explicit smaller allowances remain unchanged. Splitting retains every source passage, neighboring context, cross-fragment search and recall, and the reader's persisted global memory.

Each knowledge.process-source.phase returns one action on its frozen executor. The application validates, executes and checkpoints that action before requesting another. This operation has no team-help binding or expanded team-call allowance; other operations retain optional team coordination and all operations retain centralized authorization, evidence validation and traces.

Reference repair pairs each permitted path with its field's value schema: source identifier, citations or coverage. Local validation enforces the same pairing when large path enums are omitted. Invalid patches can retry within the existing maximum of three model calls and the original deadline, retaining the original draft, evidence and permitted paths. Note titles, bodies, ordering and unrelated fields remain unchanged. Only an action passing the original schema and complete evidence validation can advance the saved plan count; compatible checkpoints preserve completed plans and reading memory on resumption.

The application now delivers the next unsaved original automatically, eliminating a model call whose only result was a read command. Explicit read, search, recall and index actions remain available. Each prompt carries at most eight nearby index entries with its offset and total; the index action retrieves other ranges. The action schema is not repeated as a second output contract inside the reading prompt.

Every saved plan includes an updated, bounded global memory covering the accumulated argument, qualifications, contradictions and cross-chunk links. Memory and plans advance only after schema and evidence validation. Legacy checkpoints with saved plans and empty memory reconstruct their synthesis from every saved note in bounded groups before continuing; original notes remain unchanged. The table-row resume sends force=false for interrupted jobs, and a previous processed date does not prevent checkpoint resumption. Explicit reprocessing of completed work still uses force=true.

On resume, interrupted historical checkpoints for the same resource are checked against the exact runtime/source identity and the most advanced compatible plan set is selected. A fresh explicit restart creates a lineage boundary that later resumes cannot cross.

Legacy global-memory reconstruction uses the global memory allowance (at most 8,000 estimated tokens and one eighth of input context), rather than the shorter passage-summary allowance. Summary requests and validation use the same estimated-token units.

Each directed reading operation reserves at most 16,384 output tokens for its single bounded result, including format and evidence repairs. Other operations retain their existing provider settings. This avoids reserving the provider default of 65,536 tokens for each passage or memory synthesis without changing checkpoint identity.

OpenRouter usage preserves its generation identifier and the original estimate separately. When the transport omits billed cost, a bounded background metadata GET retrieves generation total_cost and updates the same usage row to reported without adding calls or token counters. Missing, invalid or unavailable costs retain their estimated/unknown label; failed lookups never fabricate zero and do not interrupt the model operation. The usage dashboard, budget and CSV read the reconciled amount.

Directed reading accepts plan.memory_updates with exact old/new edits as a compatible alternative to returning all of plan.memory. Empty old appends text; a nonempty anchor must match exactly once. Unmentioned memory is retained locally. Edits are atomic: missing or ambiguous anchors, empty memory, context limits or invalid citations/coverage prevent saving the plan and advancing. Each step still receives the complete global memory. Requests no longer repeat action descriptions already present in the schema. Existing checkpoints and plans retain their identity and contents.

Book processing now defaults to a durable 0.50 USD spending limit, editable in its confirmation dialog. Each model invocation reserves a conservative amount before reaching the provider, counting serialized input, maximum output and a 10% tariff margin without caching discounts. Unknown prices or unbounded output block the request. Opaque SDK retries are disabled for budgeted calls; governed repairs and retries reserve independently. Reservations remain held when a request fails or only an estimated cost is available. Reported transport costs or matching OpenRouter generation metadata settle them atomically. A pause preserves checkpoint progress; a resume reuses the budget and accumulated consumption. Explicitly increasing the limit requires another process request. For old checkpoints without a budget, the new limit covers remaining work and excludes historical spending.

A read-only preflight estimates the complete planned processing before starting: original passages, repeated instructions and schemas, global memory, legacy memory reconstruction, notes, final review and a bounded repair allowance. It reports the selected route, exact compatible checkpoint count, planned calls and conservative token bounds. These estimates are not a fixed invoice: additional searches, larger notes and changed provider tariffs can affect consumption. A start carrying its preflight identifier rechecks source, runtime, price, batch size and saved progress; a stale estimate cannot start a paid job.

Automatic delivery groups up to four existing fragments, reducing repeated model calls without changing fragment identity. Context limits can reduce the group size. Each batch returns a separate plan for every delivered fragment and one global memory update. All identifiers, classifications, complete coverage and literal citations are validated before committing any plan. Reference-only repair changes only the failed plan's permitted reference fields; other plans and all note bodies remain intact. Explicit single-fragment reading, search and recall remain available. The offline 191-fragment regression resumes from 166 original plans with seven batches and one final action while preserving those original plans; it does not establish semantic quality or live billing for a real book.

The preflight also reports previously saved fragments that are incompatible with the current source or processing settings. Both dialogs and starts carrying an estimate identifier block that resume, keeping the checkpoints intact instead of silently paying to read the book again. Explicit fresh processing remains distinct from resumption.

Bot-function checks and reusable evidence

The bot selector derives required functions from assigned and required skills, canonical skill ancestry, operation bindings and explicit team routes. Unknown personal skills remain unclassified. The decision view reads saved evidence without provider calls; exact-route capabilities, prices and editable catalogue floors remain eligibility constraints. Fully checked and reviewed work samples take priority, then execution cost. Catalogue scores are general references rather than measured task accuracy.

Inactive candidates expose Set up to test, opening configuration for their exact provider route. Once activated, the test panel opens automatically with spending-limit and authorization guidance. Active candidates expose Test model. Neither opening the panel nor activation runs the work samples or assigns the model to the bot. The default suite contains original work samples for all twelve functions: mail batches, invoice extraction, an essay with a revised thesis and conflicting evidence, retrieval, code diagnosis, dependency planning, grounded analysis, translation with protected elements, writing, calendar changes, bibliographic screening and meeting synthesis. Users can inspect the source, task and expected data before spending. These are representative authored cases, not private user documents or a production bot run. The legacy basic suite remains available through the API. Neither suite executes business tools or arbitrary generated code, and neither proves whole-book comprehension.

Explicit authorization and a positive budget (default 0.05 USD, converted to the configured currency, maximum 1 USD) are required. The preview reserves a conservative maximum for missing cases. Work samples use default reasoning and at most 1024 output tokens; basic checks retain 512. The audited transport, durable reservations and no automatic SDK retries remain in effect. Results are saved after every case with the deliverable, automatic verdict, original date, latency and reported/estimated/unknown cost. Transport errors, cancellation, unknown charges and truncated output stop further calls without treating an inconclusive result as poor quality.

Automatic checks verify the specified factual and structural contract, not prose quality. Open-ended work requires human acceptance or rejection after reviewing fidelity, coverage, clarity and usefulness against the source. Review comments and dates are saved in the same scoped report without model calls. A pending review cannot count as complete evidence. Rejection excludes the route for the relevant functions. Human acceptance cannot override failed factual checks. Review requires owner/admin access and cannot modify another user's evidence or an actively running report.

Reuse requires the same user, workspace, vault, exact provider/model, suite version and inference mode. The work-suite version hashes prompts, expected data and review requirements, so changed test sets cannot borrow old evidence. Results remain stored and reusable without automatic paid retests. After 30 days, successful evidence no longer earns current checked status or recommendation priority; the age threshold is an advisory policy, not a measurement of validity. Original dates are retained across reuse. Providers can silently revise a model; the warning invites an explicit retest when that matters. Only missing cases run unless the user requests repetition. Shared results and human reviews are reusable across bots with matching functions. Checks and reviews never assign or activate models. Concurrent checks of the same route are rejected.

GET  /api/agent/runs/task-evaluation-suite
GET  /api/agent/runs/task-evaluations
POST /api/agent/runs/task-evaluations/preview
POST /api/agent/runs/task-evaluations
POST /api/agent/runs/task-evaluations/{report_id}/review
version: hash of work samples; bot_tasks_v1 for basic
mode: work_default_1024; diagnostic_default_512 for basic
request: agent_id, provider, model, tasks, budget_usd, authorize_model_calls, retest, suite
storage: agent_team_artifacts / task_evaluation

Shared public work-sample bank

The public bank lives in ismigar/ismigar.github.io, under data/model-evaluations/, and is served at https://gnosi.temenosismael.org/data/model-evaluations/index.json after the site PR is merged. It starts empty. Gnosi reads it without credentials, cookies, private context or model calls; there is no automatic upload or integration with the private growth-dashboard Worker. The app validates the complete authored suite, strict allowlisted fields, content hashes, bounded inference parameters, dates and automatic verdicts again before using a public record. HTTP redirects and environment proxies are disabled, the response/cache is bounded to 4 MB, refreshes are throttled and a validated disk copy supports offline use. An unavailable or invalid bank leaves local tests usable.

Reuse compares exact model/provider, work-suite version, mode, bounded client/validator revisions, canonical endpoint, LangChain OpenAI SDK version, provider-default reasoning knobs and output limit. The initial transports are standard OpenRouter, OpenAI, DeepSeek and Mistral endpoints; custom endpoints and legacy calls without recorded parameters stay local. Provider identifies the configured gateway, not a cryptographically verified upstream deployment. For each case, at least two different GitHub contributors need concordant latest observations, reviewed through repository PR attestations. Open-ended cases additionally need accepted human reviews and maintainer approval. One person's repeated observations do not provide independent agreement. Disagreement and inconclusive attempts cause local checks, not automatic quality exclusions. Local evidence takes priority. Shared provenance and observation counts remain visible, and users can disable reuse or repeat cases explicitly. Ages are flagged without expiry; the representative shared case is the oldest participating latest observation, so newer participation does not hide older supporting evidence.

Public summaries separate automatic passes, failures and inconclusive incidents, and show cost sources plus median/range costs and latency. They do not replace current tariff estimates, establish a user's quota, prove whole-book comprehension or certify production-tool success. Stored shared copies are reconsulted against the current bank rather than counted as new local executions; withdrawal and loss of agreement invalidate reuse when an updated bank is available.

Export is administrator/owner scoped and read-only: inspect an allowlisted export, download it locally, then choose whether to contribute it through a PR. Only new results from the original public samples with recorded parameters are exportable. The export omits agent/run identities, vault paths, credentials, review notes, personal sources and reused cases. It includes public outputs, model/provider/settings, timestamps, costs with their source and verdicts; the UI requires inspection and explains that publication makes those fields public. Maintainers associate the contribution with its PR author, review open-ended cases, run the portable validator and regenerate the static index. The app performs no model call or external publication during export.

Bounded reading reasoning and truncated-response costs

Source-reading phases keep their existing 16,384-token output cap. When the bot has no explicit reasoning effort, they request low effort only if the exact OpenRouter model declares support. Explicit profile or transport choices take priority; unknown capabilities and other providers are unchanged. The binding preserves the selected route, output schema and routing requirements, and appears in the model-request trace. This changes no saved bot setting and does not invalidate validated fragment plans. It reduces the risk of spending the entire completion on reasoning, but does not guarantee completion within the book budget.

If structured response parsing raises an output-length error, accounting reads usage directly from the exception’s completion before recording the failed call. Reported cost settles that call’s reservation, including billed reasoning tokens; missing cost stays unknown and reserved. No hidden retry or budget increase is added. The resource dialog distinguishes reasoning exhaustion from a truncated answer, preserves progress, and keeps technical details collapsible and wrapped. Historical reservations without billing evidence are not silently released.

Batch-wide reference repair

Before evidence validation, the reader can restore an omitted segment digest only when the exact origin-and-sequence prefix resolves unambiguously among the supplied, already-read segments. It does not guess foreign identifiers, replace a wrong digest or alter quotations, note text, classification or global memory. Canonical references are persisted and their normalization count is traced. Coverage, exact quote matching and primary attribution still run unchanged; this transport correction preserves existing checkpoint identities.

A batch now collects reference failures from every plan before requesting its bounded repair. The patch contract names each affected plan and field; the local restorer enforces path membership and per-plan types even when a large provider grammar omits enums. Every rejected plan includes its primary originals, including when both identifier and quote are wrong. Valid notes and shared memory stay immutable, and the batch commits only after all plans validate. Repairs keep the existing three-call allowance, deadline and budget; they add no automatic restart or unbounded retry. The resource dialog summarizes a rejected evidence plan in the configured language and puts diagnostics behind the technical-details disclosure.

When a structurally complete reading action has invalid classification values, the repair collector checks its citations and coverage in the same pass. A private probe uses empty values only to expose further errors; it is never saved or returned. One patch must provide every rejected classification field and reference correction. Valid classifications, note text, order and global memory remain unchanged, and the complete restored action passes the original schema and evidence gates. Incomplete JSON or unrelated structural errors still use the bounded full-response repair. A syntax correction followed by classification and citation errors can therefore fit the same three-call limit without increasing the deadline or spending cap.

The same bounded repair also collects invalid or misplaced global-memory updates. A batch may propose memory edits inside individual plans even though the contract requires one shared update; those edits remain visible in the rejected draft and require an explicit consolidated memory patch. A private probe retains the current memory only to expose all classification, coverage and citation failures together. It is never persisted. A restored memory patch must choose a complete synthesis or exact sequential edits, never both; missing or ambiguous replacement anchors remain errors. Other notes and valid fields remain immutable. The original call limit, spending cap, deadline and checkpoint identity are unchanged. The dialog localizes a failed memory edit and retains technical diagnostics in its disclosure.

Bounded delivery recovery and measured waiting time

When the provider truncates an automatically delivered batch after emitting answer tokens, the reader halves the remaining delivery, at most from four to two to one. Reasoning-only exhaustion, explicit reads, invalid evidence and budget errors do not trigger this recovery. A single-fragment failure stops. The reduced maximum is checkpointed and respected after a restart, including when resuming a previous output-limit failure. Preflight uses the same reduced maximum and explains it. Every attempted call still reserves against the original durable budget; no spending cap is raised. The immutable fragments, exact citations, saved plans and global memory remain unchanged. This adapts batch delivery rather than changing fragment identities or truncating notes. Offline tests cover recovery, restart, manual reduction, zero-plan preflight, full evidence preservation and a budget stop during recovery; they do not prove a live book will finish.

Structured-output repair diagnostics name the failing path and constraint without resending the entire JSON schema or rejected document inside the diagnostic. For reader actions, diagnostics validate the arguments of the chosen action, avoiding a misleading error from another alternative. Automatic-delivery instructions explicitly distinguish the already supplied passages from subsequent reads. Validation, evidence checks and the bounded repair allowance are retained.

Model recommendations show recent measured sample time and, for book duties, available real reading-step durations and failures on the exact provider/model route. Reader-step time includes repairs, does not mix parent jobs or other operations, and is not extrapolated into a whole-book duration because batch sizes and contexts differ. Only the recent activity returned by the API is represented. Among candidates that passed all selected task checks, the balanced option minimizes estimated cost multiplied by average sample time only when every checked candidate has positive, recent measurements for the same current suite, mode and requested cases. Otherwise it keeps cost ordering and explicitly marks unavailable timings. The cheapest option remains ordered by cost. Older quality evidence remains reusable; it is not treated as current speed evidence. These measurements are indicative and may come from shared samples; workload and provider load can change.

Application-directed source reading

The current source-processing path uses semantic_reading.py. Gnosi schedules a source-wide overview, ordered interpretation, a joint map of every proposed note, and source-grounded review before persistence. The model no longer chooses workflow actions, copies source identifiers or rewrites working memory. The action-directed reader and its contracts described elsewhere on this page are legacy compatibility paths, not the production reader.

The original plugin.llm-wiki.process-source skill is written in English and owns intellectual methodology: substantive atomic reading notes, attribution, exact evidence, qualifications, classification and supported connections with existing knowledge. The Knowledge bot owns purpose and user criteria. Code owns batching, source identities, progress, checkpoints, retrieval, budget, validation, source sections and storage. Sources remain untrusted data. Permanent notes still require human approval.

Each interpretation returns ordered passage results with ideas, exact quotations and semantic properties. The application binds these to the already-known primary sources and configured fields. A quote must match the original exactly; ambiguous contextual quotations and notes without a primary quotation fail validation. Every primary passage has notes or an omission reason. Partial repair requests only invalid passage interpretations and preserves valid passages and observations. Each governed phase permits two model calls, retains its deadline and spending reservations, and cannot delegate.

Larger source windows contribute to a hierarchical argument map, including the ending. Local neighbours and lexical retrieval across all original passages supply context during interpretation. Prior notes, themes, questions and contradictions are stored as structured checkpoint data, and pertinent entries are selected for later reading. Every note and all observations contribute to the joint map. Review examines every proposed note with original evidence and both maps, returning sparse corrections; unchanged notes are retained locally. Exact citations establish provenance, not semantic correctness. Lexical retrieval and generated maps may miss nuance and are not a substitute for human judgment.

semantic-state checkpoints retain maps, validated plans, observations and completed reviews. Reuse requires matching execution policy, original chunks, configured fields, title and language. When only the knowledge index changes, paid source-grounded drafts and maps remain reusable, but every note must be reviewed again with current connection candidates; previous reviews cannot certify those drafts. Legacy action checkpoints remain preserved but cannot be silently imported after the skill change; preflight exposes their incompatibility and requires explicit reprocessing. No update starts a book job, changes its model or increases its spending limit. Preflight includes overview, interpretation, joint synthesis and review; note volume and repair needs are estimates, while the existing durable budget gates every actual call.

Offline regression cases cover complete long-source delivery, joint review, attribution corrections, exact quotation binding, configured property types, partial repair, output-driven batch reduction, checkpoint reuse and interruption. They validate orchestration and invariants, not a live model's understanding of a whole book.

Argument maps and joint-note syntheses are requested as bounded plain text, with no JSON output schema. Gnosi serializes them into checkpoints. Empty answers, JSON envelopes, code fences and maps exceeding reserved context capacity are rejected within the existing two-call allowance. Interpretation and review retain their strict structured contracts and evidence validation. This avoids paying to repair JSON punctuation around prose; it does not certify the map’s semantic quality.

Complete source maps that exceed the 2,000-token target remain preserved in checkpoints. The recurring global argument map and joint-note map must fit at most 2,000 estimated tokens (less for small contexts). Each contraction returns one shorter complete synthesis from all its inputs and permits at most two governed calls. A complete oversized draft is saved and compressed using only that draft; a truncated synthesis retries once from complete input maps and never branches into more synthesis windows. A second failure stops with progress retained. Versioned contraction checkpoints include frozen execution policy, title, language and exact material; completed groups survive interruption. Preflight prices the actual saved source maps for the first contraction and only bounded navigation maps in recurring context. Originals, exact quotations, attribution checks and full note review remain authoritative; a shorter map is not proof of semantic completeness.

The shorter target requested on the second contraction attempt leaves headroom; acceptance still uses the unchanged map capacity. A complete answer between that target and the capacity is valid. Resuming also promotes compatible complete drafts already within capacity into result checkpoints without another model call, including drafts saved by older stricter retries. Empty, incomplete, incompatible or still oversized drafts cannot bypass validation. No source text is cut, and the spending cap and two-call allowance remain unchanged.

Interpretation and joint review select local quote IDs from numbered spans covering the complete supplied originals, beginning with the first model response. Gnosi restores the exact text before the unchanged schema, primary-passage and citation checks; a syntax correction uses the same choices. Input budgeting includes the numbered catalog, and whitespace stays attached to original evidence. Interpretation repairs include per-note diagnostics and retain valid passages and semantic memory. The operation cache keeps its validated selection contract while reading checkpoints retain literal citations, so compatible completed work remains reusable. Context-only, ambiguous, blank or invented evidence remains invalid. The two-call allowance and spending limit are unchanged. Citation failures use the existing localized evidence message, with technical details retained.

Interpretations use named passage_N entries; review uses note_N entries with a replacement or null to retain the original. Each entry requires nonempty primary_quote_ids enumerated exclusively from its own source. Additional context_quote_ids cannot replace primary evidence. Partial repairs enforce the same constraints. Shared field definitions bound schema growth. Local validation rejects shifted passages and wrong-source choices before binding; saved reading plans remain compatible.

Reading identity version 2 canonicalizes mapping keys and knowledge-index order. Knowledge and relation catalog limits are applied after stable sorting, so a reload cannot select a different arbitrary subset. Identity components are recorded for diagnosis; source order, text, classifications and execution policy remain significant. Complete prose maps have their own identity based on the exact material, title, language and frozen execution policy, independent of classification and knowledge context. They can be reused even when draft notes need regeneration. Older map caches require explicit evidence of a complete provider response before migration.

Prose-map operations reserve at most 8,192 output tokens. Native output-limit metadata rejects incomplete text before it can be saved as a complete map or sent through a full-source format repair. Only original source windows and joint-note input windows with answer text may split; complete siblings and split decisions survive interruption. Hierarchical synthesis never splits truncated output and must contract within a finite number of levels. Overview progress advances as source windows complete; these maps are distinct from extracted note fragments.

The resource-processing dialog discovers a durable running or interrupted job on opening before enabling a paid start. Opening a source page restores interrupted work to the existing corner monitor, including after reload, rather than implying successful completion. Restoring status does not start a job, emit a success notification or mark notes as created. While an idle confirmation remains open it checks for externally started work and attaches that job without another start. The shared task store owns polling after closing or navigating; discovery is abortable, does not overlap requests and cannot overwrite a pending local start. Completed historical jobs do not block explicit new processing. The dialog shows phase, percentage and localized connection/synthesis failures, with technical details available. Notes are persisted only after source interpretation and grounded review complete.

During interpretation, recurring auxiliary context is bounded independently of the model window: retrieved originals use at most 8,000 estimated tokens, related notes 6,000, and observations 4,000, with proportionally smaller bounds on small models. Complete primary passages, neighbours, global maps and exact citation validation remain available. Structured semantic requests keep the schema in the operation/provider contract without another copy inside the reading input; partial repairs use the same transport. A substantial JSON answer ending before completion causes the reader to halve only the unsaved batch instead of requesting a full rewrite. Delivery can shrink from four fragments to two and then one; single-fragment failures stop. Each new attempt still reserves its own cost within the original book budget. Validated plans, source identities, complete maps and checkpoint lineage remain reusable. Smaller prompts do not establish a guaranteed provider latency. Link navigation is limited to the eight highest-ranked existing notes within 4,000 estimated tokens, without modifying the stored knowledge index.

Independent source-grounded review groups now run at most two at a time through semantic_review_execution.py. Interpretation remains ordered. Each group retains the same complete original evidence, global map, joint note map, schema and validation as serial execution. Separate copied execution contexts inherit the authenticated vault, parent cancellation and the same atomic book-budget reservations. A single coordinator saves every successful group, including when its peer fails, and applies corrections in source order. Failed oversized groups shrink without repeating saved neighbouring groups. A reservation blocked by its peer can be retried once that wave has made progress; a wave without progress pauses. Structured transport requests compact JSON formatting only, preserving string contents, notes, explanations, qualifications and evidence choices. Canonical checkpoint identities stay compatible; pretty-printed responses remain valid. Offline serial/parallel and recorded-response replays establish context and data equivalence, not identical stochastic model judgments or a promised whole-book speedup.

Review quote selections retain application-generated source fingerprints alongside the exact copied text. Binding checks both that fingerprint and literal containment against the supplied originals, so repeated wording cannot silently change attribution. The shared review catalog includes every note’s primary and supporting passages; selected cross-note evidence remains available during validation and is saved with the reviewed plan. Legacy checkpoints retain their original per-note evidence scope. Unknown sources, rewritten text, misaligned selections and replacements without their own primary evidence still fail; no quote or substantive correction is dropped to complete a review.

Review recovery also recognizes a JSON object cut off inside a string or at the end of input, even when a provider reports a normal stop and returns only a short prefix. It halves the unfinished group within the same budget instead of buying another full rewrite; a single-note failure stops. Older interrupted reviews with that exact parser error resume at a smaller saved size. Splits stop at already validated range boundaries, including odd group sizes, so a successful neighbouring group is never partially reviewed again. No incomplete response is accepted or completed locally.

Reading quality acceptance

A completed provider response is not a quality verdict. Joint review includes full adjacent original passages across page boundaries and explicit prose diagnostics. Unresolved internal numeric links, undefined footnotes and unsupported mixed-script corruption reject the complete reviewed batch, including unchanged notes. Review responses explicitly list unresolved defects; a nonempty list stops before publication while preserving paid interpretations and maps. Earlier review checkpoints and reduced plans cannot bypass this versioned acceptance contract. These mechanical checks do not certify semantic truth.

PDF highlighting requires a complete quote match, with native character coordinates and whitespace-only layout normalization. Short quotes are supported; repeated occurrences require an identifiable original passage. Prefix-only matches are rejected, and previously managed but now unverifiable highlights are removed when the attachment is available. Image-only pages and unresolved ambiguity remain explicit failures rather than fabricated geometry. Finished jobs retaining observations display a review warning instead of an unqualified success indicator; repeated observations are displayed once.

Quality review version 2 also supplies earlier extraction observations to the reviewer. The original draft warnings remain in checkpoints and reviewed-plan history; current warnings contain the limitations still found during review. Warnings on passages without reviewable notes remain pending. The job and source manifest distinguish a completed review from acceptance: any remaining reading, extraction or citation warning keeps reviewed false and quality_status at needs_review. This does not silently erase warnings to obtain a success state.

Policy exclusions also apply during joint review. A reviewer can exclude a note with an explicit source-grounded reason when its original passage is outside the active reading policy or cannot support a substantive note. The application keeps the passage in coverage and context, records the reason, rejects invalid or repeated note positions, and retains the original draft and review checkpoint. Already published managed notes become stale while their text and manual edits are preserved. Exclusions never authorize silently dropping substantive ideas to avoid corrections. Review quality version 3 invalidates older review decisions while reusing source drafts and maps.

Quality review version 4 scopes each batch to its supplied notes while retaining the two book-wide maps as fallible navigation. The reviewer can request complete original pages or source-language searches for a specific note through evidence_requests, with at most two evidence rounds. Search results are bounded whole passages, never silently shortened originals; explicit pages either fit in full or stop the batch. Provisional corrections cannot publish notes or waive final prose, quotation or unresolved-issue checks. Each round is checkpointed and reused during same-job budget retries as well as restarts. Successful reviews retain source fingerprints for the additional originals, which are revalidated before reuse. Older review decisions are invalidated while source drafts and maps remain reusable. The repair estimate includes these optional rounds and their format repairs; every call still uses the same cumulative book limit.

Provider transport omits the unsupported array uniqueness keyword for evidence requests; canonical validation still rejects duplicate page numbers locally.

Quality review version 5 sends unresolved semantic defects through the governed output validator. The existing single corrective call receives the specific failure and can correct notes, explain a policy exclusion, or request originals. It does not gain extra format-repair attempts, and unresolved results still stop publication. Versioned phase keys prevent older accepted-but-unresolved responses from bypassing this correction boundary; original interpretations remain reusable.

OpenRouter generation metadata can remain unavailable after a response completes. The metadata-only confirmer now retries after 2, 10, 30, 120 and 300 seconds, with at most six GETs in total. Two background workers share a bounded queue of 128 outstanding confirmations; delayed retries do not occupy workers or block newer lookups, and duplicate scheduling of an outstanding call is ignored. Only a matching provider-reported total settles a reservation. Exhausted retries retain the pending cost; they never repeat model requests, clear an unknown charge or raise the book limit.

Interpretation and its bounded repairs now retain the immutable source fingerprint for every selected quote, as review already did. Restoring text must not discard an unambiguous source choice merely because the same words also occur in another paragraph. The partial-repair round trip preserves both original characters and the selected source; unsupported source substitutions and changed originals remain invalid. Older literal checkpoints stay compatible, but ambiguous context quotations without provenance still fail rather than being assigned by guesswork.

Before interpretation, each stored primary segment inherits its document label from its parent chunk. The prompt, complete evidence collection and citation binder use that same source view; document labels are not assumed to be duplicated in stored segments. The complete-reader regression exercises this handoff as well as individual quote restoration.

Quality review version 6 checks PDF citation geometry before review and before accepting each corrected batch, using shared page indexes and serialized PDFium access. Unlocatable or ambiguous quotations become precise corrective feedback while the substantive note must be preserved. Review warnings now enter the same bounded correction path as unresolved issues: attribution and qualified source uncertainty belong in the notes and assessment, while unresolved reading defects block acceptance. Prior observations from excluded passages remain in the audit checkpoint rather than resurfacing unchanged as final warnings. The existing interpretations and maps remain reusable; older reviews are repeated under the new quality boundary.

A finished write with pending quality findings is exposed as a partial, resumable job, including historical records after an application restart. Status, preflight and execution therefore reuse the same checkpoints and accumulated budget without requiring a forced restart; the persisted audit record is unchanged.

Quality review version 7 flags residual processing-boundary caveats in final note prose for source-grounded correction. This wording check is not a semantic truth classifier: it never reconstructs the source or removes qualifications automatically. Drafts remain reusable, while final review must express the supported meaning or request genuinely missing originals. Job and manifest acceptance records now carry the review version; a legacy or obsolete semantic acceptance becomes resumable without rewriting its audit record or resetting its budget.

A bounded corrective review amends its preceding proposal. Null changes retain prior corrections and exclusions, while explicit replacements can change or revert them; the merged result still passes every evidence, prose and PDF geometry check before acceptance. This prevents a sparse second response from silently restoring defective original drafts. Diagnostic note numbers retain their original positions even when another note is excluded. The correction budget and quality version remain unchanged.

Resume selection counts reviewed groups only when their quality version matches the current acceptance rules. An older completed review must not displace newer partial accepted work with the same source coverage; obsolete review counts otherwise cause avoidable paid repetition. Original maps and interpretations remain reusable under their existing identity checks.

Quality review version 8 also detects final prose that describes the available text as cut off or a supplied sentence as lacking a complete explanation. Version 7 decisions can migrate without paid repetition only after each batch passes the current full schema, evidence, prose and citation checks. A rejected cached decision is retained in the audit; only that batch is reviewed again with its failure as feedback. Older semantic review policies still require a fresh review. Persistence ignores missing registry paths when selecting an existing managed note, selects one deterministic active copy per key, and marks other copies superseded without deleting their files or personal text.

The missing-continuation check includes inconclusive-sentence wording and explicit claims that the supplied text does not contain its continuation. It still routes these findings to original-grounded review and never removes the qualification automatically.

Profile-specific reading evidence

Book candidates must declare structured output or tool calling on the exact provider route. Their authored work sample checks literal quotes and source attribution, a sentence continued in the next passage, correction of an injected foreign word, a changed thesis and conflicting voices. The short Catalan synthesis still requires human review for language, length, fidelity and coverage; fixed data checks do not certify prose quality or a complete book. Changing the fixture changes its suite version and prevents reuse of previous passes.

A profile receives current checked status only if every detected task has criteria and every criterion has a recent accepted result. Review requirements come from the suite even if a saved row omits them. Older results remain visible, and known contract failures or human rejections still exclude the affected route until superseded. No model is blacklisted by name, and infrastructure failures are not treated as model-quality failures. Opening recommendations, changing the fixtures or losing current status never runs paid tests or changes a profile’s assigned model.

Citation Markdown and source locator formatting live in backend/domains/llm_wiki/citation_rendering.py. The backend/services/llm_wiki.py facade preserves its existing helper exports, source links and timestamp formatting. Settings controller tests keep mutable HTTP fixtures separate from their persistence assertions; the suite still exercises both budget switch states and reopening.

Compact routing and continuation accounting

agent_team_context projects only routing evidence: a request excerpt capped at 6,000 characters, four role-preserving recent messages capped at 800 characters each, deduplicated capability descriptions, and a source inventory with selection counts. It excludes tool outputs, provider metadata and source bodies. The executor and recovery artifacts retain the original request, messages, grants and exact selections. Local character counts compare payload sizes; they are not token measurements.

A complete, single, read-only writing or translation task can save a scope-bound continuation artifact. A whole-request grammar recognizes narrow stylistic revisions in Catalan, English, Spanish and French. The previous response and user message must match the artifact hashes, and the current profile, catalog revision, capabilities, role and source references must match its fingerprint. New attachments, grants, goals, ambiguous assent, temporary executors, synthesis and writes require normal routing. Executor availability and skill assignments are revalidated before every reused assignment.

Continuation eligibility obtains the registered writing and translation identifiers from agent_operation_catalog.skill_id, including core.gnosi-translation-workflow. The translation regression uses the catalog identity and verifies that a subsequent style revision reuses the specialist. Synthetic routing benchmarks must validate all assigned skills against the runtime catalog before calling models.

The plan declares operation, response_kind and output_contract; capability metadata exposes application_operation. Local validation checks that the result task uses the operation’s assigned skill and prevents direct structured deliverables from bypassing an available specialist. Greetings, necessary clarifications and genuine unavailable capabilities remain possible. JSON contracts use bounded inline schemas without references or patterns.

For native OpenRouter planning, operation_input omits the duplicate prompt schema while the provider and local executor retain the complete contract. Local providers, dynamic schemas and output repairs keep the schema in their message envelope.

explicit_output_keys recognizes complete, unquoted JSON return templates at instruction boundaries. The plan must preserve those keys; unique registered output_signatures select the corresponding available operation. Quoted instructions and fenced source text cannot supply a format directive. Empty table contracts are rejected before execution, preventing an invalid plan from repairing a requested field into an empty object. Native planning presents the current request as a top-level field, with history retained as reference evidence.

CheckedTeamOutput validates the final delegated JSON before its conversation run completes. Valid output adds no model call. Invalid syntax, keys or types allow one team.repair call with the same executor, original evidence and no tools; a failed repair raises TeamOutputContractError and cannot rerun the task graph. Confirmation events remain pending rather than being interpreted as JSON deliverables. Structured results do not install text-continuation markers.

agent_team_usage reads provider-ledger calls for the scoped run tree and separates planning/replanning, execution, synthesis and repair. It includes retries, excludes job rollups and retains missing usage/cost as unknown. A team.usage trace and the chat's response details expose the breakdown. planning_calls_avoided counts skipped routing calls, never hypothetical tokens or dollars. A before/after benchmark must compare the same synthetic requests, models and output requirements, retain provider token/cost coverage, and assess output quality. No production request is duplicated for measurement.

The first team.plan call reduces the selected OpenRouter model’s declared default reasoning effort by one supported level, with a floor of low, only for an initial greeting or an already identified writing/translation operation without authorized actions or an explicit JSON contract. Ambiguous requests, structured deliverables and team.replan retain normal effort. Profiles with an explicit effort are unchanged. Unknown defaults, none, minimal and low are left as configured; the policy never raises a cheaper default. If local schema or assignment validation rejects the plan, the existing second call uses normal effort, the same snapshot, contract and diagnostic, with no tools. It keeps the original deadline and two-call allowance; a second invalid plan stops before execution. Specialist execution, synthesis, output repair and providers without declared support retain their existing behavior.

An explicit unquoted JSON format directive, including a named contract, anchors routing through the registered output signatures. Its known root keys also constrain native planning: the object contract must explicitly declare its type and a nonempty field list. Local validation still checks the exact keys, types and selected specialist; clarification remains available. Writing correction instructions preserve the original subject’s person and number when resolving agreement.

Planning removes schema titles and defaults, and omits the temporary-specialist definition when that capability is disabled. Executable constraints, property names and literal data are preserved. Array choices are checked against the fully assembled item type locally, so a scalar choice cannot contradict an object item and reach a provider as an invalid schema.

Proofreading first anchors each subject to its explicit demonstrative, pronoun or quantity before correcting agreement. It preserves number, person, negation, IDs and conditions and checks them against the original before returning the text, within the same executor call. Explicit requests to transform the reference remain part of the current task. The synthetic corpus is backend/tests/fixtures/writing_fidelity.json. compare_case_quality in backend/services/agent_team_evaluations.py requires complete per-case evidence, unchanged case definitions and every candidate check passing. A fixed case cannot offset a newly failed case; missing, unknown or untyped evidence blocks acceptance. These checks support regression evaluation and do not certify arbitrary prose semantics.

Built-in correction chats with one fully quoted source have local checks in backend/services/agent_correction_contracts.py and backend/services/agent_correction_output.py. They check paired demonstrative/pronoun person and number, protected quantities and IDs, and loss of negation. Unknown instruction forms, explicit transformations, code/JSON output and action requests use the original workflow. Personal methods and the principal are not wrapped; workflows that call tools are not replayed. Valid text needs one call. A detected violation gets at most one tool-free repair by the same frozen executor, using the original source and the remaining parent budget. Failed repair fails the run instead of publishing the incorrect text. The local checks cover explicit references and do not provide general morphological or semantic analysis.

Exact saved-title substitutions use callable Vault capabilities instead of the writing operation. The compact catalog exposes requested action tools per skill; local plan validation requires a writable task with an activated tool-bearing skill. An action cannot complete on generated prose without a successful authorized tool response or a pending confirmation.

Complete quoted substitutions in Catalan, Spanish, English and French skip the director model while retaining team execution, cancellation, revocation, usage and confirmation controls. The unique active saved view is extracted locally from the attached page, including modern gnosi-view blocks and JSON-encoded page content, without truncating its view inventory. Missing or multiple views require clarification. Inventory provenance, completeness, saved-view revision and original titles are checked before preparing all changes. Single-letter replacements preserve words and match standalone tokens or numeric phase prefixes; substitutions are simultaneous. Confirmation checks the view and file revisions again and the existing transaction preserves unrelated fields, bodies and rows.

Credential redaction uses the actual tool-result budget, preserving complete JSON in governed executions instead of silently applying the log excerpt limit. The bulk row descriptor allows bounded argument values up to 64,000 characters; other tools retain the default. Regression coverage in backend/tests/test_agent_title_replacements.py uses 748 synthetic files with a 31-row view, verifies the actual preview and confirmed writes, direct-agent scope, topic changes, stale views/titles and zero model calls. Measured local fixture latency is not a production latency guarantee.

Title actions also accept a named @page between the field and replacement verb. Mention labels are opaque: their quotation marks do not become operands. Visible structured mentions attach their IDs; a typed label resolves only to a unique exact cached title (normalizing typography and a final full stop), revalidated against the page. A named target never falls back to an unrelated active view. Embedded-view interaction publishes the selected view and host page, and navigation republishes context even when the open record is unchanged. Saved filters using this resolve against that host, whose view membership is rechecked before confirmation. A page with multiple views and no selected view clarifies locally without a model. backend/tests/test_agent_title_mentions.py exercises the HTTP chat route with no pre-granted tools, structured and typed mentions, three page-owned views, real confirmation and 31 confirmed changes among 748 synthetic rows; unrelated rows and the host page stay unchanged.

Confirmed title edits resolve the same schema title field as native page/index reads, using current names before immutable IDs and old aliases. An outdated internal title must not reject an unchanged visible Nom, Title, Título or Titre. The preview retains the field binding; confirmation rejects a changed binding before any writes. Saving updates the visible field and canonical fallback together. HTTP regressions cover distinct internal/visible titles, renamed fields, conflicting copies, actual confirmed writes and unchanged excluded rows.

Embedded context publication is stable across app rerenders: compare page/table/view IDs and labels, rather than registry or view object identities. Repeated pointer/focus events reuse the same context until it changes or another module takes ownership. A receiving-parent regression checks that publication settles, selected tabs still update and returning to an embed restores its scope.

Literal title replacements also recognize names/titles of tasks, rows and records in the current view, with the scope before or after the verb and operands, in all four languages. The grammar consumes the entire request and still requires explicit quoted replacements and a unique active view; named/other views, other fields, negations and extra actions are not silently reduced to title edits. backend/tests/test_agent_title_view_wording.py covers the HTTP boundary without pre-granted tools, real confirmations and writes over 31 of 748 synthetic records, and no model calls even when a provider is unavailable. Provider connection failures are classified as recoverable network errors with localized messages; they do not count as model-quality failures and are never retried automatically.

A title-action checkpoint now retains the exact literal request and the saved table/view/host revision. A follow-up such as Ara canvia "Fase " per "F". P.ex.: Fase 1 per F1 replaces the operands without losing their spaces; any illustrative example must agree with them. Bare assent prepares a fresh preview, never executes an old confirmation. Reuse stops at an unrelated human turn, extra attached context, another principal, or a changed view/host/filter revision. Legacy conversations recover only from a matching scoped server preview and execution trace, never assistant prose. HTTP continuation regressions include actual confirmed writes over 31 of 748 rows and zero model calls. The bulk writer reads back each visible title before reporting completion and rolls back a failed verification. The chat reconciles a missing confirmation status once and never treats HTTP success or an unknown outcome as completed.

Team confirmations are emitted as native confirmation events and checkpoint cards, so their JSON never becomes an assistant bubble. Older raw JSON is converted only when its ID matches a scoped server confirmation; duplicates collapse to one card while preserving turn metadata, user quotes and unrelated messages. A completed or partially completed Vault action invalidates the sidebar cache and broadcasts one preview invalidation per batch, refreshing mounted views without a focus change or clearing their search. Late completions never reload another active Vault. Conversation rewind and deletion acquire the existing bounded session lock; a busy session returns chat_session_busy instead of waiting indefinitely, with a localized explanation and unchanged history.

Only tool responses can supply native confirmation evidence to team aggregation or bypass structured output validation while awaiting review. Assistant and human JSON remain data and cannot place a team in an awaiting-confirmation state.

Structured title-edit interpretation

When a unique saved view is active, requests outside the literal fast path can use team.view_edit: one governed director call with a 25-second deadline, a 1,536-token output limit, and low reasoning only when supported and not explicitly configured otherwise. The parsing snapshot excludes document contents, personal memory and the full conversation. Its ViewEditDecision contains only an operation, title field, view scope, condition and bounded text transformations; model-generated code, regular expressions, IDs and wider scopes are not executable. Numerical templates preserve {n}. Non-editing requests return to ordinary routing, while invalid or ambiguous proposals stop with clarification.

A validated title_edit stays in server graph state and selects an existing Vault-capable team member. That executor resolves the complete view inventory, checks the saved view revision, computes changed titles locally and uses the existing native confirmation and verified writer. A verified continuation can reuse the program with zero further model calls; a changed view or topic cannot inherit it. Every chat input clears stale proposal state. Real-provider interpretation tests use invented data; synthetic HTTP tests also verify all affected rows, excluded rows and files remaining unchanged before confirmation.