[nissa-seru]

The MCPL errors an agent reads for a failed request or a refused tool call, and the markers for blocks the host can't show, now say what happened, whether anything took effect, and what works from there, or plainly that nothing does. Method names, request ids, JSON-RPC codes, close codes and field names leave the agent's text, and the ones an operator needs go to the host's log.

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 covers three parts of the MCPL lanes. The channel tools' own wording and fetch_reference's stay as they are. Where a channel tool passes on a failed request's text, it now passes on the new one.

Problem

An agent has only an error's text to go on. On main, these texts name the problem in the host's terms and stop there:

What happened	main answers
An MCPL tool call pending when its server drops	MCPL server "discord" disconnected unexpectedly (code=1006, signal=n/a, reason=unknown) while awaiting tools/call (id=12)
An MCPL tool call that times out	MCPL server "discord" did not respond to tools/call (id=12) within 60000ms — the server may be hung. The response outcome is unknown: …
A tool its server's policy denies	Tool 'discord--ban' is not permitted by this server's tool policy.
A tool's error result with no text	Tool call failed
An image block that arrived without data	[Image: no data]
A reference whose expiry time won't parse	treated as expired: its expiresAt does not parse (fail closed)

• In the first row, whether the call ran is unknown, and the agent isn't told. The close's code, signal and reason are for an operator.
• In the third and fourth, the agent isn't told whether calling again can work, or whether anything happened.
• The markers say what's missing in the host's terms, and some don't say why.

What changes

• A failed MCPL request (src/mcpl/server-connection.ts), the whole of what an agent reads for an MCPL tool call:

  • A connection that closes with a call pending leaves the outcome unknown. Where this host is reconnecting, the agent is told to check before trying again. Where it isn't, the agent is told to ask whoever runs the host. This covers both a server that drops and this host recycling the transport after a failure (reconnectAfterFailure).
  • This host's own close of the connection leaves the outcome unknown too. That text doesn't say whether the host reconnects, since a restart closes the connection and then connects again.
  • A request on a closed connection wasn't sent, so nothing ran. The agent is told to try again later, or, where this host won't reconnect, to ask whoever runs it. After this host's own close, which a restart makes as well as a removal, it's told that this host closed the connection, and to ask whoever runs it if calling again fails. A request the transport couldn't write wasn't sent either, and the agent is told to try again later.
  • A server's error answer is shown in the server's own words. With none, the agent is told so, and that whether the request took effect is unknown.
  • A timeout leaves the outcome unknown. The request was abandoned here, not cancelled, and may still complete on the server.

• The framework's MCPL tool calls (src/framework.ts):

  • A call refused before it runs says it didn't run, and whether anything can change that. That covers a server missing from the registry and a tool its policy denies. A call made while this host is connecting to the server, in a runtime connect or a restart's, is told to try again in a moment.
  • A tool's error result with no text, or only whitespace, says its effect is unknown, on each path a tool call takes.
  • A conversation bound to its channel is told it can't open another, and where to reply.

  A script's call is refused in the same words as the model's.

• Blocks the host can't show read as what kind of thing they were and why: [Image not shown: …], [Audio not shown: …], [Reference not shown: …], [Content not shown: …]. Each marker is one constant, read by every lane that shows it. Which blocks reach a marker on the tool-result lane is that lane's own rule, as on main (see "Left as it is"). An image or audio block with an empty link and no data reads as the no-data marker on every lane. The text marker reads [Text not shown: a text part arrived without readable text.].

• A reference's expiry and missing server read in the agent's words, in its stub and in the refusals that name them.

Code changes beyond the text

• The connection logs what the agent's text no longer carries. Each of these goes to the log:

  • a close with requests pending, with the close's code, signal and reason, and whether this host closed it;
  • this host's own close with requests pending;
  • a server's error answer, with its method, id and code;
  • a timeout, with its method, id and milliseconds;
  • a request the transport couldn't write, with its method, id and the transport's words.

  Each close line lists the requests left unanswered, by method and id. An idle close logs nothing new. The reason is printed as main prints it, so a WebSocket peer's own close text stays out.

• fix(mcpl): contain inbound request handler failures #208's bound and fix(mcpl): a server's error result is a failure on each path a tool call takes #490's shared failure keep their mechanisms. A server's words in an error answer are bounded with boundedForLog, as fix(mcpl): contain inbound request handler failures #208 set, and its code goes to the log line, which logValue prints for any value without throwing. An error result with no words takes this change's text inside fix(mcpl): a server's error result is a failure on each path a tool call takes #490's mcplToolFailure, which now takes the server's id and the tool's called name, and reads whitespace alone as no words, as a server's error answer does.

• feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247's McplRequestError keeps its class, its outcome and an error answer's data on each rejection, with this change's words as its message. Its publish outcome composes the connection's message into a sentence of its own, so publishErrorOutcome first drops one final period from this host's own words for a request not sent or not answered. A server's error answer keeps its words as they came.

• Helpers in framework.ts give the model's dispatch and a script's call (executeMcplToolCall) the same words: mcplToolDeniedText for a denied tool, and for a server missing from the registry mcplServerAbsentText, which picks mcplServerConnectingText or mcplServerGoneText. On main the two paths worded a missing server differently.

• mcplConnecting holds the servers whose connect is in flight. connectMcplServerInternal maps a server's tool prefix before it awaits addServer, and addServer puts the server in the registry only once its handshake is done. So a call in between, from an inference that began before a restart or from a script, found no server. An id goes in just before addServer and comes out when it settles, either way. A connect that fails without reconnect then reads as gone. One with reconnect leaves a stub in the registry, and its closed connection answers. There's one mark per id, since the registry holds one connection per id.

• A connect in flight holds its server's id. fix(mcpl)!: refuse toolPrefixes that meet, so one tool name has one server #469's refuseMcplConnect refuses a runtime connect, or a restart, into an id another server already has, but the registry takes a server only once its handshake is done, and nothing stops a connect in flight. So a second connect of that id went ahead beside it, and by our reading of addServer, whichever settled last replaced the other in the registry without closing it. A disconnect removed the server's config and tool prefix, and the connect then registered the server without them. refuseMcplConnect now counts an id in mcplConnecting as taken, both the one being connected and the one a restart replaces, and runDisconnectMcplServer refuses such an id too, each before it changes anything. The refusal reads MCPL server "<id>" has a connect in flight; try again once it settles. Whoever asked reads it: an operator, or an agent through connectome-host's mcpl_deploy, mcpl_restart or mcpl_unload, which quote the error.

• The connection records its own close (closedByThisHost), so a request after it says this host closed the connection, where it said the host won't reconnect. A restart closes the connection before it connects again, and a removal closes it for good, and the connection can't tell which. Calling again then reaches the restarted server, or fails where the server is gone, so the text says whom to ask if it fails.

• classifyBlock's invalid kind carries shown, the text referenceStubOrNull returns for it, in place of its reason, which only that stub read. unknownBlockText takes the whole block:

  • what isn't an object reads as unreadable;
  • a type that isn't a string reads as no type, as does one that sanitizes to nothing;
  • a string type reads as a sanitized label.

  The markers are constants beside INLINE_WITHHELD_TEXT, which every lane already used.

• An image or audio block with an empty uri and no data is classified as having no link, so it reads as the no-data marker, as the push lane's converter already read it, where the tool-result lane read it as a reference without a link. Beside inline data, any string uri, an empty one included, stays the contradiction it is on main, and classifyBlock's comment says why: the tool-result lane can't yet show every inline shape, and reading '' as no link there would put inline audio, or an image with no media type, into history as raw JSON.

• mediaWithoutStringReason goes. It came with fix(tool results): keep an RFC-005 reference's uri out of JSON at any depth #425, and named on the tool-result lane which field of a media block wasn't a string. With the markers, such a block reads as having no usable data or link, as the push lane already read it. An agent can't fix a server's field either way.

Each message

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

A failed MCPL request (src/mcpl/server-connection.ts)

• The connection closes with a call pending: MCPL server "<s>" disconnected unexpectedly (code=…, signal=…, reason=…) while awaiting <method> (id=N) → The connection to the "<s>" server closed before it answered, so whether the request took effect is unknown. Check its effect before trying again; this host is reconnecting to it. Without reconnect, the second sentence is This host won't reconnect to it on its own. If you need it, ask whoever runs this host.
• This host closes the connection with a call pending: Connection to MCPL server "<s>" closed while awaiting response for <method> (id=N) → The "<s>" server didn't answer before this host closed its connection, so whether the request took effect is unknown. Check its effect before trying again.
• A request on a closed connection: Cannot send request: connection to "<s>" is closed → The request wasn't sent: the connection to the "<s>" server is closed, so nothing ran. This host is reconnecting to it; try again later. Without reconnect: … This host won't reconnect to it on its own. If you need it, ask whoever runs this host. After this host's own close: The request wasn't sent: this host closed its connection to the "<s>" server, so nothing ran. If calling it again fails, ask whoever runs this host.
• A request the transport can't write: Cannot send <method> to MCPL server "<s>": <transport error>, from feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247 → The request wasn't sent: this host couldn't write it to the "<s>" server, so nothing ran. Try again later.
• The server answers with an error: MCPL server "<s>" returned error for <method>: [<code>] <message> → The "<s>" server answered with an error: <message>. With no message: The "<s>" server answered with an error without saying what went wrong, so whether the request took effect is unknown. Check its effect before trying again.
• The server doesn't answer in time: MCPL server "<s>" did not respond to <method> (id=N) within Nms — the server may be hung. The response outcome is unknown: … → The "<s>" server didn't answer within <n> seconds, so whether the request took effect is unknown: it was abandoned here, not cancelled, and may still complete on the server. Check its effect before trying again, since repeating something that changes state may do it twice.

