Skip to content

Commit 648c44a

Browse files
committed
fix: retain safe ACP Prompt failure diagnostics
1 parent 8639637 commit 648c44a

18 files changed

Lines changed: 720 additions & 21 deletions

‎packages/acp/ACPX_RUNTIME.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
Read this when changing the ACP provider or a host that retains its sessions.
44
It identifies the released API XMD uses and the local acceptance boundary it
5-
still needs.
5+
still needs, together with the selected failure facts it retains.
66

77
## Applies to
88

@@ -34,6 +34,13 @@ not a reduction in maintenance. `resolveAgentCommand()` adds one small boundary
3434
adaptation for released argv registries, preserving the runtime's persisted
3535
spelling and leaving existing string commands unchanged.
3636

37+
**Failure details:** the local in-process result projection preserves the
38+
normalizer's origin and selected numeric ACP code/message/`data.details` under
39+
the `XMD prompt diagnostic:` seam. It carries no arbitrary protocol data. Core
40+
screens the optional diagnostic before saving it; the REPL's existing Prompt
41+
error page reads those facts without a runtime log or another agent call.
42+
Classification and retryable hints never authorize resend or establish acceptance.
43+
3744
**Maintenance:** keep the runtime and its declarations on the same exact
3845
artifact. An ordinary Prompt change belongs in the provider; provider turn-key
3946
interpretation belongs in `checkpoint.ts`; release refreshes update provenance,

‎packages/acp/src/events.ts‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -100,7 +100,7 @@ export function* consumeTurn(
100100
]);
101101
}
102102
const result = yield* until(turn.result);
103-
terminal = mapResult(result);
103+
terminal = mapResult(result, turn.requestId);
104104
// Read from the result rather than from the mapped event: a turn ACP
105105
// reported as completed under a stop reason this host treats as a failure
106106
// is a failure here, and a failure names no turn.
@@ -145,7 +145,7 @@ export function* consumeTurn(
145145
yield* channel.close(text);
146146
}
147147

