Prompt assembly merges tool definitions discovered via readRealmFile#5485
Open
lukemelia wants to merge 3 commits into
Open
Conversation
Tools discovered by reading a skill file become available to the model on the next generation, sourced from room events like every other prompt input — replay-correct and inspectable. The readRealmFile fulfillment embeds each read skill's usable (schema- stamped) tool entries on the result event as data.discoveredTools, each tagged with the source skill URL so the execution leg can verify calls against the declaring skill's indexed frontmatter. Entries without a well-formed definition are dropped; tool-less reads publish exactly the same event shape as before, and attachedFiles is untouched so the attachment-download path and timeline rendering are unchanged. getTools gains a third source: tool-result events' discoveredTools, merged into the tool map before the enabled-skill and message-context sources so those win on functionName conflict. A skill read many times contributes only its latest read's definitions (the file may have changed between reads), and a skill disabled in room state contributes none. CS-12046 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR extends prompt assembly so that tool definitions discovered via readRealmFile (from skill markdown file-meta frontmatter) are persisted on tool-result events and then merged into getTools on subsequent turns, making the behavior fully event-sourced and replayable from room history.
Changes:
- Embed index-stamped tool definitions from
readRealmFileresults asdata.discoveredToolson tool-result events (tagged withsourceSkillUrl). - Teach
getToolsto scan tool-result events fordiscoveredToolsand merge them into the tool map ahead of uploaded skill tools and message-context tools. - Add ai-bot tests covering fulfillment embedding/dropping, precedence/wholesale replacement rules, disabled-skill filtering, and JSON encode/decode round-trip.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/runtime-common/ai/prompt.ts | Adds discoveredTools as a third getTools source and defines conflict/precedence behavior. |
| packages/base/matrix-event.gts | Introduces DiscoveredToolDefinition and adds data.discoveredTools to tool-result event payload typing. |
| packages/ai-bot/lib/read-realm-file-fulfillment.ts | Extracts usable stamped tool definitions from read results and publishes them on tool-result events (without changing attachment shape). |
| packages/ai-bot/tests/read-realm-file-fulfillment-test.ts | Tests that fulfillment embeds stamped definitions and omits the key for tool-less reads. |
| packages/ai-bot/tests/prompt-construction-test.ts | Tests getTools discovery behavior, precedence, disabled-skill behavior, and encode/decode round-trip via constructHistory. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Contributor
Only the bot publishes readRealmFile results, so discovered definitions on anyone else's tool-result event are ignored; and an entry only counts when its definition is a well-formed function tool (type plus function.name), not just any object with a nested name. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A failed or invalid readRealmFile result is not evidence the skill was fetched, so its discoveredTools claim is ignored. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
habdelra
approved these changes
Jul 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Linear: CS-12046
Stacked on #5484 (readRealmFile file-meta reads) — the pull model's prompt-injection leg. Tools discovered by reading a skill file become callable on the model's next generation, sourced from room events — the same event-sourcing every other prompt input uses, so it's replay-correct and inspectable.
Behavior
read-realm-file-fulfillment.ts): each read skill's usable tool entries — those with a well-formed, index-stamped LLMdefinition— are embedded on the read's command-result event asdata.discoveredTools, each tagged withsourceSkillUrl(the execution leg verifies calls against the declaring skill's indexed frontmatter). Entries without a definition (a skill indexed before schema enrichment) are dropped.attachedFilesis untouched — the attachment-download path and timeline rendering see exactly the event shape they saw before, and tool-less reads publish byte-identical data.getTools(runtime-common/ai/prompt.ts) gains a third source: it scans tool-result events fordata.discoveredToolsand merges the definitions into the tool map first, so an enabled skill's uploaded definition or a message-context tool with the same functionName wins on conflict. A skill read many times contributes only its latest read's definitions — wholesale, so a tool the skill no longer declares disappears. A skill listed indisabledSkillCardscontributes none.DiscoveredToolDefinitiononToolResultWithOutputContent.data(matrix-event.gts), riding the existingdataJSON-stringify/parse wire path (sendMatrixEvent/constructHistory).Testing
ai-bot suite (240 passing; the 2 failures are the pre-existing locking tests needing a CI-provisioned Postgres role):
discoveredToolskey.getTools: discovered tools are offered on later turns; the latest read of a skill wins wholesale; a disabled skill contributes nothing; a skill both enabled and read yields one definition with the uploaded one winning; definitions round-trip the encode/decode path viaconstructHistory.🤖 Generated with Claude Code