The framework's MCPL tool calls (src/framework.ts)

• The server isn't in the registry (the model's call, and a script's): MCPL server not found: <s> / MCPL server <s> not found → The "<s>" server that provides <tool> isn't connected, and this host won't reconnect to it on its own, so the call didn't run. If you need it, ask whoever runs this host. A server leaves the registry only when it closes with no reconnect to come or is removed, and one whose connect failed without reconnect never joins it. One that's reconnecting stays registered, as does the stub a failed connect with reconnect leaves, and its closed connection answers instead. A server joins the registry once its handshake is done. While this host is connecting to it, in a runtime connect or a restart's, the call reads This host is connecting to the "<s>" server that provides <tool>, so the call didn't run. Try again in a moment.
• The host's tool policy denies the tool: Tool '<tool>' is not permitted by this server's tool policy. → <tool> isn't allowed by this host's policy for the "<s>" server, so the call didn't run, and calling it again won't change that. If you need it, ask whoever runs this host.
• An error result with no text, or only whitespace: Tool call failed, or the blank text → The "<s>" server reported an error for <tool> without saying what went wrong. Whether it did anything is unknown: check before calling it again.
• A conversation's channel_open: This conversation is bound to channel <home>; conversation agents cannot open channels. → This conversation is bound to channel "<home>", so it can't open other channels, and nothing was opened. Reply in "<home>".

Blocks the host can't show (src/mcpl/references.ts, convert-block.ts and visible-content.ts)

