extension

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 30, 2026 License: MIT Imports: 16 Imported by: 0

README

Productize Extension SDK for Go

Package extension provides the public Go SDK for building Productize executable extensions.

An executable extension runs as a subprocess alongside Productize 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.

Install

go get github.com/itseffi/productize/sdk/extension

Quick start

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/itseffi/productize/sdk/extension"
)

func main() {
	ext := extension.New("hello-ext", "0.1.0").
		OnRunPostShutdown(func(ctx context.Context, hook extension.HookContext, payload extension.RunPostShutdownPayload) error {
			fmt.Fprintf(os.Stderr, "run %s finished with %s\n", payload.RunID, payload.Summary.Status)
			return nil
		})

	if err := ext.Start(context.Background()); err != nil {
		log.Fatal(err)
	}
}

Public surface

  • Extension manages initialize, hook dispatch, event delivery, health checks, and shutdown.
  • HostAPI exposes typed clients for host.events.*, host.tasks.*, host.runs.*, host.artifacts.*, host.prompts.render, and host.memory.*.
  • 29 typed hook registration methods (OnPlanPreDiscover through OnArtifactPostWrite) with strongly-typed payload and patch parameters.
  • Constants for all 19 capabilities, 28 hook names, execution modes, and output formats.
  • Protocol version 1.

Capabilities

Extensions declare the capabilities they require. The host grants or denies each capability during initialization. Common capabilities:

Capability Grants
events.read Subscribe to and receive forwarded events
plan.mutate Register plan.* hooks
prompt.mutate Register prompt.* hooks
run.mutate Register run.* hooks
artifacts.read / artifacts.write Read or write workspace artifacts via Host API
tasks.read / tasks.create List, get, or create tasks via Host API
memory.read / memory.write Read or write workflow memory via Host API

Testing

go get github.com/itseffi/productize/sdk/extension/testing

The exttesting package provides TestHarness and MockTransport for in-process SDK tests without a running Productize instance.

package myext_test

import (
	"context"
	"testing"

	"github.com/itseffi/productize/sdk/extension"
	exttesting "github.com/itseffi/productize/sdk/extension/testing"
)

func TestExtension(t *testing.T) {
	harness := exttesting.NewTestHarness(exttesting.HarnessOptions{
		GrantedCapabilities: []extension.Capability{extension.CapabilityRunMutate},
	})

	ext := extension.New("my-ext", "0.1.0").
		OnRunPostShutdown(func(ctx context.Context, hook extension.HookContext, payload extension.RunPostShutdownPayload) error {
			return nil
		})

	ctx := context.Background()
	errCh := harness.Run(ctx, ext)
	_, err := harness.Initialize(ctx, extension.InitializeRequestIdentity{
		Name: "my-ext", Version: "0.1.0", Source: "workspace",
	})
	if err != nil {
		t.Fatal(err)
	}
	if err := harness.Shutdown(ctx, extension.ShutdownRequest{Reason: "test"}); err != nil {
		t.Fatal(err)
	}
	if err := <-errCh; err != nil {
		t.Fatal(err)
	}
}

Documentation

Documentation

Overview

Package extension provides the public Go SDK for Productize executable extensions.

An executable extension runs as a subprocess alongside Productize 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/itseffi/productize/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

View Source 
const (

	// MaxMessageSize bounds one encoded JSON-RPC message.
	MaxMessageSize = 10 * 1024 * 1024
)
View Source 
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.

func Ptr 

func Ptr[T any](value T) *T

Ptr returns a pointer to value.

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 

type ArtifactReadResult struct {
	Path    string `json:"path"`
	Content []byte `json:"content"`
}

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 

type ArtifactWriteRequest struct {
	Path    string `json:"path"`
	Content []byte `json:"content"`
}

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 

func (e *Error) DecodeData(target any) error

DecodeData unmarshals the structured error data into target.

func (*Error) Error 

func (e *Error) Error() string

Error returns a stable human-readable message.

type Event 

type Event = events.Event

Event is the public Productize event envelope forwarded to extensions.

type EventHandler 

type EventHandler func(context.Context, Event) error

EventHandler handles one forwarded Productize event.

type EventKind 

type EventKind = events.EventKind

EventKind identifies one forwarded bus event kind.

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 Productize execution mode. 

const (
	ExecutionModePRReview ExecutionMode = "pr-review"
	ExecutionModePRDTasks ExecutionMode = "prd-tasks"
	ExecutionModeExec     ExecutionMode = "exec"
)

