Skip to content

fix(clips): steer find and filter requests to library search navigation - #9563

Merged
steve8708 merged 2 commits into
mainfrom
job/j-20261120-1002-1ff
Nov 20, 2026
Merged

steve8708 merged 2 commits into
mainfrom
job/j-20261120-1002-1ff

Conversation

@steve8708

Copy link
Copy Markdown
Contributor

1. Repro

Failing evidence from K-CLIP-1-4 on served 0dc5222eab7ebdd2992d1d0607d09c0a9fbb4a44 (prompt: "find the onboarding one" while on /clips/library):

  • K-CLIP-1-4: Listed onboarding clips in chat but stayed on /clips/library without ?q= search filter

Live check on served Labs build 814d2c2317088942a07261d15dfb8c62d6b43d62 signed in as qa-fleet@builder.io:

  • /clips/library shows 4 onboarding recordings (recordingLinks: 4, searchInputValue: "")
  • /clips/library?q=zzz-no-match-repro renders unfiltered (recordingLinks: 4, searchInputValue: "")
  • list-recordings?view=library&search=ONBOARDING returns 0 vs 4 for lowercase onboarding

Companion PR #9562 fixes the URL/grid/query plumbing (use-navigation-state.ts, library-grid.tsx, search-bar.tsx, list-recordings.ts, search-recordings.ts, view-screen.ts) with zero file overlap.

2. Root cause

  • templates/clips/server/plugins/agent-chat.ts:33-46: extraContext (injected into every chat prompt variant) had no library-search navigation guidance, and mcp configured { appApprovalPage: true } with no instructions. When matching clips are already visible in <current-screen> on /clips/library, callers can answer directly from <current-screen> without invoking list-recordings or search-recordings — leaving the Library unfiltered at /clips/library (or jumping directly into a single recording player at /clips/r/<id>) instead of filtering the Library view with navigate({ view: "library", search: "<query>" }).
  • templates/clips/AGENTS.md:25: Application state guidance did not document filtering the list view via navigate with view: "library" and search: "<query>".

3. Test that fails first

Extended templates/clips/server/plugins/agent-chat.instructions.spec.ts with three regression tests covering <clips-library-search> guidance, MCP instructions (/library?q=), and AGENTS.md.

Red before fix:

 ❯ server/plugins/agent-chat.instructions.spec.ts (4 tests | 3 failed)
     ✓ continues bounded transcripts through every returned offset
     × steers find and filter requests to navigate with view=library and search
     × advertises filtered library search paths in MCP instructions
     × documents library search navigation in AGENTS.md

Green after fix:

 ✓ server/plugins/agent-chat.instructions.spec.ts (4 tests) 3ms
 ✓ src/mcp/instructions-name-advertised-tools.spec.ts (10 tests)
 ✓ src/mcp/advertised-tool-annotations.spec.ts (15 tests)
 ✓ src/mcp/agent-mcp-parity.spec.ts
 ✓ src/mcp/hidden-inline-apps.spec.ts
 ✓ pnpm --filter clips typecheck
 ✓ pnpm --filter clips build
 ✓ guard:doc-budgets / guard-no-source-reading-tests / guard:strict-lint

4. Live proof

Ref: j-20261120-1002-1ff

Add library-search guidance to Clips extraContext, MCP instructions, and
AGENTS.md so find/filter prompts filter the Library view via navigate
(view=library, search) instead of only replying in chat or jumping
straight to a single recording player.

Ref: j-20261120-1002-1ff

@builder-io-integration builder-io-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Builder reviewed your changes and found 1 potential issue 🟡

Review Details

This PR adds Clips agent guidance and MCP instructions to route keyword searches into the Library or a space, plus source-level regression checks and corresponding AGENTS.md guidance. The approach correctly recognizes that matching recordings already visible in the current screen should not prevent the agent from applying the requested filter, and it preserves the explicit distinction between finding clips and opening a specific recording. Risk assessment: standard. One medium finding remains: this PR's user-facing promise depends on companion PR #9562, which provides the URL/query plumbing; without that companion change, navigate ignores search when building the route and the list remains unfiltered. The prompt and docs would then tell the agent to perform behavior that does not occur. No separate confirmed security or performance issue was found. 🟡 MEDIUM: filtered search behavior is not delivered unless the companion plumbing is present. 🧪 Browser testing: Will run after this review (the guidance changes agent-driven navigation into UI flows).

For summaries, action-item lists, follow-up lists, and todo lists based on the recording in view, use Clips' recording/transcript actions and answer directly in this chat. Do not call Plan or another app for a generic written list. Only delegate to Plan when the user explicitly asks for a visual or structured Agent-Native Plan, a Plan artifact, or the Plans app.
</clips-agent-routing>
<clips-library-search>
When the user asks to find, search, or filter clips or recordings by keyword or topic, filter the active list view on screen by calling navigate with view="library" and search="<query>" (or view="space" with spaceId and search inside a space), even if matching recordings already appear in current-screen. Do not only list matches in chat while leaving the Library unfiltered, and do not jump straight into a single recording player (view="recording") unless the user asks to open, play, or inspect a specific clip or its transcript/comments.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Filtered navigation relies on the companion URL plumbing

This guidance instructs the agent to pass search to navigate and promises the list will update, but the current navigation path builder drops search when generating Library/space URLs. Until companion PR #9562 is merged with the query plumbing, this leaves the list unfiltered while the agent is told it applied the filter. Please ensure this change cannot land independently of that plumbing, or avoid promising the behavior until it is available.

Fix in Builder

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Acknowledged — this guidance pairs with companion PR #9562, which adds ?q= serialization in pathFromCommand and LibraryGrid ?q= filtering. Both land independently with zero file overlap; keeping the canonical navigate(view="library", search) contract in extraContext/AGENTS.md so the instructions match the navigate action schema.

@github-actions

github-actions Bot commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Visual recap — generation failed

Recap authentication failed — PLAN_RECAP_TOKEN was rejected; it may be expired, revoked, or minted for another Plans app. Personal token: run npx @agent-native/core@latest connect <app-url> --client codex, then npx @agent-native/recap-cli@latest recap setup. Org service token: an owner/admin can mint a 10-year replacement with npx -y @agent-native/core@latest connect <app-url> --service-token <name> --ttl-days 3650. Update this repo's secret.

Trim the navigation bullet in templates/clips/AGENTS.md to 5969/6000
chars so guard:agent-chat-context passes cleanly.

Ref: j-20261120-1002-1ff

@builder-io-integration builder-io-integration Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Builder reviewed your changes and has a few items to flag 🟡

Review Details

Incremental review of PR #9563: the updated diff still adds Clips agent/MCP search guidance, regression checks for instruction text, and a condensed AGENTS.md navigation note. The documentation edit does not change the previously reported functional dependency: filtered navigation still relies on the separate URL/search plumbing in PR #9562, and the existing thread at agent-chat.ts:49 remains unresolved, so I have not reposted it. I found no new confirmed medium- or high-severity issue. One low-severity MCP wording concern was identified: external hosts are told that open_app can open /library?q=... without explicitly identifying path as the parameter, and that ask_app can search recordings without restating the app's discovery boundary. Risk assessment remains standard. 🧪 Browser testing: Skipped — the browser-test-planner agent is unavailable in this environment.

@steve8708
steve8708 merged commit 371890b into main Nov 20, 2026
48 checks passed
@steve8708
steve8708 deleted the job/j-20261120-1002-1ff branch November 20, 2026 19:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant