Crate gate4agent_node_protocol 

Bounded wire contract for the local Gate4Agent node.

Modules

correlation

Opaque correlation ids and tool-class labels the node mints for a session’s provider events.

Structs

AdapterContractRevision

AdapterId

Stable identifier for one provider adapter implementation.

AgentId

Stable, extensible identifier for an agent CLI.

AgentProgressAttentionV1

AgentProgressUsageV1

AgentProgressV1

AgentStreamChunkV1

One chunk of the outbound agent content stream – the agent-stream-events-v1 capability’s push channel, mirroring NodeEvent::TerminalFrame exactly: its own subscription, its own type, no resync promise. source_sequence orders chunks within one provider source, the same number the provider event carries.

AgentStreamInteractionOptionV1

One selectable answer to an InteractionPrompt chunk – an ACP permission option, named by the provider rather than invented here.

AgentStreamNamedIdV1

One named catalog entry – a selectable session mode or model on the ModeCatalog/ModelCatalog chunk kinds. id is what SetSessionMode/SetSessionModel take back.

ArchitectureId

CapabilityId

ClientAuthentication

ClientCompatibilityOffer

ClientHello

ContextPackBytesRead

ContextPackLineageReceipt

ControllerState

DeliveryBlobChunkHexV1

DeliveryBlobDigestV1

DeliveryBlobReceiptV1

DeliveryBundleManifestV2

DeliveryCommitReceiptV1

DeliveryComponentV2

DeliveryDigestError

DeliveryManifestDigestV2

DeliveryRelativePathError

DeliveryRelativePathV2

DeliveryStageId

DeliveryStageIdError

GitCommitDetails

GitCommitSummary

GitDiff

GitDiffRequest

GitHistoryPage

GitObjectId

GitObjectIdError

GitSnapshot

GitStatusEntry

GitWorktreeSnapshot

HarnessMcpActivationDigest

HarnessMcpCallId

HarnessMcpLaunchTraceV1

Optional stdio trace opt-in of a harness-MCP launch: when the node process has a non-empty environment variable named dir_env, the node adds an environment entry named env holding a trace-file path under that directory.

HarnessMcpLaunchV1

How the node exposes a reserved harness-MCP door to the provider session it spawns – every name in it is the CALLER’s, never the node’s.

HarnessMcpLocalRequestV1

HarnessMcpLocalToken

HarnessMcpOpaquePayloadV1

An opaque harness-MCP payload.

HarnessMcpReplyChunkHexV1

HarnessMcpReservationId

HistoryCandidateSummary

HostDescriptor

HostDirectoryEntry

HostDirectoryListing

LaunchInventory

ManagedSessionRecord

ManagedWorktreeGitScope

ManagedWorktreeIdentifierError

ManagedWorktreeLeaseId

ManagedWorktreeLeaseSnapshot

ManagedWorktreeProfileSummary

ManagedWorktreeSpawnReceipt

ManagedWorktreeSpawnRequest

ManagedWorktreeSpawnRequestV2

NativeSessionCatalogEntry

NativeSessionCatalogPage

NativeSessionCatalogRoute

NativeSessionCatalogSummary

NativeSessionExternalGroup

NativeSessionSelection

NegotiatedNodeCompatibility

NodeCallHomeAnnounce

The first frame on a CALL-HOME connection, and the only frame this protocol adds for it: the node announcing which node it is.

NodeCompatibilitySupport

NodeCursor

NodeEventEnvelope

NodeFailure

NodeHello

NodeId

NodeIncarnationId

NodeSnapshot

OpaqueHostPath

OperatingSystemId

PathSemantics

ProtocolRange

ProviderAdapterContractSupport

ProviderConfigChoice

One selectable value of a select-kind ProviderConfigOption. value_json is the choice’s value pre-serialized to JSON text (this crate is a pure data contract and does not depend on serde_json; see ProviderConfigOption::value_json for the same convention applied to the option’s own current value).

ProviderConfigOption

One session configuration setting – the mechanism ACP uses to change model, reasoning effort, and similar settings, superseding session modes. ProviderEvent::ConfigOptionsUpdated always carries the FULL current set, never a delta.

ProviderContractRevision

ProviderContractSupport

ProviderRuntimeContractId

ProviderRuntimeStatus

ProviderRuntimeStatuses

ProviderRuntimeVersion

RepositoryPath

RequestEnvelope

ResolvedBundleReceipt

ResolvedContextPackReceipt

ResolvedEnvironmentProfileReceipt

Resolved environment-profile identity echoed on spawn receipts.

ResolvedHarnessMcpProxyReceiptV1

ResolvedSpawnReceipt

ResolvedSpawnSpec

ResponseEnvelope

ServerChallenge

SessionAddress

SessionAgentProgress

SessionHistorySummaryV1

Aggregate facts about one session record’s native history: how many messages and completed turns it holds and what it cost, without any of its content.

SessionKey

SessionRecordId

SessionRecordPreview

SessionRecordRetentionConfig

Node-local policy for retiring dead ManagedSessionState::Unavailable records so a long-lived node’s durable state does not grow forever. Both fields default to 0 (disabled) – a freshly started node must never silently delete a record until an operator has chosen real values via --session-record-retention-age-ms / --session-record-retention-keep. Never applies to Live, IdentityPending, or Dormant records: only Unavailable is both inert (no active_session) and not resumable.

SessionTaskBindingV1

SpawnBrowserProfileId

Opaque dig2browser station browserProfile id under node-local profiles_root.

SpawnBundleDigest

SpawnBundleDigestError

SpawnBundleId

SpawnBundleRevision

SpawnContextDigest

SpawnContextDigestError

SpawnContextId

SpawnDeadlineMs

SpawnEnvironmentProfileId

SpawnEnvironmentProfileRevision

SpawnIdempotencyKey

SpawnNetworkAllowlistId

Opaque node-local network allowlist policy id (station axis).

SpawnOverrides

Spawn-time overrides for an accepted SpawnSpec.

SpawnProfileDefaults

SpawnProfileId

SpawnProfileRevision

SpawnProfileSummary

SpawnPrompt

SpawnPromptMetadata

SpawnRequiredCapabilities

SpawnResolutionProvenance

SpawnSpec

SpawnTarget

StateSchemaSupport

TaskId

TaskIdError

WorkspaceEntry

WorkspaceFileRead

WorkspaceFileRevision

WorkspaceFileRevisionError

WorkspaceId

WorkspaceInspection

WorkspaceInspectionTruncationV1

Additive: records why (if at all) a WorkspaceInspection was cut short by the node’s own inner walk+git time/entry budget (GATE4AGENT_NODE_WORKSPACE_INSPECTION_BUDGET_MS / GATE4AGENT_NODE_WORKSPACE_INSPECTION_ENTRY_CAP) — distinct from tree_truncated, which only reflects the walk’s fixed per-response caps (WORKSPACE_TREE_MAX_ENTRIES / WORKSPACE_TREE_MAX_DEPTH). Every field is #[serde(default)] and the field itself is optional on WorkspaceInspection, so payloads produced before this field existed still parse.

WorkspaceSnapshot

WorktreeProfileId

WorktreeProfileInventory

WorktreeProfileRevision

Enums

AdapterFamily

AgentProgressAttentionKindV1

AgentProgressCurrentV1

AgentProgressEventKindV1

AgentStreamChunkKindV1

The kind of a single AgentStreamChunkV1 – content the operator needs to act on a running ACP session: what the agent is saying, a pending interaction it needs answered, and the catalogs the three ACP setter verbs (SetSessionMode, SetSessionConfigOption, SetSessionModel) operate over. Mirrors gate4agent_types::ProviderEvent’s content variants deliberately – see docs/gate4agent/plans/gate4agent-acp-control-plane-on-the-wire-2026-09-02.md §3-4.

BlockAuthorityV1

WHO or WHAT blocked an action – see AgentStreamChunkKindV1::Blocked.

ClientFrame

ClientRole

CompatibilityIdentifierError

DeliveryComponentKindV2

DeliveryContractError

DeliveryScopeV2

FrameError

GitDiffMode

GitSignatureStatus

HarnessMcpContentTypeV1

Names what shape an opaque harness-MCP payload’s body holds.

HarnessMcpContractError

HarnessMcpLocalReplyV1

The proxy’s terminal reply to a local session’s harness-MCP call.

HarnessMcpRejectReasonV1

HostDirectoryEntryError

LocalTransportKind

ManagedSessionState

ManagedWorktreeCleanupFailure

ManagedWorktreeLeaseState

ManagedWorktreeRetention

NativeSessionCatalogScope

NativeSessionCatalogWindow

NativeSessionExternalGroupKind

NodeCompatibilityAuthBindingError

NodeEvent

NodeFailureCode

NodeIdentifierError

NodeIncarnationIdError

NodeNegotiatedHandshakeCapacityError

NodeRequest

NodeResponse

OpaqueHostPathError

PathEncoding

PathStyle

ProtocolNegotiationError

ProviderConfigOptionKind

The kind of a ProviderConfigOption – select (choose one of choices) or boolean (toggle the option’s current value). Unknown is the fallback for a kind string this build does not recognize.

ProviderContractManifestError

ProviderInteractionKind

ProviderInteractionResponse

ProviderRuntimeMode

ProviderRuntimeStatusError

RepositoryPathError

ServerFrame

SessionMode

SessionTaskTargetV1

SpawnDeadlineError

SpawnFieldProvenance

SpawnIdentifierError

SpawnOverride

SpawnPromptError

SpawnRequiredCapabilitiesError

SpawnSpecResolveError

WorkspaceEntryKind

WorkspaceFileContent

WorktreeServiceMode

Constants

BUILD_STAMP

CAPABILITY_HOST_DIRECTORY_BROWSE_V1

Read-only, paged directory browsing using UTF-8 absolute host paths only. OpaqueHostPath::UnixBytes is outside this capability revision.

DEFAULT_CONTROLLER_LEASE_MS

DELIVERY_STAGE_NONCE_BYTES

HISTORY_DISCOVERY_LIMIT_MAX

MAX_ACP_BLOCKED_HELP_BYTES

Bound on the help of an agent-stream Blocked chunk – the guidance tail a CLI attaches after naming the block, which runs longer than a one-line refusal.

MAX_ACP_BLOCKED_REASON_BYTES

Bound on the reason of an agent-stream Blocked chunk.

MAX_ACP_CATALOG_ENTRIES

Mirrors gate4agent_types::PROVIDER_CONFIG_OPTIONS_MAX – the catalog list on ModeCatalog/ModelCatalog/ConfigOptions chunks.

MAX_ACP_CONTROL_ID_BYTES

Mirrors gate4agent_types::PROVIDER_EVENT_ID_MAX_BYTES – the ACP control verbs’ mode_id/option_id/model_id and the agent stream’s tool_name/catalog id fields round-trip provider-minted ids through the same bound the provider event stream already validates them against.

MAX_ACP_CONTROL_TEXT_BYTES

Mirrors gate4agent_types::PROVIDER_EVENT_TEXT_MAX_BYTES – free text carried on the agent content stream (Text, Thinking, interaction prompt/title, config value_json) and SetSessionConfigOption’s value_json.

MAX_ACP_CORRELATION_ID_BYTES

Bound on ResolveInteraction.correlation_id and on the short labels (tool_class, reason_kind) of an agent-stream Blocked chunk.

MAX_ACP_INTERACTION_OPTIONS

Mirrors gate4agent_types::PROVIDER_CONFIG_OPTION_CHOICES_MAX – the option list on one InteractionPrompt chunk.

MAX_ADAPTER_CONTRACT_REVISION_BYTES

MAX_AGENT_PROGRESS_ACTIVE_TOOL_LABELS

MAX_AGENT_PROGRESS_ENTRIES

MAX_AGENT_PROGRESS_ENTRY_BYTES

MAX_AGENT_PROGRESS_TOOL_LABEL_BYTES

MAX_COMPATIBILITY_IDENTIFIER_BYTES

MAX_CONTEXT_PACK_BYTES

MAX_CONTEXT_PACK_RETAINED_MESSAGES

MAX_CONTROLLER_LEASE_MS

MAX_DELIVERY_CHUNK_RAW_BYTES

MAX_DELIVERY_FILES

MAX_DELIVERY_FILE_BYTES

MAX_DELIVERY_RELATIVE_PATH_BYTES

MAX_DELIVERY_TOTAL_BYTES

MAX_GIT_DIFF_BYTES

MAX_GIT_HISTORY_COMMITS

MAX_HARNESS_MCP_AGGREGATE_REPLY_BYTES

MAX_HARNESS_MCP_CALL_DEADLINE_MS

MAX_HARNESS_MCP_LAUNCH_ARGS

