patchcord

type Action interface {
	// ID is the action's stable, versioned identifier.
	ID() string
	// Description is one human-readable sentence: what this action does.
	Description() string
	// InputSchema is the JSON Schema ActionInput must match.
	InputSchema() Schema
	// OutputSchema is the JSON Schema ActionOutput will match.
	OutputSchema() Schema
	// Run executes the action. connector is nil unless the workflow step
	// that invoked this action bound a connector to it.
	Run(ctx context.Context, input ActionInput, connector *ConnectorConfig) (ActionOutput, error)
}

type ActionInput map[string]any

type ActionOutput map[string]any

type Connector struct {
	// Type is the connector type's stable, versioned identifier.
	Type string
	// Description is one human-readable sentence: what system this
	// connector reaches.
	Description string
	// ConfigSchema is the JSON Schema of this connector's non-secret
	// configuration. Never describe secret fields here — a connector's
	// secrets never appear in a schema meant to be shown or stored
	// (ADR-0009).
	ConfigSchema Schema
}

type ConnectorConfig struct {
	Type    string
	Config  map[string]any
	Secrets map[string]any
}

type ConnectorTester interface {
	// TestConnector attempts to reach the external system connector
	// describes. A returned error means the attempt failed (e.g. wrong
	// password, host unreachable) — a legitimate, expected outcome, not a
	// sign the plugin itself is broken. err's message is what the caller
	// sees; never include a secret value in it.
	TestConnector(ctx context.Context, connector ConnectorConfig) error
}

type Manifest struct {
	ID      string
	Version string
}

type Plugin struct {
	Manifest   Manifest
	Actions    []Action
	Connectors []Connector
	// Tester, if set, lets this plugin's connector(s) be checked with
	// `patchcord connector test` without running a full action.
	Tester ConnectorTester
	// Permissions this plugin requires from the agent, e.g.
	// "network.outbound". Declarative only in this version: the agent does
	// not yet enforce them.
	Permissions []string
}

type Schema map[string]any