Skip to content

Commit 45251ac

Browse files
t3dotggclaude
andcommitted
feat(claude): full SDK message coverage with type-level exhaustiveness guards
Log-driven audit of real captured traffic (verification runs + wire probes) found api_retry storms rendering as 10 warning rows per 502 and several union subtypes falling into the unknown-subtype warning path. - api_retry → session.state.changed heartbeat (terminal error path already reports the real failure) - session_state_changed → authoritative session.state.changed mapping - notification → warning row only for high/immediate priority - model_refusal_fallback, local_command_output, plugin_install, commands_changed, memory_recall, elicitation_complete, prompt_suggestion → deliberately consumed, no spurious rows - default branches now narrow to never: a new SDK message type or subtype fails typecheck instead of silently warning at runtime; the runtime fallback still catches undeclared wire-only subtypes Co-Authored-By: Claude Fable 5 <[email protected]>
1 parent 8a9ebf4 commit 45251ac

2 files changed

Lines changed: 133 additions & 14 deletions

File tree

‎apps/server/src/provider/Layers/ClaudeAdapter.test.ts‎

Lines changed: 64 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1705,24 +1705,78 @@ describe("ClaudeAdapterLive", () => {
17051705
);
17061706
assert.equal(progressEvent.payload.description, "Running background teammate");
17071707
}
1708+
}).pipe(
1709+
Effect.provideService(Random.Random, makeDeterministicRandomService()),
1710+
Effect.provide(harness.layer),
1711+
);
1712+
});
1713+
1714+
it.effect("consumes undeclared and UX-internal system subtypes without warning rows", () => {
1715+
const harness = makeHarness();
1716+
return Effect.gen(function* () {
1717+
const adapter = yield* ClaudeAdapter;
1718+
const runtimeEvents: Array<ProviderRuntimeEvent> = [];
1719+
const runtimeEventsFiber = yield* Stream.runForEach(adapter.streamEvents, (event) =>
1720+
Effect.sync(() => runtimeEvents.push(event)),
1721+
).pipe(Effect.forkChild);
1722+
1723+
yield* adapter.startSession({
1724+
threadId: THREAD_ID,
1725+
provider: ProviderDriverKind.make("claudeAgent"),
1726+
runtimeMode: "full-access",
1727+
});
17081728

1709-
// The undeclared background_tasks_changed roster snapshot is consumed
1710-
// silently — it must not surface as an unknown-subtype warning row.
1729+
// Undeclared wire-only roster snapshot + typed UX-internal subtypes:
1730+
// all consumed silently, none may surface as unknown-subtype warnings.
1731+
for (const message of [
1732+
{
1733+
type: "system",
1734+
subtype: "background_tasks_changed",
1735+
tasks: [{ task_id: "t1", task_type: "local_agent", description: "Say hi" }],
1736+
session_id: "session",
1737+
uuid: "roster",
1738+
},
1739+
{ type: "system", subtype: "commands_changed", session_id: "session", uuid: "cc" },
1740+
{
1741+
type: "system",
1742+
subtype: "notification",
1743+
key: "context",
1744+
text: "low priority note",
1745+
priority: "low",
1746+
session_id: "session",
1747+
uuid: "notif",
1748+
},
1749+
]) {
1750+
harness.query.emit(message as unknown as SDKMessage);
1751+
}
1752+
// api_retry maps to a session heartbeat, not a warning row.
17111753
harness.query.emit({
17121754
type: "system",
1713-
subtype: "background_tasks_changed",
1714-
tasks: [{ task_id: "workflow-1", task_type: "local_workflow", description: "Run checks" }],
1755+
subtype: "api_retry",
1756+
attempt: 3,
1757+
max_retries: 10,
1758+
retry_delay_ms: 1000,
1759+
error_status: 502,
1760+
error: { type: "api_error" },
17151761
session_id: "session",
1716-
uuid: "roster",
1762+
uuid: "retry",
17171763
} as unknown as SDKMessage);
17181764
yield* Effect.yieldNow;
1719-
const rosterWarnings = runtimeEvents.filter(
1765+
yield* Effect.yieldNow;
1766+
1767+
const warnings = runtimeEvents.filter((event) => event.type === "runtime.warning");
1768+
assert.deepEqual(
1769+
warnings.map((event) => event.payload.message),
1770+
[],
1771+
);
1772+
const heartbeat = runtimeEvents.find(
17201773
(event) =>
1721-
event.type === "runtime.warning" &&
1722-
typeof event.payload.message === "string" &&
1723-
event.payload.message.includes("background_tasks_changed"),
1774+
event.type === "session.state.changed" &&
1775+
typeof event.payload.reason === "string" &&
1776+
event.payload.reason.startsWith("api_retry:"),
17241777
);
1725-
assert.equal(rosterWarnings.length, 0);
1778+
assert.equal(heartbeat?.type, "session.state.changed");
1779+
runtimeEventsFiber.interruptUnsafe();
17261780
}).pipe(
17271781
Effect.provideService(Random.Random, makeDeterministicRandomService()),
17281782
Effect.provide(harness.layer),

‎apps/server/src/provider/Layers/ClaudeAdapter.ts‎

Lines changed: 69 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2708,6 +2708,11 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
27082708
},
27092709
});
27102710
return;
2711+
// Task state patch (status/backgrounded/end_time). No runtime mapping
2712+
// yet — the terminal task_notification reports the outcome — but it
2713+
// must not surface as an unknown-subtype warning row.
2714+
case "task_updated":
2715+
return;
27112716
case "task_notification":
27122717
yield* emitThreadTokenUsage(
27132718
context,
@@ -2752,6 +2757,52 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
27522757
return;
27532758
case "thinking_tokens":
27542759
return;
2760+
case "api_retry":
2761+
// Transport-level retry heartbeat. Surfacing each attempt as a
2762+
// warning row spammed the work log (10 rows during a 502 storm);
2763+
// the terminal result/error path reports the actual failure. Keep
2764+
// the session visibly alive instead.
2765+
yield* offerRuntimeEvent({
2766+
...base,
2767+
type: "session.state.changed",
2768+
payload: {
2769+
state: "running",
2770+
reason: `api_retry:${message.attempt}/${message.max_retries}`,
2771+
},
2772+
});
2773+
return;
2774+
case "session_state_changed":
2775+
// Authoritative turn-over signal from the CLI.
2776+
yield* offerRuntimeEvent({
2777+
...base,
2778+
type: "session.state.changed",
2779+
payload: {
2780+
state:
2781+
message.state === "running"
2782+
? "running"
2783+
: message.state === "requires_action"
2784+
? "waiting"
2785+
: "ready",
2786+
reason: `session_state:${message.state}`,
2787+
},
2788+
});
2789+
return;
2790+
case "notification":
2791+
// User-facing CLI notification (e.g. context-limit warnings). Only
2792+
// high-priority ones warrant a work-log row.
2793+
if (message.priority === "high" || message.priority === "immediate") {
2794+
yield* emitRuntimeWarning(context, message.text, message);
2795+
}
2796+
return;
2797+
// Inner protocol/UX details with no T3 surface today — consumed
2798+
// deliberately so they don't masquerade as unknown-subtype warnings.
2799+
case "model_refusal_fallback":
2800+
case "local_command_output":
2801+
case "plugin_install":
2802+
case "commands_changed":
2803+
case "memory_recall":
2804+
case "elicitation_complete":
2805+
return;
27552806
case "permission_denied":
27562807
yield* offerRuntimeEvent({
27572808
...base,
@@ -2771,13 +2822,20 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
27712822
message,
27722823
);
27732824
return;
2774-
default:
2825+
default: {
2826+
// Exhaustiveness guard: every subtype in the SDK's typed union is
2827+
// handled above, so `message` narrows to never here — a new SDK
2828+
// release adding a subtype fails this typecheck instead of silently
2829+
// warning at runtime. The runtime fallback still catches undeclared
2830+
// wire-only subtypes (like background_tasks_changed used to be).
2831+
const unknownMessage: { subtype: string } = message satisfies never;
27752832
yield* emitRuntimeWarning(
27762833
context,
2777-
describeUnknownSdkMessage(`Claude system message '${message.subtype}'`, message),
2834+
describeUnknownSdkMessage(`Claude system message '${unknownMessage.subtype}'`, message),
27782835
message,
27792836
);
27802837
return;
2838+
}
27812839
}
27822840
});
27832841

@@ -2885,13 +2943,20 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
28852943
case "rate_limit_event":
28862944
yield* handleSdkTelemetryMessage(context, message);
28872945
return;
2888-
default:
2946+
// Composer prompt suggestions have no T3 surface; consumed deliberately.
2947+
case "prompt_suggestion":
2948+
return;
2949+
default: {
2950+
// Exhaustiveness guard (see handleSystemMessage): new SDK top-level
2951+
// message types fail typecheck here instead of warning at runtime.
2952+
const unknownMessage: { type: string } = message satisfies never;
28892953
yield* emitRuntimeWarning(
28902954
context,
2891-
describeUnknownSdkMessage(`Claude SDK message '${message.type}'`, message),
2955+
describeUnknownSdkMessage(`Claude SDK message '${unknownMessage.type}'`, message),
28922956
message,
28932957
);
28942958
return;
2959+
}
28952960
}
28962961
});
28972962

0 commit comments

Comments
 (0)