Crate gate4agent_types 

Pure data contracts shared by gate4agent engines and shells.

Structs

AcpTransportSpec

ActiveProviderTool

AdapterBinding

AdapterId

Stable identifier for one provider adapter implementation.

AgentAdapterCapabilities

AgentCapabilities

AgentCommand

AgentId

Stable, extensible identifier for an agent CLI.

AgentInstanceId

AgentReadinessSpec

AgentSpec

AgentTransportCapabilities

CapabilityModelSummary

CapabilityProbeRequest

CapabilitySnapshot

CommandEnvelope

CommandId

ContextWindowUsage

ControlEvent

ControlHealth

ControlSnapshot

DetectionSpec

EffectEnvelope

ForegroundProcess

ForegroundSnapshot

HistoryCandidateSummary

HistoryMessageRecord

HistoryQuery

HistorySessionRecord

HistorySnapshot

LaunchSpec

NativeSessionCatalogEntry

NativeSessionCatalogPage

NativeSessionCatalogSummary

NativeSessionExternalGroup

NativeSessionPreview

NativeSessionPreviewMessage

ObservationEnvelope

OperationId

OperatorGateOption

One choice as rendered on screen inside an OperatorGateState.

OperatorGateState

The full classification of a screen recognized as an OperatorGate, replacing what used to be a bare label string. kind is always known (a matcher only returns this type once it has matched a specific gate phrase); subject, input, and options degrade independently to Unknown/empty when the screen’s specific shape was not recognized – never invented from kind alone.

PendingCapabilityProbe

PendingHistoryOperation

PendingResumeOperation

PipeTransportSpec

Optional catalog override used by controlled fixtures and providers whose headless executable differs from their interactive PTY executable.

PreparedInput

PreparedWrite

PromptPayload

PromptSpec

ProviderAvailableCommand

A single slash-style command the agent advertises (ACP transport’s available_commands_update).

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.

ProviderInteraction

ProviderInteractionId

ProviderInteractionOption

One option the agent offered on a session/request_permission-style interaction, carried on ProviderEvent::InteractionRequested::options exactly as the agent gave it – see ACP’s PermissionOption in src/acp/protocol.rs (option_id, name, kind). This crate cannot depend on gate4agent (see this crate’s own CLAUDE.md), so the shape is repeated here rather than shared, the same precedent ProviderRateLimitKind already sets for a wire-typed mirror of a gate4agent-side enum.

ProviderInteractionTarget

ProviderModeInfo

One mode the agent advertised as selectable, read from ACP’s session/new handshake result (AcpSession::available_modes()) and carried on ProviderEvent::ModeChanged alongside the id that changed. Mirrors gate4agent-node-protocol’s AgentStreamNamedIdV1 field-for-field; this crate does not depend on that one (see this crate’s own CLAUDE.md), so the shape is repeated rather than shared.

ProviderPlanStep

One step of the agent’s execution plan (ACP transport’s plan update). ProviderEvent::Plan always carries the FULL plan snapshot, never a delta.

ProviderRuntimePolicy

ProviderSessionIdentity

ProviderSnapshot

ProviderSource

ProviderSourceCursor

ProviderSubagent

ResumeLaunchRequest

ResumeSessionSummary

ResumeSnapshot

SessionGeneration

SessionOptionSelection

SessionRecordPreview

SessionSnapshot

ShellCommand

StartRequest

TerminalFrame

TerminalSize

TerminalText

TokenUsage

Enums

AdapterBindingError

AdapterFamily

AdapterIdError

AdapterVerification

AgentCommandMode

AgentIdError

ApprovalLevel

How much autonomy a freshly spawned provider CLI process is granted at launch, independent of which transport (PTY, inline/pipe, ACP) execs it – these are process launch arguments, the same axis regardless of transport.

CapabilityProbeFailure

CapabilityValidationError

ControlCommand

ControlEffect

ControlError

ControlEventKind

ControlObservation

DraftReadySignal

ForegroundAuthority

ForegroundProcessKind

ForegroundRequirement

Route proof an effect executor must obtain immediately before a PTY write.

HistoryMessageRole

HistoryOperation

HistoryValidationError

HostDecisionAuthority

WHO decided a host request the agent sent to the ACP host – see ProviderEvent::HostRequestObserved. Mirrors gate4agent’s own HostDecisionAuthority one-for-one; this crate cannot depend on gate4agent (see this crate’s CLAUDE.md), so the value is converted at the boundary that already depends on both (gate4agent-shell-native).

HostRequestDecision

A typed answer to “what happened to this host request” – see ProviderEvent::HostRequestObserved. Mirrors gate4agent’s own HostRequestDecision one-for-one; see HostDecisionAuthority’s doc comment for why this crate keeps its own copy rather than importing it.

HostRequestOutcome

