[nissa-seru]

fetch_reference's failures now say what happened to the reference and what calling again can do, and save_recent_image says both where it tells the agent a reference can't be fetched. The eager fetch's and a script's fetch's log lines read the same account of what happened.

This is one of a series of pull requests that hold agent-framework's agent-facing errors to one bar: an error tells the agent how to fix what went wrong, or says plainly that nothing can be done. It follows #506, whose words for a reference's expiry and missing server it uses, and covers the reference fetcher (src/mcpl/reference-fetcher.ts) and the two tools that show its failures.

Problem

On main, fetch_reference hands the agent the fetcher's reason alone. For example:

What happened	main answers
The server answers 503	HTTP 503
A claim over the call's max_bytes	claimed 10000000 bytes exceeds fetch ceiling 1000
A download stopped at max_bytes	aborted: actual bytes exceeded ceiling at 65536
A reference on another origin	third-party origin (https://cdn.example.com != dialed http://127.0.0.1:8080); not fetched by this host
The fetch takes too long	fetch timed out or aborted
The workspace can't store it	no writable workspace mount to store the payload

• The agent isn't told whether calling again can work: a 503 may clear, a 404 won't until a fresh reference arrives, and another origin never will.
• Where a larger max_bytes would help, the agent isn't told how large, or that the server's budget caps it.
• Every failure to store reads no writable workspace mount, though the workspace may be missing or its write may have failed, and the log doesn't say which. A save that throws reaches the agent as the fetch's own error.
• save_recent_image gives the reason a fetch would be refused, and nothing about what could change it.
• A ws: reference on its server's own origin passes the scheme check, since an origin reads ws: as http:. fetch then refuses it before connecting, and the agent reads fetch failed.
• A reference whose address carries a user name or password passes the origin check, since an origin leaves them out. fetch refuses it before connecting, with a message that holds the whole address, password included. The agent reads that message as the fetch's error, and the host's log carries it for the eager fetch.

What changes

• Every failure is a clause and a remedy. The fetcher says what happened as a clause about the reference, and what calling again can do as a sentence of its own.
  • fetch_reference reads fetch_reference couldn't fetch "<ref_id>": <clause>. <remedy>.
  • save_recent_image reads It can't be fetched either — <clause>. <remedy>.
  • The eager and script-demand fetches log the clause.
• The remedies say what can work: trying again later, waiting for a fresh reference, passing a larger max_bytes (with the size it needs, and no more than the server's budget has left), asking whoever runs the host (to check its connection or its credentials for the server, raise or renew a spent budget, add back a server it no longer has, or correct a server's address), or that nothing will.
• The scheme check reads the reference's own scheme, so a ws: or wss: reference is refused before dialing.
• A reference whose address carries a user name or password is refused before dialing, in words that don't repeat them.
• The host's log says why a fetched payload wasn't stored, for each way the save can fail.

Code changes beyond the text

• FetchOutcome is a union. Its failure side carries error and remedy as strings, and each side declares the other's fields undefined, so callers read them as before. A failure path that gives no remedy doesn't compile.
• fix(mcpl): a reference from a server with no address says so when refused #518's Refusal carries { error, remedy } in place of { reason, ofReference }. ofReference let fetch_reference put reference before the reference's own phrases. Each clause now has its own subject, as in the reference is expired.
• The scheme check reads new URL(uri).protocol. The plaintext reference from a secure origin branch goes: origins compare with their schemes before it, so it never ran. A test pins that an http: reference from a server dialed over wss: is still refused, by the origin comparison.
• The origin check refuses a reference address with a user name or password, before the scheme check, so refusal() and the eager check refuse it too.
• A server address that doesn't parse is refused with a clause of its own, where it read server url does not parse, and a remedy naming whoever runs the host, who can correct it. The framework's resolver gives only an address its transport dials (fix(mcpl): a reference from a server with no address says so when refused #518), so this guards other resolvers.
• A claim past the host's own 256 MiB is refused for that first, before the server's budget, since nothing lifts it, not even a budget whoever runs the host raises. A download past it is stopped for it first in the same way, before the budget and a call's max_bytes.
• The budget's stop partway shows the server's running total, as the next refusal does, since other fetches through the server may have spent part of it.
• The save hook logs each null with why. The fetcher catches a throw from it, logs it, and answers as a storage failure.
• A thrown fetch's clause takes its cause's words, since fetch's own message is only fetch failed. Where the cause has no words of its own, as an AggregateError from a host whose every address refused, its attempts' stand in.
• noAddressReason reads as a clause.
• DEFAULT_FETCH_MAX_BYTES's comment says a call can lower it and nothing raises it, where it said it was overridable per server.
• fix(mcpl): a reference from a server with no address says so when refused #518's changelog entry, not yet released, quotes the no-address refusal's old words. It now quotes these, and this change's own entry doesn't repeat them.

Each message

main's text first, then the new clause, then its remedy. <x> marks an interpolation.

The remedies, by name:

• Later: Trying again later may work.
• Request failed: Trying again later may work; if it fails the same way, whoever runs this host can check its connection to the server.
• Fresh reference: Once a fresh reference to it arrives, fetching may work; until then, fetching it again won't.
• Nothing: Calling again won't change that.
• Budget: The budget doesn't renew on its own, so calling again won't change that unless whoever runs this host raises or renews it.
• Host ceiling: No max_bytes or setting lifts that limit, so calling again won't change it.

Before dialing

• No server delivered it: reference not tied to any server, so there's nowhere to fetch it from → it's not tied to any server, so there's nowhere to fetch it from. Fresh reference.
• A server this host no longer has: unknown server: <s> → this host no longer has the "<s>" server it came from. Calling again won't change that unless whoever runs this host adds that server back.
• A server with no address: no address: this host doesn't connect to server <s> over a network, so there's nowhere to fetch it from → this host doesn't connect to the "<s>" server over a network, so there's nowhere to fetch it from. Nothing.
• An address that doesn't parse: reference uri does not parse → its address doesn't parse as a URL. Nothing. The server's own: server url does not parse → the "<s>" server's address doesn't parse as a URL, so there's nowhere to fetch it from. Calling again won't change that unless whoever runs this host corrects the server's address.
• A user name or password in the address: fetch's own message, Request cannot be constructed from a URL that includes credentials: <the whole address> → its address carries a user name or password, which this host doesn't send. Nothing.
• Another scheme: scheme not allowed: <scheme> → its address uses <scheme>, and this host fetches only http: and https: addresses. Nothing.
• Another origin: third-party origin (<origin> != dialed <origin>); not fetched by this host → it points to <origin>, not to the "<s>" server's own address (<origin>), and this host fetches only from the server itself, where the server's address is its scheme and host as configured, such as wss://…, never its userinfo, path or query. Nothing.
• Expired: reference expired, and the two reference treated as expired, … → the reference is expired, the reference is treated as expired, …. Fresh reference.
• The server's budget is spent: per-server fetch budget exhausted (<used>/<budget> bytes); the budget doesn't renew on its own, … → this host's fetch budget for the "<s>" server is used up (<used> of <budget> bytes). Budget.
• A claim over the call's ceiling and over what's left of the budget: claimed <n> bytes exceeds what's left of the per-server fetch budget (<used>/<budget> bytes); … → it claims <n> bytes, more than the <left> bytes left of this host's fetch budget for the "<s>" server. Budget.
• A claim over the call's max_bytes: claimed <n> bytes exceeds fetch ceiling <m> → it claims <n> bytes, over the <m> bytes this call allows. Pass max_bytes of at least <n> to fetch it. Over the host's own 256 MiB, which is checked before the budget: it claims <n> bytes, over the 268435456 bytes this host fetches at most. Host ceiling.

Dialing and reading

• A redirect: redirect refused (HTTP <status>) — no redirect traversal → the "<s>" server answered HTTP <status>, a redirect, and this host doesn't follow redirects. Nothing.
• Another status: HTTP <status> → the "<s>" server answered HTTP <status>.
  • 408, 409, 423, 425, 429, and a 5xx other than 501 and 505: later.
  • 501 and 505, which say the server doesn't support the request: nothing.
  • 401: Calling again won't change that; whoever runs this host can check its credentials for the server.
  • 403: Once a fresh reference to it arrives, fetching may work; if that's refused too, whoever runs this host can check its credentials for the server.
  • The other 4xx: fresh reference.
• No body: no response body → the "<s>" server answered without any content. Fresh reference.
• The budget runs out partway: aborted: per-server fetch budget exhausted (<total>/<budget> bytes); … → this host's fetch budget for the "<s>" server ran out during the download (<total> of <budget> bytes), so it was stopped and nothing was kept. Budget.
• Past the call's max_bytes: aborted: actual bytes exceeded ceiling at <n> → the download had reached <n> bytes, past the <m> bytes this call allows, so it was stopped and nothing was kept. It's at least <n> bytes; a larger max_bytes, up to <k>, may fetch it. Here <k> is the host's ceiling or what the server's budget has left after these bytes, whichever is less. Where <k> is less than <n>, the budget is what binds, and the remedy says so and gives the budget's remedy. Past the host's own 256 MiB, which is checked first, before the budget and the call's max_bytes: the download had reached <n> bytes, past the 268435456 bytes this host fetches at most, so it was stopped and nothing was kept. Host ceiling.
• The digest doesn't match: digest mismatch (claimed <d>…, got <g>…) → the bytes that arrived don't match the reference's digest (<d>…, against <g>…), so they weren't kept. Trying again may work; if it fails the same way, fetching may work once a fresh reference to it arrives.
• The workspace can't store it: no writable workspace mount to store the payload → it was fetched, but this host couldn't store it in its workspace, so nothing was kept. Calling again is likely to fail the same way; whoever runs this host can see why in its log.
• The fetch takes too long: fetch timed out or aborted → it took longer than <n> seconds. Later.
• The request fails: the error's own message, usually fetch failed → the request to the "<s>" server failed: <its cause>. Request failed.

What each part is for

This change exists so that an agent whose fetch failed knows whether calling again can work, and what it would take.

• The clause and the remedy apart: the clause is true wherever it's read, the log lines included, and the remedy is for whoever can call again. save_recent_image shows both. None of the remedies its refusals reach names a call's own max_bytes, since fix(mcpl): a reference from a server with no address says so when refused #518's refusal() uses the host's ceiling.
• The union: without it, a failure path with no remedy would end the agent's sentence on undefined, and nothing would say so until an agent read it.
• statusRemedy: one function from a status to what a later call can do, so each status class has one answer.
• largerMaxBytes: a larger max_bytes is offered only up to what can be fetched, so the agent isn't sent to try a size the budget then refuses.
• configuredOrigin: the origin clause names the server's address as whoever runs the host configured it. URL's own origin reads null for a scheme that isn't special, and the normalized origin the comparison uses reads wss: as https:.
• whyFetchFailed: without it, every network failure reads fetch failed.
• The save hook's log lines: the storage remedy sends the agent to whoever runs the host, who needs to know why.
• The scheme check on the reference's own scheme: without it, a ws: reference is dialed, fails, and the agent is told a later try may work.
• The check for a user name or password in the address: without it, the password reaches the agent's context and the host's log in fetch's message, and the agent is told a later try may work.
• Not taken:
  • One remedy for every failure, such as calling again may not help. It would leave the agent where main does.
  • Naming fetch_reference in the remedies. The fetcher serves the eager pass and scripts too, and save_recent_image shows its remedies.
  • Keeping ofReference. Each clause carries its own subject.
  • Sending the agent to whoever runs the host for a server with no address. A stdio server has no address to give, so there's nothing to ask for.

What callers will notice

• Every text above changes. In this repository, the tests that pinned them take the new texts.
• I searched the default branches of connectome-host, discord-mcpl, slack-mcpl, context-manager, membrane, connectome-smoke, chronicle, portal, eidoverse-worlds, mcpl-core-ts and mcpl for the old texts. Two strings match, and neither reads the fetcher's: context-manager's kv-unified exact label propagation exceeded ceiling … and membrane's OpenAI Responses API returned no response body.
• FetchOutcome is a union, and Refusal has error and remedy in place of reason and ofReference. Neither is exported from the package's entry point.
• The host's log gains a line for each payload it fetched but couldn't store.
• A ws: or wss: reference on its server's own origin is refused before dialing.
• A reference whose address carries a user name or password is refused before dialing, and the words don't repeat them.

Left as it is

• fetch_reference's answer for an id with no record, unknown reference: <id> — it may have been evicted; ids are never reused, is the framework's own, and its part of the series rewords it.

Tests

These ran on Linux x86_64 with Node 24.22.0. CI runs the suite and its Node matrix on this pull request.

• At this head: typecheck and the build are clean, and these pass: mcpl-reference-fetcher 65, mcpl-reference-binding 8, save-recent-image 46, tool-result-reference-uri 20, mcpl-reference-fields 16, mcpl-agent-words 13, tool-presentation 13 and mcpl-ws-transport 13.
• Red first: this change's tests against main's source (0a7fd161) fail 38 of 65 in mcpl-reference-fetcher, 1 of 8 in mcpl-reference-binding, 3 of 46 in save-recent-image and 1 of 20 in tool-result-reference-uri. Every test this change adds or changes is among them. The one that pins an http: reference from a server dialed over wss: fails there only for its words: its refusal, by the origin comparison, holds on main too, and it stays to guard that comparison.
• What the new tests cover, in test/mcpl-reference-fetcher.test.ts:
  • each status class's remedy, 409, 423 and 425 among them, and an answer with no content;
  • a refused connection, whose clause carries the cause's words, and a cause with no words of its own, through a stand-in fetch whose rejection has an AggregateError cause, each with the failed request's remedy;
  • a save hook that throws, which is a storage failure with one log line, its cause bounded to one line;
  • an address that doesn't parse, the reference's or its server's, each with its own clause and remedy;
  • a download stopped at max_bytes past what the budget has left, which is told the budget is the limit, with the bytes it reached pinned between max_bytes and what the server sent;
  • the order of the refusals before dialing: a server fault ahead of a claim past the host's own ceiling, and that claim ahead of a spent budget;
  • a server configured on a scheme that isn't special, with userinfo, named in the origin clause by its scheme and host;
  • ws: and wss: references on their server's own origin, refused before dialing, and an http: reference from a server dialed over wss:, refused as another origin;
  • a reference whose address carries a user name and password, a user name alone or a password alone, refused before dialing by refusal(), the eager check and the fetch, with nothing dialed;
  • a payload fetched but not stored, through the framework's own fetcher and fetch_reference, with the host's log line for each way the save hook returns nothing: no workspace, no writable mount, a failed write.
• test/mcpl-reference-binding.test.ts checks fetch_reference's whole sentence through the framework for the refusals it reaches there.

Not verified

• The stop for a download past the host's own 256 MiB, its clause and its place before the budget in the read loop. No test reaches it, since a download would have to pass 256 MiB. It's read from the code; a claim past it is tested, in the same order.
• The AggregateError cause is a stand-in's. That Node's fetch rejects with such a cause when every address of a host refuses is from reading Node's net, not from a run.
• How each text reads to a model in a live turn. The tests check the text and the case it's reached in.

Merge order

A scan of the open pull requests at 17:02 UTC on October 18, at this head on main e5f50bf3, found 53 others.

• One merges onto main and conflicts with this one: fix(tool-results): show each block of a content array, never the array's JSON #527, at 1dc2c9ea, in reference-fetcher.ts and references.ts. It moves the checks this change rewords before dialing into references.ts, as dialServer and dialCheck, with Refusal and normalizedOrigin, and keeps fix(mcpl): a reference from a server with no address says so when refused #518's refusal shape, { reason, ofReference }. This change's refusal is { error, remedy }.
• 11 merge cleanly with both, and 41 conflict with main already. Of those 41, feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262 and feat(mcp): MCP servers on the 2025 revisions over Streamable HTTP #337 change references.ts, and none changes reference-fetcher.ts.

Who did what

The texts follow Phoebe-2419's sweep of agent-framework's agent-facing errors. Pippa-2571 and I agreed the clause-and-remedy shape across this change and #518, and Ada-1017 made the design calls. Our internal review read the change at de7741c5, and b9e51557 answers it. A second read it through fb480d97, and ab59c2d7 answers it. Pippa-2571 read it whole and each round after, and her probe found that a password in a reference's address reached the agent in the fetch's error; fb480d97 refuses such an address. I built and tested it.

---

• Changelog fragments added: changelog.d/fetch-reference-words.changed.md and changelog.d/fetch-reference-credentials.fixed.md, and fix(mcpl): a reference from a server with no address says so when refused #518's changelog.d/no-address-server-refusal.fixed.md updated

Written by Cordelia-2434 (Claude Opus 5.5).

Description checked and posted by Daniel-2612 (Claude Opus 5.5).

🤖 Written using Anthropic's Claude Opus 5.5 through the Rookery's Pi tooling, and posted from the shared nissa-seru account.

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable issues were found.

Summary

Adds a reason and a next step to fetch_reference and save_recent_image failures.

• Fetch failures explain what happened and what can help next.
• Reference addresses with credentials or unsupported schemes are refused before dialing.
• Failed reference saves tell the host why storage did not work.

_{Reviews (1) · Last reviewed commit: "fix(mcpl): stop a download past the host..." · Reviewed by Greptile}