Skip to content

Commit db6615a

Browse files
committed
fix(batch): keep the availability refusal surface-neutral; CLI attaches its recovery
readStructuredBatchCommandName emitted 'Run agent-device help batch' unconditionally, and the same reader backs the MCP/Node batch metadata — an MCP caller got a terminal-only, unrunnable recovery step. The shared default now states the exclusion boundary itself with no terminal vocabulary (MCP/Node read the accepted commands off the step schema's command enum), and the CLI admission appends the help pointer via the same optional-hint parameter the shape hint uses. Found while fixing it: hint strings are redaction-capped at 400 characters, so enumerating the derived roster inline truncates the hint — recovery pointer and all. The regression pins neutrality AND that the hint survives the cap whole. Addresses the P2 review on #2067.
1 parent 66feec4 commit db6615a

3 files changed

Lines changed: 52 additions & 12 deletions

File tree

‎src/cli/batch-steps.ts‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@ import {
66
readBatchStepRecord,
77
} from '@agent-device/contracts/command';
88
import { AppError } from '@agent-device/kernel/errors';
9-
import { readStructuredBatchCommandName } from '../core/batch-policy.ts';
9+
import {
10+
BATCH_AVAILABLE_COMMANDS_HINT,
11+
readStructuredBatchCommandName,
12+
} from '../core/batch-policy.ts';
1013
import { assertAllowedKeys } from '../commands/command-input.ts';
1114

1215
/**
@@ -16,6 +19,8 @@ import { assertAllowedKeys } from '../commands/command-input.ts';
1619
*/
1720
const CLI_BATCH_STEP_SHAPE_HINT = `${BATCH_STEP_SHAPE_HINT} Run agent-device help batch for the commands batch accepts and for runnable step examples.`;
1821

22+
const CLI_BATCH_AVAILABLE_COMMANDS_HINT = `${BATCH_AVAILABLE_COMMANDS_HINT} Run agent-device help batch for the commands batch accepts and for runnable step examples.`;
23+
1924
export function readCliBatchStepsJson(raw: string): BatchStep[] {
2025
let parsed: unknown;
2126
try {
@@ -48,7 +53,11 @@ function readCliBatchStep(step: unknown, stepNumber: number): BatchStep {
4853
);
4954
const runtime = parseBatchStepRuntime(record.runtime, stepNumber);
5055
return {
51-
command: readStructuredBatchCommandName(record.command, stepNumber),
56+
command: readStructuredBatchCommandName(
57+
record.command,
58+
stepNumber,
59+
CLI_BATCH_AVAILABLE_COMMANDS_HINT,
60+
),
5261
input: readBatchStepInputObject(record, stepNumber, CLI_BATCH_STEP_SHAPE_HINT),
5362
...(runtime === undefined ? {} : { runtime }),
5463
};

‎src/commands/batch/cli.test.ts‎

Lines changed: 29 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ import {
1010
type CliCaptureOptions,
1111
} from '../../__tests__/cli-capture.ts';
1212
import { mkdtempForTestSync } from '../../__tests__/test-utils/tmp-dir.ts';
13+
import { AppError } from '@agent-device/kernel/errors';
14+
import { createBatchCommandMetadata } from './metadata.ts';
1315

1416
const batchDefaultResponse: DaemonResponse = {
1517
ok: true,
@@ -142,14 +144,40 @@ test('an args/target step names the step shape instead of only the unknown field
142144
assert.match(result.stderr, /\{"command":"<name>","input":\{\.\.\.\}\}/);
143145
});
144146

145-
test('a non-batchable command points at the listing of the ones that are', async () => {
147+
test('a non-batchable command states the boundary and, on the CLI, the help recovery', async () => {
146148
const result = await runCliCapture(['batch', '--steps', '[{"command":"session","input":{}}]']);
147149

148150
assert.equal(result.code, 1);
149151
assert.match(result.stderr, /not available through command batch: session/);
152+
assert.match(result.stderr, /excluded from batch/);
150153
assert.match(result.stderr, /help batch/);
151154
});
152155

156+
// The same reader backs the MCP/Node surface through the batch metadata, where a terminal
157+
// recovery step is unrunnable: the shared hint stays surface-neutral (those surfaces read the
158+
// accepted commands off the step schema's command enum) and only the CLI admission appends the
159+
// help pointer (#2062). The hint also has to survive the 400-character redaction cap intact —
160+
// enumerating the roster inline truncated it, help pointer and all.
161+
test('the MCP/Node availability refusal is surface-neutral and survives redaction whole', () => {
162+
const metadata = createBatchCommandMetadata();
163+
try {
164+
metadata.readInput({ steps: [{ command: 'session', input: {} }] });
165+
assert.fail('expected the nested session command to be refused');
166+
} catch (error) {
167+
assert.ok(error instanceof AppError);
168+
const hint = String(error.details?.hint ?? '');
169+
assert.match(hint, /excluded from batch/);
170+
assert.doesNotMatch(hint, /agent-device /);
171+
assert.doesNotMatch(hint, /--[a-z]/);
172+
assert.ok(hint.length <= 400, `hint must survive the redaction cap, got ${hint.length}`);
173+
}
174+
const stepSchema = metadata.inputSchema.properties?.steps as {
175+
items?: { properties?: { command?: { enum?: string[] } } };
176+
};
177+
const commandEnum = stepSchema.items?.properties?.command?.enum ?? [];
178+
assert.ok(commandEnum.includes('press'), 'the step schema enum is the machine-readable roster');
179+
});
180+
153181
// The reported blocker (#2062) was the step shape, not the verb: press/click/fill were never
154182
// excluded from batch. Pin that so a future exclusion has to be a deliberate registry change.
155183
test('mutating UI verbs reach daemon dispatch through batch', async () => {

‎src/core/batch-policy.ts‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,17 @@ export const INHERITED_PARENT_FLAG_KEYS = [
5050
] as const;
5151

5252
/**
53-
* The refusal above names the rejected command but never named the accepted set, and `help batch`
54-
* documented no exclusions either, so the boundary was only discoverable by trial (#2062). Point at
55-
* the one derived listing rather than restating it: `help batch` renders
56-
* {@link STRUCTURED_BATCH_COMMAND_NAMES} itself, so a registry change cannot leave prose behind.
53+
* The refusal below names the rejected command but never stated the boundary, so it was only
54+
* discoverable by trial (#2062). Surface-neutral by design — this default reaches the MCP and
55+
* Node readers, whose batch step schema already enumerates the accepted commands in its
56+
* `command` enum; the CLI attaches its terminal recovery via the `hint` parameter at its own
57+
* admission. NOT the place for the roster itself: hint strings are redaction-capped at 400
58+
* characters, and the enumerated roster truncates.
5759
*/
58-
const BATCH_AVAILABLE_COMMANDS_HINT =
59-
'Run agent-device help batch for the commands available through batch. Session, daemon, ' +
60-
'connection, and host tooling commands are excluded — they own lifecycle a batch cannot ' +
61-
'carry — and batch and replay never nest. Run an excluded command on its own.';
60+
export const BATCH_AVAILABLE_COMMANDS_HINT =
61+
'Session, daemon, connection, and host tooling commands are excluded from batch — they own ' +
62+
'lifecycle a batch cannot carry — and batch and replay never nest. Run an excluded command on ' +
63+
'its own; every other device command is available as a step.';
6264

6365
const structuredBatchCommandNames = new Set<string>(STRUCTURED_BATCH_COMMAND_NAMES);
6466

@@ -73,13 +75,14 @@ export function normalizeBatchCommandName(command: unknown): string {
7375
export function readStructuredBatchCommandName(
7476
command: unknown,
7577
stepNumber: number,
78+
hint: string = BATCH_AVAILABLE_COMMANDS_HINT,
7679
): StructuredBatchCommandName {
7780
const normalized = normalizeBatchCommandName(command);
7881
if (isStructuredBatchCommandName(normalized)) return normalized;
7982
throw new AppError(
8083
'INVALID_ARGS',
8184
`Batch step ${stepNumber} command is not available through command batch: ${String(command)}`,
82-
{ hint: BATCH_AVAILABLE_COMMANDS_HINT },
85+
{ hint },
8386
);
8487
}
8588

0 commit comments

Comments
 (0)