Whether a Granted host request’s underlying operation actually ran without an I/O or execution problem – see [ProviderEvent:: HostRequestObserved]. Mirrors gate4agent’s own HostRequestOutcome one-for-one; see HostDecisionAuthority’s doc comment for why this crate keeps its own copy rather than importing it.

InitialPromptMode

InputAction

InputPrepareError

NativeDraftMode

NativeSessionCatalogScope

NativeSessionCatalogWindow

NativeSessionExternalGroupKind

ObservationIgnoredReason

OperatorGateInput

HOW OperatorGateState is controlled – what a caller resolving it (typically a human, occasionally a scripted answer) needs to send.

OperatorGateKind

What TYPE of blocking question OperatorGateState is showing, classified from the screen’s own top-level phrasing (see startup_operator_gate in gate4agent-shell-native, the only producer). Distinct kinds exist so a consumer can react differently to “an update is running” versus “type an answer” without parsing OperatorGateSubject/options first.

OperatorGateOptionSemantics

What choosing a given OperatorGateOption does, inferred from the verb in its own on-screen text (see classify_operator_gate_option_semantics in gate4agent-shell-native) – never from its position or number, since neither is stable across CLIs or screen wraps.

OperatorGateSubject

WHAT entity OperatorGateState is gating access to – narrower than kind (which says what TYPE of question this is): two WorkspaceTrust gates always share subject: Directory, but the path detail (when a matcher can read one off the screen) distinguishes which directory. Unknown is the honest reading for a kind whose screen text does not name a concrete subject from this list (a vendor updater or onboarding splash is not “about” a directory, a hook set, or an account) – it is never upgraded into a guess.

PipePromptDelivery

PipeProtocol

PreparedInputKind

PreparedWriteKind

ProcessMatcher

PromptFraming

ProviderActivity

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.

ProviderEvent

ProviderEventValidationError

ProviderInteractionKind

ProviderInteractionOutcome

ProviderInteractionResponse

ProviderInteractionResponseError

ProviderInteractionResponseKind

ProviderInteractionStatus

ProviderPlanPriority

Priority of a single ProviderPlanStep, carried on ProviderEvent::Plan.

ProviderPlanStatus

Status of a single ProviderPlanStep, carried on ProviderEvent::Plan.

ProviderRateLimitKind

Which class of budget a ProviderEvent::RateLimited observation concerns. This is the wire-typed counterpart of gate4agent’s own (source-of-truth) RateLimitType – kept as its own type here, rather than imported, because this crate’s contract forbids depending on gate4agent (see this crate’s CLAUDE.md); the conversion from the detector’s enum lives in the shell that already depends on both.

ProviderRuntimeCapability

ProviderRuntimePolicyError

ProviderSessionKey

ProviderStopReason

Why an ACP turn stopped – mirrors gate4agent’s own StopReason (src/core/types.rs) one-for-one; this crate cannot depend on gate4agent (see this crate’s own CLAUDE.md), the same reason every other wire-typed mirror here exists (ProviderRateLimitKind, ProviderInteractionOption, …). ProviderError is synthesized locally by gate4agent’s ACP session when session/prompt itself answers with a JSON-RPC error instead of a normal response – see that type’s own doc comment for the live Codex fixture this shape was measured against.

PtyScreenState

Whether the screen currently painted at a PTY looks like the agent’s own composer, as classified by the node from the same terminal text a human would read. This is a screen-content judgement, never a process-liveness one – SessionStatus already answers “is something running”, and a consumer must not fold the two into a single “is it running” question: a process can be Running while its screen sits on an unrelated installer prompt, and that combination is exactly the case this type exists to distinguish.

ResumeAuthorityTarget

ResumePhase

ResumeTarget

ResumeValidationError

RuntimePlatform

Runtime in which an executable is detected or launched.

SessionOptionValidationError

SessionOptionValue

SessionStatus

SpecVerification

Provenance state for a built-in launch specification.

TerminalControl

TerminalMouseProtocolEncoding

TransportKind

Constants

BRACKETED_PASTE_END

BRACKETED_PASTE_START

CAPABILITY_MODELS_MAX

CAPABILITY_MODEL_ID_MAX_BYTES

CAPABILITY_MODEL_LABEL_MAX_BYTES

CONTROL_INSTANCE_IDENTITIES_CAPACITY

CONTROL_INSTANCE_IDENTITIES_MAX

CONTROL_SESSIONS_MAX

FOREGROUND_PROCESS_NAME_MAX_BYTES

HISTORY_CANDIDATE_ID_MAX_BYTES

HISTORY_DISCOVERY_LIMIT_MAX

HISTORY_ERROR_MAX_BYTES

HISTORY_MESSAGES_MAX

HISTORY_MESSAGE_MAX_BYTES

HISTORY_MODEL_MAX_BYTES

HISTORY_SESSION_ID_MAX_BYTES

HISTORY_TITLE_MAX_BYTES

MAX_ADAPTER_REVISION_LEN

NATIVE_SESSION_CATALOG_LIMIT_MAX