Most arguments a launch description may pass to the MCP server program.

MAX_HARNESS_MCP_LAUNCH_ARG_BYTES

Longest single argument of a launch description.

MAX_HARNESS_MCP_LAUNCH_NAME_BYTES

Longest server name or environment-variable name a launch description may carry.

MAX_HARNESS_MCP_LAUNCH_SCRUB_ENV

Most environment variables a launch description may ask the node to scrub.

MAX_HARNESS_MCP_LOCAL_REQUEST_BYTES

MAX_HARNESS_MCP_PENDING_CALLS_PER_NODE

MAX_HARNESS_MCP_PENDING_CALLS_PER_SESSION

MAX_HARNESS_MCP_REPLY_CHUNK_RAW_BYTES

MAX_HARNESS_MCP_RESERVATION_TTL_MS

MAX_HARNESS_MCP_SPAWN_RELAY_DEADLINE_MS

MAX_HOST_DIRECTORY_DISPLAY_NAME_BYTES

MAX_HOST_DIRECTORY_ENTRIES

MAX_LAUNCH_BUNDLES

MAX_MANAGED_WORKTREE_LEASES

MAX_MANAGED_WORKTREE_LEASE_ID_BYTES

MAX_MANAGED_WORKTREE_PROFILES_PER_WORKSPACE

MAX_NETWORK_ALLOWLIST_CATALOG_ENTRIES

Soft bound on station network allowlist catalog ids exposed on launch inventory.

MAX_NODE_CLIENT_FRAME_BYTES

MAX_NODE_FRAME_BYTES

MAX_NODE_HELLO_FRAME_BYTES

MAX_NODE_IDENTIFIER_BYTES

MAX_NODE_TERMINAL_BYTES

MAX_NODE_TEXT_BYTES

MAX_PROVIDER_ADAPTER_CONTRACTS

MAX_PROVIDER_CONTRACTS

MAX_PROVIDER_CONTRACT_REVISION_BYTES

MAX_PROVIDER_IDENTITIES

MAX_PROVIDER_RUNTIME_CONTRACT_ID_BYTES

MAX_PROVIDER_RUNTIME_STATUSES

MAX_PROVIDER_RUNTIME_VERSION_BYTES

MAX_REPOSITORY_PATH_BYTES

MAX_SESSION_DISPLAY_NAME_BYTES

MAX_SPAWN_BUNDLE_REVISION_BYTES

MAX_SPAWN_DEADLINE_MS

MAX_SPAWN_ENVIRONMENT_PROFILE_REVISION_BYTES

MAX_SPAWN_IDEMPOTENCY_KEY_BYTES

MAX_SPAWN_PROFILES

MAX_SPAWN_PROFILE_ID_BYTES

MAX_SPAWN_PROFILE_REVISION_BYTES

MAX_SPAWN_REQUIRED_CAPABILITIES

MAX_SPAWN_RESOURCE_ID_BYTES

MAX_WORKSPACE_FILE_BYTES

MAX_WORKSPACE_ROOT_BYTES

MAX_WORKTREE_PROFILE_ID_BYTES

MAX_WORKTREE_PROFILE_REVISION_BYTES

MIN_CONTROLLER_LEASE_MS

NATIVE_SESSION_CATALOG_LIMIT_MAX

NATIVE_SESSION_PREVIEW_MESSAGE_LIMIT_MAX

NODE_ACP_CONTROL_CAPABILITY

The inbound ACP control verbs – ResolveInteraction, SetSessionMode, SetSessionConfigOption, SetSessionModel – that answer what NODE_AGENT_STREAM_EVENTS_CAPABILITY reports (same plan, §5).

NODE_AGENT_PROGRESS_SNAPSHOT_CAPABILITY

NODE_AGENT_STREAM_EVENTS_CAPABILITY

The outbound content stream – NodeEvent::AgentStream – mirroring NODE_TERMINAL_FRAME_EVENTS_CAPABILITY’s own subscription/type split rather than folding content into a telemetry vocabulary (docs/gate4agent/plans/gate4agent-acp-control-plane-on-the-wire-2026-09-02.md §3-4).

NODE_AUTH_NONCE_BYTES

NODE_AUTH_PROOF_BYTES

NODE_CHILD_ENVIRONMENT_PROFILE_CAPABILITY

NODE_COMPATIBILITY_METADATA_CAPABILITY

