Documentation
¶
Index ¶
- Constants
- Variables
- func BridgeRuntimePurposeValues() []string
- func HealthFailureDetected(state HealthState) bool
- func HealthFailureReason(state HealthState) string
- type AcceptedCapabilities
- type BridgeRuntimePurpose
- type HandlerFunc
- type HealthCheckResponse
- type HealthState
- type InitializeBridgeBoundSecret
- type InitializeBridgeManagedInstance
- type InitializeBridgeRuntime
- func (r InitializeBridgeRuntime) ManagedBridgeInstanceIDs() []string
- func (r InitializeBridgeRuntime) ManagedInstance(id string) (*InitializeBridgeManagedInstance, bool)
- func (r InitializeBridgeRuntime) SingleManagedInstance() (*InitializeBridgeManagedInstance, error)
- func (r InitializeBridgeRuntime) Validate() error
- type InitializeCapabilities
- type InitializeExtension
- type InitializeExtensionInfo
- type InitializeMethods
- type InitializeRequest
- type InitializeResponse
- type InitializeRuntime
- type InitializeSupports
- type LaunchConfig
- type Process
- func (p *Process) Call(ctx context.Context, method string, params, result any) error
- func (p *Process) Done() <-chan struct{}
- func (p *Process) HandleMethod(method string, handler HandlerFunc) error
- func (p *Process) HealthState() HealthState
- func (p *Process) Initialize(ctx context.Context, request InitializeRequest) (InitializeResponse, error)
- func (p *Process) PID() int
- func (p *Process) Shutdown(ctx context.Context) error
- func (p *Process) Stderr() string
- func (p *Process) Stdin() io.WriteCloser
- func (p *Process) Stdout() io.ReadCloser
- func (p *Process) Wait() error
- type RPCError
- type ResponseDecodeError
- type ShutdownRequest
- type ShutdownResponse
Constants ¶
const ( // InitializeBridgeRuntimeVersion2 is the purpose-scoped bridge runtime // handshake version negotiated by bridge-capable extensions. InitializeBridgeRuntimeVersion2 = "2" )
Variables ¶
var ( // ErrNotInitialized reports that an operational request was attempted before initialize completed. ErrNotInitialized = errors.New("subprocess: not initialized") // ErrShutdownInProgress reports that the process is draining and will not accept new requests. ErrShutdownInProgress = errors.New("subprocess: shutdown in progress") // ErrTransportDisabled reports that JSON-RPC transport methods were called on a raw-process launch. ErrTransportDisabled = errors.New("subprocess: transport disabled") )
var ErrTransportClosedBeforeResponse = errors.New("subprocess: transport closed before response")
ErrTransportClosedBeforeResponse reports a subprocess transport that closed while an RPC call was still waiting for its response.
Functions ¶
func BridgeRuntimePurposeValues ¶
func BridgeRuntimePurposeValues() []string
BridgeRuntimePurposeValues returns the closed launch-purpose family in stable order.
func HealthFailureDetected ¶
func HealthFailureDetected(state HealthState) bool
HealthFailureDetected reports whether a snapshot contains an observed failed verdict. A zero-value snapshot is unsupported or not yet checked and does not degrade consumers.
func HealthFailureReason ¶
func HealthFailureReason(state HealthState) string
HealthFailureReason returns the human-readable reason carried by a failed snapshot.
Types ¶
type AcceptedCapabilities ¶
type AcceptedCapabilities struct {
Provides []string `json:"provides"`
Permissions []extensionprotocol.HostAPIMethod `json:"permissions"`
}
AcceptedCapabilities is the subset the extension accepted for this session.
type BridgeRuntimePurpose ¶
type BridgeRuntimePurpose string
BridgeRuntimePurpose separates supervised service runtimes from isolated control calls.
const ( BridgeRuntimePurposeService BridgeRuntimePurpose = "service" BridgeRuntimePurposeControl BridgeRuntimePurpose = "control" )
type HandlerFunc ¶
HandlerFunc handles one inbound JSON-RPC request.
type HealthCheckResponse ¶
type HealthCheckResponse struct {
Healthy bool `json:"healthy"`
Message string `json:"message,omitempty"`
Details json.RawMessage `json:"details,omitempty"`
}
HealthCheckResponse is the structured result of the health_check RPC.
type HealthState ¶
type HealthState struct {
Healthy bool
Message string
Details json.RawMessage
LastCheckedAt time.Time
ConsecutiveFailures int
LastError string
}
HealthState captures the current health-monitor snapshot for the subprocess.
func CloneHealthState ¶
func CloneHealthState(state HealthState) HealthState
CloneHealthState returns an immutable copy of a subprocess health snapshot.
type InitializeBridgeBoundSecret ¶
type InitializeBridgeBoundSecret struct {
BindingName string `json:"binding_name"`
Kind string `json:"kind"`
Value string `json:"value"`
}
InitializeBridgeBoundSecret is one launch-time bridge secret resolved by Compozy.
func (InitializeBridgeBoundSecret) Validate ¶
func (s InitializeBridgeBoundSecret) Validate() error
Validate checks that the bound secret payload is complete.
type InitializeBridgeManagedInstance ¶
type InitializeBridgeManagedInstance struct {
Instance bridges.BridgeInstance `json:"instance"`
BoundSecrets []InitializeBridgeBoundSecret `json:"bound_secrets,omitempty"`
}
InitializeBridgeManagedInstance is one daemon-owned bridge instance snapshot granted to the provider runtime together with its resolved secret bindings.
func (InitializeBridgeManagedInstance) Validate ¶
func (m InitializeBridgeManagedInstance) Validate() error
Validate checks that the managed instance payload is complete and internally consistent.
type InitializeBridgeRuntime ¶
type InitializeBridgeRuntime struct {
RuntimeVersion string `json:"runtime_version"`
Purpose BridgeRuntimePurpose `json:"purpose"`
Provider string `json:"provider"`
Platform string `json:"platform"`
AllowedMethods []string `json:"allowed_methods,omitempty"`
ManagedInstances []InitializeBridgeManagedInstance `json:"managed_instances,omitempty"`
}
InitializeBridgeRuntime carries the provider-scoped bridge launch material granted to one bridge-capable extension session.
func CloneInitializeBridgeRuntime ¶
func CloneInitializeBridgeRuntime(src *InitializeBridgeRuntime) *InitializeBridgeRuntime
CloneInitializeBridgeRuntime returns a deep copy safe to retain in manager state.
func (InitializeBridgeRuntime) ManagedBridgeInstanceIDs ¶
func (r InitializeBridgeRuntime) ManagedBridgeInstanceIDs() []string
ManagedBridgeInstanceIDs returns the provider-owned bridge instance ids in a stable order suitable for telemetry fan-out and restart bookkeeping.
func (InitializeBridgeRuntime) ManagedInstance ¶
func (r InitializeBridgeRuntime) ManagedInstance(id string) (*InitializeBridgeManagedInstance, bool)
ManagedInstance returns one managed bridge instance snapshot by id.
func (InitializeBridgeRuntime) SingleManagedInstance ¶
func (r InitializeBridgeRuntime) SingleManagedInstance() (*InitializeBridgeManagedInstance, error)
SingleManagedInstance returns the only managed bridge instance snapshot in the provider runtime. It fails when the runtime owns zero or multiple instances and the caller did not select one explicitly.
func (InitializeBridgeRuntime) Validate ¶
func (r InitializeBridgeRuntime) Validate() error
Validate checks that a v2 purpose-scoped bridge launch payload is internally consistent.
type InitializeCapabilities ¶
type InitializeCapabilities struct {
Provides []string `json:"provides"`
GrantedPermissions []extensionprotocol.HostAPIMethod `json:"granted_permissions"`
GrantedResourceKinds []string `json:"granted_resource_kinds"`
GrantedResourceScopes []string `json:"granted_resource_scopes"`
}
InitializeCapabilities carries runtime-granted capabilities.
type InitializeExtension ¶
type InitializeExtension struct {
Name string `json:"name"`
Version string `json:"version"`
SourceTier string `json:"source_tier"`
}
InitializeExtension identifies the launched extension.
type InitializeExtensionInfo ¶
type InitializeExtensionInfo struct {
Name string `json:"name"`
Version string `json:"version"`
SDKName string `json:"sdk_name,omitempty"`
SDKVersion string `json:"sdk_version,omitempty"`
}
InitializeExtensionInfo identifies the running extension implementation.
type InitializeMethods ¶
type InitializeMethods struct {
DaemonRequests []string `json:"daemon_requests"`
ExtensionServices []string `json:"extension_services"`
}
InitializeMethods lists callable method families for the session.
type InitializeRequest ¶
type InitializeRequest struct {
ProtocolVersion string `json:"protocol_version"`
SupportedProtocolVersion []string `json:"supported_protocol_versions"`
CompozyVersion string `json:"compozy_version"`
SessionNonce string `json:"session_nonce"`
Extension InitializeExtension `json:"extension"`
Capabilities InitializeCapabilities `json:"capabilities"`
Methods InitializeMethods `json:"methods"`
Runtime InitializeRuntime `json:"runtime"`
}
InitializeRequest is the Compozy -> extension session contract request.
func CloneInitializeRequest ¶
func CloneInitializeRequest(src InitializeRequest) InitializeRequest
CloneInitializeRequest returns a deep copy safe to expose to callers.
func (InitializeRequest) Validate ¶
func (r InitializeRequest) Validate() error
Validate checks that the initialize request carries the mandatory contract fields.
type InitializeResponse ¶
type InitializeResponse struct {
ProtocolVersion string `json:"protocol_version"`
ExtensionInfo InitializeExtensionInfo `json:"extension_info"`
AcceptedCapabilities AcceptedCapabilities `json:"accepted_capabilities"`
ImplementedMethods []string `json:"implemented_methods"`
SupportedHookEvents []string `json:"supported_hook_events"`
WatchSourceKinds []string `json:"watch_source_kinds,omitempty"`
Supports InitializeSupports `json:"supports"`
}
InitializeResponse is the extension -> Compozy initialize acknowledgment.
type InitializeRuntime ¶
type InitializeRuntime struct {
HealthCheckIntervalMS int64 `json:"health_check_interval_ms"`
HealthCheckTimeoutMS int64 `json:"health_check_timeout_ms"`
ShutdownTimeoutMS int64 `json:"shutdown_timeout_ms"`
DefaultHookTimeoutMS int64 `json:"default_hook_timeout_ms"`
Bridge *InitializeBridgeRuntime `json:"bridge,omitempty"`
}
InitializeRuntime carries runtime intervals and deadlines negotiated during initialize.
type InitializeSupports ¶
type InitializeSupports struct {
HealthCheck bool `json:"health_check"`
}
InitializeSupports advertises optional protocol features.
type LaunchConfig ¶
type LaunchConfig struct {
Command string
Args []string
Dir string
Env []string
Logger *slog.Logger
// StderrSink receives stderr only after StderrTransform has scrubbed it.
StderrSink io.Writer
// StderrTransform scrubs complete stderr records before diagnostic capture or forwarding.
StderrTransform func(string) string
// DisableTransport leaves stdout unread so callers like ACP can attach their own protocol layer.
DisableTransport bool
// MaxMessageBytes bounds a single encoded JSON-RPC frame when transport is enabled.
MaxMessageBytes int
// ShutdownTimeout bounds the cooperative shutdown wait before signal escalation.
ShutdownTimeout time.Duration
// PostSignalGrace bounds the wait between SIGTERM and SIGKILL escalation.
PostSignalGrace time.Duration
// ShutdownReason is sent as the shutdown RPC reason when transport is enabled.
ShutdownReason string
// HealthFailureThreshold overrides the consecutive probe failures needed to mark the process unhealthy.
HealthFailureThreshold int
// ProcessRegistry checkpoints ownership for long-running subprocesses.
ProcessRegistry *toolruntime.Registry
ProcessRecord toolruntime.RegisterConfig
}
LaunchConfig configures a managed subprocess.
type Process ¶
type Process struct {
// contains filtered or unexported fields
}
Process manages one subprocess and its optional JSON-RPC transport.
func Launch ¶
func Launch(ctx context.Context, cfg LaunchConfig) (*Process, error)
Launch starts a managed subprocess and optionally attaches the shared JSON-RPC transport.
func (*Process) Done ¶
func (p *Process) Done() <-chan struct{}
Done closes when the subprocess exits.
func (*Process) HandleMethod ¶
func (p *Process) HandleMethod(method string, handler HandlerFunc) error
HandleMethod registers an inbound JSON-RPC request handler.
func (*Process) HealthState ¶
func (p *Process) HealthState() HealthState
HealthState returns the latest health-monitor snapshot.
func (*Process) Initialize ¶
func (p *Process) Initialize(ctx context.Context, request InitializeRequest) (InitializeResponse, error)
Initialize performs the session initialize handshake and transitions the process to ready on success.
func (*Process) Shutdown ¶
Shutdown performs cooperative shutdown when transport is enabled, then escalates signals if needed.
func (*Process) Stdin ¶
func (p *Process) Stdin() io.WriteCloser
Stdin exposes the subprocess stdin writer for callers that disable the shared transport.
func (*Process) Stdout ¶
func (p *Process) Stdout() io.ReadCloser
Stdout exposes the subprocess stdout reader for callers that disable the shared transport.
type RPCError ¶
type RPCError struct {
Code int `json:"code"`
Message string `json:"message"`
Data json.RawMessage `json:"data,omitempty"`
}
RPCError models a JSON-RPC 2.0 error object.
func NewRPCError ¶
NewRPCError constructs a JSON-RPC error with optional structured data.
type ResponseDecodeError ¶
ResponseDecodeError reports that a JSON-RPC response arrived but its result could not be materialized into the caller's negotiated response type.
func (*ResponseDecodeError) Error ¶
func (e *ResponseDecodeError) Error() string
Error implements error.
func (*ResponseDecodeError) Unwrap ¶
func (e *ResponseDecodeError) Unwrap() error
Unwrap exposes the underlying JSON decode failure.
type ShutdownRequest ¶
ShutdownRequest is the cooperative drain request sent before signal escalation.
type ShutdownResponse ¶
type ShutdownResponse struct {
Acknowledged bool `json:"acknowledged"`
}
ShutdownResponse acknowledges a cooperative drain request.