WeKnora/internal/modelcontext
lyingbug 7115cb2a61
feat(assistant): trial runs, session grants, page links, and MCP/model/skill management (#4375)
* feat(assistant): let the assistant check MCP services and retrieval

Add a probe risk for operations that change nothing but do real work
(connecting to a service, running a retrieval). Probes use POST, run
without approval at every access level, and are capped per run.

Open three operations on top of it:
- mcp_service.test: connect with the saved settings and report why not
- mcp_service.list_tools: list what a service offers before binding it
- knowledge_base.search: raw hybrid recall with thresholds, to explain
  why a document is or is not found

x-agent can now name one method when a handler documents several, and
catalog parameters accept numbers.

* feat(assistant): let the assistant try an agent it set up

Add try_agent: the assistant asks an agent one question the way a user
would and gets back its answer, the tools it called and the documents it
cited, so it can check a setup before calling it done.

- The trial runs as the signed-in user in a new agent_trial session kind,
  which ordinary listings already exclude and the API cannot create, and
  the session is removed afterwards. Runs are non-interactive, so tools
  that would ask the user are refused. Long-term memory is untouched: it
  is written only by the HTTP handler.
- The assistant itself, the Wiki fixer and the skill installer cannot be
  tried, nor any agent granted the operation catalog.
- A trial spends model calls and runs the agent's own tools, so it is a
  write for the access level: confirm asks, auto_write runs, read_only
  does not offer it. The confirmation card names the agent and question;
  ConfirmedTool now lets a wrapped tool supply that text.
- At most 3 trials per turn, 4 minutes each; the tool timeout is raised
  above that. Answers, tool errors and references are capped.
- The runner is bound to the session service after the container builds
  it, since the session service depends on the agent service.

* feat(assistant): let the user allow similar changes for the conversation

The confirmation card for a recoverable change now offers "allow this for
the rest of the conversation". Once chosen, later calls of the same kind
in the same session run without asking, so a batch tidy-up no longer
needs a click per item.

- What a grant covers is derived on the server, never taken from the
  model: the same catalog operation on the same knowledge bases (a
  document's knowledge base comes from the target read) or the same
  agent; the same Wiki tool on the run's Wiki knowledge bases; trials of
  the same agent. Deletions and operations without such a scope, such as
  creating a knowledge base, always ask.
- No new storage: the gate looks for an earlier approved prompt in the
  session with the same grant and allow_in_session set, for the same
  tenant and user. Grants therefore survive suspend/resume and replicas,
  and end with the conversation. A failed lookup asks again.
- The response validator accepts allow_in_session only on approval and
  only when the prompt offered a grant, so a client cannot widen it.
- The card shows the scope in the user's language. The model is told
  such calls may run without a card and that deletions always ask.
- describeTarget now returns its target read so the grant reuses it
  instead of reading again.

* feat(assistant): tell the assistant about settings pages and chat answers

Pages now report which page is open and, for the agent editor, which
section. The model and MCP settings name the model or service open for
editing, and chat answers gain an "ask the assistant" button that
attaches that answer. The backend resolves these for the assistant only:
models and MCP services in the caller's tenant without endpoints or
credentials, and messages through the caller's session read access, with
the question, an answer excerpt and cited sources quoted as data.

* feat(assistant): link the user to pages and filled-in forms

The assistant gains open_page, which shows a button to a knowledge base
or document, a Wiki page, an agent's editor at a tab, a model or MCP
service to edit, or a new model or MCP service with its form filled in.
Targets are read through the operation catalog as the user, so a link
never points at something they cannot open. Drafts take no credentials
and only http(s) endpoints without user info; the card shows the
endpoint, and the user enters keys and saves the form themselves.

* feat(assistant): manage MCP services, model names and skills

* fix(assistant): prefill model drafts on initial navigation

* feat(assistant): document tags, model catalog reads, clearer cards, live page refresh

- Operations project lists of objects; knowledge.get/list report tags.
- model.get shows provider, endpoint and capabilities; new
  model.list_providers and model.get_provider read the model catalog,
  including vendors an admin added.
- open_page and ask_user guidance: offer page buttons whenever the next
  step is the user's, word choices for the user.
- Chat cards: redesigned open-page card pinned under the final answer,
  ask-user inputs in the dock style, approval card with aligned fields,
  translated labels and a question built from the operation summary.
- Open pages reload after assistant changes: deletes and moves wait for
  the background task, Wiki edits now report their changes, KB list
  counts, tags and chat model selectors refresh.
- The assistant panel stays open across reloads within the tab.

* fix(ci): format assistant operation code and wrap long lines

* feat(assistant): let the assistant see, fill and open the page beside it

- read_page / fill_page tools answered by the browser over a page_action prompt,
  with refs, redaction, in-place text edits, undo card and a page-access switch
- composer shows the open page, dialog and selection; a selection bubble and an
  editor toolbar entry ask the assistant about the selected text
- edits scroll into view with a highlight and an inline undo bar
- open_page reaches any settings section, toolbox tool and list page, and can
  navigate there itself to read it, keeping the button when edits are unsaved

* feat(assistant): let the assistant open the tab it needs

A visible tab can be selected and re-read, and system settings can open straight to user management, so the next step is no longer blocked on the wrong tab.

* feat(assistant): expose read-only conversation operations

Add session.list, message.list, message.search and
message.chat_history_stats to the operation catalog, restrict the
sessions and messages areas to non-mutating operations, and search
messages with the raw query instead of the log-sanitized one.

* style(chat): restyle open-page and page-edit cards

* fix(ci): comply with assistant card styles and Go line limits
2026-10-16 23:36:01 +08:00
..
README.md refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
citations.go fix(citations): 修复原文定位、高亮范围与 DocReader 启动失败 (#3794) 2026-09-27 20:32:26 +08:00
graph_truncation_test.go fix(agent): 图谱查询的三处截断必须可见,模型不再把子图当全集 (#3885) 2026-10-07 23:59:50 +08:00
handle_table.go fix(agent): harden search-target scope and model-handle policies 2026-07-27 11:05:43 +08:00
handles.go fix(agent): harden search-target scope and model-handle policies 2026-07-27 11:05:43 +08:00
image_sources.go feat: judge image hits by their image in rerank and show them to vision models (#4013) 2026-10-09 13:01:48 +08:00
image_sources_test.go feat: judge image hits by their image in rerank and show them to vision models (#4013) 2026-10-09 13:01:48 +08:00
leaks.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
leaks_test.go refactor(modelcontext): consolidate source_refs parsing, fixed data_analysis table, and identifier leak report (#3372) 2026-09-17 22:08:16 +08:00
mcp.go fix(mcp): normalize JSON-encoded argument envelopes 2026-09-09 16:11:52 +08:00
mcp_sources.go fix(agent): prevent MCP answers from citing unrelated KB sources (#3144) 2026-09-10 00:31:43 +08:00
mcp_sources_test.go fix(agent): prevent MCP answers from citing unrelated KB sources (#3144) 2026-09-10 00:31:43 +08:00
mcp_test.go fix(mcp): normalize JSON-encoded argument envelopes 2026-09-09 16:11:52 +08:00
model_output.go fix(agent): align web_search count limit with the configured maximum (#4011) 2026-10-10 10:27:52 +08:00
omitted_results_test.go fix(chat): 在模型上下文中标注 FILTER_TOP_K 的子集截断,避免把前 N 条当作全集作答 (#3758) 2026-10-09 10:54:37 +08:00
registry.go feat(agent): add the built-in WeKnora assistant with an operation catalog (#4302) 2026-10-15 12:18:30 +08:00
registry_test.go refactor(models): rebuild vendor integration on protocol + catalog + vendor layers (#3470) 2026-09-20 21:28:23 +08:00
resources.go refactor(models): rebuild vendor integration on protocol + catalog + vendor layers (#3470) 2026-09-20 21:28:23 +08:00
resources_test.go refactor(models): rebuild vendor integration on protocol + catalog + vendor layers (#3470) 2026-09-20 21:28:23 +08:00
sources.go refactor(models): rebuild vendor integration on protocol + catalog + vendor layers (#3470) 2026-09-20 21:28:23 +08:00
sources_test.go fix(agent): prevent MCP answers from citing unrelated KB sources (#3144) 2026-09-10 00:31:43 +08:00
stream.go feat(mcp)!: streamline setup and use short routing handles 2026-09-09 16:11:52 +08:00
tool_policy.go feat(assistant): trial runs, session grants, page links, and MCP/model/skill management (#4375) 2026-10-16 23:36:01 +08:00
tool_policy_test.go refactor(modelcontext): unify source-key gating behind one dispatch table 2026-07-27 11:05:43 +08:00

README.md

Model context boundary

modelcontext.Registry is the only application-facing boundary for values that are shortened before an LLM call and restored afterwards. The whole codec lives in this one package:

File Role
registry.go Registry facade — the only type request lifecycles use
handle_table.go handleTable[M], the generic bidirectional primitive behind every handle space
sources.go source handles (cN/dN/bN/wN) and the tool-argument codec
citations.go protocol prompts, <ref/> → <kb/>/<web/> expansion, citation stream expander
model_output.go compact source-centric renderings of tool results
resources.go durable-resource handles (res://NNNN)
stream.go streamHold suffix-hold primitive and every streaming decoder
tool_policy.go the single policy layer: per-tool key contracts + sourceKeySpaces dispatch
mcp.go MCP bridge routing handles (msN/mtN), definition projection and envelope codec
mcp_sources.go bounded citation sidecar for HTTP(S) links in successful MCP results
handles.go exported HandleTable for invocation-local spaces (iN, ref-N, c000)
leaks.go LeakedIdentifiers report of raw UUIDs that survive EncodeMessages, logged at every model-call site

Identity rules

  • Durable application identities: UUIDs, Wiki slugs, URLs, and resource://... references.
  • Request-local model handles: cN, dN, bN, wN, msN, mtN, and res://NNNN.
  • Tool-private request handles: iN for Wiki issues.
  • Ingest-call handles: cNNN and ref-N, allocated with HandleTable.
  • Temporary handles are decoded before tool execution, persistence, or UI delivery. They are never accepted as durable authorization or routing data.

Request lifecycle

  1. Create one Registry for the complete request or Agent execution.
  2. Register structured source identities as they enter the context. For Agent tools, use EncodeTools to project MCP routing enums and source summaries.
  3. Call EncodeMessages immediately before the model call.
  4. Decode tool calls through DecodeToolCalls before parsing or execution.
  5. Decode complete responses with DecodeResponse, or streaming text with one StreamDecoder per response channel.

Unknown handle-shaped values in declared tool fields are rejected before tool execution. The same per-tool policy is applied when historical assistant tool calls and tool results are replayed, so handles neither disappear nor drift to new numbers across Agent rounds.

The registry owns codec ordering. Resource references are encoded before source IDs so a Wiki slug such as summary/<knowledge-id> cannot be corrupted into summary/d1.

Source addressability is separate from citation eligibility. Use RegisterContextChunk for bound-KB directory entries. Replayed citations, legacy tool history, and tool arguments also register navigation handles only. ModelToolResultForTool and explicitly supplied retrieval results authorize citations for the current execution; rereading a historical source promotes the same handle without renumbering it. Both complete and streaming decoders drop references that have not been backed by current evidence.

Observability

Every model-call site runs LeakedIdentifiers on the encoded messages and logs a warning naming the role or tool whose text still carries a raw UUID. A registered leak means the codec missed a rewrite site; an unregistered leak means a producer emitted an identifier that never entered the registry. Text-level compaction (CompactKnownText) stays in place as defense in depth until those producers are fixed and the report stays quiet.

Langfuse generation observations contain the exact encoded payload sent to and returned by the model. Agent tool spans contain both model_arguments (the model-emitted handles) and resolved_arguments (the durable values actually executed), plus argument_resolution and any unresolved handles. Sensitive tools report only argument keys and resolution counts.

Langfuse is an observer of this boundary; it must not implement another handle mapping.

Built-in tool policies

Canonical ID-bearing arguments for knowledge, graph, data, web, and Wiki tools are decoded centrally through a tool-name plus JSON-field allowlist. The sourceKeySpaces table is the single source of truth for which keys are ID-bearing and which handle space they register into; per-tool sourceIDKeys contracts gate which of those keys each tool may use. database_query.sql has an explicit policy because source handles can be embedded inside quoted SQL values when the model filters the real knowledges/chunks tables; unquoted SQL aliases and arbitrary prose are never rewritten. data_analysis.sql carries no handles: the selected document is always exposed as the fixed table dataset, so only knowledge_id is decoded. Wiki issue IDs use the same lifecycle via an iN handle space.

Dynamic MCP tools are intentionally opaque in both arguments and results. Their schemas and identity semantics are controlled by the MCP server, so the application must not guess that an arbitrary id, knowledge_id, or url field is durable or rewrite it. Durable resource handles inside MCP arguments still use the normal res://NNNN codec. A future MCP ID mapping must be an explicit server/tool annotation and should plug into this registry rather than create a parallel mapper.

Successful MCP execution results additionally receive an external_source_candidates sidecar with up to 50 distinct observed HTTP(S) links mapped to wN. The external payload is not rewritten, discovery schemas are not scanned, and article IDs are never used to guess URLs. A candidate link does not establish that its page was read: the model must select the link whose associated result supports the claim. When no handle is supplied, the citation protocol permits an exact supplied source URL as a Markdown link, never a borrowed knowledge-base citation.

The application-owned MCP bridge is an explicit exception for routing fields: discover_mcp_tools.server_id uses msN, and call_mcp_tool.tool_ref uses mtN. Tool definition enums, service summaries, discovery results and replayed calls share the same request registry. Only directory envelope fields are registered; input_schema, call_mcp_tool.arguments, and external execution results remain opaque. Arguments are restored before authorization, validation, execution, persistence and UI events. Unknown routing handles fail closed.

For model-emitted call_mcp_tool calls, one extra JSON-string encoding of the arguments envelope is accepted only when it contains a complete JSON object (including {}). Normalization runs before resource-handle decoding; original model arguments are retained for tracing. Nested business strings are unchanged, and malformed JSON, arrays, null, and further encoding layers remain invalid. The canonical object still passes the existing routing, schema and approval checks.

Wiki routing

WikiRouteResolver is intentionally separate. It stores server-side slug-to-knowledge-base provenance gathered during Wiki search/read operations, and can only return knowledge bases already present in the Agent's authorized Wiki scope. It is routing state, not a model handle table. Reads scan every legal Wiki KB so cached provenance cannot hide a duplicate slug; mutations require one unique owner. New pages use link provenance, a single Wiki scope, or a single source-document owner and reject ambiguous routing instead of asking the model for a durable KB ID.

Document/tag-constrained Wiki and graph requests are filtered by the same server-owned SearchTargets provenance. Uncited/global Wiki pages and graph results outside that subset fail closed; only an explicit whole-KB target authorizes whole-KB content.