148-
function mapResult(result: AcpRuntimeTurnResult): AgentPromptEvent {
148+
function mapResult(result: AcpRuntimeTurnResult, requestId: string): AgentPromptEvent {
149149
if (result.status === "completed") {
150150
// ACP defines end_turn as the only successful stop reason. An absent
151151
// stop reason on a completed turn is treated as end_turn — some
@@ -169,5 +169,28 @@ function mapResult(result: AcpRuntimeTurnResult): AgentPromptEvent {
169169
return terminal;
170170
}
171171
const failure = new Error(result.error.message);
172+
Object.defineProperty(failure, "executablemd.agent.prompt-diagnostic", {
173+
value: {
174+
provider: "acp",
175+
operation: "session/prompt",
176+
stage: "runtime-turn",
177+
requestId,
178+
...(result.error.code === undefined ? {} : { code: result.error.code }),
179+
...(result.error.detailCode === undefined ? {} : { detailCode: result.error.detailCode }),
180+
...(result.error.retryable === undefined ? {} : { retryable: result.error.retryable }),
181+
...(result.error.origin === undefined ? {} : { origin: result.error.origin }),
182+
...(result.error.acp === undefined
183+
? {}
184+
: {
185+
acp: {
186+
code: result.error.acp.code,
187+
message: result.error.acp.message,
188+
...(result.error.acp.details === undefined
189+
? {}
190+
: { details: result.error.acp.details }),
191+
},
192+
}),
193+
},
194+
});
172195
return { type: "terminal", status: "failed", error: failure };
173196
}

‎packages/acp/tests/provider.test.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,6 +102,37 @@ function* collectPrompt(
102102
}
103103

104104
describe("Tier AP — ACPX provider", () => {
105+
it("1039 A1: runtime classification and actual request correlation survive mapping", function* () {
106+
const harness = createFakeRuntime();
107+
harness.script({
108+
result: {
109+
status: "failed",
110+
error: {
111+
message: "Internal error",
112+
code: "ADAPTER",
113+
detailCode: "REQUEST_REJECTED",
114+
retryable: false,
115+
},
116+
},
117+
});
118+
yield* installProvider(harness);
119+
const { events } = yield* collectPrompt("do once");
120+
const terminal = events.find((event) => event.type === "terminal");
121+
expect(terminal?.error?.message).toBe("Internal error");
122+
expect(
123+
terminal?.error && Reflect.get(terminal.error, "executablemd.agent.prompt-diagnostic"),
124+
).toEqual({
125+
provider: "acp",
126+
operation: "session/prompt",
127+
stage: "runtime-turn",
128+
requestId: harness.turns[0].turn.requestId,
129+
code: "ADAPTER",
130+
detailCode: "REQUEST_REJECTED",
131+
retryable: false,
132+
});
133+
expect(harness.turns).toHaveLength(1);
134+
});
135+
105136
it("AP1: a successful turn emits started, output deltas, terminal, and the close value", function* () {
106137
const harness = createFakeRuntime();
107138
yield* scoped(function* () {

‎packages/acp/tests/released-runtime.test.ts‎

Lines changed: 57 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -115,7 +115,9 @@ function respond(request) {
115115
const text = request.params.prompt.map(block => block.text ?? "").join("");
116116
if (text !== "no-accept") update({sessionUpdate: "session_info_update", _meta: {"executablemd.session-materialization/v1": {state: "accepted"}}});
117117
update({sessionUpdate: "agent_message_chunk", content: {type: "text", text: "answer:" + text}});
118-
if (text === "fail") {
118+
if (text === "diagnostic") {
119+
send({jsonrpc: "2.0", id: request.id, error: {code: -32041, message: "Internal error", data: {details: "/work/project: adapter unavailable", authorization: "excluded raw field"}}});
120+
} else if (text === "fail") {
119121
send({jsonrpc: "2.0", id: request.id, error: {code: -32000, message: "backend refusal"}});
120122
} else {
121123
reply(request.id, {stopReason: text === "cancel" ? "cancelled" : "end_turn", _meta: {codex: {turnId: "turn-" + text}, opaque: {left: [3, null]}}});
@@ -403,6 +405,60 @@ describe(
403405
}
404406
});
405407

408+
it("1039 A1/A5: real protocol failure details reach the terminal Error", function* () {
409+
const current = yield* runtimeWorld();
410+
const turn = current.runtime.startTurn({
411+
handle: current.handle,
412+
text: "diagnostic",
413+
mode: "prompt",
414+
requestId: "actual-request",
415+
});
416+
const channel = createChannel<import("@executablemd/core").AgentPromptEvent, string>();
417+
const subscription = yield* channel;
418+
const consumer = yield* spawn(() =>
419+
consumeTurn(
420+
turn,
421+
{ agent: "scribe", session: { sessionKey: "released", cwd: current.dir } },
422+
channel,
423+
() => {},
424+
),
425+
);
426+
const events = [];
427+
let next = yield* subscription.next();
428+
while (!next.done) {
429+
events.push(next.value);
430+
next = yield* subscription.next();
431+
}
432+
yield* consumer;
433+
expect(next.value).toBe("answer:diagnostic");
434+
const terminal = events.find((event) => event.type === "terminal");
435+
const result = yield* until(turn.result);
436+
expect(result).toMatchObject({
437+
status: "failed",
438+
error: {
439+
origin: "runtime",
440+
acp: { code: -32041, details: "/work/project: adapter unavailable" },
441+
},
442+
});
443+
expect(JSON.stringify(result)).not.toContain("excluded raw field");
444+
expect(terminal?.error?.message).toBe("Internal error");
445+
expect(
446+
terminal?.error && Reflect.get(terminal.error, "executablemd.agent.prompt-diagnostic"),
447+
).toEqual({
448+
provider: "acp",
449+
operation: "session/prompt",
450+
stage: "runtime-turn",
451+
requestId: "actual-request",
452+
code: "RUNTIME",
453+
origin: "runtime",
454+
acp: {
455+
code: -32041,
456+
message: "Internal error",
457+
details: "/work/project: adapter unavailable",
458+
},
459+
});
460+
});
461+
406462
it("a final save failure keeps the returned reply inspectable and does not reprompt", function* () {
407463
const current = yield* world();
408464
let fail = true;

‎packages/acp/vendor/acpx/MANIFEST.json‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@
3131
{
3232
"path": "PROVENANCE.md",
3333
"kind": "provenance",
34-
"sha256": "18f8dde8dff5ac60be82b2d583cb175407f6c88ecd288cf900a38ee5cc5f5abc"
34+
"sha256": "bdd6b6770293029665d52eb309ffbc8c872fc53cfd489e2c6162e8263e317ad4"
3535
},
3636
{
3737
"path": "generated/agent-registry-Cz9fD9H1.js",
@@ -61,12 +61,12 @@
6161
{
6262
"path": "generated/runtime.d.ts",
6363
"kind": "generated",
64-
"sha256": "7ca427da1b33029e357c0d718969352dce16521d64df542a656533cc004b8df7"
64+
"sha256": "88aedba2daf5c6ecabee5d55f7ac85be1500f2a7f6932d89b1a1688df08a8993"
6565
},
6666
{
6767
"path": "generated/runtime.js",
6868
"kind": "generated",
69-
"sha256": "1c848668ca66f23414237e8695c0acc268af4df848dc352f15ce85a80f05b933"
69+
"sha256": "30b3da127f6e09470784541b7580ebb79ae52cb0703bb7d1ba1627ab51181e56"
7070
},
7171
{
7272
"path": "generated/session-options-BlnP3WAc.d.ts",

‎packages/acp/vendor/acpx/PROVENANCE.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,26 @@ the reviewed strictness and passes the same prompt/control, alias, configuration
116116
and admission regressions. That release qualification is separate from retiring
117117
the materialization patch or the vendor closure.
118118

119+
## Selected Prompt failure facts (#1039)
120+
121+
The released normalizer extracts protocol error code/message and `data.details`,
122+
but the in-process `failRuntimeTurn` projection drops them and normalized origin.
123+
The generated `runtime.js` correction retains origin and selected numeric
124+
code/message/details, and `runtime.d.ts` declares those same fields. It preserves
125+
an explicit empty details string and excludes arbitrary raw `acp.data`.
126+
127+
The uniquely named `XMD prompt diagnostic:` seam bounds this correction in Tier AV.
128+
Pristine upstream, exact pins, materialization and strict-resume patches stay
129+
unchanged. The shared/queue result projection is unchanged. Real adapter-child
130+
failures pass through this runtime into production Prompt publication and cold
131+
REPL error reads; no runtime log is needed for retained selected facts.
132+
133+
Other arbitrary adapter data remains unavailable through this selected result.
134+
This correction establishes no cause for the historical `Internal error` incident,
135+
and neither origin nor a retryable hint establishes acceptance or permits resend.
136+
Remove the correction only when a published runtime retains the same selected facts
137+
and passes those deterministic consumers and offline vendor verification.
138+
119139
## Released environment seam (#566)
120140

121141
The released runtime snapshots `agentProcessEnv`, delivers it to every child and

‎packages/acp/vendor/acpx/generated/runtime.d.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,9 @@ type AcpRuntimeEvent = {
302302
retryable?: boolean;
303303
};
304304
type AcpRuntimeTurnResultError = {
305+
/** XMD prompt diagnostic: selected normalized facts, without raw protocol data. */
306+
origin?: "cli" | "runtime" | "queue" | "acp";
307+
acp?: { code: number; message: string; details?: string };
305308
message: string;
306309
code?: string;
307310
detailCode?: string;

‎packages/acp/vendor/acpx/generated/runtime.js‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2073,10 +2073,15 @@ var AcpRuntimeManager = class {
20732073
task.promptStarted.reject(error);
20742074
task.sessionReady.reject(error);
20752075
const normalized = normalizeOutputError(error, { origin: "runtime" });
2076+
// XMD prompt diagnostic: retain the extracted protocol facts, never raw data.
2077+
const acp = normalized.acp;
2078+
const details = acp?.data !== null && typeof acp?.data === "object" ? acp.data.details : void 0;
20762079
return {
20772080
status: "failed",
20782081
error: {
20792082
message: normalized.message,
2083+
...normalized.origin !== void 0 ? { origin: normalized.origin } : {},
2084+
...acp ? { acp: { code: acp.code, message: acp.message, ...typeof details === "string" ? { details } : {} } } : {},
20802085
...normalized.code ? { code: normalized.code } : {},
20812086
...normalized.detailCode ? { detailCode: normalized.detailCode } : {},
20822087
...normalized.retryable !== void 0 ? { retryable: normalized.retryable } : {}

‎packages/cli/src/repl/model.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,7 @@ export interface ReplAgentTurn {
208208
* transcript is a reader's view of their own entry.
209209
*/
210210
readonly failure: string | undefined;
211+
readonly diagnostic?: NonNullable<PromptRecord["error"]>["diagnostic"];
211212
readonly configuration: ReplAgentConfiguration | undefined;
212213
readonly permissions: readonly ReplAgentPermission[];
213214
}
@@ -1322,6 +1323,15 @@ function agentTurn(
13221323
stopReason: record.stopReason,
13231324
text: record.text,
13241325
failure: record.error?.message,
1326+
diagnostic:
1327+
record.error?.diagnostic === undefined
1328+
? undefined
1329+
: freeze({
1330+
...record.error.diagnostic,
1331+
...(record.error.diagnostic.acp === undefined
1332+
? {}
1333+
: { acp: freeze({ ...record.error.diagnostic.acp }) }),
1334+
}),
13251335
configuration:
13261336
record.configuration === undefined
13271337
? undefined

‎packages/cli/src/repl/sidekick/entry-inspection.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,7 @@ export type EntryPromptPage = {
130130
readonly field: PromptField;
131131
/** The saved text, or `null` where the turn recorded none at all. */
132132
readonly text: string | null;
133+
readonly diagnostic?: ReplAgentTurn["diagnostic"] | null;
133134
readonly offset: number;
134135
readonly length: number;
135136
readonly limit: number;
@@ -291,6 +292,7 @@ export function readEntryPrompt(
291292
promptStatus: turn.status,
292293
position: pagePosition(turn.position),
293294
field: field.value,
295+
...(field.value === "error" ? { diagnostic: turn.diagnostic ?? null } : {}),
294296
};
295297
if (text === undefined) {
296298
return Ok(

0 commit comments

Comments
 (0)