adaptersdk

package
v1.5.11 Latest Latest
Warning

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

 Go to latest Published: Aug 20, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package adaptersdk provides a lightweight SDK for building deploy adapters. It exposes a JSON-RPC 2.0 server over stdio so that adapter authors can implement the deploy.Provider interface and call Serve() to run.

Index

Constants

View Source 
const (
	MethodGetProviderInfo = "get_provider_info"
	MethodValidateConfig  = "validate_config"
	MethodPlan            = "plan"
	MethodApply           = "apply"
	MethodDestroy         = "destroy"
	MethodStatus          = "status"
	MethodImport          = "import"
	MethodGetLoginURL     = "get_login_url"
	MethodCompleteLogin   = "complete_login"
)

JSON-RPC method names recognized by the adapter protocol.

View Source 
const (
	CodeParseError     = -32700
	CodeInvalidRequest = -32600
	CodeMethodNotFound = -32601
	CodeInternalError  = -32603
)

Standard JSON-RPC 2.0 error codes.

Variables

This section is empty.

Functions 

func ConsoleLink(url string) []deploy.ResourceLink

ConsoleLink builds the conventional "Console" link for a deployed resource. It is a convenience over constructing deploy.ResourceLink directly, so the common case reads the same across adapters.

It returns nil when url is empty, which is the intended way to express "the console URL is not known". Callers can append the result unconditionally: 

result.Links = append(result.Links, adaptersdk.ConsoleLink(consoleURL)...)

An adapter must never substitute a guessed URL for an unknown one — a link that 404s or lands on the wrong workspace is worse than no link at all.

func GenerateAgentCards 

func GenerateAgentCards(pack *prompt.Pack) map[string]*a2a.AgentCard

GenerateAgentCards re-exports agentcard.GenerateAgentCards for adapter convenience.

func GenerateAgentResourcePlan 

func GenerateAgentResourcePlan(pack *prompt.Pack) []deploy.ResourceChange

GenerateAgentResourcePlan creates resource changes for deploying a multi-agent pack. For each member it emits an agent_runtime and a2a_endpoint resource. For the entry agent it also emits a gateway resource. Returns nil if the pack is not multi-agent.

func GenerateToolGatewayPlan 

func GenerateToolGatewayPlan(tools []ToolInfo, targets ToolTargetMap) []deploy.ResourceChange

GenerateToolGatewayPlan creates resource changes for tools that have target mappings.

func IsMultiAgent 

func IsMultiAgent(pack *prompt.Pack) bool

IsMultiAgent returns true if the pack has an agents section with members. 

func Link(label, url, rel string) []deploy.ResourceLink

Link builds a single-element ResourceLink slice, or nil when url is empty. The nil-on-empty behavior is what makes "no link" the safe default at every call site rather than something each adapter has to remember to check.

func ParsePack 

func ParsePack(packJSON []byte) (*prompt.Pack, error)

ParsePack deserializes a .pack.json byte slice into a prompt.Pack struct.

func Serve 

func Serve(provider deploy.Provider) error

Serve reads JSON-RPC requests from stdin, dispatches them to the given deploy.Provider, and writes responses to stdout. It runs until stdin is closed or an unrecoverable I/O error occurs.

func ServeIO 

func ServeIO(
	provider deploy.Provider,
	r io.Reader,
	w io.Writer,
) error

ServeIO is like Serve but reads from r and writes to w, allowing tests to substitute stdin/stdout. If r or w is nil the function returns an error.

func SummarizeChanges 

func SummarizeChanges(changes []deploy.ResourceChange) string

SummarizeChanges generates a human-readable summary of resource changes. Example: "3 to create, 1 to update, 1 to delete"

Types

type AgentInfo 

type AgentInfo struct {
	Name        string   `json:"name"`
	Description string   `json:"description"`
	IsEntry     bool     `json:"is_entry"`
	Tags        []string `json:"tags,omitempty"`
	InputModes  []string `json:"input_modes"`
	OutputModes []string `json:"output_modes"`
}

AgentInfo provides a simplified view of an agent member for deploy adapters.

func ExtractAgents 

func ExtractAgents(pack *prompt.Pack) []AgentInfo

ExtractAgents returns agent info for all members in the pack's agents section. Returns nil if the pack is not multi-agent. Defaults: text/plain for missing input/output modes, description falls back to the corresponding prompt description.

type Existence added in v1.5.11 

type Existence int

Existence is what a probe could determine about a resource.

Unknown is the zero value on purpose: a probe that fails to answer, or a caller that forgets to set one, must land on the conservative outcome rather than on "absent". 

const (
	// ExistsUnknown means the lookup could not determine the answer. It is not
	// evidence of absence.
	ExistsUnknown Existence = iota
	// ExistsYes means the resource is present. It says nothing about health:
	// a degraded resource still exists, so it is an update, not a recreate.
	ExistsYes
	// ExistsNo means the resource is confirmed gone.
	ExistsNo
)

type ProgressReporter 

type ProgressReporter struct {
	// contains filtered or unexported fields
}

ProgressReporter wraps a deploy.ApplyCallback and provides convenient methods for emitting progress, resource, and error events.

func NewProgressReporter 

func NewProgressReporter(callback deploy.ApplyCallback) *ProgressReporter

