Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

fix(cli): support request files and reject invalid request inputs (#112)

澄潭7902562de32d
diff --git a/assets/skills/hiroute-management/SKILL.md b/assets/skills/hiroute-management/SKILL.md
index b56798c9..aa4678d6 100644
--- a/assets/skills/hiroute-management/SKILL.md
+++ b/assets/skills/hiroute-management/SKILL.md
@@ -25,6 +25,16 @@ reports `daemon=role_all` and `gateway=ready`. If not, diagnose with `service do
`service logs`; do not substitute an App-bundle path, repository binary, remote Gateway, direct
database access, or a second daemon.
+
+For JSON business requests, every `--request-stdin` command also supports
+`--request-file PATH`. Prefer a regular request file for replayable Agent submissions;
+choose exactly one source and retain the exact Preview/Apply payload and idempotency key.
+Both sources use the same strict parser and existing byte limits. Unknown fields,
+duplicate JSON members, trailing JSON and mixed sources fail before submission.
+Protected input and capability material still use their separate channels.
+`sessions receipt ID` retains the v1 receipt lookup; a v2 `facts` request through either
+JSON source uses the logical request ID returned by the v2 session timeline.
+
## Contract and authority
- Host management commands are published by `hiroute --help` and their family help: use
diff --git a/contracts/cli/contract-set.v1.json b/contracts/cli/contract-set.v1.json
index a167996b..450dbc84 100644
--- a/contracts/cli/contract-set.v1.json
+++ b/contracts/cli/contract-set.v1.json
@@ -1,10 +1,10 @@
{
- "descriptor_digest": "sha256:a435bc5901bbcaeaf2f41c8c4db15b0a7f967d988aeb544e8f5d2890abc64639",
+ "descriptor_digest": "sha256:1bdd37be3354af88208d5c9f91945f23b392c2bce3eb8ceb5677fa945126d4c5",
"files": {
"agent-check-request.v1.schema.json": "sha256:fbd9e9b19282a5ed8c3e30b5ae16538bc01318a70e4bb7c7a55e8e0472553feb",
"agent-launch-descriptor-request.v1.schema.json": "sha256:28f2f9d2d7f9a1618bea0f13383002429bc9e0ff56166cbee86958a245d0fd48",
"agent-plan-catalog-query.v2.schema.json": "sha256:a597b26eac530352f522a05c29a7c8c3a0ee2b553d69d1d911c2b0a44033338c",
- "coverage-manifest.v1.json": "sha256:0db1cde5b609480819f23b8f96d65f37694fd74b69ea7fa36a268eedd13168b6",
+ "coverage-manifest.v1.json": "sha256:0b5c8f1c46f0084f0a813675ce04b80a478ab956968b7faef717054d098affcc",
"delegation-cancel-request.v1.schema.json": "sha256:0822c53fc16acfcd618fbef66410939f33f634313389a6df4705f414a468b878",
"delegation-continue-request.v1.schema.json": "sha256:da2f81607f37d154a0fa698a107b37d4b0e9d5a03693dcbcc41e0b7e65db5b93",
"delegation-get-request.v1.schema.json": "sha256:85b29839c1c508018ebe40e4b2bb5c1dce7c3a87c27efa30b196b2d1b6658471",
@@ -16,14 +16,14 @@
"local-control-hello.v2.schema.json": "sha256:32fbce882152a886b79bd139d3b4e459b48d94e0634e56ccb189b2c9971ad772",
"local-control.v2.schema.json": "sha256:4b654de90cd6e333b3953379e5b2e1c5125f1dcbe307b7c7c73f12bb2032d18c",
"machine-envelope.v2.schema.json": "sha256:5a0b47ce1fd80628f760a3da5a88de7dc01f6df83cb6eef47fd4a6c8289070ba",
- "manifest.v1.json": "sha256:a98cee2750c670be1bbbb2cfa132bbd14e13a48f623580d807ecfbc410231d9e",
+ "manifest.v1.json": "sha256:58786a9e169957e4ff2d651698d2671919aef87fea9a57e79954ce268afd15e1",
"operation-cancel-request.v1.schema.json": "sha256:0071cbcf27de3bfb7f6644478fe2b73bb5387ebe33db93629ff5672959e8495f",
"operation-lookup.v1.schema.json": "sha256:0fbaaa15b0e75b4186979bdd856bed0485d55a4bd33a33f3caf3bd92e01a7850",
"plan-content-change.v2.schema.json": "sha256:d07d6595109e50ffc0e253b8cfad578632ebc300e014d45e33f02c446b9d42de",
"plan-draft-change.v1.schema.json": "sha256:46366339b9a3689ea0195c641ca9b16820c678641950dd8357db526a07d7bf91",
"plan-editor.v2.schema.json": "sha256:9ce9efd5d8117a9ddb6c1b46d16a9b7eb6ec11e4672b5dac8d3893323dd39ffa",
"plan-lifecycle-change.v1.schema.json": "sha256:a53203683920280574c0ed8c8f888159c10d5df8949b89af67638116ec374a62",
- "planned-manifest.v1.json": "sha256:76d35bae7439125404a6d2511dff7728cf6bcde9a894e4241749f18997a9ce82",
+ "planned-manifest.v1.json": "sha256:344e9e13c6472d64fb029a749cc794eb8620ee3ebf1a70f002c071b963ed072f",
"publication-checkpoint-change.v1.schema.json": "sha256:4d5a709ba41f529318d5e5c1b1399a2e84c5c51f49527edf927e5824412a795d",
"session-list-query.v1.schema.json": "sha256:1f71a89fc019b59c3499708c0760b694b8cb8532028b56d98702cd3b2721cd44",
"session-lookup.v1.schema.json": "sha256:0c9e0ea31bdde7f720a9a17e8dc175902a20b3fb92abc21ce4bdae9fc3d97587",
diff --git a/contracts/cli/coverage-manifest.v1.json b/contracts/cli/coverage-manifest.v1.json
index 86e392ed..5fcc7113 100644
--- a/contracts/cli/coverage-manifest.v1.json
+++ b/contracts/cli/coverage-manifest.v1.json
@@ -1219,7 +1219,7 @@
}
}
],
- "descriptor_digest": "sha256:a435bc5901bbcaeaf2f41c8c4db15b0a7f967d988aeb544e8f5d2890abc64639",
+ "descriptor_digest": "sha256:1bdd37be3354af88208d5c9f91945f23b392c2bce3eb8ceb5677fa945126d4c5",
"schema_version": {
"major": 1,
"minor": 0
diff --git a/contracts/cli/manifest.v1.json b/contracts/cli/manifest.v1.json
index 77deeda3..a1f585dc 100644
--- a/contracts/cli/manifest.v1.json
+++ b/contracts/cli/manifest.v1.json
@@ -5,7 +5,7 @@
},
"product_contract_revision": "487a807c8dc25cfb24e8b097882cd3bb9716a009",
"proposal_map_revision": "ab4da93cc49c6ec56a01e046230411ff1ca82300",
- "descriptor_digest": "sha256:a435bc5901bbcaeaf2f41c8c4db15b0a7f967d988aeb544e8f5d2890abc64639",
+ "descriptor_digest": "sha256:1bdd37be3354af88208d5c9f91945f23b392c2bce3eb8ceb5677fa945126d4c5",
"visibility": "release",
"commands": [
{
@@ -114,12 +114,15 @@
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Find the original Operation in one exact idempotency scope without submitting a write.",
- "usage": "hiroute operations find --request-stdin --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute operations find (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -302,14 +305,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.connect.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview Agent grant, catalog, Skill, overlay, and owned configuration changes.",
- "usage": "hiroute agents connect preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents connect preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -354,14 +358,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.connect.preview",
"idempotency": "required",
"help": {
"purpose": "Apply an exact AgentConnection change through the recoverable Application saga.",
- "usage": "hiroute agents connect apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents connect apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -455,14 +460,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.restore.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview field-owned Agent configuration restoration without overwriting concurrent edits.",
- "usage": "hiroute agents restore preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents restore preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -507,14 +513,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.restore.preview",
"idempotency": "required",
"help": {
"purpose": "Restore only still-owned Agent fields from an exact restore point.",
- "usage": "hiroute agents restore apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents restore apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -838,14 +845,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "compute.connection.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview a connection identity and registered endpoint change without accepting a Secret.",
- "usage": "hiroute compute connection preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts exactly one registered v1 projection, compute-management v2 save/edit, or subscription-check v2 preview request. The optional edit action is rename (display_name), append_models (checked candidate; preserves existing models), remove_models (saved source; selected refs are removals), or delete (saved source; no selected refs). Omitting edit retains released save semantics. Referenced models, including disabled routes and retained versions, cannot be deleted. Preview has no durable side effect and returns the exact digest and revisions required by Apply.",
+ "usage": "hiroute compute connection preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts exactly one registered v1 projection, compute-management v2 save/edit, or subscription-check v2 preview request. The optional edit action is rename (display_name), append_models (checked candidate; preserves existing models), remove_models (saved source; selected refs are removals), or delete (saved source; no selected refs). Omitting edit retains released save semantics. Referenced models, including disabled routes and retained versions, cannot be deleted. Preview has no durable side effect and returns the exact digest and revisions required by Apply.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -887,14 +895,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "compute.connection.preview",
"idempotency": "required",
"help": {
"purpose": "Apply an exact registered compute connection change.",
- "usage": "hiroute compute connection apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the exact preview spec, digest, revisions, and a non-empty idempotency key. Same-UID Local Control reproduces the plan; replay uses the original key and changed payloads are rejected.",
+ "usage": "hiroute compute connection apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the exact preview spec, digest, revisions, and a non-empty idempotency key. Same-UID Local Control reproduces the plan; replay uses the original key and changed payloads are rejected.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -939,13 +948,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Start or resume typed authorization for a registered connection option.",
- "usage": "hiroute compute connection authorize --request-stdin --output json",
- "arguments_and_options": "--request-stdin reads one exact subscription result operation or releases one exact validation. Starting authorization still uses connection Preview/Apply, including revision, digest, and idempotency checks.",
+ "usage": "hiroute compute connection authorize (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin reads one exact subscription result operation or releases one exact validation. Starting authorization still uses connection Preview/Apply, including revision, digest, and idempotency checks.",
"effects": "Application-owned typed operation; side effects are recorded by the Operation and external ledgers.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -987,13 +997,14 @@
"network": "local_control_then_provider_oauth",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Manage an independent Codex or Claude subscription sign-in without enabling routing.",
- "usage": "hiroute compute connection login --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts list/start with provider codex or claude; status/cancel/forget with an exact login_ref; callback with login_ref and input_candidate. Register callback text first with protected-input register --candidate <callback_input_candidate.candidate_ref> --secret-fd <FD>. OAuth codes, tokens, callback URLs and credential paths are rejected in ordinary request JSON. Start returns a browser URL; successful login still requires subscription check, model selection and save.",
+ "usage": "hiroute compute connection login (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts list/start with provider codex or claude; status/cancel/forget with an exact login_ref; callback with login_ref and input_candidate. Register callback text first with protected-input register --candidate <callback_input_candidate.candidate_ref> --secret-fd <FD>. OAuth codes, tokens, callback URLs and credential paths are rejected in ordinary request JSON. Start returns a browser URL; successful login still requires subscription check, model selection and save.",
"effects": "Manages one independent provider login session and CPA-owned credentials. Login does not enable routing; use the existing subscription check and Preview/Apply save flow after choosing models. Forget targets exactly one local login.",
"network_and_model_use": "May open the provider authorization flow and exchange or refresh independent OAuth credentials through CPA. No model inference is performed and native-client refresh tokens are never imported.",
"automation": "Keep the returned login_ref for status, cancel and forget. After uncertain delivery, list/status the existing session before starting again or resubmitting a one-use callback. Never persist the authorization URL or put callback material in argv, environment, logs or ordinary request JSON.",
@@ -1035,13 +1046,14 @@
"network": "local_control_then_registered_gateway",
"model_call": "explicit_probe_may_call_model",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Run one explicit bounded connection probe, with inference only when requested.",
- "usage": "hiroute compute connection test --request-stdin --output json",
- "arguments_and_options": "--request-stdin selects native, registered, discovered, or saved with its strict nested request. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
+ "usage": "hiroute compute connection test (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin selects native, registered, discovered, or saved with its strict nested request. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
"effects": "Runs one explicit bounded source check. It keeps protected input in daemon memory and does not persist source state until the separate Preview/Apply flow.",
"network_and_model_use": "Contacts only the explicitly selected, typed endpoint. Inventory checks make no inference call; selecting an inference model may send one bounded model request and consume provider quota.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1082,13 +1094,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Read connected candidates and exact-native plan rating suggestions.",
- "usage": "hiroute routing options --request-stdin --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute routing options (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1221,13 +1234,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "deterministic_request_replay",
"help": {
"purpose": "Select one validated Worker dependency tuple through same-UID local management.",
- "usage": "hiroute worker dependencies select --request-stdin [--output <json|text|quiet>]",
- "arguments_and_options": "Same-UID local management only. --request-stdin reads one strict JSON object with harness (codex_cli, claude_code, qoder_cli, pi, or deepseek_harness), absolute cli_path, and expected_selection_revision copied from the matching selection_revisions entry returned by worker dependencies discover --output json. codex_cli and claude_code require absolute adapter_path and accept optional absolute node_path. pi requires absolute node_path and forbids adapter_path. qoder_cli and deepseek_harness accept only cli_path and forbid adapter_path and node_path. All paths and the revision are validated again before an atomic selection update; the command never installs software or accepts an Apply capability.",
+ "usage": "hiroute worker dependencies select (--request-stdin | --request-file <PATH>) [--output <json|text|quiet>]",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Same-UID local management only. --request-stdin reads one strict JSON object with harness (codex_cli, claude_code, qoder_cli, pi, or deepseek_harness), absolute cli_path, and expected_selection_revision copied from the matching selection_revisions entry returned by worker dependencies discover --output json. codex_cli and claude_code require absolute adapter_path and accept optional absolute node_path. pi requires absolute node_path and forbids adapter_path. qoder_cli and deepseek_harness accept only cli_path and forbid adapter_path and node_path. All paths and the revision are validated again before an atomic selection update; the command never installs software or accepts an Apply capability.",
"effects": "Application-owned journaled operation after exact spec, digest, selection-revision CAS, and idempotency checks on owner-only Local Control.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Preserve the submitted JSON document. If delivery may have succeeded but no response was received, replay that same document unchanged; its deterministic request identity returns the existing Operation instead of applying twice. Do not substitute paths or a newer revision until the server reports a conflict and discovery is run again.",
@@ -1727,12 +1741,15 @@
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "List AgentPlans, optionally filtered by an AgentConnection grant.",
- "usage": "hiroute routing list [--request-stdin] --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute routing list [(--request-stdin | --request-file <PATH>)] --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1824,14 +1841,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "routing.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview a complete materialized AgentPlan change.",
- "usage": "hiroute routing preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
+ "usage": "hiroute routing preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1875,14 +1893,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "routing.preview",
"idempotency": "required",
"help": {
"purpose": "Apply an exact AgentPlan change and closed publication revision.",
- "usage": "hiroute routing apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
+ "usage": "hiroute routing apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1970,13 +1989,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "required",
"help": {
"purpose": "Save a decision service version or delete an unreferenced service with revision checking.",
- "usage": "hiroute decision services apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts a ChangeSpec preview request first, then the exact ApplyRequest with accept_digest, expected_revisions and idempotency_key. spec.desired_state contains id, expected_revision, service (null to delete), and optional protected input_slot. Replacing a credential requires a new reference. A referenced service cannot be deleted.",
+ "usage": "hiroute decision services apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts a ChangeSpec preview request first, then the exact ApplyRequest with accept_digest, expected_revisions and idempotency_key. spec.desired_state contains id, expected_revision, service (null to delete), and optional protected input_slot. Replacing a credential requires a new reference. A referenced service cannot be deleted.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2018,13 +2038,14 @@
"network": "local_control_then_registered_gateway",
"model_call": "explicit_probe_may_call_model",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Run one explicit synthetic decision through a configured decision service.",
- "usage": "hiroute decision services test --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts schema hiroute.classifier-decision-test/v1 and classifier {kind: decision_service, service: <saved version>}. Sends one fixed synthetic decision; no session history is read. Failure is reported in data.outcome and failure_code, even when the command query succeeds.",
+ "usage": "hiroute decision services test (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts schema hiroute.classifier-decision-test/v1 and classifier {kind: decision_service, service: <saved version>}. Sends one fixed synthetic decision; no session history is read. Failure is reported in data.outcome and failure_code, even when the command query succeeds.",
"effects": "Sends one fixed synthetic routing decision to the explicitly configured service; may consume provider quota. It reads no real session history and does not publish or edit a route.",
"network_and_model_use": "Sends one fixed synthetic routing decision to the explicitly configured service; may consume provider quota. It reads no real session history and does not publish or edit a route.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2068,13 +2089,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Show exact model, capability, reasoning, rating, and source facts.",
- "usage": "hiroute models show --request-stdin --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute models show (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2167,13 +2189,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Search Session and Turn facts without returning content by default.",
- "usage": "hiroute sessions list ([OPTIONS] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Human options retain the v1 query. Fact-only listing is available to the same-UID Local Control peer; --query searches retained text and therefore still requires a separately delivered protected capability. --request-stdin accepts only a strict v2 sessions intent.",
+ "usage": "hiroute sessions list ([OPTIONS] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Human options retain the v1 query. Fact-only listing is available to the same-UID Local Control peer; --query searches retained text and therefore still requires a separately delivered protected capability. --request-stdin accepts only a strict v2 sessions intent.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2218,13 +2241,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Show one Session timeline with content only under an explicit authorized mode.",
- "usage": "hiroute sessions show (<SESSION_ID> [--content <none|messages|messages-and-tools>] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Human options retain the v1 lookup and content defaults to none. Same-UID facts/timeline reads need no extra token; messages, tool content, catalog, ancestry, content pages, and search still require an exact protected capability.",
+ "usage": "hiroute sessions show (<SESSION_ID> [--content <none|messages|messages-and-tools>] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Human options retain the v1 lookup and content defaults to none. Same-UID facts/timeline reads need no extra token; messages, tool content, catalog, ancestry, content pages, and search still require an exact protected capability.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2262,17 +2286,21 @@
"scope": "p0",
"lifecycle": "released",
"kind": "query",
- "request_schema": "hiroute.session-lookup/v1",
- "response_schema": "hiroute.routing-receipt/v1",
+ "request_schema": "hiroute.session-receipt-request/union",
+ "response_schema": "hiroute.session-receipt/union",
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file",
+ "capability_fd"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Read an immutable structured RoutingReceipt without content or recomputation.",
- "usage": "hiroute sessions receipt <RECEIPT_ID>",
- "arguments_and_options": "An exact typed resource ID is required; arbitrary storage keys and SQL are forbidden.",
+ "usage": "hiroute sessions receipt (<RECEIPT_ID> | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. A positional RECEIPT_ID retains the released v1 RoutingReceipt lookup. JSON input accepts only hiroute.observation.query/v2 with view facts and the exact logical request_id returned by the session timeline, limit and optional cursor; returns the v2 facts page. Facts use same-UID Local Control; an explicitly supplied protected grant is still validated.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2365,13 +2393,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Read recorded token, cache and valuation totals with coverage.",
- "usage": "hiroute value show ([OPTIONS] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Human options use the current v2 value_report intent; defaults are the last seven days and separate totals for every currency. --group-by day returns UTC day buckets from the same snapshot. --request-stdin accepts strict v2 value, home_value or value_report intents. Same-UID reads retain known/unknown usage, amounts and coverage; missing values are never filled with zero.",
+ "usage": "hiroute value show ([OPTIONS] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Human options use the current v2 value_report intent; defaults are the last seven days and separate totals for every currency. --group-by day returns UTC day buckets from the same snapshot. --request-stdin accepts strict v2 value, home_value or value_report intents. Same-UID reads retain known/unknown usage, amounts and coverage; missing values are never filled with zero.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2417,13 +2446,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "List the latest competence assessment for each persisted execution segment.",
- "usage": "hiroute observation plan-quality samples ([OPTIONS] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Provide at least --plan-id or --session-id. Use --competence below-floor|meets-floor to compare the latest reliable score with the floor saved for that stage, or --unrated for missing/partial scores. Score bounds remain strict open bounds. Detail filters do not alter full-scope summaries. Facts are same-UID reads; protected evidence content is never returned.",
+ "usage": "hiroute observation plan-quality samples ([OPTIONS] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Provide at least --plan-id or --session-id. Use --competence below-floor|meets-floor to compare the latest reliable score with the floor saved for that stage, or --unrated for missing/partial scores. Score bounds remain strict open bounds. Detail filters do not alter full-scope summaries. Facts are same-UID reads; protected evidence content is never returned.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
diff --git a/contracts/cli/planned-manifest.v1.json b/contracts/cli/planned-manifest.v1.json
index 3557f46b..de5caf1e 100644
--- a/contracts/cli/planned-manifest.v1.json
+++ b/contracts/cli/planned-manifest.v1.json
@@ -5,7 +5,7 @@
},
"product_contract_revision": "487a807c8dc25cfb24e8b097882cd3bb9716a009",
"proposal_map_revision": "ab4da93cc49c6ec56a01e046230411ff1ca82300",
- "descriptor_digest": "sha256:a435bc5901bbcaeaf2f41c8c4db15b0a7f967d988aeb544e8f5d2890abc64639",
+ "descriptor_digest": "sha256:1bdd37be3354af88208d5c9f91945f23b392c2bce3eb8ceb5677fa945126d4c5",
"visibility": "planned",
"commands": [
{
@@ -159,12 +159,15 @@
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Find the original Operation in one exact idempotency scope without submitting a write.",
- "usage": "hiroute operations find --request-stdin --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute operations find (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -723,14 +726,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.connect.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview Agent grant, catalog, Skill, overlay, and owned configuration changes.",
- "usage": "hiroute agents connect preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents connect preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -775,14 +779,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.connect.preview",
"idempotency": "required",
"help": {
"purpose": "Apply an exact AgentConnection change through the recoverable Application saga.",
- "usage": "hiroute agents connect apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents connect apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -876,14 +881,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.restore.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview field-owned Agent configuration restoration without overwriting concurrent edits.",
- "usage": "hiroute agents restore preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents restore preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -928,14 +934,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "agents.restore.preview",
"idempotency": "required",
"help": {
"purpose": "Restore only still-owned Agent fields from an exact restore point.",
- "usage": "hiroute agents restore apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
+ "usage": "hiroute agents restore apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the strict v1 connection or v2 managed-settings request. Apply is same-UID, revision-checked, idempotent, and writes only owned Agent fields; restore refuses concurrent ownership drift.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1307,14 +1314,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "compute.connection.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview a connection identity and registered endpoint change without accepting a Secret.",
- "usage": "hiroute compute connection preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts exactly one registered v1 projection, compute-management v2 save/edit, or subscription-check v2 preview request. The optional edit action is rename (display_name), append_models (checked candidate; preserves existing models), remove_models (saved source; selected refs are removals), or delete (saved source; no selected refs). Omitting edit retains released save semantics. Referenced models, including disabled routes and retained versions, cannot be deleted. Preview has no durable side effect and returns the exact digest and revisions required by Apply.",
+ "usage": "hiroute compute connection preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts exactly one registered v1 projection, compute-management v2 save/edit, or subscription-check v2 preview request. The optional edit action is rename (display_name), append_models (checked candidate; preserves existing models), remove_models (saved source; selected refs are removals), or delete (saved source; no selected refs). Omitting edit retains released save semantics. Referenced models, including disabled routes and retained versions, cannot be deleted. Preview has no durable side effect and returns the exact digest and revisions required by Apply.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1356,14 +1364,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "compute.connection.preview",
"idempotency": "required",
"help": {
"purpose": "Apply an exact registered compute connection change.",
- "usage": "hiroute compute connection apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the exact preview spec, digest, revisions, and a non-empty idempotency key. Same-UID Local Control reproduces the plan; replay uses the original key and changed payloads are rejected.",
+ "usage": "hiroute compute connection apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the exact preview spec, digest, revisions, and a non-empty idempotency key. Same-UID Local Control reproduces the plan; replay uses the original key and changed payloads are rejected.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1408,13 +1417,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Start or resume typed authorization for a registered connection option.",
- "usage": "hiroute compute connection authorize --request-stdin --output json",
- "arguments_and_options": "--request-stdin reads one exact subscription result operation or releases one exact validation. Starting authorization still uses connection Preview/Apply, including revision, digest, and idempotency checks.",
+ "usage": "hiroute compute connection authorize (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin reads one exact subscription result operation or releases one exact validation. Starting authorization still uses connection Preview/Apply, including revision, digest, and idempotency checks.",
"effects": "Application-owned typed operation; side effects are recorded by the Operation and external ledgers.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1456,13 +1466,14 @@
"network": "local_control_then_provider_oauth",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Manage an independent Codex or Claude subscription sign-in without enabling routing.",
- "usage": "hiroute compute connection login --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts list/start with provider codex or claude; status/cancel/forget with an exact login_ref; callback with login_ref and input_candidate. Register callback text first with protected-input register --candidate <callback_input_candidate.candidate_ref> --secret-fd <FD>. OAuth codes, tokens, callback URLs and credential paths are rejected in ordinary request JSON. Start returns a browser URL; successful login still requires subscription check, model selection and save.",
+ "usage": "hiroute compute connection login (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts list/start with provider codex or claude; status/cancel/forget with an exact login_ref; callback with login_ref and input_candidate. Register callback text first with protected-input register --candidate <callback_input_candidate.candidate_ref> --secret-fd <FD>. OAuth codes, tokens, callback URLs and credential paths are rejected in ordinary request JSON. Start returns a browser URL; successful login still requires subscription check, model selection and save.",
"effects": "Manages one independent provider login session and CPA-owned credentials. Login does not enable routing; use the existing subscription check and Preview/Apply save flow after choosing models. Forget targets exactly one local login.",
"network_and_model_use": "May open the provider authorization flow and exchange or refresh independent OAuth credentials through CPA. No model inference is performed and native-client refresh tokens are never imported.",
"automation": "Keep the returned login_ref for status, cancel and forget. After uncertain delivery, list/status the existing session before starting again or resubmitting a one-use callback. Never persist the authorization URL or put callback material in argv, environment, logs or ordinary request JSON.",
@@ -1504,13 +1515,14 @@
"network": "local_control_then_registered_gateway",
"model_call": "explicit_probe_may_call_model",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Run one explicit bounded connection probe, with inference only when requested.",
- "usage": "hiroute compute connection test --request-stdin --output json",
- "arguments_and_options": "--request-stdin selects native, registered, discovered, or saved with its strict nested request. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
+ "usage": "hiroute compute connection test (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin selects native, registered, discovered, or saved with its strict nested request. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
"effects": "Runs one explicit bounded source check. It keeps protected input in daemon memory and does not persist source state until the separate Preview/Apply flow.",
"network_and_model_use": "Contacts only the explicitly selected, typed endpoint. Inventory checks make no inference call; selecting an inference model may send one bounded model request and consume provider quota.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1605,12 +1617,15 @@
"effect": "high_impact_write",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Add a credential from a protected input channel without plaintext argv.",
- "usage": "hiroute compute credential add [typed options] --non-interactive --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute compute credential add (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Application-owned journaled operation after exact spec, digest, revision, capability, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -1896,13 +1911,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Read connected candidates and exact-native plan rating suggestions.",
- "usage": "hiroute routing options --request-stdin --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute routing options (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2035,13 +2051,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "deterministic_request_replay",
"help": {
"purpose": "Select one validated Worker dependency tuple through same-UID local management.",
- "usage": "hiroute worker dependencies select --request-stdin [--output <json|text|quiet>]",
- "arguments_and_options": "Same-UID local management only. --request-stdin reads one strict JSON object with harness (codex_cli, claude_code, qoder_cli, pi, or deepseek_harness), absolute cli_path, and expected_selection_revision copied from the matching selection_revisions entry returned by worker dependencies discover --output json. codex_cli and claude_code require absolute adapter_path and accept optional absolute node_path. pi requires absolute node_path and forbids adapter_path. qoder_cli and deepseek_harness accept only cli_path and forbid adapter_path and node_path. All paths and the revision are validated again before an atomic selection update; the command never installs software or accepts an Apply capability.",
+ "usage": "hiroute worker dependencies select (--request-stdin | --request-file <PATH>) [--output <json|text|quiet>]",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Same-UID local management only. --request-stdin reads one strict JSON object with harness (codex_cli, claude_code, qoder_cli, pi, or deepseek_harness), absolute cli_path, and expected_selection_revision copied from the matching selection_revisions entry returned by worker dependencies discover --output json. codex_cli and claude_code require absolute adapter_path and accept optional absolute node_path. pi requires absolute node_path and forbids adapter_path. qoder_cli and deepseek_harness accept only cli_path and forbid adapter_path and node_path. All paths and the revision are validated again before an atomic selection update; the command never installs software or accepts an Apply capability.",
"effects": "Application-owned journaled operation after exact spec, digest, selection-revision CAS, and idempotency checks on owner-only Local Control.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Preserve the submitted JSON document. If delivery may have succeeded but no response was received, replay that same document unchanged; its deterministic request identity returns the existing Operation instead of applying twice. Do not substitute paths or a newer revision until the server reports a conflict and discovery is run again.",
@@ -2540,13 +2557,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "List visible delegated tasks in durable admission order.",
- "usage": "hiroute tasks list --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent or --capability-fd. stdin carries the typed caller plus optional cursor/limit; default 50, maximum 200. Only tasks visible to the current verified collaboration grant are returned.",
+ "usage": "hiroute tasks list (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent or --capability-fd. stdin carries the typed caller plus optional cursor/limit; default 50, maximum 200. Only tasks visible to the current verified collaboration grant are returned.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2588,13 +2606,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Read one visible task/run or find an original Start/Continue submission key.",
- "usage": "hiroute tasks show (--task <ID> [--run <ID>] | --submission-key <KEY> --operation <start|continue>) --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent or --capability-fd. Select exactly one task (and optional historical run) or the original submission key plus start|continue. A missing key is not permission to retry with a replacement key.",
+ "usage": "hiroute tasks show (--task <ID> [--run <ID>] | --submission-key <KEY> --operation <start|continue>) (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent or --capability-fd. Select exactly one task (and optional historical run) or the original submission key plus start|continue. A missing key is not permission to retry with a replacement key.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2636,13 +2655,14 @@
"model_call": "caller_selected_worker_via_managed_loopback_gateway",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "required",
"help": {
"purpose": "Start one authorized Worker run; retry only with the original idempotency key.",
- "usage": "hiroute tasks start --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent reads the private sealed installation, or --capability-fd supplies an inherited collaboration pipe; never both. stdin schema: hiroute.delegation-start-request/v1. Start returns accepted promptly. Retry the identical request with the original idempotency key; never replace the key after uncertain delivery. A result query does not cancel, and Continue is a separate operation, not a new Start.",
+ "usage": "hiroute tasks start (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent reads the private sealed installation, or --capability-fd supplies an inherited collaboration pipe; never both. stdin schema: hiroute.delegation-start-request/v1. Start returns accepted promptly. Retry the identical request with the original idempotency key; never replace the key after uncertain delivery. A result query does not cancel, and Continue is a separate operation, not a new Start.",
"effects": "Application-owned journaled operation after exact spec, digest, revision, capability, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "The command durably admits a bounded Worker run; that Worker may make model requests only through its exact run-bound loopback Gateway route.",
@@ -2684,13 +2704,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Wait boundedly for a run revision without cancelling it.",
- "usage": "hiroute tasks wait --run <ID> --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent or --capability-fd. --run must match typed stdin. after_revision and wait_ms provide a bounded observation (default 20 seconds, maximum 30); timeout or stopping the client never cancels the run.",
+ "usage": "hiroute tasks wait --run <ID> (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent or --capability-fd. --run must match typed stdin. after_revision and wait_ms provide a bounded observation (default 20 seconds, maximum 30); timeout or stopping the client never cancels the run.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2732,13 +2753,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Read an authorized run's state and persisted result; waiting does not cancel.",
- "usage": "hiroute tasks result --run <ID> --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent or --capability-fd. --run must match the typed run_id in stdin; caller selectors never grant access. stdin schema: hiroute.delegation-result-request/v1 (caller, run_id, optional offset/max_bytes). Reads actual persisted text, at most 1 MiB; next_offset advances UTF-8 byte pagination. An unfinished run remains active; querying or stopping polling does not cancel it.",
+ "usage": "hiroute tasks result --run <ID> (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent or --capability-fd. --run must match the typed run_id in stdin; caller selectors never grant access. stdin schema: hiroute.delegation-result-request/v1 (caller, run_id, optional offset/max_bytes). Reads actual persisted text, at most 1 MiB; next_offset advances UTF-8 byte pagination. An unfinished run remains active; querying or stopping polling does not cancel it.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2780,13 +2802,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "required",
"help": {
"purpose": "Persist cancellation for one exact run and wake its owned Worker scope.",
- "usage": "hiroute tasks cancel --run <ID> --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent or --capability-fd. --run and typed run_id must match; idempotency_key is mandatory. The response reports cancelling or the already-known terminal state; only owned-scope stop evidence can report cancelled/cleanup complete.",
+ "usage": "hiroute tasks cancel --run <ID> (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent or --capability-fd. --run and typed run_id must match; idempotency_key is mandatory. The response reports cancelling or the already-known terminal state; only owned-scope stop evidence can report cancelled/cleanup complete.",
"effects": "Application-owned typed operation; side effects are recorded by the Operation and external ledgers.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2828,13 +2851,14 @@
"model_call": "caller_selected_worker_via_managed_loopback_gateway",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "required",
"help": {
"purpose": "Continue one exact task through its verified native session with a new run token.",
- "usage": "hiroute tasks continue --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent or --capability-fd. stdin names task_id, expected_latest_run_id, a current permit, execution bounds, new instruction, and idempotency_key. Continue uses the retained exact Plan and verified native session with a new run/token; it never falls back to Start, the latest Plan, or session/new.",
+ "usage": "hiroute tasks continue (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent or --capability-fd. stdin names task_id, expected_latest_run_id, a current permit, execution bounds, new instruction, and idempotency_key. Continue uses the retained exact Plan and verified native session with a new run/token; it never falls back to Start, the latest Plan, or session/new.",
"effects": "Application-owned journaled operation after exact spec, digest, revision, capability, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "The command durably admits a bounded Worker run; that Worker may make model requests only through its exact run-bound loopback Gateway route.",
@@ -2876,13 +2900,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "List currently authorized published Worker plans using protected collaboration identity.",
- "usage": "hiroute work-plans list --request-stdin (--agent <codex|claude-code> | --capability-fd <FD>) --json",
- "arguments_and_options": "Required identity: --agent reads the private sealed collaboration installation, or --capability-fd supplies an inherited collaboration pipe; never both. stdin JSON contains workspace_id, context_id, and grant_id as non-secret selectors. The latest allowlist, published Worker metadata, and behavior-verified installation availability are read on every query.",
+ "usage": "hiroute work-plans list (--request-stdin | --request-file <PATH>) (--agent <codex|claude-code> | --capability-fd <FD>) --json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Required identity: --agent reads the private sealed collaboration installation, or --capability-fd supplies an inherited collaboration pipe; never both. stdin JSON contains workspace_id, context_id, and grant_id as non-secret selectors. The latest allowlist, published Worker metadata, and behavior-verified installation availability are read on every query.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -2925,12 +2950,15 @@
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "List AgentPlans, optionally filtered by an AgentConnection grant.",
- "usage": "hiroute routing list [--request-stdin] --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute routing list [(--request-stdin | --request-file <PATH>)] --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3022,14 +3050,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "routing.apply",
"idempotency": "not_applicable",
"help": {
"purpose": "Preview a complete materialized AgentPlan change.",
- "usage": "hiroute routing preview --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
+ "usage": "hiroute routing preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3073,14 +3102,15 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"preview_apply_pair": "routing.preview",
"idempotency": "required",
"help": {
"purpose": "Apply an exact AgentPlan change and closed publication revision.",
- "usage": "hiroute routing apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
+ "usage": "hiroute routing apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts only the existing strict draft, content, or lifecycle schema. Apply must reproduce Preview and carry its exact revisions, digest, and idempotency key; publication remains one recoverable Operation.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3168,13 +3198,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "required",
"help": {
"purpose": "Save a decision service version or delete an unreferenced service with revision checking.",
- "usage": "hiroute decision services apply --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts a ChangeSpec preview request first, then the exact ApplyRequest with accept_digest, expected_revisions and idempotency_key. spec.desired_state contains id, expected_revision, service (null to delete), and optional protected input_slot. Replacing a credential requires a new reference. A referenced service cannot be deleted.",
+ "usage": "hiroute decision services apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts a ChangeSpec preview request first, then the exact ApplyRequest with accept_digest, expected_revisions and idempotency_key. spec.desired_state contains id, expected_revision, service (null to delete), and optional protected input_slot. Replacing a credential requires a new reference. A referenced service cannot be deleted.",
"effects": "Same-UID Application-owned journaled operation after exact spec, digest, revision, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3216,13 +3247,14 @@
"network": "local_control_then_registered_gateway",
"model_call": "explicit_probe_may_call_model",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Run one explicit synthetic decision through a configured decision service.",
- "usage": "hiroute decision services test --request-stdin --output json",
- "arguments_and_options": "--request-stdin accepts schema hiroute.classifier-decision-test/v1 and classifier {kind: decision_service, service: <saved version>}. Sends one fixed synthetic decision; no session history is read. Failure is reported in data.outcome and failure_code, even when the command query succeeds.",
+ "usage": "hiroute decision services test (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin accepts schema hiroute.classifier-decision-test/v1 and classifier {kind: decision_service, service: <saved version>}. Sends one fixed synthetic decision; no session history is read. Failure is reported in data.outcome and failure_code, even when the command query succeeds.",
"effects": "Sends one fixed synthetic routing decision to the explicitly configured service; may consume provider quota. It reads no real session history and does not publish or edit a route.",
"network_and_model_use": "Sends one fixed synthetic routing decision to the explicitly configured service; may consume provider quota. It reads no real session history and does not publish or edit a route.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3361,13 +3393,14 @@
"network": "local_control_only",
"model_call": "never",
"stdin_channels": [
- "request_stdin"
+ "request_stdin",
+ "request_file"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Show exact model, capability, reasoning, rating, and source facts.",
- "usage": "hiroute models show --request-stdin --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute models show (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3458,12 +3491,15 @@
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Read effective current-catalog price facts and local override revisions.",
- "usage": "hiroute prices effective [typed options] --non-interactive --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute prices effective (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3507,12 +3543,15 @@
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Preview a typed local price override change.",
- "usage": "hiroute prices override preview [typed options] --non-interactive --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute prices override preview (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Stateless Preview: no ID, TTL, Operation, Secret, file, database, publication, or network write.",
"network_and_model_use": "No model use and no non-fixture network access.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3556,12 +3595,15 @@
"effect": "high_impact_write",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Apply an exact local price override revision.",
- "usage": "hiroute prices override apply [typed options] --non-interactive --output json",
- "arguments_and_options": "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
+ "usage": "hiroute prices override apply (--request-stdin | --request-file <PATH>) --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.",
"effects": "Application-owned journaled operation after exact spec, digest, revision, capability, and idempotency checks.",
"network_and_model_use": "No model inference; external access, when required, is limited to registered typed ports.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3752,13 +3794,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Search Session and Turn facts without returning content by default.",
- "usage": "hiroute sessions list ([OPTIONS] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Human options retain the v1 query. Fact-only listing is available to the same-UID Local Control peer; --query searches retained text and therefore still requires a separately delivered protected capability. --request-stdin accepts only a strict v2 sessions intent.",
+ "usage": "hiroute sessions list ([OPTIONS] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Human options retain the v1 query. Fact-only listing is available to the same-UID Local Control peer; --query searches retained text and therefore still requires a separately delivered protected capability. --request-stdin accepts only a strict v2 sessions intent.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3803,13 +3846,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Show one Session timeline with content only under an explicit authorized mode.",
- "usage": "hiroute sessions show (<SESSION_ID> [--content <none|messages|messages-and-tools>] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Human options retain the v1 lookup and content defaults to none. Same-UID facts/timeline reads need no extra token; messages, tool content, catalog, ancestry, content pages, and search still require an exact protected capability.",
+ "usage": "hiroute sessions show (<SESSION_ID> [--content <none|messages|messages-and-tools>] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Human options retain the v1 lookup and content defaults to none. Same-UID facts/timeline reads need no extra token; messages, tool content, catalog, ancestry, content pages, and search still require an exact protected capability.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -3847,17 +3891,21 @@
"scope": "p0",
"lifecycle": "released",
"kind": "query",
- "request_schema": "hiroute.session-lookup/v1",
- "response_schema": "hiroute.routing-receipt/v1",
+ "request_schema": "hiroute.session-receipt-request/union",
+ "response_schema": "hiroute.session-receipt/union",
"effect": "none",
"network": "local_control_only",
"model_call": "never",
- "stdin_channels": [],
+ "stdin_channels": [
+ "request_stdin",
+ "request_file",
+ "capability_fd"
+ ],
"idempotency": "not_applicable",
"help": {
"purpose": "Read an immutable structured RoutingReceipt without content or recomputation.",
- "usage": "hiroute sessions receipt <RECEIPT_ID>",
- "arguments_and_options": "An exact typed resource ID is required; arbitrary storage keys and SQL are forbidden.",
+ "usage": "hiroute sessions receipt (<RECEIPT_ID> | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. A positional RECEIPT_ID retains the released v1 RoutingReceipt lookup. JSON input accepts only hiroute.observation.query/v2 with view facts and the exact logical request_id returned by the session timeline, limit and optional cursor; returns the v2 facts page. Facts use same-UID Local Control; an explicitly supplied protected grant is still validated.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -4096,13 +4144,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "Read recorded token, cache and valuation totals with coverage.",
- "usage": "hiroute value show ([OPTIONS] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Human options use the current v2 value_report intent; defaults are the last seven days and separate totals for every currency. --group-by day returns UTC day buckets from the same snapshot. --request-stdin accepts strict v2 value, home_value or value_report intents. Same-UID reads retain known/unknown usage, amounts and coverage; missing values are never filled with zero.",
+ "usage": "hiroute value show ([OPTIONS] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Human options use the current v2 value_report intent; defaults are the last seven days and separate totals for every currency. --group-by day returns UTC day buckets from the same snapshot. --request-stdin accepts strict v2 value, home_value or value_report intents. Same-UID reads retain known/unknown usage, amounts and coverage; missing values are never filled with zero.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
@@ -4148,13 +4197,14 @@
"model_call": "never",
"stdin_channels": [
"request_stdin",
+ "request_file",
"capability_fd"
],
"idempotency": "not_applicable",
"help": {
"purpose": "List the latest competence assessment for each persisted execution segment.",
- "usage": "hiroute observation plan-quality samples ([OPTIONS] | --request-stdin) [--capability-fd <FD>] --non-interactive --output json",
- "arguments_and_options": "Provide at least --plan-id or --session-id. Use --competence below-floor|meets-floor to compare the latest reliable score with the floor saved for that stage, or --unrated for missing/partial scores. Score bounds remain strict open bounds. Detail filters do not alter full-scope summaries. Facts are same-UID reads; protected evidence content is never returned.",
+ "usage": "hiroute observation plan-quality samples ([OPTIONS] | (--request-stdin | --request-file <PATH>)) [--capability-fd <FD>] --non-interactive --output json",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. Provide at least --plan-id or --session-id. Use --competence below-floor|meets-floor to compare the latest reliable score with the floor saved for that stage, or --unrated for missing/partial scores. Score bounds remain strict open bounds. Detail filters do not alter full-scope summaries. Facts are same-UID reads; protected evidence content is never returned.",
"effects": "Read-only; no product side effect.",
"network_and_model_use": "No model use; any external dependency is declared by the typed Application operation.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
diff --git a/crates/application-api/src/lib.rs b/crates/application-api/src/lib.rs
index 65d0f5cb..b8d69dbd 100644
--- a/crates/application-api/src/lib.rs
+++ b/crates/application-api/src/lib.rs
@@ -230,10 +230,12 @@ mod protocol_tests {
assert!(discover.help.output.contains("omits the CAS revisions"));
let select = command_by_id("worker.dependencies.select").unwrap();
- assert_eq!(select.stdin_channels, ["request_stdin"]);
+ assert_eq!(select.stdin_channels, ["request_stdin", "request_file"]);
assert_eq!(select.idempotency, "deterministic_request_replay");
let help = select.help_document();
for required in [
+ "--request-stdin",
+ "--request-file <PATH>",
"harness",
"adapter_path",
"cli_path",
diff --git a/crates/application-api/src/protocol.rs b/crates/application-api/src/protocol.rs
index 84c073b0..eec59e71 100644
--- a/crates/application-api/src/protocol.rs
+++ b/crates/application-api/src/protocol.rs
@@ -864,7 +864,8 @@ pub(crate) fn command_request_schema(command_id: &str) -> &'static str {
"compute.connection.test" => "hiroute.compute-connection-test-request/v1",
"models.show" => "hiroute.model-catalog-query/v1",
"sessions.list" => "hiroute.session-list-query/v1",
- "sessions.show" | "sessions.receipt" => "hiroute.session-lookup/v1",
+ "sessions.show" => "hiroute.session-lookup/v1",
+ "sessions.receipt" => "hiroute.session-receipt-request/union",
"value.show" => "hiroute.observation.query/v2",
"observation.plan-quality.samples" => "hiroute.observation.query/v2",
_ => "hiroute.empty-request/v1",
@@ -930,7 +931,7 @@ pub(crate) fn command_response_schema(command_id: &str) -> &'static str {
"models.show" => "hiroute.model-catalog-view/v1",
"sessions.list" => "hiroute.session-list/v1",
"sessions.show" => "hiroute.session-detail/v1",
- "sessions.receipt" => "hiroute.routing-receipt/v1",
+ "sessions.receipt" => "hiroute.session-receipt/union",
"sessions.status" => "hiroute.session-store-status/v1",
"value.show" => "hiroute.observation.value-report/v2",
"observation.plan-quality.samples" => "hiroute.plan-quality-samples-page/v1",
@@ -961,13 +962,19 @@ pub(crate) fn command_model_call(command_id: &str) -> &'static str {
pub(crate) fn command_stdin_channels(command_id: &str) -> &'static [&'static str] {
match command_id {
"worker.exec" | "worker.continue" => &["prompt_stdin", "file"],
- "worker.dependencies.select" => &["request_stdin"],
+ "worker.dependencies.select" => &["request_stdin", "request_file"],
value if value.starts_with("worker.") => &[],
- "work-plans.list" => &["request_stdin", "capability_fd"],
- value if value.starts_with("tasks.") => &["request_stdin", "capability_fd"],
+ "work-plans.list" => &["request_stdin", "request_file", "capability_fd"],
+ value if value.starts_with("tasks.") => &["request_stdin", "request_file", "capability_fd"],
"setup.preview" => &["spec_stdin"],
"setup.apply" => &["spec_fd", "capability_fd"],
- "models.show"
+ "operations.find"
+ | "routing.list"
+ | "prices.effective"
+ | "prices.override.preview"
+ | "prices.override.apply"
+ | "compute.credential.add"
+ | "models.show"
| "compute.connection.preview"
| "compute.connection.apply"
| "compute.connection.authorize"
@@ -981,10 +988,12 @@ pub(crate) fn command_stdin_channels(command_id: &str) -> &'static [&'static str
| "agents.connect.preview"
| "agents.connect.apply"
| "agents.restore.preview"
- | "agents.restore.apply" => &["request_stdin"],
- "sessions.list" | "sessions.show" | "value.show" | "observation.plan-quality.samples" => {
- &["request_stdin", "capability_fd"]
- }
+ | "agents.restore.apply" => &["request_stdin", "request_file"],
+ "sessions.list"
+ | "sessions.show"
+ | "sessions.receipt"
+ | "value.show"
+ | "observation.plan-quality.samples" => &["request_stdin", "request_file", "capability_fd"],
"agents.check" | "operations.cancel" => &["capability_fd"],
_ => &[],
}
@@ -1040,7 +1049,7 @@ pub(crate) fn staged_coverage(command_id: &str, positive: bool) -> Option<Covera
}
pub(crate) fn command_usage(command_id: &str, joined_path: &str) -> String {
- match command_id {
+ let usage: String = match command_id {
"worker.executors" => "hiroute worker executors [--output <json|text|quiet>]".into(),
"worker.dependencies.discover" => "hiroute worker dependencies discover [--harness <codex_cli|claude_code|qoder_cli|pi|deepseek_harness>] [--output <json|text|quiet>]".into(),
"worker.dependencies.select" => "hiroute worker dependencies select --request-stdin [--output <json|text|quiet>]".into(),
@@ -1065,7 +1074,7 @@ pub(crate) fn command_usage(command_id: &str, joined_path: &str) -> String {
"agent.launch" => "hiroute agent launch --agent claude-code --context <CONTEXT_ID> -- <CLAUDE_SESSION_ARGS...>".to_owned(),
"schema.show" => "hiroute schema show --command-id <stable-command-id> --non-interactive --output json".to_owned(),
"operations.find" => "hiroute operations find --request-stdin --output json".to_owned(),
- "models.show" => "hiroute models show --request-stdin --output json".to_owned(),
+ "models.show" | "prices.effective" | "prices.override.preview" | "prices.override.apply" | "compute.credential.add" => format!("hiroute {joined_path} --request-stdin --output json"),
"compute.list" => "hiroute compute list --output json".to_owned(),
"compute.show" => "hiroute compute show <SOURCE_ID> --output json".to_owned(),
"compute.connection.preview" | "compute.connection.apply" | "compute.connection.authorize" | "compute.connection.login" | "compute.connection.test" => {
@@ -1095,13 +1104,17 @@ pub(crate) fn command_usage(command_id: &str, joined_path: &str) -> String {
format!("hiroute {joined_path} <OPERATION_ID> [OPTIONS]")
}
"agents.check" => "hiroute agents check <AGENT_ID> --scope <configuration|native-authentication|collaboration|live> --suite <quick|tool|conformance> [--target <JSON>] [--allow-model-call]; live requires an explicit context/surface/revision/model target and protected consent; local checks use same-UID trust and make no upstream model call".to_owned(),
- "sessions.receipt" => "hiroute sessions receipt <RECEIPT_ID>".to_owned(),
+ "sessions.receipt" => "hiroute sessions receipt (<RECEIPT_ID> | --request-stdin) [--capability-fd <FD>] --output json".to_owned(),
_ => format!("hiroute {joined_path} [typed options] --non-interactive --output json"),
- }
+ };
+ usage.replace(
+ "--request-stdin",
+ "(--request-stdin | --request-file <PATH>)",
+ )
}
pub(crate) fn command_arguments(command_id: &str) -> String {
- match command_id {
+ let arguments: String = match command_id {
"worker.executors" => "No Agent, Plan, allowlist, capability FD, or request body is accepted. The query checks configured entry metadata and executability, not program contents or compatibility. Ready allows a launch attempt; it does not prove optional capabilities, install, configure, authorize, or admit a run.".into(),
"worker.dependencies.discover" => "Optionally restrict discovery to one Harness. The query checks the selected path, PATH, common locations, npm globals and npx cache without installing or selecting anything.".into(),
"worker.dependencies.select" => "Same-UID local management only. --request-stdin reads one strict JSON object with harness (codex_cli, claude_code, qoder_cli, pi, or deepseek_harness), absolute cli_path, and expected_selection_revision copied from the matching selection_revisions entry returned by worker dependencies discover --output json. codex_cli and claude_code require absolute adapter_path and accept optional absolute node_path. pi requires absolute node_path and forbids adapter_path. qoder_cli and deepseek_harness accept only cli_path and forbid adapter_path and node_path. All paths and the revision are validated again before an atomic selection update; the command never installs software or accepts an Apply capability.".into(),
@@ -1142,7 +1155,15 @@ pub(crate) fn command_arguments(command_id: &str) -> String {
"observation.plan-quality.samples" => "Provide at least --plan-id or --session-id. Use --competence below-floor|meets-floor to compare the latest reliable score with the floor saved for that stage, or --unrated for missing/partial scores. Score bounds remain strict open bounds. Detail filters do not alter full-scope summaries. Facts are same-UID reads; protected evidence content is never returned.".to_owned(),
"value.show" => "Human options use the current v2 value_report intent; defaults are the last seven days and separate totals for every currency. --group-by day returns UTC day buckets from the same snapshot. --request-stdin accepts strict v2 value, home_value or value_report intents. Same-UID reads retain known/unknown usage, amounts and coverage; missing values are never filled with zero.".to_owned(),
"sessions.show" => "Human options retain the v1 lookup and content defaults to none. Same-UID facts/timeline reads need no extra token; messages, tool content, catalog, ancestry, content pages, and search still require an exact protected capability.".to_owned(),
- "sessions.receipt" | "setup.status" | "operations.get" | "operations.watch" | "operations.cancel" => "An exact typed resource ID is required; arbitrary storage keys and SQL are forbidden.".to_owned(),
+ "sessions.receipt" => "A positional RECEIPT_ID retains the released v1 RoutingReceipt lookup. JSON input accepts only hiroute.observation.query/v2 with view facts and the exact logical request_id returned by the session timeline, limit and optional cursor; returns the v2 facts page. Facts use same-UID Local Control; an explicitly supplied protected grant is still validated.".to_owned(),
+ "setup.status" | "operations.get" | "operations.watch" | "operations.cancel" => "An exact typed resource ID is required; arbitrary storage keys and SQL are forbidden.".to_owned(),
_ => "Only the typed options declared by the generated request schema are accepted; arbitrary patches, URLs, shell, or plaintext Secret argv are forbidden.".to_owned(),
+ };
+ if command_stdin_channels(command_id).contains(&"request_stdin") {
+ format!(
+ "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. {arguments}"
+ )
+ } else {
+ arguments
}
}
diff --git a/crates/cli/INPUT.md b/crates/cli/INPUT.md
new file mode 100644
index 00000000..3f3af9ab
--- /dev/null
+++ b/crates/cli/INPUT.md
@@ -0,0 +1,43 @@
+# CLI request input ownership
+
+`src/request_input.rs` owns selection of `--request-stdin` or `--request-file PATH`,
+bounded byte reads and strict UTF-8 JSON decoding. A request file must be regular;
+opening a FIFO does not wait for a writer. Relative paths use the caller's working
+directory. Prefix option-shaped filenames with `./`. Exactly one source is accepted;
+repeated sources, mixed sources and mixtures with human options fail with
+`INVALID_ARGUMENTS` before Local Control access. A file never reads stdin.
+
+The parser rejects duplicate object members at every nesting level (including escaped
+aliases of the same key) and trailing JSON. `src/request_input/fields.rs` audits the
+typed request's declared object fields, including skipped optional fields and tagged
+unit variants; maps/JSON Values keep free keys and typed map values remain checked.
+Serde's existing positional struct arrays remain accepted and checked in field order.
+Current request DTOs have matching Serialize/Deserialize names without aliases or
+flatten; future asymmetric codecs require an explicit adapter and regression tests.
+This CLI boundary must not tighten persisted Domain recovery readers. Command owners
+then select the permitted schema/intent and retain semantic checks:
+
+- `control_plane.rs`: typed management requests and Preview/Apply schema unions.
+- `observation.rs`: sessions, timeline, Facts, value and plan-quality intents.
+- `lib.rs`: Operation idempotency lookup; legacy positional command codecs.
+- `worker/input.rs`: dependency selection only; `--file` remains prompt text.
+- `tasks.rs` and `work_plans.rs`: staged collaboration selectors and grant separation;
+ adding a source does not promote these commands to the public command registry.
+
+Keep each existing limit: 1 MiB by default, 64 KiB for Operation idempotency lookup
+and dependency selection, 4 KiB for staged WorkPlan listing. Protected secret and
+capability readers are independent; JSON/file selectors do not grant authority.
+The shared reader does not execute a shell, alter requests or choose a business schema.
+
+`sessions receipt RECEIPT_ID` continues to serialize `SessionLookupV1` and read the v1
+RoutingReceipt. Both JSON sources accept only an `ObservationReadRequestV2` with the
+`facts` intent and its logical RequestId from a v2 timeline, through the existing
+`GetRoutingReceipt` operation. The response is the v2 Facts page. Wrong intents fail
+locally. Do not translate a SessionId or ReceiptId into a RequestId.
+
+Positional resource codecs exclude empty and option-shaped values. Unknown options
+must be usage errors before a lookup; a failed resource search cannot stand in for
+argument validation. `src/args.rs` preserves the request-file path as an option value
+while extracting global flags. Follow `tests/request_input.rs` for actual binary argv
+regressions and the owner codec tests for typed projections. Generated help/channel
+metadata belongs to application-api; regenerate CLI and Product E2E contracts together.
diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs
index 18e1659d..e6791e7f 100644
--- a/crates/cli/src/args.rs
+++ b/crates/cli/src/args.rs
@@ -48,6 +48,18 @@ pub(crate) fn split_globals(
index += 2;
continue;
}
+ if arguments[index] == "--request-file" {
+ remaining.push(arguments[index].clone());
+ let Some(path) = arguments
+ .get(index + 1)
+ .filter(|path| crate::request_input::valid_positional(path))
+ else {
+ return Err(split_error(globals, worker));
+ };
+ remaining.push(path.clone());
+ index += 2;
+ continue;
+ }
if worker {
if arguments[index] == "--" {
remaining.extend(arguments[index..].iter().cloned());
diff --git a/crates/cli/src/control_plane.rs b/crates/cli/src/control_plane.rs
index 357f8cfe..833b2872 100644
--- a/crates/cli/src/control_plane.rs
+++ b/crates/cli/src/control_plane.rs
@@ -3,6 +3,7 @@
//! This module owns no discovery, persistence, or routing behavior. It accepts only the exact
//! typed Local Control request DTOs and leaves the public generated command manifest unchanged.
+#[cfg(test)]
use std::io::Read;
use hiroute_application_api::{
@@ -38,7 +39,7 @@ const TYPED_CONTROL_IDS: [&str; 16] = [
"agents.restore.preview",
"agents.restore.apply",
];
-const MAX_REQUEST_BYTES: u64 = 1024 * 1024;
+use crate::request_input::{self, MAX_REQUEST_BYTES};
#[cfg(test)]
pub(crate) fn typed_control_commands() -> impl Iterator<Item = CommandDescriptorV1> {
@@ -68,15 +69,15 @@ pub(crate) fn command_payload(
options,
)),
"decision.services.apply" => Some(preview_or_apply(options)),
- "decision.services.test" => Some(stdin::<
+ "decision.services.test" => Some(request::<
hiroute_application_api::ClassifierDecisionTestRequestV1,
>(options)),
- "models.show" => Some(stdin::<hiroute_application_api::ModelCatalogQueryV1>(
+ "models.show" => Some(request::<hiroute_application_api::ModelCatalogQueryV1>(
options,
)),
- "prices.effective" => Some(stdin::<GetEffectivePricesV2>(options)),
- "prices.override.preview" => Some(stdin::<PreviewPriceOverrideChangeV2>(options)),
- "prices.override.apply" => Some(stdin::<ApplyPriceOverrideChangeV2>(options)),
+ "prices.effective" => Some(request::<GetEffectivePricesV2>(options)),
+ "prices.override.preview" => Some(request::<PreviewPriceOverrideChangeV2>(options)),
+ "prices.override.apply" => Some(request::<ApplyPriceOverrideChangeV2>(options)),
"compute.scan" => Some(empty::<ComputeScanRequestV1>(options)),
"compute.list" => Some(empty::<ComputeManagementQueryV2>(options)),
"compute.show" => Some(positional(options, |source_id| ComputeManagementQueryV2 {
@@ -84,23 +85,23 @@ pub(crate) fn command_payload(
})),
"compute.connection.options" => Some(empty::<ComputeConnectionOptionsRequestV1>(options)),
"compute.connection.preview" => Some(compute_preview(options)),
- "compute.connection.apply" => Some(stdin::<ComputeConnectionApplyRequestV1>(options)),
+ "compute.connection.apply" => Some(request::<ComputeConnectionApplyRequestV1>(options)),
"compute.connection.authorize" => {
- Some(stdin::<ComputeConnectionAuthorizationRequestV1>(options))
+ Some(request::<ComputeConnectionAuthorizationRequestV1>(options))
}
- "compute.connection.login" => Some(stdin::<
+ "compute.connection.login" => Some(request::<
hiroute_application_api::ComputeSubscriptionLoginRequestV1,
>(options)),
- "compute.connection.test" => Some(stdin::<ComputeConnectionTestRequestV1>(options)),
+ "compute.connection.test" => Some(request::<ComputeConnectionTestRequestV1>(options)),
"compute.credential.add" => Some(preview_or_apply(options)),
- "routing.list" if !options.is_empty() => Some(stdin::<
+ "routing.list" if !options.is_empty() => Some(request::<
hiroute_application_api::AgentPlanCatalogQueryV2,
>(options)),
"routing.preview" => Some(routing_request(options, false)),
"routing.apply" => Some(routing_request(options, true)),
"agents.connect.preview" => Some(agent_request(options, false)),
"routing.options" => {
- Some(stdin::<hiroute_application_api::PlanEditorOptionsRequestV1>(options))
+ Some(request::<hiroute_application_api::PlanEditorOptionsRequestV1>(options))
}
"agents.connect.apply" => Some(agent_request(options, true)),
"agents.restore.preview" => Some(agent_restore_request(options, false)),
@@ -122,10 +123,7 @@ pub(crate) fn command_payload(
}
fn compute_preview(options: &[String]) -> Result<Value, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- let value = read_value(std::io::stdin())?;
+ let value = request_input::read(options, MAX_REQUEST_BYTES)?;
if value
.get("change")
.and_then(|change| change.get("schema"))
@@ -141,19 +139,12 @@ fn compute_preview(options: &[String]) -> Result<Value, ErrorCode> {
}
fn typed_value<T: DeserializeOwned + Serialize>(value: Value) -> Result<Value, ErrorCode> {
- let request: T = serde_json::from_value(value).map_err(|_| ErrorCode::InvalidArguments)?;
+ let request: T = request_input::deserialize(value)?;
serde_json::to_value(request).map_err(|_| ErrorCode::Internal)
}
fn routing_request(options: &[String], apply: bool) -> Result<Value, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- let value = read_value(std::io::stdin())?;
- fn typed<T: DeserializeOwned + Serialize>(value: Value) -> Result<Value, ErrorCode> {
- let request: T = serde_json::from_value(value).map_err(|_| ErrorCode::InvalidArguments)?;
- serde_json::to_value(request).map_err(|_| ErrorCode::Internal)
- }
+ let value = request_input::read(options, MAX_REQUEST_BYTES)?;
if value
.get("change")
.and_then(|c| c.get("schema"))
@@ -161,9 +152,9 @@ fn routing_request(options: &[String], apply: bool) -> Result<Value, ErrorCode>
== Some(hiroute_application_api::PUBLICATION_CHECKPOINT_CHANGE_SCHEMA_V1)
{
return if apply {
- typed::<hiroute_application_api::PublicationCheckpointApplyRequestV1>(value)
+ typed_value::<hiroute_application_api::PublicationCheckpointApplyRequestV1>(value)
} else {
- typed::<hiroute_application_api::PublicationCheckpointPreviewRequestV1>(value)
+ typed_value::<hiroute_application_api::PublicationCheckpointPreviewRequestV1>(value)
};
}
if value
@@ -173,9 +164,9 @@ fn routing_request(options: &[String], apply: bool) -> Result<Value, ErrorCode>
== Some(hiroute_application_api::PLAN_LIFECYCLE_CHANGE_SCHEMA_V1)
{
return if apply {
- typed::<hiroute_application_api::PlanLifecycleApplyRequestV1>(value)
+ typed_value::<hiroute_application_api::PlanLifecycleApplyRequestV1>(value)
} else {
- typed::<hiroute_application_api::PlanLifecyclePreviewRequestV1>(value)
+ typed_value::<hiroute_application_api::PlanLifecyclePreviewRequestV1>(value)
};
}
if value
@@ -185,9 +176,9 @@ fn routing_request(options: &[String], apply: bool) -> Result<Value, ErrorCode>
== Some(hiroute_application_api::PLAN_DRAFT_CHANGE_SCHEMA_V1)
{
return if apply {
- typed::<hiroute_application_api::PlanDraftApplyRequestV1>(value)
+ typed_value::<hiroute_application_api::PlanDraftApplyRequestV1>(value)
} else {
- typed::<hiroute_application_api::PlanDraftPreviewRequestV1>(value)
+ typed_value::<hiroute_application_api::PlanDraftPreviewRequestV1>(value)
};
}
if value
@@ -199,30 +190,24 @@ fn routing_request(options: &[String], apply: bool) -> Result<Value, ErrorCode>
return Err(ErrorCode::InvalidArguments);
}
if apply {
- typed::<hiroute_application_api::PlanContentApplyRequestV2>(value)
+ typed_value::<hiroute_application_api::PlanContentApplyRequestV2>(value)
} else {
- typed::<hiroute_application_api::PlanContentPreviewRequestV2>(value)
+ typed_value::<hiroute_application_api::PlanContentPreviewRequestV2>(value)
}
}
fn agent_request(options: &[String], apply: bool) -> Result<Value, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- validate_agent_request(read_value(std::io::stdin())?, apply)
+ validate_agent_request(request_input::read(options, MAX_REQUEST_BYTES)?, apply)
}
fn agent_restore_request(options: &[String], apply: bool) -> Result<Value, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- validate_restore_request(read_value(std::io::stdin())?, apply)
+ validate_restore_request(request_input::read(options, MAX_REQUEST_BYTES)?, apply)
}
fn validate_restore_request(value: Value, apply: bool) -> Result<Value, ErrorCode> {
let value = validate_agent_request(value, apply)?;
let spec: hiroute_application_api::AgentSettingsSpecV2 =
- serde_json::from_value(value["spec"].clone()).map_err(|_| ErrorCode::InvalidArguments)?;
+ request_input::deserialize(value["spec"].clone())?;
if spec.schema_version != hiroute_application_api::AGENT_SETTINGS_SCHEMA_V2
|| !spec.is_restore_only()
{
@@ -233,22 +218,23 @@ fn validate_restore_request(value: Value, apply: bool) -> Result<Value, ErrorCod
fn validate_agent_request(value: Value, apply: bool) -> Result<Value, ErrorCode> {
let v2 = value["spec"]["schema_version"]["major"] == 2;
- let valid = match (v2, apply) {
- (true, true) => {
- serde_json::from_value::<hiroute_application_api::AgentSettingsApplyV2>(value.clone())
- .is_ok()
- }
- (true, false) => serde_json::from_value::<
- hiroute_application_api::AgentSettingsPreviewRequestV2,
- >(value.clone())
- .is_ok(),
- (false, true) => {
- serde_json::from_value::<AgentConnectionApplyRequestV1>(value.clone()).is_ok()
- }
- (false, false) => {
- serde_json::from_value::<AgentConnectionPreviewRequestV1>(value.clone()).is_ok()
- }
- };
+ let valid =
+ match (v2, apply) {
+ (true, true) => request_input::deserialize::<
+ hiroute_application_api::AgentSettingsApplyV2,
+ >(value.clone())
+ .is_ok(),
+ (true, false) => request_input::deserialize::<
+ hiroute_application_api::AgentSettingsPreviewRequestV2,
+ >(value.clone())
+ .is_ok(),
+ (false, true) => {
+ request_input::deserialize::<AgentConnectionApplyRequestV1>(value.clone()).is_ok()
+ }
+ (false, false) => {
+ request_input::deserialize::<AgentConnectionPreviewRequestV1>(value.clone()).is_ok()
+ }
+ };
if valid {
Ok(value)
} else {
@@ -257,10 +243,7 @@ fn validate_agent_request(value: Value, apply: bool) -> Result<Value, ErrorCode>
}
fn preview_or_apply(options: &[String]) -> Result<Value, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- let value = read_value(std::io::stdin())?;
+ let value = request_input::read(options, MAX_REQUEST_BYTES)?;
let keys = value
.as_object()
.ok_or(ErrorCode::InvalidArguments)?
@@ -278,11 +261,9 @@ fn preview_or_apply(options: &[String]) -> Result<Value, ErrorCode> {
.into_iter()
.collect();
if keys == preview_keys {
- serde_json::from_value::<PreviewRequestV1>(value.clone())
- .map_err(|_| ErrorCode::InvalidArguments)?;
+ request_input::deserialize::<PreviewRequestV1>(value.clone())?;
} else if keys == apply_keys {
- let apply = serde_json::from_value::<ApplyRequestV1>(value.clone())
- .map_err(|_| ErrorCode::InvalidArguments)?;
+ let apply = request_input::deserialize::<ApplyRequestV1>(value.clone())?;
if apply.apply_capability.is_some() || apply.idempotency_key.is_empty() {
return Err(ErrorCode::InvalidArguments);
}
@@ -299,7 +280,7 @@ where
let [value] = options else {
return Err(ErrorCode::InvalidArguments);
};
- if value.is_empty() {
+ if !request_input::valid_positional(value) {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(build(value.clone())).map_err(|_| ErrorCode::Internal)
@@ -315,42 +296,19 @@ where
serde_json::to_value(T::default()).map_err(|_| ErrorCode::Internal)
}
-fn stdin<T>(options: &[String]) -> Result<Value, ErrorCode>
+fn request<T>(options: &[String]) -> Result<Value, ErrorCode>
where
T: DeserializeOwned + Serialize,
{
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- typed_request::<T>(std::io::stdin())
+ request_input::typed::<T>(options, MAX_REQUEST_BYTES)
}
+#[cfg(test)]
fn typed_request<T>(reader: impl Read) -> Result<Value, ErrorCode>
where
T: DeserializeOwned + Serialize,
{
- let mut bytes = Vec::new();
- reader
- .take(MAX_REQUEST_BYTES + 1)
- .read_to_end(&mut bytes)
- .map_err(|_| ErrorCode::InvalidArguments)?;
- if bytes.len() as u64 > MAX_REQUEST_BYTES {
- return Err(ErrorCode::InvalidArguments);
- }
- let request: T = serde_json::from_slice(&bytes).map_err(|_| ErrorCode::InvalidArguments)?;
- serde_json::to_value(request).map_err(|_| ErrorCode::Internal)
-}
-
-fn read_value(reader: impl Read) -> Result<Value, ErrorCode> {
- let mut bytes = Vec::new();
- reader
- .take(MAX_REQUEST_BYTES + 1)
- .read_to_end(&mut bytes)
- .map_err(|_| ErrorCode::InvalidArguments)?;
- if bytes.len() as u64 > MAX_REQUEST_BYTES {
- return Err(ErrorCode::InvalidArguments);
- }
- serde_json::from_slice(&bytes).map_err(|_| ErrorCode::InvalidArguments)
+ typed_value::<T>(request_input::read_json(reader, MAX_REQUEST_BYTES)?)
}
#[cfg(test)]
diff --git a/crates/cli/src/lib.rs b/crates/cli/src/lib.rs
index a647fe30..e2a0176d 100644
--- a/crates/cli/src/lib.rs
+++ b/crates/cli/src/lib.rs
@@ -12,11 +12,12 @@ mod control_plane;
mod host_commands;
mod managed_launch;
mod observation;
+mod request_input;
mod service;
mod worker;
use std::ffi::OsString;
-use std::io::{Read, Write};
+use std::io::Write;
use std::sync::atomic::{AtomicU64, Ordering};
use args::{Globals, split_globals};
@@ -306,7 +307,7 @@ fn command_payload(command_id: &str, options: &[String]) -> Result<Value, ErrorC
| "sessions.status" => empty(options),
"routing.list" if options.is_empty() => empty(options),
"routing.show" => match options {
- [id] => Ok(json!({"agent_plan_id": id})),
+ [id] if request_input::valid_positional(id) => Ok(json!({"agent_plan_id": id})),
_ => Err(ErrorCode::InvalidArguments),
},
"work-plans.list" => work_plans::payload(options),
@@ -329,20 +330,7 @@ fn command_payload(command_id: &str, options: &[String]) -> Result<Value, ErrorC
}
fn client_lookup(options: &[String]) -> Result<Value, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- let mut input = String::new();
- std::io::stdin()
- .take(65_537)
- .read_to_string(&mut input)
- .map_err(|_| ErrorCode::InvalidArguments)?;
- if input.len() > 65_536 {
- return Err(ErrorCode::InvalidArguments);
- }
- let value: hiroute_application_api::OperationIdempotencyLookupV1 =
- serde_json::from_str(&input).map_err(|_| ErrorCode::InvalidArguments)?;
- serde_json::to_value(value).map_err(|_| ErrorCode::InvalidArguments)
+ request_input::typed::<hiroute_application_api::OperationIdempotencyLookupV1>(options, 65_536)
}
fn empty(options: &[String]) -> Result<Value, ErrorCode> {
@@ -431,8 +419,7 @@ fn setup_apply(options: &[String]) -> Result<Value, ErrorCode> {
index += 1;
}
serde_json::to_value(SetupApplyRequestV1 {
- spec: serde_json::from_value(spec.ok_or(ErrorCode::InvalidArguments)?)
- .map_err(|_| ErrorCode::InvalidArguments)?,
+ spec: crate::request_input::deserialize(spec.ok_or(ErrorCode::InvalidArguments)?)?,
accept_digest: digest.ok_or(ErrorCode::InvalidArguments)?,
expected_revision: revision.ok_or(ErrorCode::InvalidArguments)?,
idempotency_key: idempotency_key
@@ -443,7 +430,10 @@ fn setup_apply(options: &[String]) -> Result<Value, ErrorCode> {
}
fn operation(options: &[String], watch: bool) -> Result<Value, ErrorCode> {
- let Some(operation_id) = options.first().filter(|value| !value.is_empty()) else {
+ let Some(operation_id) = options
+ .first()
+ .filter(|value| request_input::valid_positional(value))
+ else {
return Err(ErrorCode::InvalidArguments);
};
let mut after_sequence = 0;
@@ -463,7 +453,10 @@ fn operation(options: &[String], watch: bool) -> Result<Value, ErrorCode> {
}
fn operation_cancel(options: &[String]) -> Result<Value, ErrorCode> {
- let Some(operation_id) = options.first().filter(|value| !value.is_empty()) else {
+ let Some(operation_id) = options
+ .first()
+ .filter(|value| request_input::valid_positional(value))
+ else {
return Err(ErrorCode::InvalidArguments);
};
if options.len() != 3 || options[1] != "--idempotency-key" || options[2].is_empty() {
@@ -477,7 +470,10 @@ fn operation_cancel(options: &[String]) -> Result<Value, ErrorCode> {
}
fn agent_check(options: &[String]) -> Result<Value, ErrorCode> {
- let Some(agent_id) = options.first().filter(|value| !value.is_empty()) else {
+ let Some(agent_id) = options
+ .first()
+ .filter(|value| request_input::valid_positional(value))
+ else {
return Err(ErrorCode::InvalidArguments);
};
let mut request = AgentCheckRequestV1 {
@@ -545,16 +541,8 @@ fn next(options: &[String], index: &mut usize) -> Result<String, ErrorCode> {
.ok_or(ErrorCode::InvalidArguments)
}
-fn read_json(reader: impl Read) -> Result<Value, ErrorCode> {
- let mut bytes = Vec::new();
- reader
- .take(1024 * 1024 + 1)
- .read_to_end(&mut bytes)
- .map_err(|_| ErrorCode::InvalidArguments)?;
- if bytes.len() > 1024 * 1024 {
- return Err(ErrorCode::InvalidArguments);
- }
- serde_json::from_slice(&bytes).map_err(|_| ErrorCode::InvalidArguments)
+fn read_json(reader: impl std::io::Read) -> Result<Value, ErrorCode> {
+ request_input::read_json(reader, request_input::MAX_REQUEST_BYTES)
}
fn resolve_callable(arguments: &[String]) -> Option<(CommandDescriptorV1, usize)> {
diff --git a/crates/cli/src/observation.rs b/crates/cli/src/observation.rs
index 4141bc0d..db61a83b 100644
--- a/crates/cli/src/observation.rs
+++ b/crates/cli/src/observation.rs
@@ -1,5 +1,6 @@
//! Finite CLI codecs for observation and value reads.
+#[cfg(test)]
use std::io::Read;
use hiroute_application_api::{
@@ -9,11 +10,17 @@ use hiroute_application_api::{
};
use serde_json::Value;
-use super::{next, read_json};
+use super::next;
+#[cfg(test)]
+use super::read_json;
+use crate::request_input::{MAX_REQUEST_BYTES, RequestInput, valid_positional};
pub(super) fn plan_quality_samples(options: &[String]) -> Result<Value, ErrorCode> {
- if options == ["--request-stdin"] {
- return observation_read_payload(ObservationCommand::PlanQuality, std::io::stdin());
+ if let Some(input) = RequestInput::optional(options)? {
+ return observation_value_payload(
+ ObservationCommand::PlanQuality,
+ input.read(MAX_REQUEST_BYTES)?,
+ );
}
let mut query = hiroute_application_api::PlanQualitySamplesQuery {
competence: None,
@@ -71,8 +78,11 @@ pub(super) fn plan_quality_samples(options: &[String]) -> Result<Value, ErrorCod
}
pub(super) fn sessions_list(options: &[String]) -> Result<Value, ErrorCode> {
- if options == ["--request-stdin"] {
- return observation_read_payload(ObservationCommand::Sessions, std::io::stdin());
+ if let Some(input) = RequestInput::optional(options)? {
+ return observation_value_payload(
+ ObservationCommand::Sessions,
+ input.read(MAX_REQUEST_BYTES)?,
+ );
}
let mut query = SessionListRequestV1::default();
let mut index = 0;
@@ -107,10 +117,13 @@ pub(super) fn sessions_list(options: &[String]) -> Result<Value, ErrorCode> {
}
pub(super) fn session_show(options: &[String]) -> Result<Value, ErrorCode> {
- if options == ["--request-stdin"] {
- return observation_read_payload(ObservationCommand::Timeline, std::io::stdin());
+ if let Some(input) = RequestInput::optional(options)? {
+ return observation_value_payload(
+ ObservationCommand::Timeline,
+ input.read(MAX_REQUEST_BYTES)?,
+ );
}
- let Some(id) = options.first().filter(|value| !value.is_empty()) else {
+ let Some(id) = options.first().filter(|value| valid_positional(value)) else {
return Err(ErrorCode::InvalidArguments);
};
let content = if options.len() == 1 {
@@ -133,9 +146,18 @@ pub(super) fn session_show(options: &[String]) -> Result<Value, ErrorCode> {
}
pub(super) fn session_receipt(options: &[String]) -> Result<Value, ErrorCode> {
+ if let Some(input) = RequestInput::optional(options)? {
+ return observation_value_payload(
+ ObservationCommand::Facts,
+ input.read(MAX_REQUEST_BYTES)?,
+ );
+ }
let [id] = options else {
return Err(ErrorCode::InvalidArguments);
};
+ if !valid_positional(id) {
+ return Err(ErrorCode::InvalidArguments);
+ }
serde_json::to_value(SessionLookupV1 {
id: id.clone(),
content: None,
@@ -144,8 +166,11 @@ pub(super) fn session_receipt(options: &[String]) -> Result<Value, ErrorCode> {
}
pub(super) fn value_show(options: &[String]) -> Result<Value, ErrorCode> {
- if options == ["--request-stdin"] {
- return observation_read_payload(ObservationCommand::Value, std::io::stdin());
+ if let Some(input) = RequestInput::optional(options)? {
+ return observation_value_payload(
+ ObservationCommand::Value,
+ input.read(MAX_REQUEST_BYTES)?,
+ );
}
let mut query = ObservationValueReportOptionsV2::default();
let mut index = 0;
@@ -195,19 +220,27 @@ pub(super) fn value_show(options: &[String]) -> Result<Value, ErrorCode> {
enum ObservationCommand {
Sessions,
Timeline,
+ Facts,
Value,
PlanQuality,
}
+#[cfg(test)]
fn observation_read_payload(
command: ObservationCommand,
reader: impl Read,
) -> Result<Value, ErrorCode> {
- let value = read_json(reader)?;
- let request: ObservationReadRequestV2 =
- serde_json::from_value(value).map_err(|_| ErrorCode::InvalidArguments)?;
+ observation_value_payload(command, read_json(reader)?)
+}
+
+fn observation_value_payload(
+ command: ObservationCommand,
+ value: Value,
+) -> Result<Value, ErrorCode> {
+ let request: ObservationReadRequestV2 = crate::request_input::deserialize(value)?;
let matches_command = match (command, &request.intent) {
(ObservationCommand::Sessions, ObservationReadIntentV2::Sessions(_)) => true,
+ (ObservationCommand::Facts, ObservationReadIntentV2::Facts(_)) => true,
(ObservationCommand::Timeline, ObservationReadIntentV2::Timeline(query)) => {
query.session_id.is_some()
}
diff --git a/crates/cli/src/request_input.rs b/crates/cli/src/request_input.rs
new file mode 100644
index 00000000..f6f7d28b
--- /dev/null
+++ b/crates/cli/src/request_input.rs
@@ -0,0 +1,215 @@
+//! JSON request transport only; command owners retain their typed schema and byte limit.
+
+use std::io::Read;
+use std::path::Path;
+
+use hiroute_application_api::ErrorCode;
+use serde::de::{DeserializeOwned, MapAccess, SeqAccess, Visitor};
+use serde::{Deserialize, Serialize};
+use serde_json::{Map, Number, Value};
+
+mod fields;
+
+pub(crate) const MAX_REQUEST_BYTES: u64 = 1024 * 1024;
+
+pub(crate) enum RequestInput<'a> {
+ Stdin,
+ File(&'a Path),
+}
+
+impl<'a> RequestInput<'a> {
+ pub(crate) fn parse(options: &'a [String]) -> Result<Self, ErrorCode> {
+ match options {
+ [flag] if flag == "--request-stdin" => Ok(Self::Stdin),
+ [flag, path] if flag == "--request-file" && valid_positional(path) => {
+ Ok(Self::File(Path::new(path)))
+ }
+ _ => Err(ErrorCode::InvalidArguments),
+ }
+ }
+
+ /// Human/positional codecs may fall back only when no request source was supplied.
+ pub(crate) fn optional(options: &'a [String]) -> Result<Option<Self>, ErrorCode> {
+ if options
+ .iter()
+ .any(|option| matches!(option.as_str(), "--request-stdin" | "--request-file"))
+ {
+ Self::parse(options).map(Some)
+ } else {
+ Ok(None)
+ }
+ }
+
+ pub(crate) fn read(self, limit: u64) -> Result<Value, ErrorCode> {
+ match self {
+ Self::Stdin => read_json(std::io::stdin(), limit),
+ Self::File(path) => {
+ let mut options = std::fs::OpenOptions::new();
+ options.read(true);
+ #[cfg(unix)]
+ {
+ use std::os::unix::fs::OpenOptionsExt;
+ options.custom_flags(nix::libc::O_NONBLOCK | nix::libc::O_NOCTTY);
+ }
+ let file = options
+ .open(path)
+ .map_err(|_| ErrorCode::InvalidArguments)?;
+ // A request file is a finite regular file, never a blocking device or pipe.
+ if !file
+ .metadata()
+ .map_err(|_| ErrorCode::InvalidArguments)?
+ .is_file()
+ {
+ return Err(ErrorCode::InvalidArguments);
+ }
+ read_json(file, limit)
+ }
+ }
+ }
+}
+
+pub(crate) fn read(options: &[String], limit: u64) -> Result<Value, ErrorCode> {
+ RequestInput::parse(options)?.read(limit)
+}
+
+pub(crate) fn typed<T: DeserializeOwned + Serialize>(
+ options: &[String],
+ limit: u64,
+) -> Result<Value, ErrorCode> {
+ let request: T = deserialize(read(options, limit)?)?;
+ serde_json::to_value(request).map_err(|_| ErrorCode::Internal)
+}
+
+pub(crate) fn deserialize<T: DeserializeOwned + Serialize>(value: Value) -> Result<T, ErrorCode> {
+ let request = serde_json::from_value(value.clone()).map_err(|_| ErrorCode::InvalidArguments)?;
+ fields::validate(&request, &value).map_err(|_| ErrorCode::InvalidArguments)?;
+ Ok(request)
+}
+
+pub(crate) fn valid_positional(value: &str) -> bool {
+ !value.is_empty() && !value.starts_with('-')
+}
+
+pub(crate) fn read_json(reader: impl Read, limit: u64) -> Result<Value, ErrorCode> {
+ let mut bytes = Vec::new();
+ reader
+ .take(limit + 1)
+ .read_to_end(&mut bytes)
+ .map_err(|_| ErrorCode::InvalidArguments)?;
+ if bytes.len() as u64 > limit {
+ return Err(ErrorCode::InvalidArguments);
+ }
+ let StrictValue(value) =
+ serde_json::from_slice(&bytes).map_err(|_| ErrorCode::InvalidArguments)?;
+ Ok(value)
+}
+
+// Value's normal deserializer silently keeps the last duplicate member. Reject duplicates
+// recursively before command owners choose a schema or deserialize tagged/flattened DTOs.
+struct StrictValue(Value);
+
+impl<'de> Deserialize<'de> for StrictValue {
+ fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
+ struct StrictVisitor;
+ impl<'de> Visitor<'de> for StrictVisitor {
+ type Value = StrictValue;
+
+ fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ formatter.write_str("one JSON value without duplicate object members")
+ }
+ fn visit_bool<E: serde::de::Error>(self, value: bool) -> Result<Self::Value, E> {
+ Ok(StrictValue(Value::Bool(value)))
+ }
+ fn visit_i64<E: serde::de::Error>(self, value: i64) -> Result<Self::Value, E> {
+ Ok(StrictValue(Value::Number(value.into())))
+ }
+ fn visit_u64<E: serde::de::Error>(self, value: u64) -> Result<Self::Value, E> {
+ Ok(StrictValue(Value::Number(value.into())))
+ }
+ fn visit_f64<E: serde::de::Error>(self, value: f64) -> Result<Self::Value, E> {
+ Number::from_f64(value)
+ .map(Value::Number)
+ .map(StrictValue)
+ .ok_or_else(|| E::custom("invalid JSON number"))
+ }
+ fn visit_str<E: serde::de::Error>(self, value: &str) -> Result<Self::Value, E> {
+ Ok(StrictValue(Value::String(value.to_owned())))
+ }
+ fn visit_string<E: serde::de::Error>(self, value: String) -> Result<Self::Value, E> {
+ Ok(StrictValue(Value::String(value)))
+ }
+ fn visit_unit<E: serde::de::Error>(self) -> Result<Self::Value, E> {
+ Ok(StrictValue(Value::Null))
+ }
+ fn visit_seq<A: SeqAccess<'de>>(self, mut access: A) -> Result<Self::Value, A::Error> {
+ let mut values = Vec::new();
+ while let Some(StrictValue(value)) = access.next_element()? {
+ values.push(value);
+ }
+ Ok(StrictValue(Value::Array(values)))
+ }
+ fn visit_map<A: MapAccess<'de>>(self, mut access: A) -> Result<Self::Value, A::Error> {
+ let mut values = Map::new();
+ while let Some(key) = access.next_key::<String>()? {
+ if values.contains_key(&key) {
+ return Err(serde::de::Error::custom("duplicate JSON member"));
+ }
+ let StrictValue(value) = access.next_value()?;
+ values.insert(key, value);
+ }
+ Ok(StrictValue(Value::Object(values)))
+ }
+ }
+ deserializer.deserialize_any(StrictVisitor)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn rejects_ambiguous_or_missing_sources_before_reading() {
+ for options in [
+ vec![],
+ vec!["--request-file"],
+ vec!["--request-file", ""],
+ vec!["--request-file", "--request-stdin"],
+ vec!["--request-stdin", "--request-file", "request.json"],
+ vec!["--request-stdin", "--request-stdin"],
+ vec!["--request-file", "one", "--request-file", "two"],
+ vec!["id", "--request-stdin"],
+ ] {
+ assert!(
+ RequestInput::parse(&options.into_iter().map(str::to_owned).collect::<Vec<_>>())
+ .is_err()
+ );
+ }
+ }
+
+ #[test]
+ fn strict_json_rejects_duplicate_members_trailing_input_and_invalid_utf8() {
+ for bytes in [
+ br#"{"schema":"v1","schema":"v2"}"#.as_slice(),
+ br#"{"nested":[{"id":"first","id":"second"}]}"#,
+ br#"{"id":"first","\u0069d":"second"}"#,
+ b"{} {}",
+ b"",
+ b"\xff",
+ ] {
+ assert_eq!(
+ read_json(bytes, MAX_REQUEST_BYTES),
+ Err(ErrorCode::InvalidArguments)
+ );
+ }
+ let bytes = br#"{"array":[null,true,-2,3,1.5,"text"]}"#;
+ assert_eq!(
+ read_json(bytes.as_slice(), bytes.len() as u64).unwrap(),
+ serde_json::json!({"array":[null,true,-2,3,1.5,"text"]})
+ );
+ assert_eq!(
+ read_json(bytes.as_slice(), bytes.len() as u64 - 1),
+ Err(ErrorCode::InvalidArguments)
+ );
+ }
+}
diff --git a/crates/cli/src/request_input/fields.rs b/crates/cli/src/request_input/fields.rs
new file mode 100644
index 00000000..59a88de0
--- /dev/null
+++ b/crates/cli/src/request_input/fields.rs
@@ -0,0 +1,272 @@
+//! Check object member names at the CLI boundary without tightening persisted DTO readers.
+//!
+//! Request DTOs use matching Serialize/Deserialize field names (no aliases or flatten).
+//! Serialize exposes both emitted and skipped struct fields, including buffered tagged
+//! variants that can hide ignored fields from a deserializer wrapper. Maps and JSON Values
+//! retain their free keys; typed map values and sequence elements are checked recursively.
+//! Serde's accepted positional struct arrays use the same declared field order.
+
+use serde::Serialize;
+use serde::ser::{self, SerializeMap, SerializeSeq, SerializeStruct};
+use serde_json::{Error, Value};
+
+pub(super) fn validate<T: ?Sized + Serialize>(request: &T, source: &Value) -> Result<(), Error> {
+ request.serialize(Fields(Some(source)))
+}
+
+struct Fields<'a>(Option<&'a Value>);
+
+struct Object<'a> {
+ source: Option<&'a Value>,
+ fields: Vec<&'static str>,
+}
+
+struct Sequence<'a> {
+ source: Option<&'a Value>,
+ index: usize,
+}
+
+struct Map<'a> {
+ source: Option<&'a Value>,
+ key: Option<String>,
+}
+
+macro_rules! scalar {
+ ($($method:ident($type:ty)),+ $(,)?) => {$(
+ fn $method(self, _value: $type) -> Result<(), Error> { Ok(()) }
+ )+};
+}
+
+impl<'a> ser::Serializer for Fields<'a> {
+ type Ok = ();
+ type Error = Error;
+ type SerializeSeq = Sequence<'a>;
+ type SerializeTuple = Sequence<'a>;
+ type SerializeTupleStruct = Sequence<'a>;
+ type SerializeTupleVariant = Sequence<'a>;
+ type SerializeMap = Map<'a>;
+ type SerializeStruct = Object<'a>;
+ type SerializeStructVariant = Object<'a>;
+
+ scalar!(
+ serialize_bool(bool),
+ serialize_i8(i8),
+ serialize_i16(i16),
+ serialize_i32(i32),
+ serialize_i64(i64),
+ serialize_i128(i128),
+ serialize_u8(u8),
+ serialize_u16(u16),
+ serialize_u32(u32),
+ serialize_u64(u64),
+ serialize_u128(u128),
+ serialize_f32(f32),
+ serialize_f64(f64),
+ serialize_char(char),
+ serialize_str(&str),
+ serialize_bytes(&[u8])
+ );
+
+ fn serialize_none(self) -> Result<(), Error> {
+ Ok(())
+ }
+ fn serialize_unit(self) -> Result<(), Error> {
+ Ok(())
+ }
+ fn serialize_unit_struct(self, _name: &'static str) -> Result<(), Error> {
+ Ok(())
+ }
+ fn serialize_unit_variant(
+ self,
+ _name: &'static str,
+ _index: u32,
+ _variant: &'static str,
+ ) -> Result<(), Error> {
+ Ok(())
+ }
+
+ fn serialize_some<T: ?Sized + Serialize>(self, value: &T) -> Result<(), Error> {
+ value.serialize(self)
+ }
+
+ fn serialize_newtype_struct<T: ?Sized + Serialize>(
+ self,
+ _name: &'static str,
+ value: &T,
+ ) -> Result<(), Error> {
+ value.serialize(self)
+ }
+
+ fn serialize_newtype_variant<T: ?Sized + Serialize>(
+ self,
+ _name: &'static str,
+ _index: u32,
+ variant: &'static str,
+ value: &T,
+ ) -> Result<(), Error> {
+ value.serialize(Fields(self.0.and_then(|source| source.get(variant))))
+ }
+
+ fn serialize_seq(self, _len: Option<usize>) -> Result<Sequence<'a>, Error> {
+ Ok(Sequence {
+ source: self.0,
+ index: 0,
+ })
+ }
+ fn serialize_tuple(self, len: usize) -> Result<Sequence<'a>, Error> {
+ self.serialize_seq(Some(len))
+ }
+ fn serialize_tuple_struct(
+ self,
+ _name: &'static str,
+ len: usize,
+ ) -> Result<Sequence<'a>, Error> {
+ self.serialize_tuple(len)
+ }
+ fn serialize_tuple_variant(
+ self,
+ _name: &'static str,
+ _index: u32,
+ variant: &'static str,
+ len: usize,
+ ) -> Result<Sequence<'a>, Error> {
+ Fields(self.0.and_then(|source| source.get(variant))).serialize_tuple(len)
+ }
+
+ fn serialize_map(self, _len: Option<usize>) -> Result<Map<'a>, Error> {
+ Ok(Map {
+ source: self.0,
+ key: None,
+ })
+ }
+ fn serialize_struct(self, _name: &'static str, len: usize) -> Result<Object<'a>, Error> {
+ Ok(Object {
+ source: self.0,
+ fields: Vec::with_capacity(len),
+ })
+ }
+ fn serialize_struct_variant(
+ self,
+ name: &'static str,
+ _index: u32,
+ variant: &'static str,
+ len: usize,
+ ) -> Result<Object<'a>, Error> {
+ Fields(self.0.and_then(|source| source.get(variant))).serialize_struct(name, len)
+ }
+}
+
+impl SerializeSeq for Sequence<'_> {
+ type Ok = ();
+ type Error = Error;
+ fn serialize_element<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Error> {
+ if let Some(source) = self.source.and_then(|source| source.get(self.index)) {
+ validate(value, source)?;
+ }
+ self.index += 1;
+ Ok(())
+ }
+ fn end(self) -> Result<(), Error> {
+ Ok(())
+ }
+}
+
+macro_rules! sequence {
+ ($($trait:ident => $method:ident),+ $(,)?) => {$(
+ impl ser::$trait for Sequence<'_> {
+ type Ok = ();
+ type Error = Error;
+ fn $method<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Error> {
+ SerializeSeq::serialize_element(self, value)
+ }
+ fn end(self) -> Result<(), Error> { Ok(()) }
+ }
+ )+};
+}
+sequence!(
+ SerializeTuple => serialize_element,
+ SerializeTupleStruct => serialize_field,
+ SerializeTupleVariant => serialize_field,
+);
+
+impl SerializeMap for Map<'_> {
+ type Ok = ();
+ type Error = Error;
+ fn serialize_key<T: ?Sized + Serialize>(&mut self, key: &T) -> Result<(), Error> {
+ self.key = Some(match serde_json::to_value(key)? {
+ Value::String(key) => key,
+ key @ (Value::Number(_) | Value::Bool(_)) => key.to_string(),
+ _ => return Err(ser::Error::custom("invalid JSON object key")),
+ });
+ Ok(())
+ }
+ fn serialize_value<T: ?Sized + Serialize>(&mut self, value: &T) -> Result<(), Error> {
+ let key = self
+ .key
+ .take()
+ .ok_or_else(|| <Error as ser::Error>::custom("missing map key"))?;
+ if let Some(source) = self.source.and_then(|source| source.get(&key)) {
+ validate(value, source)?;
+ }
+ Ok(())
+ }
+ fn end(self) -> Result<(), Error> {
+ Ok(())
+ }
+}
+
+impl SerializeStruct for Object<'_> {
+ type Ok = ();
+ type Error = Error;
+ fn serialize_field<T: ?Sized + Serialize>(
+ &mut self,
+ key: &'static str,
+ value: &T,
+ ) -> Result<(), Error> {
+ let index = self.fields.len();
+ self.fields.push(key);
+ if let Some(source) = self.source.and_then(|source| match source {
+ Value::Array(values) => values.get(index),
+ _ => source.get(key),
+ }) {
+ validate(value, source)?;
+ }
+ Ok(())
+ }
+ fn skip_field(&mut self, key: &'static str) -> Result<(), Error> {
+ self.fields.push(key);
+ Ok(())
+ }
+ fn end(self) -> Result<(), Error> {
+ if self
+ .source
+ .and_then(Value::as_object)
+ .is_some_and(|source| {
+ source
+ .keys()
+ .any(|key| !self.fields.contains(&key.as_str()))
+ })
+ {
+ return Err(ser::Error::custom("unknown request field"));
+ }
+ Ok(())
+ }
+}
+
+impl ser::SerializeStructVariant for Object<'_> {
+ type Ok = ();
+ type Error = Error;
+ fn serialize_field<T: ?Sized + Serialize>(
+ &mut self,
+ key: &'static str,
+ value: &T,
+ ) -> Result<(), Error> {
+ SerializeStruct::serialize_field(self, key, value)
+ }
+ fn skip_field(&mut self, key: &'static str) -> Result<(), Error> {
+ SerializeStruct::skip_field(self, key)
+ }
+ fn end(self) -> Result<(), Error> {
+ SerializeStruct::end(self)
+ }
+}
diff --git a/crates/cli/src/tasks.rs b/crates/cli/src/tasks.rs
index e69ffe75..dad2638c 100644
--- a/crates/cli/src/tasks.rs
+++ b/crates/cli/src/tasks.rs
@@ -1,115 +1,114 @@
+use crate::request_input::{MAX_REQUEST_BYTES, RequestInput, valid_positional};
use hiroute_application_api::{
DelegationCancelRequestV1, DelegationContinueRequestV1, DelegationGetRequestV1,
DelegationListRequestV1, DelegationResultRequestV1, DelegationStartRequestV1,
DelegationWaitRequestV1, ErrorCode,
};
-use std::io::Read;
pub(crate) fn payload(command: &str, options: &[String]) -> Result<serde_json::Value, ErrorCode> {
- let mut bytes = Vec::new();
- std::io::stdin()
- .take(1024 * 1024 + 1)
- .read_to_end(&mut bytes)
- .map_err(|_| ErrorCode::InvalidArguments)?;
- if bytes.len() > 1024 * 1024 {
+ let source_start = if options.last().is_some_and(|flag| flag == "--request-stdin") {
+ options.len() - 1
+ } else if options.len() >= 2 && options[options.len() - 2] == "--request-file" {
+ options.len() - 2
+ } else {
return Err(ErrorCode::InvalidArguments);
- }
- let value = parse(command, &bytes)?;
- validate_options(command, options, &value)?;
+ };
+ let input = RequestInput::parse(&options[source_start..])?;
+ let selectors = &options[..source_start];
+ validate_selectors(command, selectors, None)?;
+ let value = parse_value(command, input.read(MAX_REQUEST_BYTES)?)?;
+ validate_selectors(command, selectors, Some(&value))?;
Ok(value)
}
-fn validate_options(
+fn validate_selectors(
command: &str,
options: &[String],
- value: &serde_json::Value,
+ value: Option<&serde_json::Value>,
) -> Result<(), ErrorCode> {
- let invalid = || Err(ErrorCode::InvalidArguments);
+ let matches =
+ |key: &str, expected: &str| value.is_none_or(|value| value[key].as_str() == Some(expected));
match (command, options) {
- ("tasks.list" | "tasks.start" | "tasks.continue", [stdin])
- if stdin == "--request-stdin" =>
- {
- Ok(())
- }
- ("tasks.wait" | "tasks.result" | "tasks.cancel", [flag, run, stdin])
- if flag == "--run"
- && !run.is_empty()
- && stdin == "--request-stdin"
- && value["run_id"].as_str() == Some(run.as_str()) =>
+ ("tasks.list" | "tasks.start" | "tasks.continue", []) => Ok(()),
+ ("tasks.wait" | "tasks.result" | "tasks.cancel", [flag, run])
+ if flag == "--run" && valid_positional(run) && matches("run_id", run) =>
{
Ok(())
}
- ("tasks.show", [task_flag, task, stdin])
- if task_flag == "--task"
- && !task.is_empty()
- && stdin == "--request-stdin"
- && value["task_id"].as_str() == Some(task.as_str())
- && value.get("run_id").is_none() =>
+ ("tasks.show", [flag, task])
+ if flag == "--task"
+ && valid_positional(task)
+ && matches("task_id", task)
+ && value.is_none_or(|value| value.get("run_id").is_none()) =>
{
Ok(())
}
- ("tasks.show", [task_flag, task, run_flag, run, stdin])
+ ("tasks.show", [task_flag, task, run_flag, run])
if task_flag == "--task"
&& run_flag == "--run"
- && !task.is_empty()
- && !run.is_empty()
- && stdin == "--request-stdin"
- && value["task_id"].as_str() == Some(task.as_str())
- && value["run_id"].as_str() == Some(run.as_str()) =>
+ && valid_positional(task)
+ && valid_positional(run)
+ && matches("task_id", task)
+ && matches("run_id", run) =>
{
Ok(())
}
- ("tasks.show", [key_flag, key, operation_flag, operation, stdin])
+ ("tasks.show", [key_flag, key, operation_flag, operation])
if key_flag == "--submission-key"
&& operation_flag == "--operation"
&& !key.is_empty()
&& matches!(operation.as_str(), "start" | "continue")
- && stdin == "--request-stdin"
- && value["submission_key"].as_str() == Some(key.as_str())
- && value["submission_operation"].as_str() == Some(operation.as_str()) =>
+ && matches("submission_key", key)
+ && matches("submission_operation", operation) =>
{
Ok(())
}
- _ => invalid(),
+ _ => Err(ErrorCode::InvalidArguments),
}
}
+#[cfg(test)]
fn parse(command: &str, bytes: &[u8]) -> Result<serde_json::Value, ErrorCode> {
+ parse_value(
+ command,
+ crate::request_input::read_json(bytes, MAX_REQUEST_BYTES)?,
+ )
+}
+
+fn parse_value(command: &str, value: serde_json::Value) -> Result<serde_json::Value, ErrorCode> {
let invalid = |_| ErrorCode::InvalidArguments;
match command {
- "tasks.list" => typed::<DelegationListRequestV1>(bytes, invalid),
- "tasks.show" => typed::<DelegationGetRequestV1>(bytes, invalid),
+ "tasks.list" => typed::<DelegationListRequestV1>(value, invalid),
+ "tasks.show" => typed::<DelegationGetRequestV1>(value, invalid),
"tasks.start" => {
- let request: DelegationStartRequestV1 =
- serde_json::from_slice(bytes).map_err(invalid)?;
+ let request: DelegationStartRequestV1 = crate::request_input::deserialize(value)?;
if !request.valid() {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(request).map_err(invalid)
}
- "tasks.wait" => typed::<DelegationWaitRequestV1>(bytes, invalid),
+ "tasks.wait" => typed::<DelegationWaitRequestV1>(value, invalid),
"tasks.result" => {
- let request: DelegationResultRequestV1 =
- serde_json::from_slice(bytes).map_err(invalid)?;
+ let request: DelegationResultRequestV1 = crate::request_input::deserialize(value)?;
if !request.valid() {
return Err(ErrorCode::InvalidArguments);
}
serde_json::to_value(request).map_err(invalid)
}
- "tasks.cancel" => typed::<DelegationCancelRequestV1>(bytes, invalid),
- "tasks.continue" => typed::<DelegationContinueRequestV1>(bytes, invalid),
+ "tasks.cancel" => typed::<DelegationCancelRequestV1>(value, invalid),
+ "tasks.continue" => typed::<DelegationContinueRequestV1>(value, invalid),
_ => Err(ErrorCode::UnknownCommand),
}
}
fn typed<T>(
- bytes: &[u8],
+ value: serde_json::Value,
invalid: fn(serde_json::Error) -> ErrorCode,
) -> Result<serde_json::Value, ErrorCode>
where
T: serde::de::DeserializeOwned + serde::Serialize + ValidRequest,
{
- let request: T = serde_json::from_slice(bytes).map_err(invalid)?;
+ let request: T = crate::request_input::deserialize(value)?;
if !request.valid() {
return Err(ErrorCode::InvalidArguments);
}
@@ -160,30 +159,28 @@ mod tests {
.unwrap();
let value = parse("tasks.show", &bytes).unwrap();
assert!(
- validate_options(
+ validate_selectors(
"tasks.show",
&[
"--submission-key".into(),
"continue/one".into(),
"--operation".into(),
"continue".into(),
- "--request-stdin".into(),
],
- &value,
+ Some(&value),
)
.is_ok()
);
assert_eq!(
- validate_options(
+ validate_selectors(
"tasks.show",
&[
"--submission-key".into(),
"different".into(),
"--operation".into(),
"continue".into(),
- "--request-stdin".into(),
],
- &value,
+ Some(&value),
),
Err(ErrorCode::InvalidArguments)
);
@@ -200,18 +197,18 @@ mod tests {
.unwrap();
let value = parse("tasks.wait", &bytes).unwrap();
assert!(
- validate_options(
+ validate_selectors(
"tasks.wait",
- &["--run".into(), "run/one".into(), "--request-stdin".into()],
- &value,
+ &["--run".into(), "run/one".into()],
+ Some(&value),
)
.is_ok()
);
assert_eq!(
- validate_options(
+ validate_selectors(
"tasks.wait",
- &["--run".into(), "run/two".into(), "--request-stdin".into()],
- &value,
+ &["--run".into(), "run/two".into()],
+ Some(&value),
),
Err(ErrorCode::InvalidArguments)
);
diff --git a/crates/cli/src/work_plans.rs b/crates/cli/src/work_plans.rs
index 41a90bcc..35c30b95 100644
--- a/crates/cli/src/work_plans.rs
+++ b/crates/cli/src/work_plans.rs
@@ -3,20 +3,7 @@ use hiroute_application_api::{ErrorCode, WorkPlanListRequestV1};
use std::io::Read;
pub(crate) fn payload(options: &[String]) -> Result<serde_json::Value, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- let mut input = String::new();
- std::io::stdin()
- .take(4097)
- .read_to_string(&mut input)
- .map_err(|_| ErrorCode::InvalidArguments)?;
- if input.len() > 4096 {
- return Err(ErrorCode::InvalidArguments);
- }
- let query: WorkPlanListRequestV1 =
- serde_json::from_str(&input).map_err(|_| ErrorCode::InvalidArguments)?;
- serde_json::to_value(query).map_err(|_| ErrorCode::InvalidArguments)
+ crate::request_input::typed::<WorkPlanListRequestV1>(options, 4096)
}
/// Same protected capability carrier, constrained to an inherited pipe and bounded on both
diff --git a/crates/cli/src/worker/input.rs b/crates/cli/src/worker/input.rs
index 0abe5bde..4a3712c6 100644
--- a/crates/cli/src/worker/input.rs
+++ b/crates/cli/src/worker/input.rs
@@ -46,19 +46,9 @@ pub(super) fn parse_dependencies_discover(
pub(super) fn parse_dependency_selection(
options: &[String],
) -> Result<WorkerDependenciesSelectRequestV1, ErrorCode> {
- if options != ["--request-stdin"] {
- return Err(ErrorCode::InvalidArguments);
- }
- let mut bytes = Vec::new();
- std::io::stdin()
- .take(MAX_DEPENDENCY_SELECTION_BYTES + 1)
- .read_to_end(&mut bytes)
- .map_err(|_| ErrorCode::InvalidArguments)?;
- if bytes.is_empty() || bytes.len() as u64 > MAX_DEPENDENCY_SELECTION_BYTES {
- return Err(ErrorCode::InvalidArguments);
- }
- let request: WorkerDependenciesSelectRequestV1 =
- serde_json::from_slice(&bytes).map_err(|_| ErrorCode::InvalidArguments)?;
+ let request: WorkerDependenciesSelectRequestV1 = crate::request_input::deserialize(
+ crate::request_input::read(options, MAX_DEPENDENCY_SELECTION_BYTES)?,
+ )?;
request
.valid()
.then_some(request)
diff --git a/crates/cli/tests/contracts.rs b/crates/cli/tests/contracts.rs
index a4cdfa3e..97c01590 100644
--- a/crates/cli/tests/contracts.rs
+++ b/crates/cli/tests/contracts.rs
@@ -91,13 +91,13 @@ fn release_manifest_is_a_strict_subset_of_planned_registry() {
}
#[test]
-fn released_worker_dependency_selection_declares_only_its_request_stdin_channel() {
+fn released_worker_dependency_selection_declares_both_json_sources() {
let command = release_manifest()
.commands
.into_iter()
.find(|command| command.command_id == "worker.dependencies.select")
.unwrap();
- assert_eq!(command.stdin_channels, ["request_stdin"]);
+ assert_eq!(command.stdin_channels, ["request_stdin", "request_file"]);
assert!(!command.help.usage.contains("capability"));
assert!(!command.help.effects.contains("capability"));
assert!(!command.help_document().contains("--capability-fd"));
diff --git a/crates/cli/tests/request_input.rs b/crates/cli/tests/request_input.rs
new file mode 100644
index 00000000..f565349a
--- /dev/null
+++ b/crates/cli/tests/request_input.rs
@@ -0,0 +1,318 @@
+use std::io::Write;
+use std::path::Path;
+use std::process::{Command, Stdio};
+
+use serde_json::{Value, json};
+
+fn invoke(root: &Path, arguments: &[&str], input: &[u8]) -> (i32, Value) {
+ let mut child = Command::new(env!("CARGO_BIN_EXE_hiroute"))
+ .args(arguments)
+ .env("HIROUTE_RUNTIME_DIR", root)
+ .stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::piped())
+ .spawn()
+ .unwrap();
+ let _ = child.stdin.take().unwrap().write_all(input);
+ let output = child.wait_with_output().unwrap();
+ let envelope = serde_json::from_slice(&output.stdout).unwrap_or_else(|_| {
+ panic!(
+ "invalid CLI response: {}",
+ String::from_utf8_lossy(&output.stdout)
+ )
+ });
+ (output.status.code().unwrap(), envelope)
+}
+
+fn facts() -> Vec<u8> {
+ serde_json::to_vec(&json!({
+ "schema":"hiroute.observation.query/v2",
+ "intent":{"view":"facts","query":{
+ "request_id":"request/one", "limit":100, "cursor":null
+ }}
+ }))
+ .unwrap()
+}
+
+#[test]
+fn unknown_options_never_become_resource_ids_or_reach_transport() {
+ let root = tempfile::tempdir().unwrap();
+ for path in [
+ vec!["sessions", "receipt"],
+ vec!["sessions", "show"],
+ vec!["routing", "show"],
+ vec!["compute", "show"],
+ vec!["agents", "connect", "status"],
+ vec!["agents", "check"],
+ vec!["operations", "get"],
+ ] {
+ for invalid_id in ["--unknown", "-x", ""] {
+ let mut args = path.clone();
+ args.extend([invalid_id, "--output", "json"]);
+ let (exit, envelope) = invoke(root.path(), &args, b"");
+ assert_eq!(exit, 2, "{args:?}: {envelope}");
+ assert_eq!(envelope["error"]["code"], "INVALID_ARGUMENTS");
+ }
+ }
+}
+
+#[test]
+fn facts_file_and_stdin_parse_before_the_same_transport_boundary() {
+ let root = tempfile::tempdir().unwrap();
+ let path = root.path().join("事实 request.json");
+ let input = facts();
+ std::fs::write(&path, &input).unwrap();
+ for (args, stdin) in [
+ (
+ vec![
+ "sessions",
+ "receipt",
+ "--request-file",
+ path.to_str().unwrap(),
+ "--output",
+ "json",
+ ],
+ b"malformed unused stdin".as_slice(),
+ ),
+ (
+ vec!["sessions", "receipt", "--request-stdin", "--output", "json"],
+ input.as_slice(),
+ ),
+ (
+ vec!["sessions", "receipt", "receipt/one", "--output", "json"],
+ b"ignored legacy stdin".as_slice(),
+ ),
+ ] {
+ let (exit, envelope) = invoke(root.path(), &args, stdin);
+ assert_eq!(exit, 6, "{args:?}: {envelope}");
+ assert_eq!(envelope["error"]["code"], "DAEMON_UNAVAILABLE");
+ }
+}
+
+#[test]
+fn both_sources_reject_wrong_intents_unknown_fields_and_ambiguous_json() {
+ let root = tempfile::tempdir().unwrap();
+ let path = root.path().join("request.json");
+ for bytes in [
+ br#"{"schema":"hiroute.observation.query/v2","intent":{"view":"facts","query":{"request_id":"one","request_id":"two","limit":100}}}"#.as_slice(),
+ br#"{"schema":"hiroute.observation.query/v2","intent":{"view":"facts","query":{"request_id":"one","limit":100,"secret":"reject"}}}"#,
+ br#"{"schema":"hiroute.observation.query/v2","intent":{"view":"status","query":{}}}"#,
+ b"{} {}", b"", b"\xff", b"{",
+ ] {
+ std::fs::write(&path, bytes).unwrap();
+ for (args, stdin) in [
+ (vec!["sessions", "receipt", "--request-file", path.to_str().unwrap()], b"unused".as_slice()),
+ (vec!["sessions", "receipt", "--request-stdin"], bytes),
+ ] {
+ let (exit, envelope) = invoke(root.path(), &args, stdin);
+ assert_eq!(exit, 2, "{args:?}: {envelope}");
+ assert_eq!(envelope["error"]["code"], "INVALID_ARGUMENTS");
+ }
+ }
+}
+
+#[test]
+fn typed_requests_reject_nested_unknowns_and_keep_declared_optional_and_dynamic_fields() {
+ let root = tempfile::tempdir().unwrap();
+ let file = root.path().join("typed.json");
+ let agent = json!({"spec":{
+ "schema_version":{"major":2,"minor":0},
+ "context_id":"agent-context/codex/test",
+ "model":{"intent":"restore","restore_point_ref":"model-restore/original"},
+ "collaboration":{"intent":"keep"},
+ "access_token":{"intent":"keep"},
+ "restore_native_model":null,"protected_native_model_ids":[]
+ }});
+ let decision = json!({
+ "schema_version":{"major":1,"minor":0},
+ "spec":{
+ "schema_version":{"major":1,"minor":0},
+ "command_id":"decision.services.apply","resource_id":null,
+ "desired_state":{"arbitrary":{"intent":"keep","typo":1}}
+ }
+ });
+ let mut cases = vec![
+ (vec!["agents", "connect", "preview"], agent.clone(), 6),
+ (vec!["decision", "services", "apply"], decision.clone(), 6),
+ ];
+ let mut positional_spec = decision.clone();
+ positional_spec["schema_version"] = json!([1, 0]);
+ positional_spec["spec"] = json!([
+ {"major":1,"minor":0}, "decision.services.apply", null, {"arbitrary":1}
+ ]);
+ cases.push((
+ vec!["decision", "services", "apply"],
+ positional_spec.clone(),
+ 6,
+ ));
+ positional_spec["spec"][0]["typo"] = Value::Null;
+ cases.push((vec!["decision", "services", "apply"], positional_spec, 2));
+ let mut authorization = json!({"action":"result","operation":{
+ "operation_id":"operation/one","state":"succeeded","sequence":1,"cancellable":false
+ }});
+ cases.push((
+ vec!["compute", "connection", "authorize"],
+ authorization.clone(),
+ 6,
+ ));
+ authorization["operation"]["typo"] = Value::Null;
+ cases.push((vec!["compute", "connection", "authorize"], authorization, 2));
+ for pointer in [
+ "/spec/schema_version/typo",
+ "/spec/model/typo",
+ "/spec/collaboration/typo",
+ "/spec/access_token/typo",
+ ] {
+ let mut request = agent.clone();
+ let (parent, key) = pointer.rsplit_once('/').unwrap();
+ request.pointer_mut(parent).unwrap()[key] = Value::Null;
+ cases.push((vec!["agents", "connect", "preview"], request, 2));
+ }
+ let mut keep = agent.clone();
+ keep["spec"]["model"] = json!({"intent":"keep","typo":null});
+ cases.push((vec!["agents", "connect", "preview"], keep, 2));
+ let mut regenerate = agent.clone();
+ regenerate["spec"]["access_token"] = json!({"intent":"regenerate","typo":null});
+ cases.push((vec!["agents", "connect", "preview"], regenerate, 2));
+ let mut apply = agent.clone();
+ apply["accept_digest"] = json!(format!("sha256:{}", "0".repeat(64)));
+ apply["dependency_digest"] = apply["accept_digest"].clone();
+ apply["idempotency_key"] = json!("regression-only");
+ apply["expected_revisions"] = json!({"target":0,"dependencies":{"arbitrary":1}});
+ apply["login_item"] = Value::Null;
+ cases.push((vec!["agents", "connect", "apply"], apply.clone(), 6));
+ apply["expected_revisions"]["typo"] = Value::Null;
+ cases.push((vec!["agents", "connect", "apply"], apply, 2));
+ for pointer in [
+ "/schema_version/typo",
+ "/spec/schema_version/typo",
+ "/spec/typo",
+ ] {
+ let mut request = decision.clone();
+ let (parent, key) = pointer.rsplit_once('/').unwrap();
+ request.pointer_mut(parent).unwrap()[key] = Value::Null;
+ cases.push((vec!["decision", "services", "apply"], request, 2));
+ }
+ for (path, request, expected_exit) in cases {
+ let bytes = serde_json::to_vec(&request).unwrap();
+ std::fs::write(&file, &bytes).unwrap();
+ for source in [
+ vec!["--request-file", file.to_str().unwrap()],
+ vec!["--request-stdin"],
+ ] {
+ let mut args = path.clone();
+ args.extend(source);
+ let (exit, envelope) = invoke(root.path(), &args, &bytes);
+ assert_eq!(exit, expected_exit, "{args:?} {request}: {envelope}");
+ assert_eq!(
+ envelope["error"]["code"],
+ if expected_exit == 2 {
+ "INVALID_ARGUMENTS"
+ } else {
+ "DAEMON_UNAVAILABLE"
+ }
+ );
+ }
+ }
+}
+
+#[test]
+fn conflicting_missing_and_nonregular_request_files_are_usage_errors() {
+ let root = tempfile::tempdir().unwrap();
+ let path = root.path().join("request.json");
+ std::fs::write(&path, facts()).unwrap();
+ for options in [
+ vec!["--request-file"],
+ vec!["--request-file", ""],
+ vec!["--request-file", "--request-stdin"],
+ vec!["--request-file", "missing-request.json"],
+ vec!["--request-file", root.path().to_str().unwrap()],
+ vec!["--request-file", path.to_str().unwrap(), "--request-stdin"],
+ vec!["--request-stdin", "--request-file", path.to_str().unwrap()],
+ vec![
+ "--request-file",
+ path.to_str().unwrap(),
+ "--request-file",
+ path.to_str().unwrap(),
+ ],
+ vec!["--request-stdin", "--request-stdin"],
+ vec!["receipt/one", "--request-file", path.to_str().unwrap()],
+ ] {
+ let mut args = vec!["sessions", "receipt"];
+ args.extend(options);
+ let (exit, envelope) = invoke(root.path(), &args, &facts());
+ assert_eq!(exit, 2, "{args:?}: {envelope}");
+ assert_eq!(envelope["error"]["code"], "INVALID_ARGUMENTS");
+ }
+}
+
+#[test]
+fn existing_per_command_byte_limits_apply_to_files_and_stdin() {
+ let root = tempfile::tempdir().unwrap();
+ for (path, limit, request) in [
+ (
+ vec!["operations", "find"],
+ 65_536,
+ json!({
+ "principal_kind":"interactive_user","operation_kind":"change",
+ "idempotency_key":"test","accepted_digest":format!("sha256:{}", "0".repeat(64))
+ }),
+ ),
+ (
+ vec!["worker", "dependencies", "select"],
+ 65_536,
+ json!({
+ "harness":"codex_cli","cli_path":"/tmp/hiroute-request-test/codex",
+ "adapter_path":"/tmp/hiroute-request-test/codex-acp",
+ "expected_selection_revision":0
+ }),
+ ),
+ (vec!["routing", "options"], 1024 * 1024, json!({})),
+ ] {
+ // Whitespace is valid JSON framing, so oversize cannot hide behind syntax rejection.
+ let mut bytes = serde_json::to_vec(&request).unwrap();
+ for (size, expected_exit, expected_code) in [
+ (limit, 6, "DAEMON_UNAVAILABLE"),
+ (limit + 1, 2, "INVALID_ARGUMENTS"),
+ ] {
+ bytes.resize(size, b' ');
+ let file = root.path().join("bounded.json");
+ std::fs::write(&file, &bytes).unwrap();
+ for source in [
+ vec!["--request-file", file.to_str().unwrap()],
+ vec!["--request-stdin"],
+ ] {
+ let mut args = path.clone();
+ args.extend(source);
+ args.extend(["--output", "json"]);
+ let (exit, envelope) = invoke(root.path(), &args, &bytes);
+ assert_eq!(exit, expected_exit, "{args:?}: {envelope}");
+ assert_eq!(envelope["error"]["code"], expected_code);
+ }
+ }
+ }
+}
+
+#[cfg(unix)]
+#[test]
+fn a_request_fifo_without_a_writer_is_rejected_without_opening_a_stream() {
+ let root = tempfile::tempdir().unwrap();
+ let fifo = root.path().join("request.pipe");
+ nix::unistd::mkfifo(
+ &fifo,
+ nix::sys::stat::Mode::S_IRUSR | nix::sys::stat::Mode::S_IWUSR,
+ )
+ .unwrap();
+ let (exit, envelope) = invoke(
+ root.path(),
+ &[
+ "sessions",
+ "receipt",
+ "--request-file",
+ fifo.to_str().unwrap(),
+ ],
+ b"",
+ );
+ assert_eq!(exit, 2, "{envelope}");
+ assert_eq!(envelope["error"]["code"], "INVALID_ARGUMENTS");
+}
diff --git a/docs/code-map/architecture.md b/docs/code-map/architecture.md
index 8f04352e..36d5b642 100644
--- a/docs/code-map/architecture.md
+++ b/docs/code-map/architecture.md
@@ -16,6 +16,11 @@
| Business evidence | [Observation](../../crates/observation/src), [authorized queries](../../crates/application/src/observation_query) | Execution facts, managed content, session queries and valuation; [diagnostics](../../crates/diagnostics/src) remain separate |
| Product presentation | [Desktop product shell](../../apps/desktop/src/product), [native host](../../apps/desktop/src-tauri/src), [CLI](../../crates/cli/src) | The native host projects safe DTOs; frontend state does not grant authority or establish durable success |
+CLI JSON request sources (`--request-file` / `--request-stdin`) share the bounded
+[strict input reader](../../crates/cli/src/request_input.rs). Command codecs retain
+typed intent, selector and byte-limit ownership; see the [CLI input guide](../../crates/cli/INPUT.md)
+and [production argv regressions](../../crates/cli/tests/request_input.rs).
+
CLI/Desktop → client-core → daemon control → Application → storage/native adapters
is the control path. Published plans and grants feed Gateway execution. Worker
admission freezes a plan and run authority before the native client calls Gateway.
diff --git a/docs/standalone-cli.md b/docs/standalone-cli.md
index dbd89a4c..02a5810c 100644
--- a/docs/standalone-cli.md
+++ b/docs/standalone-cli.md
@@ -567,6 +567,26 @@ still owned by HiRoute; concurrent user changes conflict instead of being overwr
Code uses its public profile/launcher contract. Do not configure a Responses-only Codex plan
for a surface that supports only Messages.
+## JSON request input
+
+Every command that accepts `--request-stdin` also accepts `--request-file PATH`:
+
+```sh
+hiroute routing preview --request-file route-preview.json --output json
+# Existing pipelines and shell redirection remain supported:
+hiroute routing preview --request-stdin --output json < route-preview.json
+```
+
+Choose exactly one source. Both use the same bounded UTF-8 JSON parser and typed
+command schema; unknown fields, duplicate object members, trailing JSON, repeated
+sources and mixtures with human options return `INVALID_ARGUMENTS` before contacting
+Local Control. A file must be regular. Relative paths resolve from the calling
+working directory; prefix a filename beginning with `-` with `./`. Quote paths
+containing spaces. Existing byte limits remain in force (normally 1 MiB; operation
+lookup and Worker dependency selection use 64 KiB). A request file never replaces
+the separate protected-input or inherited capability channel. `worker --file`
+continues to carry prompt text under its existing contract.
+
## Sessions, actual selection, and usage facts
After an Agent or Worker request completes:
@@ -581,6 +601,25 @@ hiroute observation plan-quality samples --plan-id PLAN_ID --output json
hiroute observation plan-quality samples --session-id SESSION_ID --limit 50 --output json
```
+A positional `sessions receipt RECEIPT_ID` retains the v1 RoutingReceipt query.
+To read a v2 Facts page, use the exact logical `request_id` returned by the v2
+session timeline (a session ID or v1 receipt ID is a different locator):
+
+```json
+{
+ "schema": "hiroute.observation.query/v2",
+ "intent": {
+ "view": "facts",
+ "query": {"request_id": "REQUEST_ID_FROM_TIMELINE", "limit": 100, "cursor": null}
+ }
+}
+```
+
+Save this as `facts-request.json`, then run
+`hiroute sessions receipt --request-file facts-request.json --output json`.
+`--request-stdin` accepts the identical request. The response is a v2 Facts page;
+use its returned cursor with the same request ID to read further pages.
+
`sessions show` returns facts and timeline by default, not conversation bodies. Ordered
RoutingReceipt facts such as `route_decision`, `attempt_started`, and `usage_and_cache` record
the actual plan, model choice, Attempt, and known upstream-reported tokens. `value show`
diff --git a/docs/standalone-cli.zh-CN.md b/docs/standalone-cli.zh-CN.md
index 6dd86907..1fce9ae5 100644
--- a/docs/standalone-cli.zh-CN.md
+++ b/docs/standalone-cli.zh-CN.md
@@ -489,6 +489,24 @@ Standalone daemon 已是 resident service,因此 preview 不要求 Desktop log
并发用户修改会导致冲突而不是被覆盖。Claude Code 使用其公开 profile/launcher 合同;不要把
Codex 的 Responses 计划直接配置给只支持 Messages 的 surface。
+## JSON 请求输入
+
+所有接受 `--request-stdin` 的命令也接受 `--request-file PATH`:
+
+```sh
+hiroute routing preview --request-file route-preview.json --output json
+# 原有管道和 shell 重定向保持可用:
+hiroute routing preview --request-stdin --output json < route-preview.json
+```
+
+输入来源只能选一个。两种方式共用有大小上限的 UTF-8 JSON 解析器和命令类型校验;
+未知字段、重复 JSON 成员、多段 JSON、重复或混合来源、与人工选项混用均在连接
+Local Control 前返回 `INVALID_ARGUMENTS`。文件必须是普通文件,相对路径以调用者
+工作目录为准;以 `-` 开头的文件名加 `./` 前缀,带空格的路径需要引号。
+保留现有大小限制(通常为 1 MiB,Operation 查找和 Worker 依赖选择为 64 KiB)。
+请求文件不替代独立的 protected-input 或继承的 capability 通道。
+Worker 原有 `--file` 继续读取提示词文本。
+
## 会话、实际选择与用量事实
一次 Agent 或 Worker 请求完成后:
@@ -501,6 +519,26 @@ hiroute sessions status --output json
hiroute value show --routing PLAN_ID --session SESSION_ID --output json
```
+位置参数 `sessions receipt RECEIPT_ID` 保留 v1 RoutingReceipt 查询。
+查询 v2 Facts 时,使用 v2 session timeline 返回的准确逻辑 `request_id`;
+Session ID、v1 Receipt ID 与此定位符不同:
+
+```json
+{
+ "schema": "hiroute.observation.query/v2",
+ "intent": {
+ "view": "facts",
+ "query": {"request_id": "REQUEST_ID_FROM_TIMELINE", "limit": 100, "cursor": null}
+ }
+}
+```
+
+保存为 `facts-request.json` 后运行
+`hiroute sessions receipt --request-file facts-request.json --output json`。
+`--request-stdin` 接受相同请求,返回 v2 Facts 分页;后续页沿用同一 request ID
+并传入返回的 cursor。
+
+
`sessions show` 默认只返回事实和 timeline,不返回对话正文。RoutingReceipt 的
`route_decision`、`attempt_started`、`usage_and_cache` 等有序事实给出实际计划、模型选择、Attempt
和上游报告的已知 token。`value show` 只返回已有账价值;没有可信价格证据时金额保持 `null`,
diff --git a/e2e/product/schema/contract-set.v1.json b/e2e/product/schema/contract-set.v1.json
index 0028b749..77463da5 100644
--- a/e2e/product/schema/contract-set.v1.json
+++ b/e2e/product/schema/contract-set.v1.json
@@ -1,10 +1,10 @@
{
- "descriptor_digest": "sha256:a435bc5901bbcaeaf2f41c8c4db15b0a7f967d988aeb544e8f5d2890abc64639",
+ "descriptor_digest": "sha256:1bdd37be3354af88208d5c9f91945f23b392c2bce3eb8ceb5677fa945126d4c5",
"files": {
"dependency-gate.v1.json": "sha256:b8ac81155266dca921f159d1cfabec6605f2e4bab0320ad6b23a3dbee51e6fa1",
"product-action.v1.schema.json": "sha256:faf815b27fd292e564a7d51de20c5a2825abbe710315a2364a9932ae3b5e4b7e",
"product-oracle-evidence.v1.schema.json": "sha256:faab6582bf3fba307b0f9f2949c51726409a209b0fa62e847114e0c6301038c6",
- "product-oracle-manifest.v1.json": "sha256:bbcdce63841053bba9567ae2514bba228d9685328438c9a31ecf10e883ba57e2",
+ "product-oracle-manifest.v1.json": "sha256:238789cb8c23435d4401b3b3e5522cca6b4d70bd1d411b20a25dec475c5232e5",
"product-result.v1.schema.json": "sha256:72fc76be77572e40eed7516754911b45fdc9d55a8c089ba74c21427a33809def"
},
"schema_version": {
diff --git a/e2e/product/schema/product-oracle-manifest.v1.json b/e2e/product/schema/product-oracle-manifest.v1.json
index 8c863c7b..04ad540f 100644
--- a/e2e/product/schema/product-oracle-manifest.v1.json
+++ b/e2e/product/schema/product-oracle-manifest.v1.json
@@ -1,5 +1,5 @@
{
- "descriptor_digest": "sha256:a435bc5901bbcaeaf2f41c8c4db15b0a7f967d988aeb544e8f5d2890abc64639",
+ "descriptor_digest": "sha256:1bdd37be3354af88208d5c9f91945f23b392c2bce3eb8ceb5677fa945126d4c5",
"expected_red_reasons": [],
"planned_commands": [
"schema.list",
diff --git a/scripts/ci-shards.py b/scripts/ci-shards.py
index 033f3cfa..e1a8cbee 100755
--- a/scripts/ci-shards.py
+++ b/scripts/ci-shards.py
@@ -32,6 +32,7 @@ INTEGRATION_SHARDS = {
("hiroute-diagnostics", "writer_bounds"),
("hiroute-cli", "contracts"),
("hiroute-cli", "desktop_locator"),
+ ("hiroute-cli", "request_input"),
("hiroute-cli", "service_proxy"),
("hiroute-cli", "transport_unavailable"),
("hiroute-cli", "work_plans"),