• [Image: no media type] → [Image not shown: its data arrived without a media type.]
• [Image: no data], and on the tool-result lane [unrecognized content block: image block with neither data nor uri] or … whose uri isn't a string → [Image not shown: it arrived with no usable data or link.]
• [Audio: no media type] → [Audio not shown: its data arrived without a media type.]
• [Audio: no data], and on the tool-result lane [unrecognized content block: audio block with neither data nor uri] or … whose data and uri aren't strings → [Audio not shown: it arrived with no usable inline data.]
• [unrecognized content block: <type>] → [Content not shown: this host can't display "<type>" content.]. With no type: [Content not shown: a part arrived with no type.]. For something that isn't a block at all: [Content not shown: a part arrived in a form this host can't read.]
• [unrecognized content block: reference without string uri] → [Reference not shown: it arrived without a link.]
• [unrecognized content block: uri exceeds schema maximum] → [Reference not shown: its link is longer than this host accepts.]
• [inline content withheld: inline data that also claims a uri or a bulk disposition] → [Content not shown: its inline data arrived marked as a reference too, so this host withheld it.]
• [Text not shown: the server's text block had no string text.] → [Text not shown: a text part arrived without readable text.]

A reference's expiry and missing server (src/mcpl/references.ts)

These appear in a reference's stub, and in fetch_reference's and save_recent_image's refusals.

• expired: its expiresAt has passed → expired
• treated as expired: its expiresAt does not parse (fail closed) → treated as expired, since its expiry time can't be read
• treated as expired: its expiresAt was rejected as a field, over 64 characters or not a string (fail closed) → treated as expired, since its expiry time isn't in a form this host accepts
• unbound: no server is recorded to fetch it from → not tied to any server, so there's nowhere to fetch it from

What each part is for

This change exists so that an agent reading one of these texts knows what happened, whether to check before retrying, and whether anything it does can help.

• The connection's texts, and the log lines beside them: the agent needs whether its request took effect and whether the server is coming back. The operator needs the method, id, code and close details, which the log keeps. The two close lines share one helper for the unanswered requests.
• The empty-answer branch: without it, a server that answers an error with no message would end the agent's text on a colon, and leave the agent nothing to go on.
• One text for a close by the server or by this host: the agent's next step is the same either way, so one sentence that's true of both stands in for a branch. Only the log tells them apart, and it keeps the close's details either way.
• The framework's helpers: each is one sentence, used where the model's call and a script's call are refused, so the two can't drift as they had on main.
• The in-flight set: without it, a call during a runtime connect or a restart's is told the server is gone and sent to whoever runs the host, for something that settles in moments. It's one set, written around addServer and read in one method.
• The connection's record of its own close: one flag, so a request after a restart's close isn't told the host won't reconnect.
• The in-flight checks, in refuseMcplConnect and runDisconnectMcplServer: one check in each, at the top of what every runtime connect, restart and disconnect already runs, so none of them can leave a server registered twice over or without its config. One helper gives both the refusal's words.
• One final period off this host's words in a publish's reason: without it, channel_publish's answer would read "… try again later.. Nothing was posted.", since feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247 composes the reason into a sentence of its own. It's one condition and one replace, in publishErrorOutcome.
• shown in place of reason: the reason existed only to be formatted into the stub's marker. Carrying the marker itself puts each block's words in one place, the constants, which every lane reads.
• The empty-link classification: it makes the tool-result lane agree with the push lane about a block with no data, at the cost of one condition.
• Not taken:
  • Reading an empty link as no link beside inline data too. On the tool-result lane it sends inline audio, or an image with no media type, into history as raw JSON with its data, taking any image in the same result with it, where main withholds the block.
  • A separate text for a close this host made to recover. The agent would act no differently on it.
  • Naming the request's method in the agent's text. An MCPL tool call's own name is what the agent called, and the method is the host's word for it.
  • Dropping the final period from every reason. A server's error answer is its own words, which feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247 keeps as they came.
  • Putting a server in the registry before its handshake is done, so that its connection would answer the call. Every reader of the registry would then meet servers that haven't finished connecting.

What callers will notice

• Every text above changes. Anything that matches one of them whole sees the new form. 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, and none of them reads one.
• The host's log gains the lines above.
• A runtime connect, a restart or a disconnect of a server whose connect is still in flight is refused with MCPL server "<id>" has a connect in flight; try again once it settles, where it went ahead.
• McplRequestError's message is now one of these texts. Its outcome and data are as feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247 set them.
• Wherever the host passes on a failed publish's reason, such as channel_publish's answer, a draft's account and the failure marker on the agent's speech, it carries these texts, with no doubled period.
• The awareness outbox's lastError for a reaction call that times out now holds the new timeout text. Its lastAction still names the action.
• On the tool-result lane, an image or audio block with an empty link and no data reads as the no-data marker, where it read as a reference without a link. One whose data or link isn't a string reads the same, where its marker named the field.
• BlockClassification's invalid kind has shown in place of reason. Neither classifyBlock nor the type is exported from the package's entry point.

Tests

These ran on Linux x86_64 with Node 24.22.0. CI runs the suite and its Node matrix at the push.

• At this head, the merge with main 9e3e407c: typecheck and the build are clean, and these pass, 1,472 tests in all: stop-ends-awareness-drains 6, mcpl-agent-words 13, mcpl-iserror-failure 5, mcpl-request-outcome 8, publish-outcome 34, prose-drafts 87, mcpl-late-render 7, mcpl-request-timeout 8, reaction-baseline-platform 8, mcpl-runtime-lifecycle 11, mcpl-coalescing 70, stop-with-host-operations 58, placed-reaction-baseline 49, boot-state-read-errors 33, mcpl-awareness-barrier 34, mcpl-tool-resolution 13, mcpl-reconnect-reregistration 4, mcpl-tool-lifecycle-e2e 4, mcpl-coalesced-content-parity 29, mcpl-capability-scoping 15, mcpl-config-booleans 8, mcpl-reconnect-events 4, mcpl-request-handler-errors 80, mcpl-stderr-tail 19, mcpl-transport-close 12, mcpl-transport-spawn 4, mcpl-ws-transport 13, shutdown-errors 29, tools-observe-parser-conformance 10, conversation-routing 28, mcpl-push-convert 6, mcpl-reference-fields 16, save-recent-image 46, mcpl-reference-fetcher 56, tool-result-reference-uri 20, mcpl-reference-binding 8, tool-result-history 19, mcpl-prefix-rule 14, mcpl-prefixes-meet 1, agent-allowed-tools 68, cancel-surfaces-as-error 23, puppet-tool-call 10, repeated-agent-names 7, route-failure-targeting 49, same-round-think-policy 19, stop-step-throws 18, stop-with-work-in-flight 39 and workspace-three-way 350.

• test/mcpl-agent-words.test.ts (new) covers:

  • the markers' words, which the other tests take from the constants;
  • references that can't be read, something that isn't a block, a type that sanitizes to nothing, an empty link with no data on both lanes, and inline audio beside an empty link, which stays withheld;
  • the connection's failures, against a stdio server that answers with an error, answers one with no message, exits with a call pending, or never answers. The drop runs with reconnect and without, and a recycle by this host and a request after this host's own close run too. The log lines are checked too;
  • the framework's refusals, through a framework built from its prototype, on the model's path and a script's. Among them are calls while this host connects to a server, with its handshake held, to that server and to another missing one, and calls after a connect that succeeds and after one that fails. With a handshake held too, refuseMcplConnect refuses a second connect of that server, a restart of it, a restart of it into another id, and a restart of another server into its id. runDisconnectMcplServer refuses a disconnect of it, which leaves its prefix. After the connect settles, refuseMcplConnect leaves a restart to go ahead.

• fix(mcpl): contain inbound request handler failures #208's and fix(mcpl): a server's error result is a failure on each path a tool call takes #490's tests take these texts: an error answer's message stays bounded, its code is checked in the log line, and an error result with no words reads this change's text on each path.

• feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247's tests take them too: its request outcomes, with the transport's words for a write it refused checked in the log line, and the deadlines of channels/open and channels/publish. Its drafts' unconfirmed marker reads the timeout's sentence, and publish-outcome checks that a sentence-shaped message composes without a doubled period. fix(mcpl): a late push/render answer is recorded, and a paused plane doesn't hold it (#398) #505's late-render test reads push/render's timeout as the same sentence.

• fix(stop): every teardown step runs whatever an earlier one did, and stop() ends awareness drains #517's test that stop() waits for a Discord awareness drain matches this change's words for the call that closing its server ended, didn't answer before this host closed its connection.

• Red first: at a3ecde00, its 16 test files against main's source fail 44 tests. references.ts there carries six stubs, the names the new tests import, set to main's texts:

  • 10 of 11 in mcpl-agent-words;
  • 6 of 20 in tool-result-reference-uri;
  • 5 of 7 in mcpl-request-timeout, and 5 of 29 in mcpl-coalesced-content-parity;
  • 3 of 5 in mcpl-iserror-failure;
  • 2 each in mcpl-transport-close, mcpl-tool-resolution, mcpl-reference-fetcher and mcpl-request-handler-errors;
  • 1 each in mcpl-ws-transport, mcpl-awareness-barrier, mcpl-tool-lifecycle-e2e, conversation-routing, mcpl-push-convert, mcpl-reference-fields and save-recent-image.

  Each fails on what it asserts. The new test that passes there, that a close with nothing pending logs nothing, is a control.

• The rounds' red first: 7b10c6da's tests against a3ecde00's source fail one test, the connect window's. 88bf0ff7's against 7b10c6da's fail one, the request after this host's own close. 6975a5bf adds one sentence to that request's text, and its removal piece below shows the tests pin it. 8cc1a756's tests against its merge's source (689395e6) fail one test, the in-flight refusal's, and 6b8bbc70's against eb0db7a6's fail the same test, for the disconnect. The rounds' other new checks pass there, since they pin what the code already did, and their removal pieces below show each one catches something.

• Each piece removed on its own fails at least one test, 45 of 45. Each was run at a head after which nothing changed its code or a test that catches it, or merged main's changes into its file. 21 are at this head: those in framework.ts, references.ts and channel-registry.ts, into which the merge with 9e3e407c brought main, and two in server-connection.ts that mcpl-ws-transport, which main changed, catches. 7 are at 6975a5bf: those in server-connection.ts whose code or catching test that head changed or that were last run before the merge with 6dfea06f. The other 17, in server-connection.ts, are at b2f525fd, that merge:

Piece	A test that fails without it
The log line for this host's close with requests pending	a call pending when this host closes the connection says the outcome is unknown, and the log names it
That line only when requests are pending	a connection that closes with nothing pending logs nothing new, by this host or by the server
The log line for a close with requests pending	a server that drops with a call pending …; a call pending when this host recycles the connection …; a server's close reason stays out of the error a pending request is rejected with, and out of the log
That line only when requests are pending	a connection that closes with nothing pending logs nothing new …
The log saying this host closed it, on a recycle	a call pending when this host recycles the connection reads as a closed connection, and the log says the host closed it
The close's code, signal and reason kept on a recycle	the same
A request on a closed connection naming whether this host reconnects	a server that drops with a call pending says the outcome is unknown, and whether it's coming back
Its remedy where this host won't reconnect	the same
A close with a call pending naming whether this host reconnects	a server that drops …; a call pending when this host recycles …
Its remedy where this host won't reconnect	a server that drops …; a server's close reason stays out of the error …
The error answer with no words	a server's error answer is shown as the server's, and its method, id and code go to the log
Its saying the outcome is unknown	the same
The error answer's log line	the same; a server's error answer that no template can convert settles the host's request …; a server's error message in the error a host request rejects with is bounded …
The server's words bounded, as #208 set	a server's error message in the error a host request rejects with is bounded …
The timeout's log line	tools/call against a hung server rejects within the configured timeout
One second in the singular	a timeout of one second says so in the singular
A script's call of a server missing from the registry reading as the model's	an MCPL tool call refused before it runs says it didn't run …; a call while this host connects to the tool's server says so, and after a connect that failed, that the server's gone
A server's id marked while this host connects to it	a call while this host connects to the tool's server says so …
The mark cleared when the connect settles, a failed one included	the same
The model's call reading the mark	the same
A script's call reading the mark	the same
The connection's record of its own close	a call pending when this host closes the connection says the outcome is unknown, and the log names it; #247's "a request on a closed connection is not-sent"
A request after this host's close saying that it closed	the same
Its next step, whom to ask if calling again fails	the same
The mark cleared when a connect succeeds	a call while this host connects to the tool's server says so …
The mark read for the server named, not for any connect	the same
A server's words passed through with the whitespace around them	#490's test of an in-process caller and the model's call
A request the transport couldn't write, in these words	#247's "a synchronous write rejection is not-sent …"
Its log line, with the method, id and the transport's words	the same
#247's class kept on this host's close with a request pending	#247's "closing the connection while a request awaits its answer rejects it as no-response"
The class kept on a request on a closed connection	#247's "a request on a closed connection is not-sent"
The class kept on a timeout	#247's "a request nobody answers is no-response" and "channels/open keeps a deadline …"; "requestTimeoutMs: 0 leaves channels/publish its own deadline …"
The class kept on an error answer, with its data	#247's "an error response is error-response …"; the publish test "the resident's failure marker never claims an uncertain delivery did not happen"
The class kept on a drop with a request pending	#247's "a connection lost while awaiting is no-response"
One final period off this host's words in a publish's reason	the publish test "answers a request refused before it was written as failed …"
A script's call of a denied tool reading as the model's	an MCPL tool call refused before it runs …
An error result with no words reading as one whose effect is unknown, on each path	an MCPL tool's error result with no words says so …; three of #490's tests: an in-process caller, the admin puppet and the model's call's trace
Whitespace alone read as no words	#490's test of an in-process caller and the model's call
An empty link with no data read as none	a reference block that can't be read says which part is missing …
Inline data beside an empty link left withheld (removed, it's shown)	the same
A type that sanitizes to nothing read as no type	the same; two content-parity tests of malformed blocks
Something that isn't a block read as unreadable	the same; a content-parity test of blocks that aren't objects
A second connect of a server whose connect is in flight refused	a second connect, a restart or a disconnect of a server whose connect is in flight is refused before it writes anything
A restart that would replace such a server refused	the same
A disconnect of such a server refused	the same

Not verified

• How each wording reads to a model in a live turn. The tests check the text and the case it's reached in.
• The in-flight refusals through connectMcplServer, restartMcplServer and disconnectMcplServer themselves. The test calls refuseMcplConnect and runDisconnectMcplServer with a stand-in registry whose handshake it holds. The rest is from reading the code. A connect reaches its check and its mark with no await between them. A restart awaits its disconnect between its own check and the mark, and its connect then checks again, with no await before the mark, which covers that gap.
• A restart of a live server with a call in its window. The test runs connectMcplServerInternal itself, with a stand-in registry whose handshake it holds, and checks a restart's close on the connection alone, by closing it and then sending a request.

Left as it is

• The conversation guard's refusal of another channel's channel_publish or channel_close is the framework's own tool, which this change leaves as it is.
• MCPL not initialized, which a script's call meets on a host without MCPL, and the handshake's initialize error, which fails the connection and reaches no agent.
• A request written as the transport goes, before the connection has seen its close, is dropped silently by the transport's writeLine, and reads as one whose outcome is unknown. Making writeLine report a dropped write is a change to the transports.
• On the tool-result lane, a tool result's inline audio, an image with data but no mimeType, and a block of a type the host doesn't know go into the agent's history as JSON, base64 data included, where the push lane shows a marker for each. That's the tool-result lane's behaviour, as on main, not these texts. A probe of toolResultDataToHistoryString at this head and at main d1b9d35c shows it.
• A restart's gap between its close and its connect. runDisconnectMcplServer unmaps the server's tool prefix there, so a call to one of its tools reads as one to a module the host doesn't have, Module not found: <prefix>, as on main. Covering it would mean keeping a restart's prefix routed, a change to how a restart routes calls.
• A WebSocket server's accessProvider that never settles holds its connect before the initialize timer starts, as on main. A call meanwhile reads as one while this host connects.
• The channel tools read a server that isn't registered as Server not found: <id>, during a connect too, as on main. This change leaves their texts as they are.
• Audio with a plain link shows as a reference stub on the tool-result lane and as [Audio not shown: it arrived with no usable inline data.] on the push, channel and context-injection lanes, as on main.

Merge order

A scan of the open pull requests at 15:19 UTC on October 18, at this head on main c7ad41d4, found 55 others. This head merges cleanly onto that main, which has taken #284 and #468 since this head's last merge.

• feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250, at 7ea6512c, merges onto main and conflicts with this one in two test files. In test/stop-ends-awareness-drains.test.ts, this change rewords the text an assertion matches, and feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250's port of that test keeps the old text. test/mcpl-awareness-barrier.test.ts is deleted by feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250 and modified by this change. feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250 also adds two assertions to test/mcpl-request-outcome.test.ts that match old texts this change rewords, disconnected unexpectedly and closed while awaiting response, and git merges those without a conflict.
• 8 merge cleanly with both, and 46 conflict with main already. Of those 46, 9 change the MCPL files this one changes (server-connection.ts, references.ts, convert-block.ts, visible-content.ts): feat(delivery): opt-in prose outbox — undelivered speech and sends are kept, retried in order, never double-posted #182, feat(mcpl): stamp each inbound item's delivered-body and stored-copy digests #252, feat(receipts): per-channel receipt clocks and fold receipts from confirmed provider rounds #253, feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255, feat(routing): speech follows its conversation, and publishes only where MCPL RFC-011 declares the place #256, feat(mcpl): every channel item names its conversation in a stored source header #257, feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262, feat(mcp): MCP servers on the 2025 revisions over Streamable HTTP #337 and fix(channels): the host posts nothing into a channel its server declared inbound-only #350. 18 change channel-registry.ts, and of them only fix(channels): the host posts nothing into a channel its server declared inbound-only #350 changes publishErrorOutcome, the one function this change touches there.
• fix(channels): the host posts nothing into a channel its server declared inbound-only #350, at b67453cf, conflicts with main in framework.ts, and with this change in server-connection.ts, channel-registry.ts and test/mcpl-request-handler-errors.test.ts too. Both change how a server's error answer reads.
  • This change makes the connection's message the agent's text, The "<s>" server answered with an error: <words>, and moves the method, id and code to a log line.
  • fix(channels): the host posts nothing into a channel its server declared inbound-only #350 keeps the message as MCPL server "<s>" returned error for <method>: [<code>] <words>, adds the server's words to McplRequestError, and has a publish's reason read them as server "<s>" answered with an error: <words>.
• feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262 holds a server's id from its connect's admission until the connect is done (mcpServerOps), and its mcpServerIdTaken refuses another connect of that id meanwhile. This change's mcplConnecting marks the same window for an MCPL server: a call meets its text while the connect runs, and another connect, a restart or a disconnect of that id is refused.

This head merges main up to 9e3e407c, in four merges.

• With 6dfea06f: feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247 wraps five of the rejections this change rewords in McplRequestError. Each keeps feat(drafts): hold suppressed plain speech as resendable drafts (with structured publish outcomes) #247's class, its outcome and an error answer's data, with this change's words as its message.
• With d1b9d35c: fix(mcpl): references are bound to every server that delivered them #510 registers a successful result's references in executeMcplToolCall, after the line where this change returns an error result, so only a success registers them, as on main. UNBOUND_REASON keeps this change's value, under fix(mcpl): references are bound to every server that delivered them #510's rewording of its comment.
• With 8a32054d, with no conflicts: it brings fix(mcpl)!: refuse toolPrefixes that meet, so one tool name has one server #469, whose refuseMcplConnect the commit after the merge extends, as above.
• With 9e3e407c: git merged every file on its own. fix(stop): every teardown step runs whatever an earlier one did, and stop() ends awareness drains #517's new stop-ends-awareness-drains.test.ts matched the ledger's record of a call that stop() closed in flight against this host's old text, closed while awaiting response. It now matches this change's words for that case, didn't answer before this host closed its connection.

Who did what

The entries come from Phoebe-2419's sweep of agent-framework's agent-facing errors, and Alfred-2570 found the invalid-reference label and the text marker's wording. Ada-1017 made the design calls. Our internal review read the change before its rebase onto main after #208 and #490, then that rebase and its last round at 2f8796b4, and the next two rounds at 7b10c6da; 88bf0ff7 answers that review. Greptile's review of this pull request found that a call made while this host connects to a server was told the server had gone. Desmond-2579 read it whole, its rounds, the rebase and the merges with main included. His probe of the tool-result lane changed how an empty link beside inline data is read. His read of the round that answers that review gave the text after this host's close its next step. His probe of a disconnect while the same server connects, which left the server registered without its config, led this change to refuse that disconnect too. Basil-1007's test run of this pull request merged with main and others found that #517's new test still matched this host's old text. I built and tested it.

---

• Changelog fragments added: changelog.d/mcpl-agent-words.changed.md and changelog.d/mcpl-connect-in-flight.fixed.md

Written by Cordelia-2434 (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: 4/5

[Medium impact] The changes reach several MCPL agent-facing paths within one bounded workflow.

The PR appears safe to merge, with a non-blocking correction to retry advice during server restarts.

Findings

1.  Restart looks permanent ▶

Fix with agent prompt

### Issue 1
src/framework.ts:144-145
During a runtime restart, `connectMcplServerInternal` restores the tool prefix before `addServer` finishes connecting. A tool call in that window reaches this message even though the host is already bringing the server back. Telling the agent it won't reconnect sends it to the operator instead of letting it retry later. Check for a pending connection, or avoid treating a missing registry entry as permanent.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Updates MCPL failures and missing-content markers so agents receive clearer explanations and next steps.

• MCPL request failures tell agents what happened and what to check.
• MCPL tool refusals say whether the call ran and what to do next.
• Hidden content markers tell agents what arrived and why it is missing.
• Reference messages explain when expiry or a missing server blocks a fetch.

Acknowledged by nissa-seru: silently dropped transport writes, JSON fallbacks for some tool-result blocks, and plain-link audio differences remain unchanged. These were left for separate transport or content work.

Intentional scope from nissa-seru: other channel refusals, MCPL not initialized, and handshake errors stay unchanged. Inline data beside an empty uri stays withheld to avoid storing it as raw JSON.

Review checks used source and test inspection; no tests were run.

_{Reviews (1) · Last reviewed commit: "fix(mcpl): the af-w4a-3 round: an error ..." · Reviewed by Greptile}

[greptile-apps]

Restart looks permanent

During a runtime restart, connectMcplServerInternal restores the tool prefix before addServer finishes connecting. A tool call in that window reaches this message even though the host is already bringing the server back. Telling the agent it won't reconnect sends it to the operator instead of letting it retry later. Check for a pending connection, or avoid treating a missing registry entry as permanent.

Knowledge Base Used: MCPL transport and server registration

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/framework.ts
Line: 144-145

Comment:
**Restart looks permanent**

During a runtime restart, `connectMcplServerInternal` restores the tool prefix before `addServer` finishes connecting. A tool call in that window reaches this message even though the host is already bringing the server back. Telling the agent it won't reconnect sends it to the operator instead of letting it retry later. Check for a pending connection, or avoid treating a missing registry entry as permanent.

**Knowledge Base Used:** [MCPL transport and server registration](https://app.greptile.com/anima-labs/-/custom-context/knowledge-base/anima-research/agent-framework/-/docs/mcpl-transport-and-registration.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[nissa-seru]

This is right, and it's fixed at 6975a5bf.

While this host connects to a server, at runtime or in a restart, the server's tool prefix already routes its calls, but the registry holds the server only once its handshake is done. So a call in that window was told that the server isn't connected, that this host won't reconnect to it on its own, and to ask whoever runs this host, for something that settles in moments.

The framework now keeps the ids whose connect is in flight. Both refusals, the model's call and a script's, check them first: This host is connecting to the "<s>" server that provides <tool>, so the call didn't run. Try again in a moment. After a connect that fails without reconnect, a call gets the earlier text, which is true by then.

The same claim stood in a restart's close. A request on a connection this host has closed said the host wouldn't reconnect to it, though a restart closes the connection before it connects again. It now reads The request wasn't sent: this host closed its connection to the "<s>" server, so nothing ran. If calling it again fails, ask whoever runs this host.

Written by Cordelia-2434.

— Lottie-2661