action

type Action ¶

type Action interface {
	// contains filtered or unexported methods
}

Action is the sealed interface for all action types. Only types in this package can implement it (unexported method).

type AskHuman ¶

type AskHuman struct {
	Prompt string
	Schema json.RawMessage // optional JSON schema for structured response validation
}

AskHuman pauses the loop and requests a human response. The loop enters Interrupted state; Resume continues after HumanResponded is appended.

type Finish ¶

type Finish struct {
	Result json.RawMessage
}

Finish signals the loop is complete. Result is the marshaled R value. The runtime unmarshals Result into the Runner's R type parameter.

type ID ¶

type ID string

ID is a ULID assigned by the runtime to each action instance. It links ActionRequested events to their corresponding result events.

type Kind ¶

type Kind string

Kind identifies the type of action.

const (
	KindModelCall Kind = "ModelCall"
	KindToolCall  Kind = "ToolCall"
	KindAskHuman  Kind = "AskHuman"
	KindSpawn     Kind = "Spawn"
	KindFinish    Kind = "Finish"
)

func ActionKind(a Action) Kind

type Message ¶

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

Message is a single conversation turn.

type ModelCall ¶

type ModelCall struct {
	Provider string
	Model    string
	Request  ModelRequest
}

ModelCall requests the runtime to call a model provider.

type ModelRequest ¶

type ModelRequest struct {
	Messages []Message       `json:"messages"`
	System   string          `json:"system,omitempty"`
	Config   json.RawMessage `json:"config,omitempty"`
}

ModelRequest is a minimal model request type for SP1. SP2 (providers) extends this compatibly without breaking existing code. Deprecated: use core/model.Request instead.

type ReplaySemantics ¶

type ReplaySemantics int

ReplaySemantics governs how the runtime handles an unacknowledged (dangling) action when resuming after a crash.

• AtMostOnce (zero value, safest default): if the action completed but its result was not recorded, it is NOT re-executed. The runtime delivers a synthetic ToolCalled{isError:true, "unknown completion state"} to the transition.
• Idempotent: safe to re-execute; the runtime re-runs the action on resume.
• SideEffectFree: same as Idempotent but signals the action has no observable effects (e.g., read-only queries). Safe to re-execute without any concern.

const (
	// AtMostOnce is the zero value and safest default. Document your tools carefully.
	AtMostOnce ReplaySemantics = iota
	// Idempotent marks actions safe to re-execute on resume.
	Idempotent
	// SideEffectFree marks actions with no observable side effects (e.g., read-only).
	SideEffectFree
)

type Spawn ¶

type Spawn struct {
	// Definition is the registered child definition name (see loopkit.Registry).
	Definition string
	// Request is the marshalled child input (Req of the Contract).
	Request json.RawMessage
	// Budget is the carved-out budget for the child. The runtime validates that
	// child Budget ≤ parent remaining; violation → SubAgentCompleted{BudgetExceeded}.
	Budget budget.Budget
	// Grant is the policy grant for the child. Must be ⊆ parent grant.
	// Violation → SubAgentCompleted{PolicyDenied}.
	Grant policy.Grant
}

Spawn requests the runtime to launch a child loop (sub-agent). The child shares the parent's store, provider, and tools but has its own event log (own LoopID). Budget is validated by the runtime against the parent's remaining capacity; Grant must be ⊆ parent grant (no escalation).

type ToolCall ¶

type ToolCall struct {
	Tool      string
	Args      json.RawMessage
	Semantics ReplaySemantics
}

ToolCall requests the runtime to execute a named tool. Semantics controls crash-resume behavior for this specific call.