You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 18d1058
Browse filesBrowse the repository at this point in the historyBrowse files
refactor: extract command surface and separate CLI presentation (#4100)
* refactor(command-surface): extract command declarations into a package
Move the command metadata, input schemas, CLI grammar, request projection,
MCP output schemas and the client port out of `src/commands` into the private
`@agent-device/command-surface` package, which exposes one named entry.
Command facets no longer carry a CLI output formatter. Formatters stay in the
root, keyed by `CommandName` in `src/commands/cli-output.ts` with a duplicate
guard, so the SDK and request projection load no CLI presentation. The
`AgentDeviceClient` and `AgentDeviceCommandClient` declarations now live in the
package, and `src/client/client-types.ts` re-exports exactly those two names.
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
* docs(command-surface): record the declaration and presentation split
Amend ADR 0008 and the agent ownership and CLI flag guides for the
`@agent-device/command-surface` package and the root presentation layer.
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
* test(command-surface): follow the replay declaration to the package in the startup closure guard
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
* fix(command-surface): narrow projection names and pin formatter bindings
* Address command surface review feedback
* docs(command-surface): state config defaults precisely and align fold hinge-angle wording
Co-Authored-By: Claude Sonnet 5.5 <[email protected]>
* docs: keep ownership guidance within budget
* test(command-surface): pin batch names to daemon writers
---------
Co-authored-by: Claude Sonnet 5.5 <[email protected]>
Copy file name to clipboardExpand all lines: .fallowrc.json
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -289,7 +289,7 @@
289
289
"exports": ["IS_PREDICATE_USAGE_HINT"]
290
290
},
291
291
{
292
-
// Workspace-package symbols whose only consumers are test-tree files, which --production analysis does not see. Each import is the package specifier, so the façade entry is load-bearing: parseTargetAnnotationV1Payload from packages/selectors/src/target-evidence.test.ts, MAESTRO_COMPAT_* from src/cli/parser/__tests__/maestro-support-matrix.test.ts, SCRIPT_FLAG_COMMANDS/scriptFlagEntries from src/commands/replay/script-flag-admission.test.ts (the #3197 two-way drift guard between the .ad grammar and the CLI schema).
292
+
// Workspace-package symbols whose only consumers are test-tree files, which --production analysis does not see. Each import is the package specifier, so the façade entry is load-bearing: parseTargetAnnotationV1Payload from packages/selectors/src/target-evidence.test.ts, MAESTRO_COMPAT_* from src/cli/parser/__tests__/maestro-support-matrix.test.ts, SCRIPT_FLAG_COMMANDS/scriptFlagEntries from packages/command-surface/src/replay/script-flag-admission.test.ts (the #3197 two-way drift guard between the .ad grammar and the CLI schema).
Copy file name to clipboardExpand all lines: docs/adr/0008-command-descriptor-registry.md
+7-2Lines changed: 7 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,7 +11,7 @@ Amended by [ADR 0019](0019-request-bound-platform-runtime.md): device capability
11
11
- Declare each command once in the descriptor registry. Compose the declaration from facets owned by their domains. No second table declares the same traits.
12
12
- Derive every shared consumer table as a pure projection. Do not copy a derived classification back into a consumer as a hand-authored set.
13
13
- Keep a narrow fact on the descriptor when several projections consume it: `timeoutPolicy`, `recordingEffect`, `postActionObservation`.
14
-
- Keep grammar, decoding, executable surface metadata, and client invocation in `src/commands/**`. Keep shared option and result data in domain contracts. Keep the client facade in the client layer.
14
+
- Keep grammar, decoding, executable surface metadata, request projection, and client invocation in `@agent-device/command-surface`. Keep CLI output formatters, help, and progress in `src/commands/`. A command facet declares no formatter. Keep shared option and result data in domain contracts. The package declares the client port once. The client layer re-exports it.
15
15
- Declare daemon route and request policy in the separately typed `daemon` facet. Derive the daemon registry from it. Expose request-policy predicates only through the daemon registry.
16
16
- Request modules consume named predicates. Handler modules own execution logic only. Neither recreates command sets or coverage tables.
17
17
- Public grammar, client options, MCP schemas, help, and capability contracts must not derive from daemon-only traits. A diagnostic display, such as `command explain`, may show them.
@@ -32,7 +32,11 @@ Keep a narrow fact on the descriptor when more than one projection consumes it.
32
32
33
33
### Domain-owned surfaces
34
34
35
-
Keep CLI grammar, input decoding, executable surface metadata, and client-backed invocation in `src/commands/**`. Keep shared option and result shapes in domain contracts under `packages/contracts/src`: both surfaces need that vocabulary, so a shared shape sits below both. A type-only dependency on the `AgentDeviceClient` facade from a command module is an accepted ratchet-bounded position, not shared data that must move to contracts. The facade declares its signatures in that vocabulary. Add a type projection only when it removes real duplication across consumers.
35
+
Keep CLI grammar, input decoding, executable surface metadata, request projection, and client-backed invocation in `@agent-device/command-surface`. The package exposes one entry, `.`, that names its exports. Keep shared option and result shapes in domain contracts under `packages/contracts/src`: both surfaces need that vocabulary, so a shared shape sits below both.
36
+
37
+
The package declares the client port, `AgentDeviceClient` and `AgentDeviceCommandClient`, once, in contracts and command-registry vocabulary. The command definitions invoke that port. `src/client/client-types.ts` re-exports exactly those two port names from the package. Its other published vocabulary is unchanged, so the published SDK types do not change and the package has no edge into the client layer. Add a type projection only when it removes real duplication across consumers.
38
+
39
+
Keep CLI presentation in `src/commands/`: output formatters, the warning dispatcher, help, and progress. A formatter is keyed by `CommandName` in `src/commands/cli-output.ts`, and a duplicate key throws when the table builds. The package reaches no root module, so request projection and the SDK load no presentation.
36
40
37
41
The client `invoke` seam is cross-process; the daemon `execute` seam runs the platform handler inside the daemon process. The process boundary is never collapsed.
38
42
@@ -74,4 +78,5 @@ About ten hand-maintained tables once repeated command identity, route membershi
74
78
75
79
## Decision history
76
80
81
+
- 2026-10-30 — the command declaration surface moved to `@agent-device/command-surface`. Formatters left the facets for a `CommandName`-keyed table in `src/commands/cli-output.ts`, so the SDK no longer evaluates CLI presentation. The client port is declared in the package and re-exported by the client layer.
77
82
- 2026-09-05 — [#2294](https://github.com/callstack/agent-device/pull/2294) removed the navigation-only phantom-type projection: direct signatures were simpler and preserved the published contract.
Copy file name to clipboardExpand all lines: docs/adr/0012-interactive-replay.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1284,7 +1284,7 @@ After bounded expiry, the tombstone disappears and the key is free.
1284
1284
> The flags retain their different scopes:
1285
1285
>
1286
1286
> - Common `--no-record` belongs to `COMMON_COMMAND_SUPPORTED_FLAG_KEYS`.
1287
-
> Every recordable reader forwards it with `noRecordInputFromFlags` (`src/commands/cli-grammar/common.ts`, #1304).
1287
+
> Every recordable reader forwards it with `noRecordInputFromFlags` (`packages/command-surface/src/cli-grammar/common.ts`, #1304).
1288
1288
> - Scoped `--record` is not common.
1289
1289
> Only `snapshot`/`get`/`is` and dynamically validated `find` permit it.
1290
1290
> Only their readers use `observationRecordInputFromFlags`.
@@ -1295,10 +1295,10 @@ After bounded expiry, the tombstone disappears and the key is free.
1295
1295
> That fail-open is what the split prevents.
1296
1296
> Both flags then use the ordinary typed path:
1297
1297
>
1298
-
> - Node forwards them through `buildRequestFlags`/`buildFlags` in `src/commands/command-flags.ts`.
1298
+
> - Node forwards them through `buildRequestFlags`/`buildFlags` in `packages/command-surface/src/command-flags.ts`.
1299
1299
> Sources are `InternalRequestOptions`, `GetOptions`, `IsOptions`, `FindOptions`, and `CaptureSnapshotOptions`.
1300
1300
> - MCP exposes `record`/`noRecord` on `get`/`is`/`find`/`snapshot` tools.
1301
-
> `src/commands/interaction/metadata.ts` and `src/commands/capture/snapshot.ts` use `CommandMetadata.inputSchema` plus `readMetadataCommandFlags`, as for other typed fields.
1301
+
> `packages/command-surface/src/interaction/metadata.ts` and `packages/command-surface/src/capture/snapshot.ts` use `CommandMetadata.inputSchema` plus `readMetadataCommandFlags`, as for other typed fields.
1302
1302
>
1303
1303
> There is no separate per-surface recording contract.
Copy file name to clipboardExpand all lines: docs/agents/cli-flags.md
+10-17Lines changed: 10 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,50 +6,43 @@ Pass a flag only through layers that consume it:
6
6
Add its definition to the owner in `packages/command-registry/src/flag-definitions-*.ts`.
7
7
Add it to the applicable group in `packages/command-registry/src/flag-groups.ts`, for example `SNAPSHOT_FLAGS`.
8
8
Update the command family metadata/schema that exposes the flag.
9
-
To find the owner, run `rg -n "<command>|helpDescription|summary|supportedFlags|allowedFlags" src/commands src/cli/parser`.
10
-
For schema-only CLI commands, use `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in `src/commands/schema/command-overrides.ts`.
9
+
To find the owner, run `rg -n "<command>|helpDescription|summary|supportedFlags|allowedFlags" packages/command-surface/src src/commands src/cli/parser`.
10
+
For schema-only CLI commands, use `SCHEMA_ONLY_CLI_COMMAND_SCHEMAS` in `packages/command-surface/src/schema/command-overrides.ts`.
11
11
Each flag declaration requires `projectConfig` and `recorded`.
12
12
`projectConfig` permits a project `agent-device.json` to set the flag.
13
13
`recorded` makes the session recorder copy it into `SessionAction.flags`.
14
-
Compilation enforces completeness, without an allowlist. A declaration without either field does not compile.
15
14
Only when repository control is safe, set `projectConfig: true`. Otherwise, a new flag is operator-only.
16
15
Only when a `.ad` recording must carry the flag, set `recorded: true`.
17
-
2. In `src/commands/cli-grammar/*`, read the CLI flag into command input.
16
+
2. In `packages/command-surface/src/cli-grammar/*`, read the CLI flag into command input.
18
17
3. If the flag affects daemon execution, write the input into the daemon request.
19
-
Use `src/commands/command-projection.ts` and the command-family projection helpers.
18
+
Use `packages/command-surface/src/index.ts` (`prepareDaemonCommandRequest`) and the command-family projection helpers.
20
19
4. If Node.js or MCP should expose structured input, add a field to the command's field map. `defineFieldCommandMetadata` generates `inputSchema` and the audience.
21
-
For a credential, its destination endpoint, or operator infrastructure, declare the input key with `operatorField(...)` (`src/commands/command-input.ts`).
20
+
For a credential, its destination endpoint, or operator infrastructure, declare the input key with `operatorField(...)` (`packages/command-surface/src/command-input.ts`).
22
21
MCP and AI SDK tool schemas thus exclude parameters for the model to write that input.
23
-
For a shared common key, declare the same audience in its `src/commands/common-input-fields.ts` row instead.
24
-
5. If Node.js exposes the option, update the public typed client option in `src/client/client-types.ts`.
22
+
For a shared common key, declare the same audience in its `packages/command-surface/src/common-input-fields.ts` row instead.
23
+
5. If Node.js exposes the option, update the public typed client option in the owning `packages/contracts/src/client-*.ts` type.
25
24
6. If the request still needs public-to-internal translation, update daemon flag normalization in `src/client/client-normalizers.ts`.
26
25
7. If the field enters platform dispatch, add it to `packages/daemon/src/core/context.ts` and `packages/daemon/src/core/dispatch-context.ts`.
27
26
8. Only after the command surface, grammar, and projection prove applicability, pass the option through handler/platform modules.
28
27
9. In `scripts/integration-progress-model.ts`, classify the flag as device-observable or intentionally-outside.
29
-
In CI, the architecture-progress gate fails on unclassified public flags.
30
28
10. If the flag changes interaction semantics, examine the affected cells in `packages/contracts/src/interaction-guarantees.ts` again.
31
29
If only some commands have the flag, use `appliesTo` to limit its scope.
32
30
33
-
Command-only flags that never reach the platform layer usually stop at steps 1–3, plus step 9.
34
-
An example is `find --first`.
35
-
36
31
## Where CLI help and schema live
37
32
38
33
- Long help prose is in `src/commands/schema/cli-help.ts`.
39
-
CLI input readers are in `src/commands/cli-grammar/`.
34
+
CLI input readers are in `packages/command-surface/src/cli-grammar/`.
40
35
-`src/commands/schema/usage.ts` generates the synopsis `[label]` flag tail from `allowedFlags`.
41
-
A new option reaches `--help` without a synopsis edit.
42
36
Only when the command synopsis names fewer options, declare `usageFlags`.
43
37
For pure grammar or grammar with its own mutually-exclusive brackets, use `[]`.
44
38
Otherwise, use the subset it names. `Command flags:` always lists all of `allowedFlags`.
45
39
For an opt-in across commands, set `usageHidden: true` on its flag definition. This excludes it from every synopsis.
46
-
`src/commands/schema/usage.test.ts` rejects tail options that the command does not accept or the handwritten grammar already includes.
47
40
- If the first positional selects an action, declare `flagsByAction` on the CLI schema.
48
41
Map each action to the options it reads. Derive `allowedFlags` from that table.
49
42
From caller-supplied keys, the parser rejects typed options that the action never reads.
50
-
Config, env, and remote-config defaults populate `flags` without becoming a request. Thus, `AGENT_DEVICE_FPS=30` never breaks `record stop`.
43
+
Options the selected action ignores stay out of its request, even when config, env, or remote-config defaults set them. Thus, `AGENT_DEVICE_FPS=30` never breaks `record stop`.
51
44
Exclude options that every action reads from the table.
52
45
The parser rejects only options in rows. If it rejected `--json`, it would reject the command.
53
46
- Keep command-specific usage/flag metadata with the command family metadata that owns the command.
54
47
- Keep argument parsing in `src/cli/parser/`. Keep help rendering in `src/commands/schema/`.
55
-
Command schema metadata derives from command metadata, family declarations, and the schema-only merge in `src/commands/schema/command-overrides.ts`.
48
+
Command schema metadata derives from command metadata, family declarations, and the schema-only merge in `packages/command-surface/src/schema/command-overrides.ts`.
0 commit comments