NODE_DELIVERY_BUNDLE_V2_STAGE_COMMIT_CAPABILITY

NODE_GIT_READ_CAPABILITY

NODE_HARNESS_MCP_READ_PROXY_CAPABILITY

NODE_HISTORY_CONTEXT_PACK_CAPABILITY

NODE_INCARNATION_ID_BYTES

NODE_LEGACY_PROVIDER_IDS

NODE_MANAGED_WORKTREE_LIFECYCLE_CAPABILITY

NODE_MANAGED_WORKTREE_SPAWN_V2_CAPABILITY

NODE_NATIVE_SESSION_CATALOG_CAPABILITY

NODE_NATIVE_SESSION_CATALOG_PAGING_CAPABILITY

NODE_NATIVE_SESSION_INDEX_CAPABILITY

NODE_NATIVE_SESSION_PREVIEW_CAPABILITY

NODE_OPAQUE_UNIX_PATH_CAPABILITY

NODE_PROVIDER_CONTRACT_MANIFEST_CAPABILITY

NODE_PROVIDER_ID_OPEN_CAPABILITY

NODE_PROVIDER_RUNTIME_STATUS_CAPABILITY

NODE_PROVIDER_SESSION_REFERENCE_INDEX_CAPABILITY

NODE_REPOSITORY_PATH_CAPABILITY

NODE_SESSION_BUNDLE_MATERIALIZATION_CAPABILITY

NODE_SESSION_RECORD_CONTEXT_EXPORT_CAPABILITY

NODE_SESSION_TASK_CORRELATION_CAPABILITY

NODE_SPAWN_PROFILE_REVISION_CAPABILITY

NODE_SPAWN_SPEC_DEFAULTS_OVERRIDES_CAPABILITY

NODE_STANDALONE_WORKSPACE_LIFECYCLE_CAPABILITY

NODE_STATE_SCHEMA_V1

NODE_STATE_SCHEMA_V2

NODE_STATE_SCHEMA_V3

NODE_STATE_SCHEMA_V4

NODE_STATE_SCHEMA_V5

NODE_STATE_SCHEMA_V6

NODE_STATE_SCHEMA_V7

NODE_STATE_SCHEMA_V8

NODE_STATE_SCHEMA_V9

NODE_STATE_SCHEMA_V10

NODE_TERMINAL_FRAME_EVENTS_CAPABILITY

NODE_WORKSPACE_ENTRY_CREATE_CAPABILITY

NODE_WORKSPACE_FILE_READ_CAPABILITY

NODE_WORKSPACE_FILE_WRITE_CAPABILITY

NODE_WORKTREE_SELECTION_CAPABILITY

SPAWN_RUNTIME_PROVIDER_SESSION_IDENTITY

SPAWN_RUNTIME_RAW_PTY_LIFECYCLE

SPAWN_RUNTIME_SEMANTIC_READINESS

SPAWN_RUNTIME_SEMANTIC_RESUME

SPAWN_RUNTIME_STRUCTURED_PROMPT

TASK_ID_NONCE_BYTES

Functions

context_pack_digest

The one definition of the context pack digest formula: SHA256(domain || JSON(lineage) || 0x00 || bytes), rendered sha256:<hex>. Both the node (computing a pack’s digest when it exports one) and the harness (recomputing a fetched pack’s digest to check it against a mailed receipt) call this instead of keeping their own copy, so the formula can only drift in one place.

encode_node_compatibility_auth_binding

production_node_client_compatibility_offer

provider_id_is_legacy

read_json_frame

read_json_frame_limited

read_json_frame_limited_body_timeout

sha256_hex

A bare (no sha256: prefix) lowercase hex SHA-256 digest of bytes. Used where the wire already names the hash algorithm by convention rather than in the value itself – HarnessMailRefV1::WorkspacePath.sha256 and the node’s own WorkspaceFileRevision are both this shape (unlike the context pack digest above, which reuses the prefixed sha256:<hex> form since it must distinguish itself from any other hash the wire might one day carry for the same object). Plain SHA-256 with no domain separation: a workspace file’s bytes are not reused as an input to any other digest this wire computes, so there is nothing for a domain tag to separate it from.

validate_node_negotiated_handshake_capacity

validate_provider_contract_manifest

write_json_frame

write_json_frame_limited

Type Aliases

NativeSessionPreview