invoke

type Confirmation struct {
	ConfirmationRequired bool   `json:"confirmation_required"`
	Kind                 string `json:"kind"`
	Confirm              string `json:"confirm"`
	SideEffect           string `json:"side_effect"`
	Reason               string `json:"reason"`
	Plan                 any    `json:"plan"`
}

type Decision struct {
	// Kind is DecisionRun, DecisionConfirm or DecisionRefuse.
	Kind string
	// SideEffect is the effective side effect (flag escalation applied).
	SideEffect string
	// ConfirmKind is plan or request when a confirmation was asked for or
	// consumed, else empty.
	ConfirmKind string
	// Flags are the invoker-owned argv items to add before the "--" separator
	// (consent flags, --<id_flag>=<id>) when Kind is DecisionRun.
	Flags []string
	// Confirmation is the document to return when Kind is DecisionConfirm.
	Confirmation *Confirmation
	// Refusal is the invoker error when Kind is DecisionRefuse and Result is nil.
	Refusal error
	// Result, when set with DecisionRefuse, is the response to return as is:
	// the child's error envelope from the plan exec, or an E422/E423 for it.
	Result *Result
}

type Guard struct {
	// Now is the clock; tests inject a fixed or advancing one. Set it before
	// the Guard is shared between goroutines.
	Now func() time.Time
	// contains filtered or unexported fields
}

type Options struct {
	// Transport defaults to TransportMCP.
	Transport string
	// Dir is the project directory the child runs in.
	Dir string
	// Timeout of 0 selects DefaultTimeout for document transports and no
	// timeout for TransportHTTPStream.
	Timeout time.Duration
	// KillDelay overrides the SIGTERM grace period; zero keeps the 5 s default.
	KillDelay time.Duration
	// Stdout, with TransportHTTPStream, receives the child's NDJSON.
	Stdout io.Writer
	// Guard holds the confirmation nonces and the audit path (gate.go,
	// confirm.go, audit.go). One Guard per server process. A nil Guard fails
	// closed: remote and destructive commands are refused (E421), writes run
	// and nothing is audited.
	Guard *Guard
	// Surface labels the audit line: mcp-stdio, mcp-sse, mcp-http or http.
	// Empty selects http for TransportHTTP and TransportHTTPStream and
	// mcp-stdio for TransportMCP.
	Surface string
}

type Request struct {
	// Args are the positional values, one argv element each.
	Args []string `json:"args,omitempty"`
	// Flags maps a flag name to bool, integer, number, string or []string.
	Flags map[string]any `json:"flags,omitempty"`
	// Argv is the verbatim argv of a plugin command that declares no args or flags.
	Argv []string `json:"argv,omitempty"`
	// Confirm is a plan id or a server-issued nonce (consumed by the gate).
	Confirm string `json:"confirm,omitempty"`
}

type Result struct {
	// Stdout is the document bytes: the child's stdout (Exec) or the validated
	// document / error envelope (Invoke).
	Stdout []byte
	// Stderr is the raw, unredacted stderr tail. Exec only: Invoke clears it.
	// Never forward it to a client.
	Stderr []byte
	// ExitCode is the child's exit status, or the exit class of an E42x envelope;
	// -1 when the child was killed by a signal.
	ExitCode int
	// TimedOut is true when the invocation deadline ended the child.
	TimedOut bool
	// StdoutTruncated is true when the child wrote more than MaxStdoutBytes.
	StdoutTruncated bool
	// RequestID is the redacted request id (Invoke only).
	RequestID string
	// ErrorCode is the E42x code when Stdout is an envelope written by this
	// package (Invoke only); empty when Stdout is the child's own document.
	ErrorCode string
	// Confirmation is true only when Invoke issued a gate confirmation.
	// Child output cannot set this trusted transport status metadata.
	Confirmation bool
}

type SecretBundle struct {
	Nonce  string   `json:"nonce"`
	Values []string `json:"values"`
}

type Spec struct {
	// Argv is everything after the binary: path tokens, --json, flags, "--", args.
	Argv []string
	// Dir is the child's working directory (the server's project dir); empty inherits.
	Dir string
	// Transport is TransportMCP, TransportHTTP or TransportHTTPStream.
	Transport string
	// Path, when set, is the classified command path the child must resolve
	// to (PathEnv); empty sets no pin.
	Path string
	// Timeout of 0 means none (NDJSON): only context cancellation ends the child.
	Timeout time.Duration
	// KillDelay overrides the SIGTERM grace period; zero keeps the 5 s default.
	KillDelay time.Duration
	// Stdout, when set, receives the child's stdout as it is produced (NDJSON);
	// the child's output is then not captured and Result.Stdout is nil.
	Stdout io.Writer
	// Secrets holds the values the Argv placeholders stand for; nil when none.
	Secrets *SecretBundle
}