Skip to content

fix(cache): reject private metadata across sessions - #743

Merged
nicobailon merged 4 commits into
nicobailon:mainfrom
quifox:fix/private-cache-scope
Sep 30, 2026
Merged

nicobailon merged 4 commits into
nicobailon:mainfrom
quifox:fix/private-cache-scope

Conversation

@quifox

@quifox quifox commented Sep 30, 2026

Copy link
Copy Markdown
Contributor

Summary

Honor MCP cacheScope: "private" at the adapter's persistent metadata-cache boundary.

The adapter's disk cache is shared by server configuration and is not partitioned by authorization context. A fresh private entry with a positive TTL was therefore considered valid on a later session and could register cached direct tools or prompts before the server reconnected.

This PR keeps the fix narrow:

  • persistent entries marked private are never considered reusable by isServerCacheValid()
  • current-session live metadata still works through the existing sessionMetadata overlay, which strips persistence-only TTL/scope before rebuilding the live tool surface
  • prompt-discovery fallback now prefers current-session metadata and only falls back to a disk entry when that entry passes normal cache validity checks

This is intentionally narrower than the cache-policy work that was previously combined in #740. It does not introduce cache eviction, file locking, or new pagination policy.

Reproduction

On current main, a cache entry with:

{
  "ttlMs": 60000,
  "cacheScope": "private"
}

is treated as valid, and cached direct tools can be registered in a later session. A failed prompt discovery can also revive prompts from the same private disk entry.

With this patch, the same entry is invalid for persistent reuse, while live session metadata remains available after connection.

Validation

  • focused cache / prompt / lifecycle / direct / namespace suites: 301 passed
  • broader Vitest run excluding four Mac sandbox process-discovery suites: 147 test files passed, 2081 tests passed
  • the excluded http-ca, request-headers-command, server-manager-http-auth, and server-manager-oauth-service-headers suites fail identically on clean main in this LocalCodex macOS sandbox because ps axeww is killed
  • npm run typecheck
  • npm run build:public
  • npm run test:public-exports: 3 passed, 1 platform skip
  • browser suite: 1 environment skip
  • git diff --check

The change is based on current main at b8ed5a0.

@greptile-apps

greptile-apps Bot commented Sep 30, 2026 •

Copy link
Copy Markdown

RetriggerConfidence Score: 5/5

[Medium risk] Prevents private metadata from persisting across sessions.

The PR appears safe to merge based on the reviewed changes.

Summary

The PR rejects private entries at the persistent metadata-cache boundary while retaining live metadata for the connected session.

  • Prompt and resource discovery fallbacks now check the current session entry before using a valid disk entry.
  • Output shapes learned from private listings are kept in-session rather than saved for later sessions.
  • Regression tests cover private cache entries, discovery failures, lifecycle behavior, and output shapes.

Reviews (3) · Last reviewed commit: "fix: keep private session metadata out o..."

@nicobailon
nicobailon force-pushed the fix/private-cache-scope branch 2 times, most recently from 8683b95 to 1aebde3 Compare September 30, 2026 14:04
quifox and others added 3 commits September 30, 2026 07:07
Saved output shapes live on the shared cache entry, so rejecting private entries at startup was not enough: a shape observed under a private tool listing could still be saved and reach another session.