NATIVE_SESSION_EXTERNAL_GROUP_ID_MAX_BYTES

NATIVE_SESSION_EXTERNAL_GROUP_LABEL_MAX_BYTES

NATIVE_SESSION_PREVIEW_MESSAGE_LIMIT_MAX

NATIVE_SESSION_PREVIEW_TEXT_MAX_BYTES

OPERATOR_GATE_OPTIONS_MAX

Bound on OperatorGateState::options – large enough for any list a real prompt has ever been observed to render (2-4 choices), small enough that a garbled or hostile screen capture cannot inflate the wire payload.

OPERATOR_GATE_OPTION_TEXT_MAX_BYTES

Per-OperatorGateOption::text byte bound, same scale as PTY_SCREEN_GATE_NAME_MAX_BYTES – an option label is a single short line off the screen, never a paragraph.

OPERATOR_GATE_PATH_MAX_BYTES

Bound on OperatorGateSubject::Directory’s path, matching the scale of other path-shaped fields carried on this wire (see WORKING_DIRECTORY_MAX_BYTES for the same order of magnitude on a full working-directory string).

PROVIDER_AVAILABLE_COMMANDS_MAX

PROVIDER_CONFIG_OPTIONS_MAX

PROVIDER_CONFIG_OPTION_CHOICES_MAX

PROVIDER_EVENT_ID_MAX_BYTES

PROVIDER_EVENT_TEXT_MAX_BYTES

PROVIDER_EVENT_TOOLS_MAX

PROVIDER_INGRESS_EVENTS_MAX

PROVIDER_INTERACTIONS_MAX

PROVIDER_INTERACTION_FAILURE_MAX_BYTES

PROVIDER_INTERACTION_OPTIONS_MAX

Bound on ProviderEvent::InteractionRequested::options – same rationale as OPERATOR_GATE_OPTIONS_MAX: an ACP session/request_ permission call offers a subset of exactly four PermissionOptionKind values, so this gives headroom over that domain maximum without letting a garbled or hostile agent inflate the wire payload.

PROVIDER_INTERACTION_RESPONSE_MAX_BYTES

PROVIDER_MODE_CATALOG_MAX

PROVIDER_PLAN_STEPS_MAX

PROVIDER_SESSION_LOCATOR_MAX_BYTES

PROVIDER_SUBAGENTS_MAX

PTY_SCREEN_GATE_NAME_MAX_BYTES

RESUME_ERROR_MAX_BYTES

SEMANTIC_PROMPT_MAX_BYTES

SESSION_OPTION_ID_MAX_BYTES

SESSION_OPTION_VALUES_MAX

SESSION_OPTION_VALUE_MAX_BYTES

TERMINAL_COLUMNS_MAX

TERMINAL_INPUT_CHUNK_MAX_BYTES

TERMINAL_INPUT_MAX_BYTES

TERMINAL_ROWS_MAX

TERMINAL_SUBMIT_DELAY_MS

TERMINAL_WRITE_DELAY_MAX_MS

WORKING_DIRECTORY_MAX_BYTES

Functions

normalize_executable_name

Normalize an executable name for portable provider matching.

normalize_semantic_prompt

Validate and normalize a semantic prompt before it crosses a process or protocol boundary. Terminal controls are rendered inert consistently with PTY prompt preparation, but no terminal framing bytes are added.

prepare_agent_command

Prepare a provider-native slash command after a dispatcher has selected the foreground agent. Arguments are TUI text segments, not shell arguments.

prepare_input

Converts an input action to bounded writes without touching a PTY.

prepare_input_with_limits

prepare_shell_command

Prepare an intentional command line for a dispatcher that has just confirmed a shell owns the PTY foreground.

sanitize_prompt_text

Neutralizes terminal control sequences while preserving prompt newlines and tabs.

validate_candidate_id

validate_capability_models

validate_history_error

validate_native_session_id

validate_resume_error

validate_session_config_value_json

Bounds check for ControlCommand::SetSessionConfigOption’s value_json: required, bounded the same as any other provider-scoped free text (PROVIDER_EVENT_TEXT_MAX_BYTES), free of unsafe control bytes. Mirrors gate4agent-node-protocol’s deserialize_acp_config_value_json minus the JSON-parseability check – this crate is a pure data contract and does not depend on serde_json, so confirming the text actually parses is the shell executor’s job (AcpSession::set_config_option takes an already-parsed serde_json::Value).

validate_session_control_id

Bounds check for the mode_id/option_id/model_id an ACP session control command (ControlCommand::SetSessionMode/ SetSessionConfigOption/SetSessionModel) carries – the same bound as any other provider-scoped id (PROVIDER_EVENT_ID_MAX_BYTES), required and free of control characters. Mirrors what gate4agent-node-protocol’s wire boundary already enforces (deserialize_acp_control_id) before a command ever reaches gate4agent-engine; re-checked here because a ControlCommand is constructible directly (tests, other embedders), not only through that one wire.