fix(config)!: remove processLogging.broadcast and refusalHandling.announceHumanTurns

[nissa-seru]

This removes two settings that haven't changed what the framework does in any release, beyond isProcessLoggingEnabled() reporting one of them back: processLogging.broadcast and an agent's refusalHandling.announceHumanTurns. It also removes the Discord announcement that the second one gated, which has had no caller since, and two fields of the rewind's record that nothing in src reads: one built for that announcement, and one whose last reader was the announcement's check. isProcessLoggingEnabled() now returns { persist }. It's a breaking change for TypeScript code that names either setting in an object literal checked against the framework's types, or that reads either one back. That code no longer compiles.

Problem

On main (61a6997):

• processLogging.broadcast is documented as "Broadcast process:completed trace events (default: false)" (src/types/framework.ts:27-28). create() reads it into a field (src/framework.ts:2546) that only isProcessLoggingEnabled() returns (:6639-6644). The framework emits process:completed whatever it says (:10685-10686, "Always emit trace for observability"). The check that gated that emit was removed in e9a79d7a, before 0.1.0.
• An agent's refusalHandling.announceHumanTurns is documented as announcing on Discord, "Default true", when a refusal rewind sets aside a human message (src/types/agent.ts:175-180). Its one reader, the call to announceRewind, was removed in 9f9cb9a5. That commit and 1bbff412, which added the setting, both first shipped in 0.6.2, so no release has read it. announceRewind (src/framework.ts:8102-8129) has had no caller since. Nothing in src has ever read RewindRecord.discordRef (:1507), a Discord message reference that shedNewestTurn builds (:8046-8048) and that came in with the announcement in 1bbff412. RewindRecord.kind (:1501) has had no reader in src since 9f9cb9a5 removed its last one, the announcement's rec.kind === 'human' check.

A setting that does nothing misleads whoever writes a config, and each of these misleads at its documented default. broadcast defaults to false, yet the framework emits process:completed to its trace, and the API server sends it on to its WebSocket clients (src/api/server.ts:331-340). announceHumanTurns defaults to true, yet no release has posted the notice.

Changes

• The types. ProcessLoggingConfig.broadcast and AgentConfig.refusalHandling.announceHumanTurns are removed, with their docs.
• The framework. create() no longer reads broadcast, and the framework no longer stores it. isProcessLoggingEnabled() returns { persist }, and its doc now says that this reports whether process events are written to Chronicle, while process:completed is emitted either way.
• The announcement. The private announceRewind is removed, with RewindRecord.discordRef and RewindRecord.kind. The shed tests that asserted kind or discordRef assert the whole descriptor instead, which /unstick's outcome post and the inference-exhaustion log read. shedNewestTurn's doc still described the marker it stopped adding in 9f9cb9a5, and now says what it does.
• A config that still sets either starts as before. The framework ignores the key, as it ignores any key it doesn't know, with no refusal or warning.
• Text: a breaking changelog fragment, changelog.d/fix-remove-no-op-settings.breaking.md.

Who needs to act

• A host whose config sets either setting deletes the line. In TypeScript, an object literal checked against the framework's types, such as a config passed straight to create(), no longer compiles while it names either one. A JSON config, or a host that passes on a config object of its own, still starts.
• A caller that reads either setting back drops the read, whether it's isProcessLoggingEnabled().broadcast or announceHumanTurns on an agent's refusalHandling (src/agent.ts:150). In TypeScript, neither read compiles. In plain JavaScript, .broadcast reads undefined, while refusalHandling.announceHumanTurns still reads what the config set, since the agent keeps the object as given (:281). In this repository only tests call isProcessLoggingEnabled(): two read .persist (test/config-switches.test.ts:160, :189), and the new one compares its whole result. A GitHub code search of anima-research and antra-tess finds no other caller, though it isn't proof, since GitHub doesn't index a file as large as src/framework.ts.
• connectome-host (main d555ff0) has no processLogging. Its Recipe type declares refusalHandling.announceHumanTurns (src/recipe.ts:381), two example recipes set it (docs/AGENT-ONBOARDING.md:284, docs/claude-code-ingest.md:364), and a composition test passes it through (test/framework-fkm-composition.test.ts:52, :84). src/framework-agent-config.ts:134 hands the recipe's refusalHandling object to the framework whole, not as an object literal. fix(recipe): stop suggesting refusalHandling.announceHumanTurns, which no agent-framework release reads connectome-host#325, open, takes the key out of those two example recipes and marks it @deprecated in the Recipe type. The two pull requests merge safely in either order, since neither needs the other.

What each part is for

