fix(pages): make pages discoverable to agents — org-wide CLI list, search, recall guidance

AV
2mo ago
+163-27

Problem

A user published Superset Pages expecting a later agent session to read them back, and the agent could not find them.

Root causes (discovery path only; publish and permissions were fine)

  1. CLI pages list was silently workspace-scoped. packages/cli/src/commands/pages/list/command.ts defaulted --workspace to $SUPERSET_WORKSPACE_ID, which every Superset terminal sets (apps/desktop/src/main/lib/terminal/env.ts:485, packages/host-service/src/terminal/env.ts:265). Inside a workspace the agent only ever saw pages published from that workspace. The desktop Pages tab (PagesView.tsx:54, page.list.useQuery({})), the MCP pages_list tool, and the page skill all treat "no workspace" as the whole org, and the skill literally said # or omit --workspace for the whole org. So the user saw the page in the Pages tab and the agent's list came back without it.
  2. Slugs cannot be guessed. mintPageSlug appends a random 6-char suffix (packages/shared/src/page-slug.ts), so pages get <title-slug> returns "Page not found" for a page that exists. No tool description or skill text said to list first.
  3. No search on page.list. Recall meant scanning the whole org list.

Not a cause, but checked: visibility defaults to org at the app layer (publish.ts:551, page.ts:173; the DB-level just_me default in schema.ts:1385 is only reachable by rows created before #6932). The list's visibility filter includes the caller's own just_me pages, so a same-user agent always sees its user's private pages. Org scoping is correct: MCP API keys and host-service terminals are pinned to one org, so a multi-org user whose page lives in another org gets a FORBIDDEN "belongs to X" on get, and a list that simply lacks it.

Fix

  • CLI pages list: whole org by default, --workspace only when passed; new --search/-s; UPDATED column. Test added.
  • tRPC page.list: optional search, case-insensitive contains over title/description/slug, LIKE metacharacters escaped (search.ts + test).
  • MCP pages_list: search param, description says it is the only way to discover a page and to omit workspaceId when looking one up. pages_get/pages_pull/pages_versions now say slugs cannot be guessed and point at pages_list.
  • Skill superset:page: "Find a page and read it back" section replaces the incorrect comment; troubleshooting row for the guessed-slug symptom.
  • Docs: "Find a Page Later" section in pages.mdx; pages_list row in mcp-server.mdx.

Verification

  • bun test over packages/trpc/src/router/page, packages/mcp, packages/cli/src/commands/pages: 88 pass.
  • tsc --noEmit clean in packages/trpc, packages/mcp, packages/cli.
  • bun run check:plugins passes (the superset plugin is bundled, not marketplace-published, so no version bump applies).
  • Biome clean on changed files.

Follow-ups not in this PR

  • The Slack agent allows pages_list but its system prompt says nothing about pages; the improved tool description is what it will see.
  • page.list still returns every row with signed view/thumbnail tickets and no limit; fine for current org sizes, worth a limit when the list grows.

Summary by cubic

Fixes agent recall of published pages by making pages list discover all pages the agent can read and by guiding agents to list before fetching. Previously the CLI silently scoped to $SUPERSET_WORKSPACE_ID, so pages published from another workspace, machine, or session were invisible to agents while visible to the user. Now the command is org-wide by default, supports --search, and only scopes to a workspace when --workspace is passed. Search (case-insensitive, escaped LIKE) was added to page.list and the MCP pages_list tool, and MCP, skill, and docs guidance now instructs agents to find pages by name via list because slugs end in a random suffix and can't be guessed.

Migration

  • Scripts that relied on the old default workspace scoping must pass --workspace explicitly.

Summary by CodeRabbit

  • New Features

    • Added page search across titles, descriptions, and slugs using the CLI and MCP tools.
    • Added optional workspace filtering and organization-wide page listing.
    • CLI results now show when pages were last updated.

  • Documentation

    • Clarified how to find pages by name, retrieve their IDs or slugs, and use pages across workspaces and sessions.
    • Documented that slugs include random suffixes and should not be guessed.