Each in-memory shape now records whether any observation merged into it was made under a private listing, checked both when the call starts and when its result arrives. Such a shape is used in the current session only and never saved, including after the listing turns public. A rewrite of a cache entry also no longer carries shapes out of an entry marked private.
@nicobailon
nicobailon force-pushed the fix/private-cache-scope branch from 1aebde3 to 4aa1e2f Compare September 30, 2026 14:09
Comment thread init.ts Resolved
When prompt or resource discovery fails, updateMetadataCache fills the entry from the current session's metadata. That entry may come from an earlier private listing, while the new entry takes the reconnected listing's scope, so private prompts or resources could be written to a public entry and reused by a later session. A private session entry now only fills an entry that is private too.
@nicobailon
nicobailon merged commit 0ff0b85 into nicobailon:main Sep 30, 2026
4 checks passed
brooksmcmillin added a commit to brooksmcmillin/pi-mcp-adapter that referenced this pull request Oct 5, 2026
* revert: remove the Serply preset from /mcp setup (#723)

Vendor search presets that need their own API key don't belong in the adapter's built-in list. Anyone can still add Serply as a normal server entry.

This reverts commit 4e9f9df4 (#710). It was never released.

* docs: add VISION.md and point agents at it (#724)

Sets what fits in the adapter and what it refuses, including vendor presets, so scope calls like #710 have a written reference. AGENTS.md tells coding agents to read it before scope or backlog decisions.

* docs: require maintainer approval for vendor-specific changes (#725)

Drops the clause excluding presets proposed by the server's vendor. Presets must meet the no-signup bar, and anything specific to one vendor or server needs the maintainer's approval before it is accepted. It can be rejected without asking.

* chore(release): v3.2.0

Adds the host-managed entry point for embedding apps, defaults the OAuth callback to 127.0.0.1, and fixes the false project-trust warning, disappearing direct tools, hidden mcp__<server> tools after a failed connection, and mcpScript in Bun-compiled Pi.

* chore(deps): drop unused @modelcontextprotocol/ext-apps dependency (#726)

No runtime module imports ext-apps since the host moved to the bundled app bridge and local helpers. Its peer requirement on the legacy MCP SDK v1 made plain npm installs pull SDK v1 and its HTTP server stack into production dependencies. The manifest test now asserts the lockfile keeps SDK v1 dev-only.

* feat(jev): use OPENROUTER_API_KEY for the OpenRouter endpoint (#727)

Honor OPENROUTER_API_KEY only when SYSTEMONE_ENDPOINT points at
openrouter.ai, default the model to typesafe/jev-1.13 there unless one
is configured, and accept provider metadata (id, provider, usage.cost)
in decision responses so the documented OpenRouter setup works.

* feat: keep MCP tool annotations and show them in describe and approval (#728)

* feat: keep MCP tool annotations and show them in describe and approval

Servers declare read-only, destructive, idempotent, and open-world hints on their tools. The adapter dropped them, so neither the model nor the user could tell a read-only tool from one that deletes data.

Keep the spec annotation fields on tool metadata (live and cached), drop malformed values, and show them only where a decision is made: mcp describe, mcpScript tools.describe, and the approval prompt. Search results and direct-tool descriptions are unchanged.

* fix: approve direct tools against live tool annotations

A direct tool's spec is fixed when it is registered, often from the metadata cache, and with freezeDirectTools it is never re-registered. Approval read the hints from that spec, so a server that now marks a tool destructive was prompted without the warning.

Look up the tool's hints in the live metadata that lazy connect refreshes, and drop annotations from DirectToolSpec and its re-registration fingerprint.

* fix: escape server tool titles in describe hints

* fix: pause a tool call's timeout while the user answers an elicitation prompt (#729)

* fix: pause a tool call's timeout while the user answers an elicitation prompt

* test: cover direct-tool calls and cancellation while an elicitation form is open

* feat: show observed output shapes for tools without an output schema (#730)

* feat: show observed output shapes for tools without an output schema

After a successful call to a tool that declares no outputSchema, infer a
bounded shape (field names and JSON types only, never values) from its
structuredContent or single JSON text result and keep it in memory for the
session. mcp({ describe }) and mcpScript tools.describe show it, labeled as
observed and not a contract. Nothing is persisted and no new config is added.

* fix: keep data-shaped keys out of observed output shapes

Treat an object as a map when it is wider than the key cap or any key does
not look like a field name, so small maps keyed by emails or ids no longer
show their keys. Count keys with an early exit, and name size limits in
characters rather than bytes.

* fix: reset observed output shapes for a replaced server and keep __proto__ keys out

* feat: approveTools "destructive" asks before tools that may change data (#731)

* feat: approveTools "destructive" asks before tools that may change data

approveTools accepted true or name globs, so asking before every tool that may change or delete data meant listing names server by server.

approveTools now also accepts "destructive", globally or per server. Following the MCP defaults, a tool runs without a prompt only when its server marks it readOnlyHint: true or destructiveHint: false; unannotated tools are gated, and resource reads are not.

An unknown approveTools value used to turn approval off silently. Adapter config files with one are now rejected with a warning naming the key, and such values from other sources require approval.

* test: cover direct tools and resource reads under approveTools "destructive"

* feat: autocomplete MCP prompt argument names (#733)

* feat: autocomplete MCP prompt argument names

* docs(changelog): credit PR #733

* fix: skip prompt argument completions for disabled servers

---------

Co-authored-by: quifox <[email protected]>
Co-authored-by: Nico Bailon <[email protected]>

* fix: normalize Unix socket text chunks (#732)

* fix: normalize Unix socket text chunks

Accept the string | Buffer data contract in newer Node typings before
passing chunks to the SDK ReadBuffer. Preserve binary chunks unchanged.

Cover fragmented text and UTF-8 bytes split inside a multibyte character.

* docs(changelog): credit PR #732

---------

Co-authored-by: Nico Bailon <[email protected]>

* chore(release): v3.3.0

* fix: detect Pi's built-in MCP extension by its builtin:mcp path (#737)

Pi 0.99 names built-in extensions builtin:<name>. The adapter compared the
built-in /mcp command against <inline:mcp>, so it never detected it: it
registered its own /mcp and warned about mcp.json on every start.

Fixes #736

* feat: let other extensions call MCP tools through the event bus (#735)

* feat: add MCP_RUNTIME_TOOL_CALL_EVENT

Adds one new event on the existing pi.events bus, letting a sibling Pi
extension invoke an already-configured MCP tool programmatically, from
its own backend code, without a model turn.

pi.events already carries MCP_RUNTIME_REGISTER_EVENT (register a server
at runtime) and MCP_RUNTIME_SNAPSHOT_EVENT (read one back), but nothing
for a sibling extension to CALL a tool on an already-configured server.
The only two existing invocation paths are the model-facing mcp proxy
tool (a conversation turn) or createHostManagedMcpAdapter (requires
owning session construction via createAgentSession, not usable from a
sibling extension inside an already-running session).

Composes rather than invents: the handler delegates entirely to the
existing executeCall() in proxy-modes.ts -- the same function the
mcp({ tool }) proxy call and mcpScript's tools.call() already use.
Server resolution, ambiguity handling, disabled-server checks, and the
approval broker all run identically to a model-issued call. No new
call/auth/approval logic is introduced.

request.result is written as a Promise rather than a resolved value
(unlike the synchronous registration event), because a tool call is
inherently async and pi.events' on() handler signature is synchronous.

Tests: __tests__/runtime-tool-call.test.ts, mirroring
runtime-register.test.ts's exact mocking/event-bus harness. 7 cases:
successful call, explicit server override, no-active-session refusal,
empty-tool-name refusal, executeCall() rejection surfaced as ok:false
rather than an uncaught rejection, first-listener-wins on a prefilled
result, and unsupported-version refusal.

npm run typecheck: clean.
npx vitest run: 2153 passed, 1 skipped, 2 failed -- both pre-existing
on unmodified main (interactive-visualizer-server.test.ts, missing
example build artifacts unrelated to this change).

* fix: address review findings (deferred init, resolved-failure detection)

Issue 1: a session using valid cached metadata defers real MCP
initialization until something needs it -- state AND initPromise are
both absent in that case. The event previously refused to call in this
state instead of starting initialization the way the mcp proxy tool's
own first call does via ensureSessionRuntime(ctx). Fixed by building
the same minimal ctx-shaped object startLoadTimeInitialization()
already constructs and calling the existing startInitialization() --
no new initialization logic, composing with what already exists.

Issue 2: executeCall() resolves tool errors/denials as a NORMAL
resolved value carrying details.error; it does not reject for those
outcomes. The event previously returned { ok: true } for any call
that didn't throw, so a real failed call (denied approval, tool error,
disabled server) was reported as success. Fixed by inspecting
result.details.error after a successful resolve and mapping a present
error to { ok: false }.

Issue 3: the one existing failure test mocked executeCall() to reject,
which doesn't exercise the real failure shape. Added a test for the
resolved-with-details.error case (the actual failure shape), a test
for the deferred-init path calling executeCall() successfully, and
replaced the now-stale no-init-starts-nothing test with one for
initialization genuinely failing.

npm run typecheck: clean.
npx vitest run: 2155 passed (up from 2153), 1 skipped, 2 failed -- same
2 pre-existing failures on unmodified main, unrelated to this change.

* fix: never self-start MCP initialization from the tool-call event (review round 2)

Both findings from the second review round were valid and pointed at
the same root problem: the round-1 fix's "start init ourselves with a
synthetic context" approach had two real races.

Issue 1: if this event's synthetic-context startInitialization() call
raced ahead of session_start's own initPromise check (session_start
sets initPromise only after its own internal cleanup await), session_
start would see initPromise already set and skip starting its OWN
real-context initialization for the rest of that session -- permanent
contamination (missing isProjectTrusted(), wrong cwd), not a one-off
degraded call.

Issue 2: session_shutdown clears state/initPromise/currentOwner to
null, indistinguishable from "never started" -- so self-starting would
silently reconnect servers after the session already ended.

Fix: this event never calls startInitialization() itself. It only
ever uses a state/initPromise a real, ExtensionContext-bearing caller
already created (session_start or the load-time path). A new
sessionEnded flag (set only by session_shutdown, cleared only by the
next session_start) makes the shutdown case explicitly refused rather
than silently reconnecting.

Tests: replaced the two round-1 tests that asserted the now-removed
self-starting behavior with four: refuses when neither state nor
initPromise exist (no self-start), waits on an already-started
initPromise from a real session_start, refuses after session_shutdown
without creating a new owner, and allows a fresh call again after a
session_start that follows a shutdown (sessionEnded clears correctly).

npm run typecheck: clean.
npx vitest run: 2157 passed (up from 2155), 1 skipped, 2 failed -- same
2 pre-existing failures on unmodified main, unrelated to this change.

* fix: run runtime tool calls in deferred warm-cache sessions

With cached metadata, session_start defers MCP initialization, so the
tool-call event refused every call in a normal running session. Keep the
live session context and start the runtime through ensureSessionRuntime,
as the mcp proxy tool does. Clearing the context at shutdown replaces the
sessionEnded flag. Trim review-history comments and reduce the tests to one
per behavior.

* docs: document runtime tool calls from other extensions

* refactor: drop narrating comments from the runtime tool-call handler

* refactor: fold runtime tool-call validation into the async result

---------

Co-authored-by: jasonh <[email protected]>
Co-authored-by: Nico Bailon <[email protected]>

* test: fix two tests that fail on slow CI runners (#738)

* test: keep the elicitation timeout tests from timing out the handshake

The short requestTimeoutMs these tests use also bounded connect(), so a slow
CI runner could time out spawning the fixture server before the call under
test started. Set the timeout after connecting instead.

* test: kill Chrome's whole process group in the browser CSP test

Killing only the main Chrome process on Linux leaves helper processes running
for a moment, and they can write into the profile directory while the test
removes it, failing with ENOTEMPTY.

* test: skip the group kill when Chrome never got a pid

* test: kill Chrome's process group even after its main process exits

* feat!: make mcpScript opt-in and fix its result guidance (#744)

* docs: trim the mcp-scripting skill

Once read, the skill stays in context for every later turn. Jev
evaluation, cache-refresh notes, and memory-budget detail moved out or
were condensed; jev lives in references/jev.md.

* fix: tell mcpScript callers how to read tool results

Scripts assumed data was the parsed payload, so paging loops compared
undefined lengths and ran until the 30s timeout.

* fix: size observed output shapes by what describe shows

The 4 KiB bound was measured on the stored JSON form, about 2.5x the
rendered text. GitHub-style issue lists lost labels[].name while three
copies of an 18-field user object were kept.

* feat!: make mcpScript opt-in and add settings.scriptSkill

mcpScript, its skill, and the mcp description's pointer to it now need
settings.scriptMode: true. The skill stays manual-only; scriptSkill:
"model" names its path in the mcpScript description, because Pi reads
disable-model-invocation from the skill file and extensions cannot
override it.

* feat: hint mcpScript on large results that may feed another call

Claude retyped a 15 KB result into the next call. Wording in tool
descriptions did not change that; a hint on the result itself does.

* fix: keep mcpScript guidance aligned with the registered tool

The mcp description and the large-result hint read the session config, but
mcpScript is registered from the config Pi loaded with, so a session in
another directory could be told to use a tool it does not have. Both now
follow the load-time decision.

The hint also moves to a guard footer so truncated results keep it,
measures its threshold in UTF-8 bytes, and is left off results delivered
to other extensions through the runtime tool-call event.

* fix: stop mcpScript callers doubling the server prefix

The code parameter told the model to use tools.<prefixedToolName>, so
Claude added the server prefix to names that already carried it and
called tracker_tracker_list_issues. It now says to use the names exactly
as mcp lists them.

* feat: show mcpScript the result fields when a script finds nothing

Most MCP tools declare no output schema, so models spent a turn calling a
tool just to see its fields before writing the real script. When a script
throws, times out, or returns [], {}, null, "" or nothing, its result now
ends with the observed shapes of the tools it called, so a wrong guess
is fixed in the next script instead of after a separate look.

Observed shapes also write a wide object that repeats (a user under user,
assignee and assignees) once as a named type, which keeps every field and
cuts a GitHub issue list shape by about 40%. The skill tells the model to
guess first and guard write loops.

* feat: save observed output shapes for later mcpScript sessions

A shape learned in one session was gone in the next, so every session
paid a turn to look at an unfamiliar tool's result again. With mcpScript
on, a shape that changes is now saved in the tool's mcp-cache.json entry
(field names and types, never values) and loaded at startup, so describe
shows it before the tool is called.

Each shape is tied to the tool's description and input schema. A session
shows or merges a shape only while the definition it sees still matches,
and a rewritten cache entry keeps a saved shape only when the server
config and that key are unchanged, so another Pi session rewriting the
shared cache cannot show or erase the wrong shape. Shapes read back from
the file are validated before use.

observedOutput no longer reports a call count, since a saved shape can
come from earlier sessions.

* fix: find git packages installed from URLs with a port or user (#746)

* fix: accept Pi 0.99 in the pi-ai peer range (#747)

The optional @earendil-works/pi-ai peer range stopped at ^0.87.0, so npm warned on every install next to Pi 0.99. Add ^0.99.0 and move the dev pins to 0.99.1 so typecheck and tests run against the current host.

Fixes #741

* fix: retry failed list_changed metadata publication (#742)

* fix: retry failed list_changed metadata publication

* docs: credit quifox for the list_changed retry fix

---------

Co-authored-by: Nico Bailon <[email protected]>

* fix: find git packages installed at a ref that contains a slash (#748)

* fix: find git packages installed at a ref that contains a slash

Pi splits a package source's ref at the first @ after the host, so a source such as https://host/acme/tools.git@release/v2 installs under host/acme/tools. The adapter only cut a trailing @segment without a slash, looked for host/acme/tools.git@release/v2, and skipped the package's MCP servers.

This also rebuilds the tracked dist/package-mcp-loader.js, which #746 left behind its source.

* ci: fail when tracked dist files do not match the sources

The published ./config and ./metadata-cache helpers load tracked dist/ files. #746 changed package-mcp-loader.ts without rebuilding them, and no check noticed. npm test already ends with build:public, so CI now fails when that build changes a tracked dist/ file.

* fix(cache): reject private metadata across sessions (#743)

* fix(cache): reject private metadata across sessions

* fix: keep output shapes from private listings out of the shared cache

Saved output shapes live on the shared cache entry, so rejecting private entries at startup was not enough: a shape observed under a private tool listing could still be saved and reach another session.

Each in-memory shape now records whether any observation merged into it was made under a private listing, checked both when the call starts and when its result arrives. Such a shape is used in the current session only and never saved, including after the listing turns public. A rewrite of a cache entry also no longer carries shapes out of an entry marked private.

* docs: credit quifox for the private cache scope fix

* fix: keep private session metadata out of public cache entries

When prompt or resource discovery fails, updateMetadataCache fills the entry from the current session's metadata. That entry may come from an earlier private listing, while the new entry takes the reconnected listing's scope, so private prompts or resources could be written to a public entry and reused by a later session. A private session entry now only fills an entry that is private too.

---------

Co-authored-by: Nico Bailon <[email protected]>

* feat: share one search core between mcp search and mcpScript (#749)

* feat: share one search core between mcp search and mcpScript

mcpScript's tools.search had its own copy of the search logic and had
drifted from mcp({ search }): regex: true was ignored, an empty query
with a server returned nothing, and scoped searches on a disabled or
backed-off server returned an empty page instead of an error. Scripts
also could not reach a tool whose name two servers share: tools.describe
returned the first match and tools.call failed as ambiguous, with no way
to pass the server a search hit returned.

findTools() is now the one search core, and resolveDescribeTarget() the
one describe lookup, used by both surfaces. tools.describe and
tools.call accept the hit's server. The README gains a "Composable tool
search" section and drops a stale claim that search includes Pi tools.

* fix: give scripts guidance they can follow for scoped describe and call errors

With the new server option, an unknown server or a name ambiguous on that server returned advice to use mcp(), which scripts cannot call. Script errors now point at tools.search. Also asserts that an invalid regex in tools.search returns invalid_pattern.

* fix: quote the server name in the scoped ambiguous-tool example

* docs: narrow the changelog claim and list the describe change as breaking

* docs: qualify when tools.describe reports ambiguous_tool

* fix: keep the server in mcpScript output-shape examples for shared tool names (#752)

When two servers share a tool name, as with toolPrefix "none", the
tools.call example in tools.describe's observedOutput.target and in the
fields listed after a failed or empty script dropped the server, so
copying it failed with ambiguous_tool. The footer also tracked called
tools by path alone, so calling the shared name on both servers kept only
the last server's shape.

The example now adds { server } only when an unscoped tools.call of that
path would not reach the described server, decided by the same exact-name
lookup executeCall makes first; unique names keep today's text. Called
tools are tracked by server and path, so each server gets its own section.

Closes #751

* feat: make Figma desktop the easy path and explain rejected OAuth registration (#750)

* feat(setup): offer Figma desktop MCP server when Figma is installed

* fix(auth): explain rejected client registration

* fix: explain unreachable local MCP servers

* fix(auth): explain rejected client registration during connect

* chore: rebuild dist for setup preset changes

* docs: surface Figma setup and rejected-registration troubleshooting

* fix(setup): describe the port check without claiming the server is ready

* feat: give /mcp-adapter setup a fixed-size two-pane layout (#753)

* feat: give /mcp-adapter setup a fixed-size two-pane layout

The setup overlay grew and shrank as the cursor moved because the preview,
notices, and a wrapped header paragraph all changed length. The panel now
derives its height from the terminal rows, groups actions into sections,
shows details beside the list (stacked below 72 columns), keeps notices in
fixed footer rows, and no longer word-wraps JSON diff lines.

* fix: fit /mcp-adapter setup into short terminals and show notices beside the list

Cap the body at 22 rows, use a one-row footer with key hints and Working…,
and drop the spacer rows and lower body floor to 3 so the frame and hints
fit down to about 10 terminal rows. Notices and preview errors now lead the
details pane so small panes still show them.

* fix: scroll long /mcp-adapter setup details and keep tiny panes readable

Details that don't fit now scroll with PgUp/PgDn (shift+up/down for one
line) with ↑/↓ N more markers, so a cut-off write diff can be read before
Enter writes it. Markers need a 3-row pane, so a 1-row pane still shows
the notice or error. The header counts servers only, and paths wrap by
grapheme width.

* fix(setup): keep the scroll hint visible in narrow footers

* refactor: tighten unreleased code, comments and tool copy (#754)

* chore(release): v4.0.0

* fix: explain refused Figma connections and keep desktop servers global (#755)

* fix: explain refused Figma connections and keep desktop servers global

* docs: note Figma setup fixes in changelog

* fix(setup): warn when an added server won't take effect

* docs: note setup precedence warning in changelog

* fix(setup): warn when an override disables an added server

* docs: mention disabled overrides in changelog

* fix(setup): stop naming a possibly wrong file in the setup warning

* docs: split the README into a short overview and docs/ reference (#756)

* docs: split the README into a short overview and docs/ reference

* docs: link the moved headless OAuth fallback

* docs: fix moved changelog link and check every README docs link

* feat: add a server description field (#760)

* feat: add a server description field shown in listings, search, and the panel

Refs #758

* fix: check imported server descriptions and keep listing descriptions on one line

* feat(cli): add pi-mcp-adapter doctor (#761)

* feat(cli): add pi-mcp-adapter doctor to check configured servers

Connects each enabled server the way a non-interactive session would and
prints its state, tool count, and error or hint (--json for an array).
Project servers follow Pi's project trust and per-server approval, OAuth
sign-in is reported from stored credentials and never started, secrets
and URL query strings are redacted, and every connection is closed
before exit. Exits 1 when an enabled server fails or needs a sign-in.

Refs #759

* fix(cli): redact short secrets and never acquire OAuth tokens in doctor

Redact every configured secret regardless of length, route debug stderr
through redaction, and drop the client_credentials exemption so doctor
never requests tokens without a stored sign-in. Trim docs and redundant
build includes.

Refs #759

* fix(cli): redact URL query values in doctor and keep short flags readable

Refs #759

* fix(cli): print only adapter-composed facts in doctor errors

Doctor no longer prints server-originated text: stdio failures drop the
child's stderr tail, and HTTP failures show only the status, network
error codes, the endpoint probe result, and a refused-connection hint
built from the configured URL with variables unexpanded. The 15 s
deadline now covers the whole check, including the follow-up probe, and
stored OAuth records without tokens count as a missing sign-in.

Refs #759

* feat: read Pi's own mcp.json files on Pi 0.99+ (#762)

* feat: read Pi's own mcp.json files on Pi 0.99+ (#757)

Add ~/.pi/agent/mcp.json and .pi/mcp.json as config sources right below
the mcp-adapter.json in the same folder, translated from Pi's server
format. Untranslatable entries and settings are reported once per file
and listed in /mcp-adapter. Off on Pi 0.84-0.87, in exclusive mode, and
outside the extension.

* refactor: tighten Pi mcp.json translation after review (#757)

Hidden toolExposure names that start with the server's tool prefix, and
hidden patterns, are now ignored and listed: excludeTools would also hide
other tools through their prefixed names. Carry Pi's description, which
the adapter now supports. Read each Pi file once for provenance, and say
'adapter config' in the panel's copy notice.

* fix: hide every tool Pi's mcp.json hides (#757)

Translate all hidden toolExposure entries, including server-prefixed
names, patterns, and names with '?', into excludeTools. It matches a
superset of Pi's hidden entries, so it can hide more than Pi but never
exposes a tool Pi hides. Docs no longer claim skipped entries appear in
/mcp-adapter.

* feat(cli): check Pi's own mcp.json files in doctor on Pi 0.99+

* feat: restart tool call timeouts on progress (#763)

* feat: restart tool call timeouts on progress notifications

* docs: note that task-augmented calls don't restart the timeout on progress

* build: regenerate dist for progress-aware timeouts

* fix(cli): print the doctor report before closing connections (#764)

* fix(cli): print the doctor report before closing connections

* fix(cli): close doctor connections even when printing the report fails

* feat: connect servers registered with pi.registerMcpServer() (#765)

* feat: connect servers registered with pi.registerMcpServer()

* fix: keep a Pi registration made during load over a later adapter registration

* fix: check Pi registrations against the active session's config

* docs: say re-registering replaces a server only when its config changes

* feat: offer to import sign-ins from Pi's built-in MCP (#766)

* feat: offer to import sign-ins from Pi's built-in MCP

* fix: import Pi sign-ins only without adapter credentials, from the current config

* fix: keep failed Pi sign-in imports available to retry

* build: update dist types for Pi sign-in import results

* feat: support auth.provider for HTTP MCP servers (#767)

* chore(deps): bump @earendil-works/pi-coding-agent devDependency to 0.99.2

* feat: send a Pi provider's token to HTTP servers with auth.provider

* fix: keep a malformed provider token out of connection errors

* fix: report needs sign-in when a provider token stops working mid-session

* fix: check env-interpolated auth.provider URLs once resolved

* build: regenerate dist after rebase

* fix: never replace adapter credentials saved while the Pi sign-in prompt was open (#769)

* fix: connect an overridden Pi server once the adapter registration is disposed (#768)

* fix: connect an overridden Pi server once the adapter registration is disposed

* fix: restore an overridden Pi server even when closing the adapter registration fails

* fix: keep invalid header credentials out of connection errors (#770)

* fix: keep malformed bearer tokens and header values out of connection errors

* test: build the malformed token newline inside node so it also works under cmd.exe

* feat!: replace Pi's built-in MCP extension in sessions (#771)

* feat!: replace Pi's built-in MCP extension by registering /mcp during load

* docs: shorten the README first-run row for Pi's built-in MCP

* fix: keep Pi's built-in MCP when a host supplies its own config

* feat: register search-mode tools as Pi deferred tools on Pi 0.99+ (#772)

* feat: register search-mode tools as Pi deferred tools on Pi 0.99+

* refactor: keep the direct tool execute in place and trim deferred-tool comments

* docs: note where allowedServers and Pi's tool_call hooks stop applying (#773)

* docs: compare Pi's built-in MCP with pi-mcp-adapter (#774)

* docs: compare Pi's built-in MCP with pi-mcp-adapter

* docs: add a tool search row to the Pi built-in comparison

* docs: tighten the Pi built-in comparison's startup, config, and transport cells

* docs: say only a missing metadata cache connects lazy servers at startup

* docs: limit the first-session connect to enabled, trusted servers

* docs: put the comparison with Pi's built-in MCP near the top of the README (#776)

* docs: compare pi-mcp-adapter with Pi's built-in MCP at the top of the README

* docs: keep Why This Exists and add the built-in comparison after it

* docs: drop the proxy token estimate from the comparison table

* docs: compare guided setup and server presets with Pi's built-in MCP (#777)

* test: fire mcpScript deadline tests once the call is in flight (#775)

* test: fire the semantic search deadline only once the search is in flight

* test: fire mcpScript deadlines only once the timed-out call is in flight

* test: report an early script result instead of hanging on the in-flight signal

* docs: show that Pi's codemode works with the adapter too (#778)

* docs: say what mcpScript reaches compared with codemode (#779)

* feat: turn off Pi's built-in MCP when the adapter is installed or updated (#780)

* feat: turn off Pi's built-in MCP when the adapter is installed or updated

* refactor: tighten the built-in MCP turn-off comment and changelog

* docs: say the adapter changes Pi's settings, not pi config

* test: skip the read-only settings test when running as root

* docs: compare tool search, including Jev semantic search (#782)

* fix: import materialized-resource cleanup statically (#781) (#784)

Runtime cleanup loaded tool-registrar.ts with a dynamic import during
teardown. Under Pi 0.99's jiti loader this failed with a TDZ ReferenceError
on scopedMaterializedResourceSessions, so every session shutdown logged
cleanup errors and materialized resource temp dirs were not removed.

tool-registrar.ts only imports Node built-ins, so a static import adds no
meaningful startup cost.

Reported-by: wu546526

* perf: build the direct-tool selector index once per resolve (#785)

resolveDirectTools rebuilt the same cross-server selector candidate index
for every server with includeTools or excludeTools. The index depends only
on config, cache, and prefix, so with 100 filtered servers x 50 tools the
pass took about 1 second. Build it lazily on the first filtered server and
reuse it for the rest of the call; output is unchanged (about 60 ms).

Refs #783

* fix: keep in-use servers from being idle-closed (#786)

* fix: keep in-use servers from being idle-closed

The idle check closes a server when nothing is in flight and its last use
is older than idleTimeout. Three kinds of use were invisible to it:

- Tool calls marked the server in flight only after approval, so an
  approval dialog left open past the idle timeout let the check close the
  server and the approved call failed (proxy, direct tools, and MCP UI
  app calls).
- An open MCP UI page heartbeats every 10 seconds, but the heartbeat only
  fed the UI watchdog, so UI actions returned 503 after the timeout.
- An accepted URL elicitation did not count as use, so the server could
  stop while the user finished the browser step.

Calls now mark the server in flight right after the final connected
check, and the existing try/finally covers the approval wait. Approval
errors still propagate unchanged. The UI heartbeat and URL elicitation
acceptance and completion touch the server.

Refs #783

* build: regenerate dist for the idle-close fix

* fix(cache): stop expiring tool metadata after 7 days (#787)

* fix(cache): stop expiring tool metadata after 7 days

The first session stamps every server's cache entry with the same time,
and only servers you use get restamped. A week later every unused
server's entry expired together, and nothing rediscovered plain lazy
servers, so rarely used servers dropped out of search for good.

Cached metadata now has no adapter age limit by default. An entry stays
valid until the server's config hash changes, a server-declared ttlMs
runs out (ttlMs 0 is never cached), or it is private; the next connect
refreshes it. isServerCacheValid keeps its public maxAgeMs parameter;
it now defaults to 0 (no limit), and an explicit cap still applies.

Refs #783

* fix(prompts): refresh stale cached arguments before rejecting a call

With the cache age cap gone, a prompt command can keep cached argument
metadata after the server drops or renames a required argument. The
handler rejected a missing required argument before connecting, so the
connect that would refresh the metadata never ran and the command kept
failing.

A rejection based on cached metadata now connects once and checks the
arguments again against the refreshed metadata; only that result
counts. A rejection based on live metadata is still final and does not
connect.

Refs #783

* perf: stop servers after startup discovery and write the cache once (#788)

* perf: close servers after startup discovery

The first session connected every enabled server to read its tools and left
them all running until the idle timeout, because idle checks only start after
initialization. Later sessions never discovered a server whose cached tools
were missing, so a server added after the first session stayed unsearchable.
Each discovered server also reread and rewrote the whole metadata cache file,
which takes seconds with many large catalogs.

Startup now decides per server: a server with valid cached tools loads from
the cache, and one whose entry is missing, from a changed config, corrupt, or
past a server-declared TTL is discovered once. Private entries are still not
discovered at startup. Each worker captures the catalog into the session
metadata, then closes plain lazy servers before freeing its slot; lazy-keep-
alive, idleTimeout 0, eager, keep-alive, and needs-auth connections stay
open. The pass saves its captured entries in one merged cache write before
the direct-tools bootstrap reads the cache, and the bootstrap no longer
retries servers that startup already attempted. The startup notice counts
only servers that stay connected.

Refs #783

* docs: say servers without cached tools start once at session start

The README, lifecycle docs, and Pi comparison said that only the first
session, before the cache file exists, connects servers to cache their tools.
Startup now does this for any server without valid cached tools and then
stops plain lazy servers.

Refs #783

* perf: try a server that fails startup discovery once per config

Discovering every server without cached tools at each start meant a server
that never produces an entry was retried every session: a server that hangs
cost 60 seconds of initialization and up to 30 seconds on the first MCP call,
and an OAuth server nobody signed in to warned at every start. Before, both
happened only in the first session.

A failed discovery now writes a marker entry for the server's current config
in the pass's single cache write. Later sessions skip a marked server at
startup and in the direct-tools bootstrap until its config changes or the
cache file is missing or corrupt; the first successful connect replaces the
marker with a normal entry. Cache consumers treat a marked entry like a
missing one. Temporary HTTP outages are not marked.

The startup discovery test now also checks search, direct tools, prompt
execution, and a resource read after discovery stops the server.

Refs #783

* refactor: trim startup discovery comments and changelog

Shorten comments and the changelog entry for startup discovery; no behavior
change.

Refs #783

* build: regenerate dist after rebase

* fix: keep newer cache entries when startup discovery saves

The startup pass saves every discovered entry in one write after all workers
finish. If another session saved a fresh entry for the same server during the
pass, that write replaced it with metadata captured earlier. Per-server writes
had the same last-writer-wins race, but the batch widened the window to the
whole pass.

The batched write now keeps an entry on disk whose cachedAt is newer than the
one being written, comparing against the file contents read at write time.
Failure markers take the pass start time, so they never replace an entry
saved during the pass. Single connects still overwrite as before.

The changelog now says the once-per-config skip applies to lazy and
lazy-keep-alive servers; eager and keep-alive servers still connect at every
start.

Refs #783

* fix: never let a startup failure marker replace a real catalog

The startup batch write kept whichever entry was newer. A newer failure
marker from another session could then drop the catalog this session just
captured, leaving the server unsearchable and skipped at startup until used.
A marker written over an older catalog for the same config, such as one whose
server-declared TTL had expired, replaced stale but real tools with nothing.
And a newer entry for a previous config could win over our capture for the
current config.

The batch write now follows one rule per entry: a marker is written only when
disk has nothing for the same config or only a marker, and a catalog is
skipped only when disk has a newer catalog for the same config. An entry for
another config is always replaced. Single connects still overwrite.

Refs #783

* fix: let a startup failure marker replace only an unchanged entry

febddf6b kept any same-config catalog over our failure marker. A server whose
catalog had passed its server-declared TTL and then failed discovery was
therefore retried at every start. A marker from a session on an old config
could also replace a catalog that a session on the new config saved during
the pass.

The startup batch write now receives the cache snapshot loaded at the start of
the pass. A failure marker is written only if the entry on disk is unchanged
since that snapshot, so it never destroys another session's write but does
replace an expired catalog nobody touched. A catalog is written unless disk
has a newer catalog for the same config, and it keeps output shapes another
session saved during the pass. Single connects still overwrite.

Refs #783

* docs: show how many MCP servers stay running, with measurements (#789)

* test: add a dev benchmark for idle MCP server processes and memory

Issue #783 claims the adapter keeps tools searchable without keeping
every local server running, and compares that with Pi's built-in MCP.
Nothing measured either side.

bench/server-memory.mjs starts 100 stub servers with 50-tool catalogs
in isolated temp directories, drives an adapter session (Pi 0.99.2,
loaded from the installed package) without a model, and samples live
server processes and RSS by matching the fixture path on the command
line. Scenarios: first session with no cache, cached session with an
idle stop and reconnect, Pi's built-in MCP, and one real
server-everything process. Results append to --out as they are
measured, and interrupting the bench stops everything it started.

tools-only-server.mjs gets an opt-in --tools N flag; its default
behavior is unchanged.

Refs #783

* docs: show how many servers stay running, with measurements

The README said only that idle servers stop after 10 minutes. It gave no
numbers, didn't say what keeps a server running or how far the timeout can
slip, and didn't say how this differs from Pi's built-in MCP, which keeps
every enabled server running for the whole session.

The README now has a short "Many servers, few running" section: the Pi
0.99.2 built-in vs adapter comparison for 100 local stdio servers, measured
process counts and memory (built-in: 100 running after 15 minutes; adapter
first session: at most 10 during discovery and 0 when ready, down from 100),
and pointers to lazy-keep-alive, idleTimeout 0, and rmcp-mux.
docs/configuration.md gains "How idle shutdown works", and the Pi comparison
row now covers stopping as well as starting. The bench script's header says
how to install the real server and how to read RSS.

Refs #783

* fix: make the memory bench touch only its own server processes

Cleanup killed and the sampler counted every process whose command line contained the fixture path, so a test or a second bench using the same fixture could be killed or miscounted. Stub servers now get a --bench-run=<pid> argument and only those are counted or killed. A scenario that failed also left its sampler polling, so the bench could hang instead of exiting with the error; cleanup now stops every active sampler.

* docs: show servers running in the README's built-in comparison (#790)

* docs: show servers running in the README's built-in comparison

The separate 'Many servers, few running' section repeated the comparison in its own format, mixed in version history and methodology, and was hard to scan. The difference is now one row in the existing comparison table plus one small measured table under it. The full measurements moved to docs/pi-builtin-comparison.md.

* docs: qualify the servers-running table and keep the measured unit

* ci: skip pull-request CI for docs-only changes (#793)

Every push to a PR that changed only Markdown ran the full typecheck and test suite, about four minutes, before the PR could merge. Docs-only PRs now skip the CI workflow; anything under .github/ still runs it, and pushes to main always run the full suite, so a README edit that breaks the docs-link test is still caught.

* docs: lead the README's built-in comparison with what you get by switching (#791)

* docs: list scripts with the other ways the adapter reaches tools

The README's 'How the model reaches tools' row named codemode scripts only for Pi's built-in, so the adapter looked like it had no scripts; its script support sat two rows down. The two rows are now one, listing the default, per-server options, and opt-in scripts for each side.

* docs: lead the built-in comparison with what you get by switching

A new user comparing the adapter with Pi's built-in MCP had to dig through a long table of equal-weight rows to find why the adapter is worth installing, and the summary paragraph named 'the MCP features the built-in doesn't handle' without saying what they are. The section now opens with four concrete outcomes: idle servers cost nothing, more servers work fully, tokens stay in the keychain, and servers install from one URL with no reload. The table gains a memory row and an 'Add a server' row, and pi mcp add is no longer listed as a built-in-only advantage.

* docs: qualify the startup memory row and the Tasks prerequisite

* docs: qualify the default idle stop, token store, imports, and OAuth install order

* docs: group the full built-in comparison and lead with what you get (#792)

* docs: group the full built-in comparison and lead with what you get

The full comparison with Pi's built-in MCP was one 20-row table in no particular order, opening with a summary that named advantages only in general terms. A new user couldn't find why the adapter is worth installing, and terms like elicitation and sampling had no explanation. The doc now opens with the same concrete outcomes as the README and groups rows under headings, with a short definition on each MCP feature. The startup row now says a failed discovery isn't retried at every start. Pi's Figma clientName aside is removed. All other facts and links are unchanged.

* docs: qualify the cached-tools memory claim and the Tasks prerequisite

* docs: say which settings retry a failed discovery, and when OAuth installs check tools

* docs: qualify the default idle stop, token store, imports, and OAuth install order

* docs: say plainly what server memory the adapter uses (#794)

* docs: say plainly what server memory the adapter uses

The README's memory row said 'None at session start once their tools are cached; only servers in use after that', which a new user can't parse. It now reads 'Only the 3 in use, then none once they're idle', matching the 100-servers-installed, 3-in-use setup measured below it. The built-in cell now also shows the 15-minute reading.

* docs: report measured server memory in GB and MB

Readers know GB, not GiB. The measured memory figures now use decimal units, converted from the raw MiB readings (6705 MiB = 7.0 GB, 5668 MiB = 5.9 GB, 70-71 MiB = about 74 MB). Exact technical limits such as the 16 MiB script budget stay in binary units.

* docs: show token cost and semantic search in the built-in comparison (#795)

* docs: show token cost and semantic search in the built-in comparison

The README said the adapter avoids context bloat but never compared token cost with Pi's built-in, whose default runs every MCP call as a codemode script. A measured head-to-head (78 runs, GPT and Claude) shows single lookups cost 10-33% less with the adapter's default, while bulk work costs up to 7x more unless scriptMode is on, which brings it level with codemode. The README now has a token row and a bullet saying both, and the full table and method are in docs/pi-builtin-comparison.md.

Semantic tool search was a bare 'optional semantic search with Jev'. It's now a benefit in both lists with its measured result: the right tool first in 10 of 11 requests against 5 for word search.

* docs: qualify the codemode comparison and add the token-cost benchmark

The token row and bullets said every built-in call is a codemode script, which is only the built-in's default; they now say so. The measured costs had no way to check them, so the benchmark that produced them is in bench/token-cost/: the two test servers, their fixture data, and a runner that drives headless Pi with the built-in, the adapter, and the adapter with scriptMode, then prints the medians. It is dev-only and not part of CI.

* fix(bench): match the published token-cost runs and check write targets

The default run also ran scriptMode on the single-call tasks, 12 runs the published method didn't include; the scripts setup now runs only the bulk tasks, so the default is the 78 published runs. The transcript check ignored the note title and the batch check allowed comments on issues that aren't stale; both now fail those runs. Rechecking the server logs of the published runs under the stricter checks changes no result.

* chore: trim dead test setup, duplicate tests, and restating comments (#796)

Several tests still set up state the code no longer reads: init.ts gets
the metadata cache through loadMetadataCache, so the mocked
getMetadataCachePath and the cache files written to disk in the
lazy-keep-alive and transient-startup tests did nothing. The progress
timeout test built UI handler state its fixture never uses.

Three tests repeated a neighbor's setup to check one more assertion.
The disposed-registration, same-server newer-catalog, and echoed URL
query cases are now folded into the tests that already build that
setup.

Some comments restated the code next to them, and the token-cost bench
header ran ten lines for what fits in five. The Pi sign-in import
prompt drops to two lines with the same content, and its no-adapter-
entry check is inlined instead of living in a one-line helper.

* fix: default project-server approval to don't allow (#797) (#798)

* docs: link the #781 contributor in the changelog (#799)

* chore(release): v5.0.0

* feat: add keyless Tavily Search setup preset (#800)

* feat: add keyless Tavily Search setup preset

Co-authored-by: Cursor <[email protected]>

* build: regenerate dist for Tavily preset

* docs(changelog): credit Tavily preset contributor

---------

Co-authored-by: Cursor <[email protected]>
Co-authored-by: Nico Bailon <[email protected]>

* fix: support Pi 1.0.0 (#801)

* fix: support Pi 1.0.0

Co-authored-by: Pi (gpt-6-luna) <[email protected]>

* docs: credit @lucascaro for Pi 1.0.0 support

---------

Co-authored-by: Lucas Caro <[email protected]>
Co-authored-by: Pi (gpt-6-luna) <[email protected]>
Co-authored-by: Nico Bailon <[email protected]>

* fix: keep SSE abort reachable through bearer/provider fetch wrappers (#802)

* fix: keep SSE abort reachable through bearer/provider fetch wrappers

createBearerCommandFetch and createProviderTokenFetch re-wrapped the SDK's request in
new Request objects. undici links a Request's signal to its source weakly, so once the
wrapper is garbage-collected, transport.close() no longer aborts the long-lived SSE GET.
Its socket stays referenced and keeps the process alive (pi -p never exits with a
keep-alive server that uses bearerTokenCommand).

Forward url+init with the caller's own signal instead, matching request-headers-command.ts.

* fix: preserve request settings in forwarded init; always close manager in SSE abort test

* docs: credit #802 in changelog

* build: regenerate dist for #802

---------

Co-authored-by: Nico Bailon <[email protected]>

* feat: add per-server openUi: false to keep a server's MCP App UIs closed (#804)

Refs #803

* fix: require the Pi peers the adapter imports at runtime (#806)

* fix: require the Pi peers the adapter imports at runtime

pi-tui and typebox are imported at module load, so hosts that import the package outside Pi's extension loader fail when npm skips them as optional peers. Pi-managed installs pass --legacy-peer-deps and are unchanged; type-only pi-ai stays optional.

Fixes #805

* test: catch subpath, side-effect, dynamic and re-export peer imports

---------

Co-authored-by: Nico Bailon <[email protected]>
Co-authored-by: quick_fox <[email protected]>
Co-authored-by: quifox <[email protected]>
Co-authored-by: Aboul Wahab Salifou Panga <[email protected]>
Co-authored-by: Djarid <[email protected]>
Co-authored-by: jasonh <[email protected]>
Co-authored-by: Shura <[email protected]>
Co-authored-by: Lakshya Agarwal <[email protected]>
Co-authored-by: Cursor <[email protected]>
Co-authored-by: Lucas Caro <[email protected]>
Co-authored-by: Lucas Caro <[email protected]>
Co-authored-by: Pi (gpt-6-luna) <[email protected]>
Co-authored-by: Nguyen Duong Minh Tam Dat <[email protected]>
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.

2 participants