NewProgressReporter creates a ProgressReporter that sends events through the given ApplyCallback.

func (*ProgressReporter) Error 

func (pr *ProgressReporter) Error(err error) error

Error emits an error event.

func (*ProgressReporter) Progress 

func (pr *ProgressReporter) Progress(message string, pct float64) error

Progress emits a progress event with a human-readable message and a completion percentage (0.0 to 1.0).

func (*ProgressReporter) Resource 

func (pr *ProgressReporter) Resource(result *deploy.ResourceResult) error

Resource emits a resource result event.

type ResourcePlan 

type ResourcePlan struct {
	Changes []deploy.ResourceChange
	Tools   []ToolInfo
	Targets ToolTargetMap
	Policy  *ToolPolicyInfo
}

ResourcePlan holds the combined plan result.

func GenerateResourcePlan 

func GenerateResourcePlan(packJSON, arenaConfigJSON, deployConfigJSON string) (*ResourcePlan, error)

GenerateResourcePlan builds a combined resource plan from PlanRequest fields. It extracts agent resources from the pack, tool resources from ArenaConfig, filters by tool policy blocklist, and matches tools against deploy targets. Adapters can call this directly from their Plan() method for a complete plan, or use the individual functions for custom logic.

type ResourceProbe added in v1.5.11 

type ResourceProbe interface {
	Exists(ctx context.Context, ref ResourceRef) (Existence, error)
}

ResourceProbe answers whether a previously-deployed resource still exists.

Adapters implement this against their own API; everything else about drift reconciliation is shared. Returning an error is equivalent to answering ExistsUnknown — the error is kept for the message, not for the decision.

type ResourceRef added in v1.5.11 

type ResourceRef struct {
	Type string `json:"type"`
	Name string `json:"name"`
	ID   string `json:"id,omitempty"`
}

ResourceRef identifies a resource recorded in prior state.

Type and Name mirror deploy.ResourceChange so a dropped resource can be reported without translation. ID carries the provider's own identifier when the adapter stored one — often the only handle a lookup can use.

func ReconcilePriorState added in v1.5.11 

func ReconcilePriorState(
	ctx context.Context, probe ResourceProbe, refs []ResourceRef,
) (kept []ResourceRef, drift []deploy.ResourceChange)

ReconcilePriorState drops resources that no longer exist and reports them as drift.

A plan built from a stored state blob alone cannot see changes made outside promptarena: delete a resource in the cloud console and the adapter plans an UPDATE against something that is gone, which then fails at apply. Probing prior state against the live provider is what closes that gap.

Three rules, and the third is the one worth sharing:

  • confirmed absent → drop, and report drift
  • present, however degraded → keep; it exists, so it is an update
  • lookup failed or unknown → keep

The last is easy to get backwards and expensive when wrong. Dropping a resource because the lookup errored plans a CREATE that collides with the live resource at apply time — turning a transient API error into a hard failure, or worse, a duplicate. Vertex makes this concrete: a malformed resource name returns InvalidArgument, not NotFound, so any "not found means absent" shortcut that treats every error alike deletes real state.

A nil probe keeps everything: an adapter that cannot look up resources has no basis to drop them, and silently dropping would turn every plan into a full recreate.

type ToolInfo 

type ToolInfo struct {
	Name        string      `json:"name"`
	Description string      `json:"description"`
	Mode        string      `json:"mode"` // "mock", "live", "mcp", "a2a"
	HasSchema   bool        `json:"has_schema"`
	InputSchema interface{} `json:"input_schema,omitempty"`
	HTTPURL     string      `json:"http_url,omitempty"`
	HTTPMethod  string      `json:"http_method,omitempty"`
}

ToolInfo holds tool metadata extracted from ArenaConfig for deploy planning.

func ExtractToolInfo 

func ExtractToolInfo(arenaConfigJSON string) ([]ToolInfo, error)

ExtractToolInfo parses an ArenaConfig JSON string and returns tool info for deploy planning. It reads from both inline ToolSpecs and loaded tool data.

func FilterBlocklistedTools 

func FilterBlocklistedTools(tools []ToolInfo, policy *ToolPolicyInfo) []ToolInfo

FilterBlocklistedTools removes tools whose names appear in the policy blocklist.

type ToolPolicyInfo 

type ToolPolicyInfo struct {
	Blocklist []string `json:"blocklist,omitempty"`
}

ToolPolicyInfo holds tool policy from scenarios for deploy planning.

func ExtractToolPolicies 

func ExtractToolPolicies(arenaConfigJSON string) (*ToolPolicyInfo, error)

ExtractToolPolicies returns a merged ToolPolicyInfo from all scenarios in the ArenaConfig.

type ToolTargetMap 

type ToolTargetMap map[string]json.RawMessage

ToolTargetMap is an opaque map of tool name → adapter-specific target config. Each adapter defines its own target schema; the SDK only tracks which tools have targets.

func ParseDeployToolTargets 

func ParseDeployToolTargets(deployConfigJSON string) (ToolTargetMap, error)

ParseDeployToolTargets extracts the tool_targets map from the opaque deploy config JSON. Returns raw JSON per tool so each adapter can unmarshal into its own target type.

Source Files

View all Source files

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.