Supported execution modes.

type ExplicitRuntimeFlags 

type ExplicitRuntimeFlags struct {
	IDE             bool
	Model           bool
	ReasoningEffort bool
	AccessMode      bool
}

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 New 

func New(name string, version string) *Extension

New constructs a new extension runtime with the provided identity.

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) Host 

func (e *Extension) Host() *HostAPI

Host returns the Host API client bound to the current extension session.

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 

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 

func (e *Extension) OnReviewWatchFinished(
	handler func(context.Context, HookContext, ReviewWatchFinishedPayload) error,
) *Extension

OnReviewWatchFinished registers the review.watch_finished handler.

func (*Extension) OnReviewWatchPostRound 

func (e *Extension) OnReviewWatchPostRound(
	handler func(context.Context, HookContext, ReviewWatchPostRoundPayload) error,
) *Extension

OnReviewWatchPostRound registers the review.watch_post_round handler.

func (*Extension) OnReviewWatchPrePush 

func (e *Extension) OnReviewWatchPrePush(
	handler func(context.Context, HookContext, ReviewWatchPrePushPayload) (ReviewWatchPrePushPatch, error),
) *Extension

OnReviewWatchPrePush registers the review.watch_pre_push handler.

func (*Extension) OnReviewWatchPreRound 

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 

func (e *Extension) Start(ctx context.Context) error

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 

func (e *Extension) WithSDKVersion(version string) *Extension

WithSDKVersion overrides the sdk_version reported during initialize.

func (*Extension) WithTransport 

func (e *Extension) WithTransport(transport Transport) *Extension

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 

type FixOutcome struct {
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
}

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 

type HookContext struct {
	InvocationID string
	Hook         HookInfo
	Host         *HostAPI
}

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"`
	ProductizeVersion         string                    `json:"productize_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 

type IssueEntry struct {
	Name     string
	AbsPath  string
	Content  string
	CodeFile string
}

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
	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 

type JobPreExecutePayload struct {
	RunID string `json:"run_id"`
	Job   Job    `json:"job"`
}

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 

type MCPServerStdio struct {
	Name    string
	Command string
	Args    []string
	Env     map[string]string
}

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 

type MemoryWriteResult struct {
	Path         string `json:"path"`
	BytesWritten int    `json:"bytes_written"`
}

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 

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 

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 

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 

type ReviewProviderContext struct {
	Provider string
	Host     *HostAPI
}

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 

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 

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 

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 

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 

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 

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
	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"`
	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 

type RunPreShutdownPayload struct {
	RunID  string `json:"run_id"`
	Reason string `json:"reason"`
}

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
	Persist                    bool
	EnableExecutableExtensions bool
	DaemonOwned                bool
	RunID                      string
	ParentRunID                string
	PromptText                 string
	PromptFile                 string
	ReadPromptStdin            bool
	ResolvedPromptText         string
	IncludeCompleted           bool
	IncludeResolved            bool
	Timeout                    time.Duration
	MaxRetries                 int
	RetryBackoffMultiplier     float64
	SoundEnabled               bool
	SoundOnCompleted           string
	SoundOnFailed              string
}

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 

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 

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 

type ShutdownRequest struct {
	Reason     string `json:"reason"`
	DeadlineMS int64  `json:"deadline_ms"`
}

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 Supports 

type Supports struct {
	HealthCheck bool `json:"health_check"`
	OnEvent     bool `json:"on_event"`
}

Supports reports which optional base methods the extension serves.

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 

type TaskGetRequest struct {
	Workflow string `json:"workflow"`
	Number   int    `json:"number"`
}

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 

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 

type TaskRuntimePatch struct {
	Runtime *TaskRuntime `json:"runtime,omitempty"`
}

TaskRuntimePatch replaces the effective runtime for one task.

type TaskRuntimeRule 

type TaskRuntimeRule struct {
	ID              *string `json:"id,omitempty"`
	Type            *string `json:"type,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 

type TaskRuntimeTask struct {
	ID       string `json:"id,omitempty"`
	SafeName string `json:"safe_name,omitempty"`
	Title    string `json:"title,omitempty"`
	Type     string `json:"type,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.

Source Files

View all Source files

Directories

Path Synopsis
Package exttesting provides in-process test utilities for Productize extension authors.
 Package exttesting provides in-process test utilities for Productize extension authors.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.