Documentation
¶
Overview ¶
Package extension provides the public Go SDK for Compozy executable extensions.
An executable extension runs as a subprocess alongside Compozy and communicates over line-delimited JSON-RPC 2.0 on stdin/stdout. The SDK handles protocol negotiation, capability exchange, hook dispatch, event delivery, health checks, and graceful shutdown.
Quick start ¶
ext := extension.New("my-ext", "0.1.0").
OnRunPostShutdown(func(
ctx context.Context,
hook extension.HookContext,
payload extension.RunPostShutdownPayload,
) error {
fmt.Fprintf(os.Stderr, "run %s finished\n", payload.RunID)
return nil
})
if err := ext.Start(context.Background()); err != nil {
log.Fatal(err)
}
Host API ¶
After initialization, extension handlers can call back into the host through Extension.Host. The HostAPI exposes typed clients for events, tasks, runs, artifacts, prompts, and memory.
Testing ¶
Import the github.com/compozy/compozy/sdk/extension/testing package for [exttesting.TestHarness] and [exttesting.MockTransport], which simulate the host side of the protocol for in-process unit tests.
Index ¶
- Constants
- func MustJSON(value any) json.RawMessage
- func Ptr[T any](value T) *T
- type AgentOnSessionUpdatePayload
- type AgentPostSessionCreatePayload
- type AgentPostSessionEndPayload
- type AgentPreSessionCreatePayload
- type AgentPreSessionResumePayload
- type ArtifactPostWritePayload
- type ArtifactPreWritePayload
- type ArtifactReadRequest
- type ArtifactReadResult
- type ArtifactWritePatch
- type ArtifactWriteRequest
- type ArtifactWriteResult
- type ArtifactsClient
- type BatchParams
- type BatchParamsPatch
- type Capability
- type EntriesPatch
- type Error
- type Event
- type EventHandler
- type EventKind
- type EventPublishRequest
- type EventPublishResult
- type EventSubscribeRequest
- type EventSubscribeResult
- type EventsClient
- type ExecuteHookRequest
- type ExecuteHookResponse
- type ExecutionMode
- type ExplicitRuntimeFlags
- type Extension
- func (e *Extension) AcceptedCapabilities() []Capability
- func (e *Extension) Handle(event HookName, handler RawHookHandler) *Extension
- func (e *Extension) Host() *HostAPI
- func (e *Extension) InitializeRequest() (InitializeRequest, bool)
- func (e *Extension) OnAgentOnSessionUpdate(handler func(context.Context, HookContext, AgentOnSessionUpdatePayload) error) *Extension
- func (e *Extension) OnAgentPostSessionCreate(...) *Extension
- func (e *Extension) OnAgentPostSessionEnd(handler func(context.Context, HookContext, AgentPostSessionEndPayload) error) *Extension
- func (e *Extension) OnAgentPreSessionCreate(...) *Extension
- func (e *Extension) OnAgentPreSessionResume(...) *Extension
- func (e *Extension) OnArtifactPostWrite(handler func(context.Context, HookContext, ArtifactPostWritePayload) error) *Extension
- func (e *Extension) OnArtifactPreWrite(...) *Extension
- func (e *Extension) OnEvent(handler EventHandler, kinds ...EventKind) *Extension
- func (e *Extension) OnHealthCheck(handler HealthCheckHandler) *Extension
- func (e *Extension) OnJobPostExecute(handler func(context.Context, HookContext, JobPostExecutePayload) error) *Extension
- func (e *Extension) OnJobPreExecute(...) *Extension
- func (e *Extension) OnJobPreRetry(...) *Extension
- func (e *Extension) OnPlanPostDiscover(...) *Extension
- func (e *Extension) OnPlanPostGroup(...) *Extension
- func (e *Extension) OnPlanPostPrepareJobs(...) *Extension
- func (e *Extension) OnPlanPreDiscover(...) *Extension
- func (e *Extension) OnPlanPreGroup(...) *Extension
- func (e *Extension) OnPlanPrePrepareJobs(...) *Extension
- func (e *Extension) OnPlanPreResolveTaskRuntime(...) *Extension
- func (e *Extension) OnPromptPostBuild(...) *Extension
- func (e *Extension) OnPromptPreBuild(...) *Extension
- func (e *Extension) OnPromptPreSystem(...) *Extension
- func (e *Extension) OnReviewPostFetch(...) *Extension
- func (e *Extension) OnReviewPostFix(handler func(context.Context, HookContext, ReviewPostFixPayload) error) *Extension
- func (e *Extension) OnReviewPreBatch(...) *Extension
- func (e *Extension) OnReviewPreFetch(...) *Extension
- func (e *Extension) OnReviewPreResolve(...) *Extension
- func (e *Extension) OnReviewWatchFinished(handler func(context.Context, HookContext, ReviewWatchFinishedPayload) error) *Extension
- func (e *Extension) OnReviewWatchPostRound(handler func(context.Context, HookContext, ReviewWatchPostRoundPayload) error) *Extension
- func (e *Extension) OnReviewWatchPrePush(...) *Extension
- func (e *Extension) OnReviewWatchPreRound(...) *Extension
- func (e *Extension) OnRunPostShutdown(handler func(context.Context, HookContext, RunPostShutdownPayload) error) *Extension
- func (e *Extension) OnRunPostStart(handler func(context.Context, HookContext, RunPostStartPayload) error) *Extension
- func (e *Extension) OnRunPreShutdown(handler func(context.Context, HookContext, RunPreShutdownPayload) error) *Extension
- func (e *Extension) OnRunPreStart(...) *Extension
- func (e *Extension) OnShutdown(handler ShutdownHandler) *Extension
- func (e *Extension) RegisterReviewProvider(name string, handler ReviewProviderHandler) *Extension
- func (e *Extension) Start(ctx context.Context) error
- func (e *Extension) WithCapabilities(capabilities ...Capability) *Extension
- func (e *Extension) WithSDKVersion(version string) *Extension
- func (e *Extension) WithTransport(transport Transport) *Extension
- type ExtraSourcesPatch
- type FetchConfig
- type FetchConfigPatch
- type FetchRequest
- type FixOutcome
- type GroupsPatch
- type HealthCheckHandler
- type HealthCheckRequest
- type HealthCheckResponse
- type HookContext
- type HookInfo
- type HookName
- type HostAPI
- type InitializeRequest
- type InitializeRequestIdentity
- type InitializeResponse
- type InitializeResponseInfo
- type InitializeRuntime
- type IssueEntry
- type IssuesPatch
- type Job
- type JobPatch
- type JobPostExecutePayload
- type JobPreExecutePayload
- type JobPreRetryPayload
- type JobResult
- type JobsPatch
- type MCPServer
- type MCPServerStdio
- type MemoryClient
- type MemoryReadRequest
- type MemoryReadResult
- type MemoryWriteMode
- type MemoryWriteRequest
- type MemoryWriteResult
- type Message
- type OnEventRequest
- type OutputFormat
- type PlanPostDiscoverPayload
- type PlanPostGroupPayload
- type PlanPostPrepareJobsPayload
- type PlanPreDiscoverPayload
- type PlanPreGroupPayload
- type PlanPrePrepareJobsPayload
- type PlanPreResolveTaskRuntimePayload
- type PromptIssueRef
- type PromptPostBuildPayload
- type PromptPreBuildPayload
- type PromptPreSystemPayload
- type PromptRenderParams
- type PromptRenderRequest
- type PromptRenderResult
- type PromptTextPatch
- type PromptsClient
- type RawHookHandler
- type ResolveDecisionPatch
- type ResolveIssuesRequest
- type ResolvedIssue
- type ResumeSessionRequest
- type ResumeSessionRequestPatch
- type RetryDecisionPatch
- type ReviewItem
- type ReviewPostFetchPayload
- type ReviewPostFixPayload
- type ReviewPreBatchPayload
- type ReviewPreFetchPayload
- type ReviewPreResolvePayload
- type ReviewProvider
- type ReviewProviderContext
- type ReviewProviderHandler
- type ReviewWatchFinishedPayload
- type ReviewWatchPostRoundPayload
- type ReviewWatchPrePushPatch
- type ReviewWatchPrePushPayload
- type ReviewWatchPreRoundPatch
- type ReviewWatchPreRoundPayload
- type RunArtifacts
- type RunConfig
- type RunHandle
- type RunPostShutdownPayload
- type RunPostStartPayload
- type RunPreShutdownPayload
- type RunPreStartPayload
- type RunStartRequest
- type RunSummary
- type RunsClient
- type RuntimeConfig
- type RuntimeConfigPatch
- type SessionIdentity
- type SessionOutcome
- type SessionRequest
- type SessionRequestPatch
- type SessionStatus
- type SessionUpdate
- type ShutdownHandler
- type ShutdownRequest
- type ShutdownResponse
- type StdIOTransport
- type Supports
- type SystemAddendumPatch
- type Task
- type TaskCreateRequest
- type TaskFrontmatter
- type TaskGetRequest
- type TaskListRequest
- type TaskRuntime
- type TaskRuntimePatch
- type TaskRuntimeRule
- type TaskRuntimeTask
- type TasksClient
- type Transport
- type Usage
- type WorkflowMemoryContext
Constants ¶
const (
// MaxMessageSize bounds one encoded JSON-RPC message.
MaxMessageSize = 10 * 1024 * 1024
)
const ProtocolVersion = "1"
ProtocolVersion identifies the extension subprocess protocol version the SDK speaks.
Variables ¶
This section is empty.
Functions ¶
func MustJSON ¶
func MustJSON(value any) json.RawMessage
MustJSON marshals value into json.RawMessage or panics.
Types ¶
type AgentOnSessionUpdatePayload ¶
type AgentOnSessionUpdatePayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
SessionID string `json:"session_id"`
Update SessionUpdate `json:"update"`
}
AgentOnSessionUpdatePayload is delivered for agent.on_session_update.
type AgentPostSessionCreatePayload ¶
type AgentPostSessionCreatePayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
SessionID string `json:"session_id"`
Identity SessionIdentity `json:"identity"`
}
AgentPostSessionCreatePayload is delivered for agent.post_session_create.
type AgentPostSessionEndPayload ¶
type AgentPostSessionEndPayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
SessionID string `json:"session_id"`
Outcome SessionOutcome `json:"outcome"`
}
AgentPostSessionEndPayload is delivered for agent.post_session_end.
type AgentPreSessionCreatePayload ¶
type AgentPreSessionCreatePayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
SessionRequest SessionRequest `json:"session_request"`
}
AgentPreSessionCreatePayload is delivered for agent.pre_session_create.
type AgentPreSessionResumePayload ¶
type AgentPreSessionResumePayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
ResumeRequest ResumeSessionRequest `json:"resume_request"`
}
AgentPreSessionResumePayload is delivered for agent.pre_session_resume.
type ArtifactPostWritePayload ¶
type ArtifactPostWritePayload struct {
RunID string `json:"run_id"`
Path string `json:"path"`
BytesWritten int `json:"bytes_written"`
}
ArtifactPostWritePayload is delivered for artifact.post_write.
type ArtifactPreWritePayload ¶
type ArtifactPreWritePayload struct {
RunID string `json:"run_id"`
Path string `json:"path"`
ContentPreview string `json:"content_preview"`
}
ArtifactPreWritePayload is delivered for artifact.pre_write.
type ArtifactReadRequest ¶
type ArtifactReadRequest struct {
Path string `json:"path"`
}
ArtifactReadRequest reads one artifact path through the host.
type ArtifactReadResult ¶
ArtifactReadResult returns artifact content scoped by the host.
type ArtifactWritePatch ¶
type ArtifactWritePatch struct {
Path *string `json:"path,omitempty"`
Content *string `json:"content,omitempty"`
Cancel *bool `json:"cancel,omitempty"`
}
ArtifactWritePatch mutates an artifact write request.
type ArtifactWriteRequest ¶
ArtifactWriteRequest writes one artifact path through the host.
type ArtifactWriteResult ¶
type ArtifactWriteResult struct {
Path string `json:"path"`
BytesWritten int `json:"bytes_written"`
}
ArtifactWriteResult acknowledges one artifact write.
type ArtifactsClient ¶
type ArtifactsClient struct {
// contains filtered or unexported fields
}
ArtifactsClient wraps the host.artifacts namespace.
func (*ArtifactsClient) Read ¶
func (c *ArtifactsClient) Read( ctx context.Context, req ArtifactReadRequest, ) (*ArtifactReadResult, error)
Read reads one artifact path through the host.
func (*ArtifactsClient) Write ¶
func (c *ArtifactsClient) Write( ctx context.Context, req ArtifactWriteRequest, ) (*ArtifactWriteResult, error)
Write writes one artifact path through the host.
type BatchParams ¶
type BatchParams struct {
Name string `json:"name,omitempty"`
Round int `json:"round,omitempty"`
Provider string `json:"provider,omitempty"`
PR string `json:"pr,omitempty"`
ReviewsDir string `json:"reviews_dir,omitempty"`
BatchGroups map[string][]IssueEntry `json:"batch_groups,omitempty"`
AutoCommit bool `json:"auto_commit,omitempty"`
Mode ExecutionMode `json:"mode,omitempty"`
Memory *WorkflowMemoryContext `json:"memory,omitempty"`
}
BatchParams mirrors the prompt build input snapshot exposed to prompt hooks.
type BatchParamsPatch ¶
type BatchParamsPatch struct {
BatchParams *BatchParams `json:"batch_params,omitempty"`
}
BatchParamsPatch replaces prompt build parameters.
type Capability ¶
type Capability string
Capability declares one extension capability grant.
const ( CapabilityEventsRead Capability = "events.read" CapabilityEventsPublish Capability = "events.publish" CapabilityPromptMutate Capability = "prompt.mutate" CapabilityPlanMutate Capability = "plan.mutate" CapabilityAgentMutate Capability = "agent.mutate" CapabilityJobMutate Capability = "job.mutate" CapabilityRunMutate Capability = "run.mutate" CapabilityReviewMutate Capability = "review.mutate" CapabilityArtifactsRead Capability = "artifacts.read" CapabilityArtifactsWrite Capability = "artifacts.write" CapabilityTasksRead Capability = "tasks.read" CapabilityTasksCreate Capability = "tasks.create" CapabilityRunsStart Capability = "runs.start" CapabilityMemoryRead Capability = "memory.read" CapabilityMemoryWrite Capability = "memory.write" CapabilityProvidersRegister Capability = "providers.register" CapabilitySkillsShip Capability = "skills.ship" CapabilitySubprocessSpawn Capability = "subprocess.spawn" CapabilityNetworkEgress Capability = "network.egress" )
Supported capability values.
type EntriesPatch ¶
type EntriesPatch struct {
Entries *[]IssueEntry `json:"entries,omitempty"`
}
EntriesPatch replaces one issue entry slice.
type Error ¶
type Error struct {
Code int `json:"code"`
Message string `json:"message"`
Data json.RawMessage `json:"data,omitempty"`
}
Error is the public JSON-RPC error object returned by the extension or host.
func (*Error) DecodeData ¶
DecodeData unmarshals the structured error data into target.
type EventHandler ¶
EventHandler handles one forwarded Compozy event.
type EventPublishRequest ¶
type EventPublishRequest struct {
Kind string `json:"kind"`
Payload json.RawMessage `json:"payload,omitempty"`
}
EventPublishRequest publishes a custom extension event through the host.
type EventPublishResult ¶
type EventPublishResult struct {
Seq uint64 `json:"seq,omitempty"`
}
EventPublishResult reports the journal sequence assigned to a published extension event.
type EventSubscribeRequest ¶
type EventSubscribeRequest struct {
Kinds []EventKind `json:"kinds"`
}
EventSubscribeRequest narrows the forwarded event kinds for this extension.
type EventSubscribeResult ¶
type EventSubscribeResult struct {
SubscriptionID string `json:"subscription_id"`
}
EventSubscribeResult acknowledges the active event subscription filter.
type EventsClient ¶
type EventsClient struct {
// contains filtered or unexported fields
}
EventsClient wraps the host.events namespace.
func (*EventsClient) Publish ¶
func (c *EventsClient) Publish( ctx context.Context, req EventPublishRequest, ) (*EventPublishResult, error)
Publish forwards one extension event through the host event bus.
func (*EventsClient) Subscribe ¶
func (c *EventsClient) Subscribe( ctx context.Context, req EventSubscribeRequest, ) (*EventSubscribeResult, error)
Subscribe registers the current event kind filter.
type ExecuteHookRequest ¶
type ExecuteHookRequest struct {
InvocationID string `json:"invocation_id"`
Hook HookInfo `json:"hook"`
Payload json.RawMessage `json:"payload"`
}
ExecuteHookRequest is one host-originated hook invocation envelope.
type ExecuteHookResponse ¶
type ExecuteHookResponse struct {
Patch json.RawMessage `json:"patch,omitempty"`
}
ExecuteHookResponse is the hook response envelope returned to the host.
type ExecutionMode ¶
type ExecutionMode string
ExecutionMode identifies the target Compozy execution mode.
const ( ExecutionModePRReview ExecutionMode = "pr-review" ExecutionModePRDTasks ExecutionMode = "prd-tasks" ExecutionModeExec ExecutionMode = "exec" )
Supported execution modes.
type ExplicitRuntimeFlags ¶
ExplicitRuntimeFlags mirrors which runtime flags were explicitly overridden.
type Extension ¶
type Extension struct {
// contains filtered or unexported fields
}
Extension is the public Go SDK runtime used by executable extension authors.
func (*Extension) AcceptedCapabilities ¶
func (e *Extension) AcceptedCapabilities() []Capability
AcceptedCapabilities returns the negotiated capability list after initialize.
func (*Extension) Handle ¶
func (e *Extension) Handle(event HookName, handler RawHookHandler) *Extension
Handle registers a raw hook handler for one hook event.
func (*Extension) InitializeRequest ¶
func (e *Extension) InitializeRequest() (InitializeRequest, bool)
InitializeRequest returns the last initialize request processed by the extension, when available.
func (*Extension) OnAgentOnSessionUpdate ¶
func (e *Extension) OnAgentOnSessionUpdate( handler func(context.Context, HookContext, AgentOnSessionUpdatePayload) error, ) *Extension
OnAgentOnSessionUpdate registers the agent.on_session_update handler.
func (*Extension) OnAgentPostSessionCreate ¶
func (e *Extension) OnAgentPostSessionCreate( handler func(context.Context, HookContext, AgentPostSessionCreatePayload) error, ) *Extension
OnAgentPostSessionCreate registers the agent.post_session_create handler.
func (*Extension) OnAgentPostSessionEnd ¶
func (e *Extension) OnAgentPostSessionEnd( handler func(context.Context, HookContext, AgentPostSessionEndPayload) error, ) *Extension
OnAgentPostSessionEnd registers the agent.post_session_end handler.
func (*Extension) OnAgentPreSessionCreate ¶
func (e *Extension) OnAgentPreSessionCreate( handler func(context.Context, HookContext, AgentPreSessionCreatePayload) (SessionRequestPatch, error), ) *Extension
OnAgentPreSessionCreate registers the agent.pre_session_create handler.
func (*Extension) OnAgentPreSessionResume ¶
func (e *Extension) OnAgentPreSessionResume( handler func(context.Context, HookContext, AgentPreSessionResumePayload) (ResumeSessionRequestPatch, error), ) *Extension
OnAgentPreSessionResume registers the agent.pre_session_resume handler.
func (*Extension) OnArtifactPostWrite ¶
func (e *Extension) OnArtifactPostWrite( handler func(context.Context, HookContext, ArtifactPostWritePayload) error, ) *Extension
OnArtifactPostWrite registers the artifact.post_write handler.
func (*Extension) OnArtifactPreWrite ¶
func (e *Extension) OnArtifactPreWrite( handler func(context.Context, HookContext, ArtifactPreWritePayload) (ArtifactWritePatch, error), ) *Extension
OnArtifactPreWrite registers the artifact.pre_write handler.
func (*Extension) OnEvent ¶
func (e *Extension) OnEvent(handler EventHandler, kinds ...EventKind) *Extension
OnEvent registers one forwarded event handler with an optional filter.
func (*Extension) OnHealthCheck ¶
func (e *Extension) OnHealthCheck(handler HealthCheckHandler) *Extension
OnHealthCheck overrides the default healthy response.
func (*Extension) OnJobPostExecute ¶
func (e *Extension) OnJobPostExecute( handler func(context.Context, HookContext, JobPostExecutePayload) error, ) *Extension
OnJobPostExecute registers the job.post_execute handler.
func (*Extension) OnJobPreExecute ¶
func (e *Extension) OnJobPreExecute( handler func(context.Context, HookContext, JobPreExecutePayload) (JobPatch, error), ) *Extension
OnJobPreExecute registers the job.pre_execute handler.
func (*Extension) OnJobPreRetry ¶
func (e *Extension) OnJobPreRetry( handler func(context.Context, HookContext, JobPreRetryPayload) (RetryDecisionPatch, error), ) *Extension
OnJobPreRetry registers the job.pre_retry handler.
func (*Extension) OnPlanPostDiscover ¶
func (e *Extension) OnPlanPostDiscover( handler func(context.Context, HookContext, PlanPostDiscoverPayload) (EntriesPatch, error), ) *Extension
OnPlanPostDiscover registers the plan.post_discover handler.
func (*Extension) OnPlanPostGroup ¶
func (e *Extension) OnPlanPostGroup( handler func(context.Context, HookContext, PlanPostGroupPayload) (GroupsPatch, error), ) *Extension
OnPlanPostGroup registers the plan.post_group handler.
func (*Extension) OnPlanPostPrepareJobs ¶
func (e *Extension) OnPlanPostPrepareJobs( handler func(context.Context, HookContext, PlanPostPrepareJobsPayload) (JobsPatch, error), ) *Extension
OnPlanPostPrepareJobs registers the plan.post_prepare_jobs handler.
func (*Extension) OnPlanPreDiscover ¶
func (e *Extension) OnPlanPreDiscover( handler func(context.Context, HookContext, PlanPreDiscoverPayload) (ExtraSourcesPatch, error), ) *Extension
OnPlanPreDiscover registers the plan.pre_discover handler.
func (*Extension) OnPlanPreGroup ¶
func (e *Extension) OnPlanPreGroup( handler func(context.Context, HookContext, PlanPreGroupPayload) (EntriesPatch, error), ) *Extension
OnPlanPreGroup registers the plan.pre_group handler.
func (*Extension) OnPlanPrePrepareJobs ¶
func (e *Extension) OnPlanPrePrepareJobs( handler func(context.Context, HookContext, PlanPrePrepareJobsPayload) (GroupsPatch, error), ) *Extension
OnPlanPrePrepareJobs registers the plan.pre_prepare_jobs handler.
func (*Extension) OnPlanPreResolveTaskRuntime ¶ added in v0.2.0
func (e *Extension) OnPlanPreResolveTaskRuntime( handler func(context.Context, HookContext, PlanPreResolveTaskRuntimePayload) (TaskRuntimePatch, error), ) *Extension
OnPlanPreResolveTaskRuntime registers the plan.pre_resolve_task_runtime handler.
func (*Extension) OnPromptPostBuild ¶
func (e *Extension) OnPromptPostBuild( handler func(context.Context, HookContext, PromptPostBuildPayload) (PromptTextPatch, error), ) *Extension
OnPromptPostBuild registers the prompt.post_build handler.
func (*Extension) OnPromptPreBuild ¶
func (e *Extension) OnPromptPreBuild( handler func(context.Context, HookContext, PromptPreBuildPayload) (BatchParamsPatch, error), ) *Extension
OnPromptPreBuild registers the prompt.pre_build handler.
func (*Extension) OnPromptPreSystem ¶
func (e *Extension) OnPromptPreSystem( handler func(context.Context, HookContext, PromptPreSystemPayload) (SystemAddendumPatch, error), ) *Extension
OnPromptPreSystem registers the prompt.pre_system handler.
func (*Extension) OnReviewPostFetch ¶
func (e *Extension) OnReviewPostFetch( handler func(context.Context, HookContext, ReviewPostFetchPayload) (IssuesPatch, error), ) *Extension
OnReviewPostFetch registers the review.post_fetch handler.
func (*Extension) OnReviewPostFix ¶
func (e *Extension) OnReviewPostFix( handler func(context.Context, HookContext, ReviewPostFixPayload) error, ) *Extension
OnReviewPostFix registers the review.post_fix handler.
func (*Extension) OnReviewPreBatch ¶
func (e *Extension) OnReviewPreBatch( handler func(context.Context, HookContext, ReviewPreBatchPayload) (GroupsPatch, error), ) *Extension
OnReviewPreBatch registers the review.pre_batch handler.
func (*Extension) OnReviewPreFetch ¶
func (e *Extension) OnReviewPreFetch( handler func(context.Context, HookContext, ReviewPreFetchPayload) (FetchConfigPatch, error), ) *Extension
OnReviewPreFetch registers the review.pre_fetch handler.
func (*Extension) OnReviewPreResolve ¶
func (e *Extension) OnReviewPreResolve( handler func(context.Context, HookContext, ReviewPreResolvePayload) (ResolveDecisionPatch, error), ) *Extension
OnReviewPreResolve registers the review.pre_resolve handler.
func (*Extension) OnReviewWatchFinished ¶ added in v0.2.0
func (e *Extension) OnReviewWatchFinished( handler func(context.Context, HookContext, ReviewWatchFinishedPayload) error, ) *Extension
OnReviewWatchFinished registers the review.watch_finished handler.
func (*Extension) OnReviewWatchPostRound ¶ added in v0.2.0
func (e *Extension) OnReviewWatchPostRound( handler func(context.Context, HookContext, ReviewWatchPostRoundPayload) error, ) *Extension
OnReviewWatchPostRound registers the review.watch_post_round handler.
func (*Extension) OnReviewWatchPrePush ¶ added in v0.2.0
func (e *Extension) OnReviewWatchPrePush( handler func(context.Context, HookContext, ReviewWatchPrePushPayload) (ReviewWatchPrePushPatch, error), ) *Extension
OnReviewWatchPrePush registers the review.watch_pre_push handler.
func (*Extension) OnReviewWatchPreRound ¶ added in v0.2.0
func (e *Extension) OnReviewWatchPreRound( handler func(context.Context, HookContext, ReviewWatchPreRoundPayload) (ReviewWatchPreRoundPatch, error), ) *Extension
OnReviewWatchPreRound registers the review.watch_pre_round handler.
func (*Extension) OnRunPostShutdown ¶
func (e *Extension) OnRunPostShutdown( handler func(context.Context, HookContext, RunPostShutdownPayload) error, ) *Extension
OnRunPostShutdown registers the run.post_shutdown handler.
func (*Extension) OnRunPostStart ¶
func (e *Extension) OnRunPostStart( handler func(context.Context, HookContext, RunPostStartPayload) error, ) *Extension
OnRunPostStart registers the run.post_start handler.
func (*Extension) OnRunPreShutdown ¶
func (e *Extension) OnRunPreShutdown( handler func(context.Context, HookContext, RunPreShutdownPayload) error, ) *Extension
OnRunPreShutdown registers the run.pre_shutdown handler.
func (*Extension) OnRunPreStart ¶
func (e *Extension) OnRunPreStart( handler func(context.Context, HookContext, RunPreStartPayload) (RuntimeConfigPatch, error), ) *Extension
OnRunPreStart registers the run.pre_start handler.
func (*Extension) OnShutdown ¶
func (e *Extension) OnShutdown(handler ShutdownHandler) *Extension
OnShutdown overrides the default graceful shutdown behavior.
func (*Extension) RegisterReviewProvider ¶
func (e *Extension) RegisterReviewProvider(name string, handler ReviewProviderHandler) *Extension
RegisterReviewProvider registers one executable review provider handler by name.
func (*Extension) Start ¶
Start serves the extension over the configured transport until shutdown or transport termination.
func (*Extension) WithCapabilities ¶
func (e *Extension) WithCapabilities(capabilities ...Capability) *Extension
WithCapabilities declares the capabilities this extension requires.
func (*Extension) WithSDKVersion ¶
WithSDKVersion overrides the sdk_version reported during initialize.
func (*Extension) WithTransport ¶
WithTransport overrides the transport used by Start.
type ExtraSourcesPatch ¶
type ExtraSourcesPatch struct {
ExtraSources *[]string `json:"extra_sources,omitempty"`
}
ExtraSourcesPatch replaces the extra source list for plan.pre_discover.
type FetchConfig ¶
type FetchConfig struct {
ReviewsDir string `json:"reviews_dir,omitempty"`
IncludeResolved bool `json:"include_resolved,omitempty"`
}
FetchConfig mirrors the review provider fetch configuration.
type FetchConfigPatch ¶
type FetchConfigPatch struct {
FetchConfig *FetchConfig `json:"fetch_config,omitempty"`
}
FetchConfigPatch replaces the review fetch configuration.
type FetchRequest ¶
type FetchRequest struct {
PR string `json:"pr"`
IncludeNitpicks bool `json:"include_nitpicks,omitempty"`
}
FetchRequest mirrors the host-side review provider fetch request.
type FixOutcome ¶
FixOutcome mirrors the review fix result payload.
type GroupsPatch ¶
type GroupsPatch struct {
Groups *map[string][]IssueEntry `json:"groups,omitempty"`
}
GroupsPatch replaces one grouped issue map.
type HealthCheckHandler ¶
type HealthCheckHandler func(context.Context, HealthCheckRequest) (HealthCheckResponse, error)
HealthCheckHandler overrides the default health check result.
type HealthCheckRequest ¶
type HealthCheckRequest struct{}
HealthCheckRequest is the host-originated liveness probe payload.
type HealthCheckResponse ¶
type HealthCheckResponse struct {
Healthy bool `json:"healthy"`
Message string `json:"message,omitempty"`
Details map[string]any `json:"details,omitempty"`
}
HealthCheckResponse describes the extension health status.
type HookContext ¶
HookContext carries request metadata and Host API access for one handler invocation.
type HookInfo ¶
type HookInfo struct {
Name string `json:"name"`
Event HookName `json:"event"`
Mutable bool `json:"mutable"`
Required bool `json:"required"`
Priority int `json:"priority"`
TimeoutMS int64 `json:"timeout_ms"`
}
HookInfo describes the current hook invocation metadata.
type HookName ¶
type HookName string
HookName identifies one canonical extension hook event.
const ( HookPlanPreDiscover HookName = "plan.pre_discover" HookPlanPostDiscover HookName = "plan.post_discover" HookPlanPreGroup HookName = "plan.pre_group" HookPlanPostGroup HookName = "plan.post_group" HookPlanPrePrepareJobs HookName = "plan.pre_prepare_jobs" HookPlanPreResolveTaskRuntime HookName = "plan.pre_resolve_task_runtime" HookPlanPostPrepareJobs HookName = "plan.post_prepare_jobs" HookPromptPreBuild HookName = "prompt.pre_build" HookPromptPostBuild HookName = "prompt.post_build" HookPromptPreSystem HookName = "prompt.pre_system" HookAgentPreSessionCreate HookName = "agent.pre_session_create" HookAgentPostSessionCreate HookName = "agent.post_session_create" HookAgentPreSessionResume HookName = "agent.pre_session_resume" HookAgentOnSessionUpdate HookName = "agent.on_session_update" HookAgentPostSessionEnd HookName = "agent.post_session_end" HookJobPreExecute HookName = "job.pre_execute" HookJobPostExecute HookName = "job.post_execute" HookJobPreRetry HookName = "job.pre_retry" HookRunPreStart HookName = "run.pre_start" HookRunPostStart HookName = "run.post_start" HookRunPreShutdown HookName = "run.pre_shutdown" HookRunPostShutdown HookName = "run.post_shutdown" HookReviewPreFetch HookName = "review.pre_fetch" HookReviewPostFetch HookName = "review.post_fetch" HookReviewPreBatch HookName = "review.pre_batch" HookReviewPostFix HookName = "review.post_fix" HookReviewPreResolve HookName = "review.pre_resolve" HookReviewWatchPreRound HookName = "review.watch_pre_round" HookReviewWatchPostRound HookName = "review.watch_post_round" HookReviewWatchPrePush HookName = "review.watch_pre_push" HookReviewWatchFinished HookName = "review.watch_finished" HookArtifactPreWrite HookName = "artifact.pre_write" HookArtifactPostWrite HookName = "artifact.post_write" )
Supported hook names.
type HostAPI ¶
type HostAPI struct {
Events *EventsClient
Tasks *TasksClient
Runs *RunsClient
Artifacts *ArtifactsClient
Prompts *PromptsClient
Memory *MemoryClient
}
HostAPI exposes the public host callback surface available to extension handlers after initialization succeeds.
type InitializeRequest ¶
type InitializeRequest struct {
ProtocolVersion string `json:"protocol_version"`
SupportedProtocolVersions []string `json:"supported_protocol_versions"`
CompozyVersion string `json:"compozy_version"`
Extension InitializeRequestIdentity `json:"extension"`
GrantedCapabilities []Capability `json:"granted_capabilities,omitempty"`
Runtime InitializeRuntime `json:"runtime"`
}
InitializeRequest is the host-originated initialize request.
type InitializeRequestIdentity ¶
type InitializeRequestIdentity struct {
Name string `json:"name"`
Version string `json:"version"`
Source string `json:"source"`
}
InitializeRequestIdentity identifies the extension instance the host loaded.
type InitializeResponse ¶
type InitializeResponse struct {
ProtocolVersion string `json:"protocol_version"`
ExtensionInfo InitializeResponseInfo `json:"extension_info"`
AcceptedCapabilities []Capability `json:"accepted_capabilities,omitempty"`
SupportedHookEvents []HookName `json:"supported_hook_events,omitempty"`
RegisteredReviewProviders []string `json:"registered_review_providers,omitempty"`
Supports Supports `json:"supports"`
}
InitializeResponse is the extension's initialize acknowledgement.
type InitializeResponseInfo ¶
type InitializeResponseInfo struct {
Name string `json:"name,omitempty"`
Version string `json:"version,omitempty"`
SDKName string `json:"sdk_name,omitempty"`
SDKVersion string `json:"sdk_version,omitempty"`
}
InitializeResponseInfo describes the running SDK identity.
type InitializeRuntime ¶
type InitializeRuntime struct {
RunID string `json:"run_id"`
ParentRunID string `json:"parent_run_id"`
WorkspaceRoot string `json:"workspace_root"`
InvokingCommand string `json:"invoking_command"`
ShutdownTimeoutMS int64 `json:"shutdown_timeout_ms"`
DefaultHookTimeoutMS int64 `json:"default_hook_timeout_ms"`
HealthCheckIntervalMS int64 `json:"health_check_interval_ms"`
}
InitializeRuntime describes the run-scoped runtime contract.
type IssueEntry ¶
IssueEntry mirrors the issue/task entry shape used in planning hooks.
type IssuesPatch ¶
type IssuesPatch struct {
Issues *[]IssueEntry `json:"issues,omitempty"`
}
IssuesPatch replaces one review issue slice.
type Job ¶
type Job struct {
CodeFiles []string
Groups map[string][]IssueEntry
TaskNumber int
TaskTitle string
TaskType string
SafeName string
IDE string
Model string
ReasoningEffort string
Prompt []byte
SystemPrompt string
MCPServers []MCPServer
OutPromptPath string
OutLog string
ErrLog string
}
Job mirrors the planned job shape exposed to run/job hooks.
type JobPatch ¶
type JobPatch struct {
Job *Job `json:"job,omitempty"`
}
JobPatch replaces one job payload.
type JobPostExecutePayload ¶
type JobPostExecutePayload struct {
RunID string `json:"run_id"`
Job Job `json:"job"`
Result JobResult `json:"result"`
}
JobPostExecutePayload is delivered for job.post_execute.
type JobPreExecutePayload ¶
JobPreExecutePayload is delivered for job.pre_execute.
type JobPreRetryPayload ¶
type JobPreRetryPayload struct {
RunID string `json:"run_id"`
Job Job `json:"job"`
Attempt int `json:"attempt"`
LastError string `json:"last_error"`
}
JobPreRetryPayload is delivered for job.pre_retry.
type JobResult ¶
type JobResult struct {
Status string `json:"status"`
ExitCode int `json:"exit_code,omitempty"`
Attempts int `json:"attempts,omitempty"`
DurationMS int64 `json:"duration_ms,omitempty"`
Error string `json:"error,omitempty"`
}
JobResult mirrors the job execution result payload.
type JobsPatch ¶
type JobsPatch struct {
Jobs *[]Job `json:"jobs,omitempty"`
}
JobsPatch replaces one prepared job slice.
type MCPServer ¶
type MCPServer struct {
Stdio *MCPServerStdio
}
MCPServer mirrors one stdio-backed MCP server attachment.
type MCPServerStdio ¶
MCPServerStdio mirrors the stdio MCP server transport fields.
type MemoryClient ¶
type MemoryClient struct {
// contains filtered or unexported fields
}
MemoryClient wraps the host.memory namespace.
func (*MemoryClient) Read ¶
func (c *MemoryClient) Read(ctx context.Context, req MemoryReadRequest) (*MemoryReadResult, error)
Read reads one workflow or task memory document.
func (*MemoryClient) Write ¶
func (c *MemoryClient) Write( ctx context.Context, req MemoryWriteRequest, ) (*MemoryWriteResult, error)
Write writes one workflow or task memory document.
type MemoryReadRequest ¶
type MemoryReadRequest struct {
Workflow string `json:"workflow"`
TaskFile string `json:"task_file,omitempty"`
}
MemoryReadRequest reads one workflow or task memory document.
type MemoryReadResult ¶
type MemoryReadResult struct {
Path string `json:"path"`
Content string `json:"content"`
Exists bool `json:"exists"`
NeedsCompaction bool `json:"needs_compaction"`
}
MemoryReadResult returns a workflow or task memory document.
type MemoryWriteMode ¶
type MemoryWriteMode string
MemoryWriteMode identifies how a memory document write is applied.
const ( MemoryWriteModeReplace MemoryWriteMode = "replace" MemoryWriteModeAppend MemoryWriteMode = "append" )
Supported memory write modes.
type MemoryWriteRequest ¶
type MemoryWriteRequest struct {
Workflow string `json:"workflow"`
TaskFile string `json:"task_file,omitempty"`
Content string `json:"content"`
Mode MemoryWriteMode `json:"mode,omitempty"`
}
MemoryWriteRequest writes one workflow or task memory document.
type MemoryWriteResult ¶
MemoryWriteResult acknowledges one workflow or task memory write.
type Message ¶
type Message struct {
JSONRPC string `json:"jsonrpc"`
ID json.RawMessage `json:"id,omitempty"`
Method string `json:"method,omitempty"`
Params json.RawMessage `json:"params,omitempty"`
Result json.RawMessage `json:"result,omitempty"`
Error *Error `json:"error,omitempty"`
}
Message is one line-delimited JSON-RPC envelope.
type OnEventRequest ¶
type OnEventRequest struct {
Event Event `json:"event"`
}
OnEventRequest is one host-originated event delivery request.
type OutputFormat ¶
type OutputFormat string
OutputFormat identifies the requested output rendering mode.
const ( OutputFormatText OutputFormat = "text" OutputFormatJSON OutputFormat = "json" OutputFormatRawJSON OutputFormat = "raw-json" )
Supported output formats.
type PlanPostDiscoverPayload ¶
type PlanPostDiscoverPayload struct {
RunID string `json:"run_id"`
Workflow string `json:"workflow"`
Entries []IssueEntry `json:"entries,omitempty"`
}
PlanPostDiscoverPayload is delivered for plan.post_discover.
type PlanPostGroupPayload ¶
type PlanPostGroupPayload struct {
RunID string `json:"run_id"`
Groups map[string][]IssueEntry `json:"groups,omitempty"`
}
PlanPostGroupPayload is delivered for plan.post_group.
type PlanPostPrepareJobsPayload ¶
type PlanPostPrepareJobsPayload struct {
RunID string `json:"run_id"`
Jobs []Job `json:"jobs,omitempty"`
}
PlanPostPrepareJobsPayload is delivered for plan.post_prepare_jobs.
type PlanPreDiscoverPayload ¶
type PlanPreDiscoverPayload struct {
RunID string `json:"run_id"`
Workflow string `json:"workflow"`
Mode ExecutionMode `json:"mode"`
ExtraSources []string `json:"extra_sources,omitempty"`
}
PlanPreDiscoverPayload is delivered for plan.pre_discover.
type PlanPreGroupPayload ¶
type PlanPreGroupPayload struct {
RunID string `json:"run_id"`
Entries []IssueEntry `json:"entries,omitempty"`
}
PlanPreGroupPayload is delivered for plan.pre_group.
type PlanPrePrepareJobsPayload ¶
type PlanPrePrepareJobsPayload struct {
RunID string `json:"run_id"`
Groups map[string][]IssueEntry `json:"groups,omitempty"`
}
PlanPrePrepareJobsPayload is delivered for plan.pre_prepare_jobs.
type PlanPreResolveTaskRuntimePayload ¶ added in v0.2.0
type PlanPreResolveTaskRuntimePayload struct {
RunID string `json:"run_id"`
Task TaskRuntimeTask `json:"task"`
Runtime TaskRuntime `json:"runtime"`
}
PlanPreResolveTaskRuntimePayload is delivered for plan.pre_resolve_task_runtime.
type PromptIssueRef ¶
type PromptIssueRef struct {
Name string `json:"name"`
AbsPath string `json:"abs_path,omitempty"`
Content string `json:"content,omitempty"`
CodeFile string `json:"code_file,omitempty"`
}
PromptIssueRef mirrors the prompt render issue input shape.
type PromptPostBuildPayload ¶
type PromptPostBuildPayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
PromptText string `json:"prompt_text"`
BatchParams BatchParams `json:"batch_params"`
}
PromptPostBuildPayload is delivered for prompt.post_build.
type PromptPreBuildPayload ¶
type PromptPreBuildPayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
BatchParams BatchParams `json:"batch_params"`
}
PromptPreBuildPayload is delivered for prompt.pre_build.
type PromptPreSystemPayload ¶
type PromptPreSystemPayload struct {
RunID string `json:"run_id"`
JobID string `json:"job_id"`
SystemAddendum string `json:"system_addendum"`
BatchParams BatchParams `json:"batch_params"`
}
PromptPreSystemPayload is delivered for prompt.pre_system.
type PromptRenderParams ¶
type PromptRenderParams struct {
Name string `json:"name,omitempty"`
Round int `json:"round,omitempty"`
Provider string `json:"provider,omitempty"`
PR string `json:"pr,omitempty"`
ReviewsDir string `json:"reviews_dir,omitempty"`
BatchGroups map[string][]PromptIssueRef `json:"batch_groups,omitempty"`
AutoCommit bool `json:"auto_commit,omitempty"`
Mode ExecutionMode `json:"mode,omitempty"`
Memory *WorkflowMemoryContext `json:"memory,omitempty"`
}
PromptRenderParams describes the prompt render input snapshot.
type PromptRenderRequest ¶
type PromptRenderRequest struct {
Template string `json:"template"`
Params PromptRenderParams `json:"params"`
}
PromptRenderRequest renders one host-managed prompt template.
type PromptRenderResult ¶
type PromptRenderResult struct {
Rendered string `json:"rendered"`
}
PromptRenderResult returns one rendered prompt body.
type PromptTextPatch ¶
type PromptTextPatch struct {
PromptText *string `json:"prompt_text,omitempty"`
}
PromptTextPatch replaces the rendered prompt text.
type PromptsClient ¶
type PromptsClient struct {
// contains filtered or unexported fields
}
PromptsClient wraps the host.prompts namespace.
func (*PromptsClient) Render ¶
func (c *PromptsClient) Render( ctx context.Context, req PromptRenderRequest, ) (*PromptRenderResult, error)
Render renders one host-managed prompt template.
type RawHookHandler ¶
type RawHookHandler func(context.Context, HookContext, json.RawMessage) (json.RawMessage, error)
RawHookHandler handles one hook using the raw JSON payload.
type ResolveDecisionPatch ¶
type ResolveDecisionPatch struct {
Resolve *bool `json:"resolve,omitempty"`
Message *string `json:"message,omitempty"`
}
ResolveDecisionPatch controls remote issue resolution.
type ResolveIssuesRequest ¶
type ResolveIssuesRequest struct {
PR string `json:"pr"`
Issues []ResolvedIssue `json:"issues,omitempty"`
}
ResolveIssuesRequest mirrors the host-side review provider resolve request.
type ResolvedIssue ¶
type ResolvedIssue struct {
FilePath string `json:"file_path"`
ProviderRef string `json:"provider_ref,omitempty"`
}
ResolvedIssue mirrors the host-side resolved issue payload.
type ResumeSessionRequest ¶
type ResumeSessionRequest struct {
SessionID string `json:"session_id,omitempty"`
Prompt []byte `json:"prompt,omitempty"`
WorkingDir string `json:"working_dir,omitempty"`
Model string `json:"model,omitempty"`
MCPServers []MCPServer `json:"mcp_servers,omitempty"`
ExtraEnv map[string]string `json:"extra_env,omitempty"`
}
ResumeSessionRequest mirrors the mutable resume-session payload delivered to agent hooks.
func (ResumeSessionRequest) MarshalJSON ¶ added in v0.2.2
func (r ResumeSessionRequest) MarshalJSON() ([]byte, error)
MarshalJSON keeps resume prompts readable in hook payloads and patches, matching the runtime-side ACP resume request contract.
func (*ResumeSessionRequest) UnmarshalJSON ¶ added in v0.2.2
func (r *ResumeSessionRequest) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts the runtime-side readable prompt string instead of the base64 representation that encoding/json would otherwise require for []byte.
type ResumeSessionRequestPatch ¶
type ResumeSessionRequestPatch struct {
ResumeRequest *ResumeSessionRequest `json:"resume_request,omitempty"`
}
ResumeSessionRequestPatch replaces the ACP resume-session request payload.
type RetryDecisionPatch ¶
type RetryDecisionPatch struct {
Proceed *bool `json:"proceed,omitempty"`
DelayMS *int64 `json:"delay_ms,omitempty"`
}
RetryDecisionPatch controls retry continuation and delay.
type ReviewItem ¶
type ReviewItem struct {
Title string `json:"title"`
File string `json:"file"`
Line int `json:"line,omitempty"`
Severity string `json:"severity,omitempty"`
Author string `json:"author,omitempty"`
Body string `json:"body"`
ProviderRef string `json:"provider_ref,omitempty"`
ReviewHash string `json:"review_hash,omitempty"`
SourceReviewID string `json:"source_review_id,omitempty"`
SourceReviewSubmittedAt string `json:"source_review_submitted_at,omitempty"`
}
ReviewItem mirrors the host-side normalized review item shape.
type ReviewPostFetchPayload ¶
type ReviewPostFetchPayload struct {
RunID string `json:"run_id"`
PR string `json:"pr"`
Issues []IssueEntry `json:"issues,omitempty"`
}
ReviewPostFetchPayload is delivered for review.post_fetch.
type ReviewPostFixPayload ¶
type ReviewPostFixPayload struct {
RunID string `json:"run_id"`
PR string `json:"pr"`
Issue IssueEntry `json:"issue"`
Outcome FixOutcome `json:"outcome"`
}
ReviewPostFixPayload is delivered for review.post_fix.
type ReviewPreBatchPayload ¶
type ReviewPreBatchPayload struct {
RunID string `json:"run_id"`
PR string `json:"pr"`
Groups map[string][]IssueEntry `json:"groups,omitempty"`
}
ReviewPreBatchPayload is delivered for review.pre_batch.
type ReviewPreFetchPayload ¶
type ReviewPreFetchPayload struct {
RunID string `json:"run_id"`
PR string `json:"pr"`
Provider string `json:"provider"`
FetchConfig FetchConfig `json:"fetch_config"`
}
ReviewPreFetchPayload is delivered for review.pre_fetch.
type ReviewPreResolvePayload ¶
type ReviewPreResolvePayload struct {
RunID string `json:"run_id"`
PR string `json:"pr"`
Issue IssueEntry `json:"issue"`
Outcome FixOutcome `json:"outcome"`
}
ReviewPreResolvePayload is delivered for review.pre_resolve.
type ReviewProvider ¶
type ReviewProvider struct {
FetchReviewsFunc func(context.Context, ReviewProviderContext, FetchRequest) ([]ReviewItem, error)
ResolveIssuesFunc func(context.Context, ReviewProviderContext, ResolveIssuesRequest) error
}
ReviewProvider adapts plain functions to ReviewProviderHandler.
func (ReviewProvider) FetchReviews ¶
func (p ReviewProvider) FetchReviews( ctx context.Context, reviewCtx ReviewProviderContext, req FetchRequest, ) ([]ReviewItem, error)
FetchReviews implements ReviewProviderHandler.
func (ReviewProvider) ResolveIssues ¶
func (p ReviewProvider) ResolveIssues( ctx context.Context, reviewCtx ReviewProviderContext, req ResolveIssuesRequest, ) error
ResolveIssues implements ReviewProviderHandler.
type ReviewProviderContext ¶
ReviewProviderContext carries provider-local metadata and Host API access.
type ReviewProviderHandler ¶
type ReviewProviderHandler interface {
FetchReviews(context.Context, ReviewProviderContext, FetchRequest) ([]ReviewItem, error)
ResolveIssues(context.Context, ReviewProviderContext, ResolveIssuesRequest) error
}
ReviewProviderHandler serves one registered executable review provider.
type ReviewWatchFinishedPayload ¶ added in v0.2.0
type ReviewWatchFinishedPayload struct {
RunID string `json:"run_id"`
ChildRunID string `json:"child_run_id,omitempty"`
Provider string `json:"provider"`
PR string `json:"pr"`
Workflow string `json:"workflow"`
Round int `json:"round,omitempty"`
HeadSHA string `json:"head_sha,omitempty"`
Status string `json:"status"`
TerminalReason string `json:"terminal_reason,omitempty"`
Stopped bool `json:"stopped,omitempty"`
Clean bool `json:"clean,omitempty"`
MaxRounds bool `json:"max_rounds,omitempty"`
Error string `json:"error,omitempty"`
}
ReviewWatchFinishedPayload is delivered for review.watch_finished.
type ReviewWatchPostRoundPayload ¶ added in v0.2.0
type ReviewWatchPostRoundPayload struct {
RunID string `json:"run_id"`
Provider string `json:"provider"`
PR string `json:"pr"`
Workflow string `json:"workflow"`
Round int `json:"round"`
HeadSHA string `json:"head_sha,omitempty"`
ChildRunID string `json:"child_run_id,omitempty"`
Status string `json:"status,omitempty"`
Remote string `json:"remote,omitempty"`
Branch string `json:"branch,omitempty"`
Total int `json:"total,omitempty"`
Resolved int `json:"resolved,omitempty"`
Unresolved int `json:"unresolved,omitempty"`
Pushed bool `json:"pushed,omitempty"`
StopReason string `json:"stop_reason,omitempty"`
Error string `json:"error,omitempty"`
}
ReviewWatchPostRoundPayload is delivered for review.watch_post_round.
type ReviewWatchPrePushPatch ¶ added in v0.2.0
type ReviewWatchPrePushPatch struct {
Remote *string `json:"remote,omitempty"`
Branch *string `json:"branch,omitempty"`
Push *bool `json:"push,omitempty"`
StopReason *string `json:"stop_reason,omitempty"`
}
ReviewWatchPrePushPatch controls one review-watch push attempt.
type ReviewWatchPrePushPayload ¶ added in v0.2.0
type ReviewWatchPrePushPayload struct {
RunID string `json:"run_id"`
Provider string `json:"provider"`
PR string `json:"pr"`
Workflow string `json:"workflow"`
Round int `json:"round"`
HeadSHA string `json:"head_sha"`
Remote string `json:"remote"`
Branch string `json:"branch"`
Push bool `json:"push"`
StopReason string `json:"stop_reason,omitempty"`
}
ReviewWatchPrePushPayload is delivered for review.watch_pre_push.
type ReviewWatchPreRoundPatch ¶ added in v0.2.0
type ReviewWatchPreRoundPatch struct {
Nitpicks *bool `json:"nitpicks,omitempty"`
RuntimeOverrides *json.RawMessage `json:"runtime_overrides,omitempty"`
Batching *json.RawMessage `json:"batching,omitempty"`
Continue *bool `json:"continue,omitempty"`
StopReason *string `json:"stop_reason,omitempty"`
}
ReviewWatchPreRoundPatch controls one review-watch round before fetch/fix.
type ReviewWatchPreRoundPayload ¶ added in v0.2.0
type ReviewWatchPreRoundPayload struct {
RunID string `json:"run_id"`
Provider string `json:"provider"`
PR string `json:"pr"`
Workflow string `json:"workflow"`
Round int `json:"round"`
HeadSHA string `json:"head_sha"`
ReviewID string `json:"review_id,omitempty"`
ReviewState string `json:"review_state,omitempty"`
Status string `json:"status,omitempty"`
Nitpicks bool `json:"nitpicks"`
RuntimeOverrides json.RawMessage `json:"runtime_overrides,omitempty"`
Batching json.RawMessage `json:"batching,omitempty"`
Continue bool `json:"continue"`
StopReason string `json:"stop_reason,omitempty"`
}
ReviewWatchPreRoundPayload is delivered for review.watch_pre_round.
type RunArtifacts ¶
type RunArtifacts struct {
RunID string
RunDir string
RunDBPath string
RunMetaPath string
EventsPath string
TurnsDir string
JobsDir string
RecoveryDir string
ResultPath string
}
RunArtifacts mirrors the run artifact directory layout exposed to run hooks.
type RunConfig ¶
type RunConfig struct {
WorkspaceRoot string `json:"workspace_root,omitempty"`
Name string `json:"name,omitempty"`
Round int `json:"round,omitempty"`
Provider string `json:"provider,omitempty"`
PR string `json:"pr,omitempty"`
ReviewsDir string `json:"reviews_dir,omitempty"`
TasksDir string `json:"tasks_dir,omitempty"`
AutoCommit bool `json:"auto_commit,omitempty"`
Concurrent int `json:"concurrent,omitempty"`
BatchSize int `json:"batch_size,omitempty"`
IDE string `json:"ide,omitempty"`
Model string `json:"model,omitempty"`
AddDirs []string `json:"add_dirs,omitempty"`
TailLines int `json:"tail_lines,omitempty"`
ReasoningEffort string `json:"reasoning_effort,omitempty"`
AccessMode string `json:"access_mode,omitempty"`
Mode ExecutionMode `json:"mode,omitempty"`
OutputFormat OutputFormat `json:"output_format,omitempty"`
Verbose bool `json:"verbose,omitempty"`
TUI bool `json:"tui,omitempty"`
Persist bool `json:"persist,omitempty"`
RunID string `json:"run_id,omitempty"`
PromptText string `json:"prompt_text,omitempty"`
PromptFile string `json:"prompt_file,omitempty"`
ReadPromptStdin bool `json:"read_prompt_stdin,omitempty"`
IncludeCompleted bool `json:"include_completed,omitempty"`
IncludeResolved bool `json:"include_resolved,omitempty"`
TimeoutMS int64 `json:"timeout_ms,omitempty"`
MaxRetries int `json:"max_retries,omitempty"`
RetryBackoffMultiplier float64 `json:"retry_backoff_multiplier,omitempty"`
}
RunConfig is the Host API run-start payload.
type RunHandle ¶
type RunHandle struct {
RunID string `json:"run_id"`
ParentRunID string `json:"parent_run_id,omitempty"`
}
RunHandle identifies a host-started run.
type RunPostShutdownPayload ¶
type RunPostShutdownPayload struct {
RunID string `json:"run_id"`
Reason string `json:"reason"`
Summary RunSummary `json:"summary"`
}
RunPostShutdownPayload is delivered for run.post_shutdown.
type RunPostStartPayload ¶
type RunPostStartPayload struct {
RunID string `json:"run_id"`
Config RuntimeConfig `json:"config"`
}
RunPostStartPayload is delivered for run.post_start.
type RunPreShutdownPayload ¶
RunPreShutdownPayload is delivered for run.pre_shutdown.
type RunPreStartPayload ¶
type RunPreStartPayload struct {
RunID string `json:"run_id"`
Config RuntimeConfig `json:"config"`
Artifacts RunArtifacts `json:"artifacts"`
}
RunPreStartPayload is delivered for run.pre_start.
type RunStartRequest ¶
type RunStartRequest struct {
Runtime RunConfig `json:"runtime"`
}
RunStartRequest launches a new child run through the host.
type RunSummary ¶
type RunSummary struct {
Status string `json:"status"`
JobsTotal int `json:"jobs_total"`
JobsSucceeded int `json:"jobs_succeeded,omitempty"`
JobsFailed int `json:"jobs_failed,omitempty"`
JobsCanceled int `json:"jobs_canceled,omitempty"`
Error string `json:"error,omitempty"`
TeardownError string `json:"teardown_error,omitempty"`
}
RunSummary mirrors the terminal run summary payload.
type RunsClient ¶
type RunsClient struct {
// contains filtered or unexported fields
}
RunsClient wraps the host.runs namespace.
func (*RunsClient) Start ¶
func (c *RunsClient) Start(ctx context.Context, req RunStartRequest) (*RunHandle, error)
Start launches one child run through the host.
type RuntimeConfig ¶
type RuntimeConfig struct {
WorkspaceRoot string
Name string
Round int
Provider string
PR string
Nitpicks bool
ReviewsDir string
TasksDir string
DryRun bool
AutoCommit bool
Concurrent int
BatchSize int
IDE string
Model string
AddDirs []string
TailLines int
ReasoningEffort string
AccessMode string
AgentName string
ExplicitRuntime ExplicitRuntimeFlags
TaskRuntimeRules []TaskRuntimeRule
Mode ExecutionMode
OutputFormat OutputFormat
Verbose bool
TUI bool
Persist bool
EnableExecutableExtensions bool
DaemonOwned bool
RunID string
ParentRunID string
PromptText string
SystemPrompt string
TargetTaskNumber *int
PromptFile string
ReadPromptStdin bool
ResolvedPromptText string
IncludeCompleted bool
Recursive bool
RecoveryAttempt int
IncludeResolved bool
Timeout time.Duration
MaxRetries int
RetryBackoffMultiplier float64
SoundEnabled bool
SoundOnCompleted string
SoundOnFailed string
SoundOnParked string
StallEnabled *bool
StallTimeout time.Duration
ChildStallTimeout time.Duration
TerminalCommandTimeout time.Duration
StallRetries *int
}
RuntimeConfig mirrors the run configuration payload exposed to run hooks.
type RuntimeConfigPatch ¶
type RuntimeConfigPatch struct {
Config *RuntimeConfig `json:"config,omitempty"`
}
RuntimeConfigPatch replaces the run configuration payload.
type SessionIdentity ¶
type SessionIdentity struct {
ACPSessionID string `json:"acp_session_id"`
AgentSessionID string `json:"agent_session_id,omitempty"`
Resumed bool `json:"resumed,omitempty"`
}
SessionIdentity captures the stable agent session identifiers.
type SessionOutcome ¶
type SessionOutcome struct {
Status SessionStatus `json:"status"`
Error string `json:"error,omitempty"`
}
SessionOutcome mirrors the terminal session outcome payload.
type SessionRequest ¶
type SessionRequest struct {
Prompt []byte `json:"prompt,omitempty"`
WorkingDir string `json:"working_dir,omitempty"`
Model string `json:"model,omitempty"`
MCPServers []MCPServer `json:"mcp_servers,omitempty"`
ExtraEnv map[string]string `json:"extra_env,omitempty"`
}
SessionRequest mirrors the mutable create-session payload delivered to agent hooks.
func (SessionRequest) MarshalJSON ¶ added in v0.2.2
func (r SessionRequest) MarshalJSON() ([]byte, error)
MarshalJSON keeps session prompts readable in hook payloads and patches, matching the runtime-side ACP session request contract.
func (*SessionRequest) UnmarshalJSON ¶ added in v0.2.2
func (r *SessionRequest) UnmarshalJSON(data []byte) error
UnmarshalJSON accepts the runtime-side readable prompt string instead of the base64 representation that encoding/json would otherwise require for []byte.
type SessionRequestPatch ¶
type SessionRequestPatch struct {
SessionRequest *SessionRequest `json:"session_request,omitempty"`
}
SessionRequestPatch replaces the ACP create-session request payload.
type SessionStatus ¶
type SessionStatus = eventkinds.SessionStatus
SessionStatus identifies the public session terminal state.
type SessionUpdate ¶
type SessionUpdate = eventkinds.SessionUpdate
SessionUpdate is the public streamed session update shape.
type ShutdownHandler ¶
type ShutdownHandler func(context.Context, ShutdownRequest) error
ShutdownHandler overrides the default graceful shutdown behavior.
type ShutdownRequest ¶
ShutdownRequest is the host-originated graceful shutdown request.
type ShutdownResponse ¶
type ShutdownResponse struct {
Acknowledged bool `json:"acknowledged"`
}
ShutdownResponse acknowledges a graceful shutdown request.
type StdIOTransport ¶
type StdIOTransport struct {
// contains filtered or unexported fields
}
StdIOTransport implements the line-delimited subprocess transport used by executable extensions.
func NewStdIOTransport ¶
func NewStdIOTransport(reader io.Reader, writer io.Writer) *StdIOTransport
NewStdIOTransport constructs a line-delimited transport over reader/writer.
func (*StdIOTransport) Close ¶
func (t *StdIOTransport) Close() error
Close closes the underlying reader and writer when possible.
func (*StdIOTransport) ReadMessage ¶
func (t *StdIOTransport) ReadMessage() (Message, error)
ReadMessage reads the next non-empty message from the transport.
func (*StdIOTransport) WriteMessage ¶
func (t *StdIOTransport) WriteMessage(message Message) error
WriteMessage writes one JSON-RPC message with a trailing newline.
type SystemAddendumPatch ¶
type SystemAddendumPatch struct {
SystemAddendum *string `json:"system_addendum,omitempty"`
}
SystemAddendumPatch replaces the system prompt addendum.
type Task ¶
type Task struct {
Workflow string `json:"workflow"`
Number int `json:"number"`
Path string `json:"path"`
Status string `json:"status"`
Title string `json:"title,omitempty"`
Type string `json:"type,omitempty"`
Complexity string `json:"complexity,omitempty"`
Dependencies []string `json:"dependencies,omitempty"`
Body string `json:"body,omitempty"`
}
Task identifies one task document returned by the Host API.
type TaskCreateRequest ¶
type TaskCreateRequest struct {
Workflow string `json:"workflow"`
Title string `json:"title"`
Body string `json:"body"`
Frontmatter TaskFrontmatter `json:"frontmatter"`
UpdateIndex bool `json:"update_index,omitempty"`
}
TaskCreateRequest creates a new task through the host task service.
type TaskFrontmatter ¶
type TaskFrontmatter struct {
Status string `json:"status"`
Type string `json:"type"`
Complexity string `json:"complexity,omitempty"`
Dependencies []string `json:"dependencies,omitempty"`
}
TaskFrontmatter describes the task metadata written by host.tasks.create.
type TaskGetRequest ¶
TaskGetRequest fetches one task by workflow and task number.
type TaskListRequest ¶
type TaskListRequest struct {
Workflow string `json:"workflow"`
}
TaskListRequest lists tasks inside one workflow directory.
type TaskRuntime ¶ added in v0.2.0
type TaskRuntime struct {
IDE string `json:"ide,omitempty"`
Model string `json:"model,omitempty"`
ReasoningEffort string `json:"reasoning_effort,omitempty"`
}
TaskRuntime mirrors the effective runtime fields that may vary per task.
type TaskRuntimePatch ¶ added in v0.2.0
type TaskRuntimePatch struct {
Runtime *TaskRuntime `json:"runtime,omitempty"`
}
TaskRuntimePatch replaces the effective runtime for one task.
type TaskRuntimeRule ¶ added in v0.2.0
type TaskRuntimeRule struct {
ID *string `json:"id,omitempty"`
Type *string `json:"type,omitempty"`
Complexity *string `json:"complexity,omitempty"`
IDE *string `json:"ide,omitempty"`
Model *string `json:"model,omitempty"`
ReasoningEffort *string `json:"reasoning_effort,omitempty"`
}
TaskRuntimeRule mirrors one task-scoped runtime override rule.
type TaskRuntimeTask ¶ added in v0.2.0
type TaskRuntimeTask struct {
ID string `json:"id,omitempty"`
SafeName string `json:"safe_name,omitempty"`
Title string `json:"title,omitempty"`
Type string `json:"type,omitempty"`
Complexity string `json:"complexity,omitempty"`
}
TaskRuntimeTask mirrors the PRD task whose runtime is being resolved.
type TasksClient ¶
type TasksClient struct {
// contains filtered or unexported fields
}
TasksClient wraps the host.tasks namespace.
func (*TasksClient) Create ¶
func (c *TasksClient) Create(ctx context.Context, req TaskCreateRequest) (*Task, error)
Create writes one new task document through the host task service.
func (*TasksClient) Get ¶
func (c *TasksClient) Get(ctx context.Context, req TaskGetRequest) (*Task, error)
Get reads one task document by workflow and number.
func (*TasksClient) List ¶
func (c *TasksClient) List(ctx context.Context, req TaskListRequest) ([]Task, error)
List enumerates the tasks inside one workflow directory.
type Transport ¶
type Transport interface {
ReadMessage() (Message, error)
WriteMessage(Message) error
Close() error
}
Transport exchanges line-delimited JSON-RPC messages.
type Usage ¶
type Usage = eventkinds.Usage
Usage is the public usage summary shape embedded in session updates.
type WorkflowMemoryContext ¶
type WorkflowMemoryContext struct {
Directory string `json:"directory,omitempty"`
WorkflowPath string `json:"workflow_path,omitempty"`
TaskPath string `json:"task_path,omitempty"`
WorkflowNeedsCompaction bool `json:"workflow_needs_compaction,omitempty"`
TaskNeedsCompaction bool `json:"task_needs_compaction,omitempty"`
}
WorkflowMemoryContext describes the current workflow memory documents.