• Removing the two settings is the change. Each documents a behaviour the framework doesn't have.
• isProcessLoggingEnabled() returning { persist }. The method returned the stored broadcast, and keeping a broadcast field in its result would keep the setting in the API. The method itself stays, since persist writes each process event to Chronicle.
• Removing announceRewind, discordRef and kind. Nothing calls the announcement, and its doc describes a notice that's never sent. Nothing in src reads the reference built for it, and nothing there has read kind since the announcement's check was removed.
• No refusal or warning for the old keys. Neither setting has done anything in a release, so ignoring it changes no behaviour, while a refusal would stop a host from starting over a line that did nothing.
• Removal rather than deprecation. Marking both settings @deprecated and ignoring them would keep a TypeScript host's build green. But both would stay in the public types, where each still reads as a setting a host can turn, and taking them out later would break the same builds then. Removing them now breaks those builds once, in the minor release that carries breaking changes, with an entry saying what to delete.
• The test, test/removed-settings.test.ts. Its runtime case runs with persist false and true, and pins that such a config starts and that isProcessLoggingEnabled() reports persist and nothing else. Its two type-level lines fail the build if either key comes back to its type, with any type.
• Left out: a doc line saying the settings do nothing, in place of removing them, which would leave them there to mislead.

Tests

On Linux with Node 24.22.0, at the second commit, d56e479, unless a bullet names another:

• Typecheck and build are clean.
• The files that cover it pass: test/removed-settings.test.ts 1, test/config-switches.test.ts 8, test/refusal-rewind.test.ts 6 and test/state-registration-errors.test.ts 25. So do test/workspace-read-image.test.ts 15, test/state-scaling-e2e.test.ts 1, test/refusals-are-error-results.test.ts 4, test/inference-exhaustion-rewind.test.ts 13 and test/tool-result-guard.test.ts 146, which set processLogging or reach the refusal rewind.
• With main's three changed source files under the second commit's tests, the build fails at the new test's two type-level lines (TS2322, test/removed-settings.test.ts:19, :20). With those lines also taken out, the build passes, and the test fails because isProcessLoggingEnabled() returns { persist: false, broadcast: true }.
• Each type change, taken back alone, fails the build: broadcast in ProcessLoggingConfig at :19, and so does broadcast as a string, while announceHumanTurns in refusalHandling fails it at :20. A constant { persist: false } from isProcessLoggingEnabled() fails the runtime case's persist: true run.
• The removals of announceRewind, discordRef and kind have no test of their own, since nothing in src read them.
• At a4f1aa1, the third commit, which drops kind, the build is clean, and test/refusal-rewind.test.ts 6, test/inference-exhaustion-rewind.test.ts 13, test/refusals-are-error-results.test.ts 4, test/removed-settings.test.ts 1 and test/config-switches.test.ts 8 pass. Rewording either descriptor that the shed tests now assert fails its test.
• At 3c1b520, the fourth commit: CI at a4f1aa1 failed test/operator-surgery.test.ts's shed test, which still asserted kind through a cast that the typecheck can't see past, and the fourth commit makes it assert the descriptor. At 3c1b520 the build is clean, and test/operator-surgery.test.ts 27, test/refusal-rewind.test.ts 6, test/inference-exhaustion-rewind.test.ts 13, test/inference-failure-bounds.test.ts 30, test/refusals-are-error-results.test.ts 4, test/removed-settings.test.ts 1, test/config-switches.test.ts 8 and test/state-registration-errors.test.ts 25 pass. Rewording the tool descriptor fails the shed tests in both operator-surgery and refusal-rewind.
• An internal review read the first commit, 24e5546, and the second and third commits answer it. The fourth answers CI.

Not verified

• connectome-host wasn't built against this change. By reading, it still compiles. Its one use in src hands refusalHandling on as a value of its own type, which shares autoRewind and maxRewinds with the framework's, and TypeScript rejects unknown properties only in an object literal. Its tsconfig.json includes only src, so the object literals in its test aren't typechecked.

Related

• A trial merge of 3c1b520 with each of the other 62 open pull requests at 13:11Z found no conflict that main doesn't already have with it, and it merges cleanly onto main at 8a32054. None of them adds or removes a use of either setting, announceRewind or isProcessLoggingEnabled().broadcast, and feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255 is the one that adds a use of kind or discordRef.
• feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255, stacked on feat(awareness): make Discord awareness marks an explicit, one-shot choice that never gates MCPL #250, splits shedNewestTurn so that planShedExchange builds the record, kind and discordRef included (src/framework.ts:5601-5628 at its head), and the shed passes them on (:5548). In a trial merge, :5622-5628 fall in the conflict feat(framework): gated operator body changes with journaled recovery (stacked on #250; merge after it) #255 already has with main at that return, and :5548 merges cleanly. :5601's let kind and its three assignments (:5604, :5614, :5618) merge out, since this change removes the lines they came from. By reading, with both in, kind and discordRef come out of both places, since planShedExchange returns a RewindRecord with an anchor.

---

• Changelog fragment added: changelog.d/fix-remove-no-op-settings.breaking.md

Written by Effie-2756 (Claude Opus 5.5), on Ada-1017's calls. Myrtle-2415 (Claude Opus 5.5) reviewed the change.

Description checked and posted by Fiona-2757 (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]

Required label not found on this PR.