Documentation
¶
Overview ¶
Package workflow decodes KAS's workflow-run wire shapes. It holds no run state: `_kiro/workflow/inspect` returns it whole and the read endpoints pass it through. What remains is which ACP session executed a given step, plus KAS's `-32603` error unwrapping.
`inspect` has no stepSessions array: `state.root` holds `sessionId`, `agentName`, `iteration` and `branchId` ON each step node, so the tree IS the join.
Index ¶
- Variables
- func AskPosition(workflowID string, st *StepSession) string
- func Classify(err error) error
- func PathKey(path []string) string
- func PausedOnAsks(reply Inspect) bool
- func StepRecords(s *State) map[string]StepRecord
- type Ask
- type Inspect
- type InspectResult
- type RunLog
- type State
- type StepLog
- type StepRecord
- type StepSession
Constants ¶
This section is empty.
Variables ¶
var ErrJustClaimed = errors.New("another claim on this run is in flight")
ErrJustClaimed means another claim on the run is in flight right now.
var ErrUnknownMethod = errors.New("workflow verb not registered on this kiro-cli build")
ErrUnknownMethod means the verb does not exist on this KAS build: a permanent capability answer, unlike a transient failure. Callers ask errors.Is.
Functions ¶
func AskPosition ¶ added in v0.15.0
func AskPosition(workflowID string, st *StepSession) string
AskPosition is one step execution's ask identity across its turns: an Ask's Position, and the first component of every Ask.ID asked there.
func Classify ¶
Classify types a `_kiro/workflow/*` RPC failure AT THE BOUNDARY, wrapping its sentinel with the original still unwrappable. It reads `error.data`, never the message chain: RPCError.Error() for this shape is the literal "Internal error".
func PathKey ¶ added in v0.13.0
PathKey is a node path's one string identity: the run log's turn key, the step-transcript address and the client's row key (run-node-key.ts, pinned by testdata/node_path_key.json). A node id is free-form, so a separator join would collide ["a/b","c"] with ["a","b/c"]. It is an equality key only: a path over keyenc.MaxComponentBytes keys by a hash no split reads back, so a reader needing the segments or the node id carries them beside the key.
func PausedOnAsks ¶ added in v0.15.0
PausedOnAsks reports whether reply is a paused run whose every paused leaf waits on a person, the state where KAS's resume re-parks each step at once.
func StepRecords ¶ added in v0.15.0
func StepRecords(s *State) map[string]StepRecord
StepRecords indexes every step node of a run's tree by its PathKey; nil for a state with no tree.
Types ¶
type Ask ¶ added in v0.15.0
type Ask struct {
ID string
Position string
NodeID string
StepSessionID string
AgentName string
Text string
TextSource marotte.RunAskText
// Reason is KAS's sentence for why this step parked, set only for a park with no signal (a lost
// send_message signal, or a step that ended its turn without one) and only when it is the run's
// sole waiting step: the reply carries one run-level reason, so with two waiting steps it names either.
Reason string
// Hold is what marotte's own requests on the run block: stopping or pending.
Hold marotte.RunAskBlocker
// Wait is what KAS's state blocks, computed without reading Hold, so a verb that registered its
// own pending before its check still sees KAS's refusal conditions.
Wait marotte.RunAskBlocker
// AskedAt is KAS's park start, display only.
AskedAt string
NodePath []string
}
Ask is one step waiting on a person, derived from one inspect reply and marotte's run log.
func OpenAsks ¶ added in v0.15.0
OpenAsks is every step of reply waiting on a person, in pre-order. Pure: it reads no clock and does no I/O. An unreadable reply answers none, which the caller must not publish as "answered".
func (*Ask) Blocked ¶ added in v0.15.0
func (a *Ask) Blocked() marotte.RunAskBlocker
Blocked is the one blocker a card and the wire carry.
type Inspect ¶ added in v0.15.0
Inspect is one decoded `_kiro/workflow/inspect` reply. OK is false for a reply with no readable state, which a reader must treat as "unknown", never as "nothing is waiting". Pending counts the top-level steps of the queued plan revision: 0 when none is queued, -1 when the reply's pendingSteps is not an array.
func DecodeInspect ¶ added in v0.15.0
func DecodeInspect(workflowID string, raw json.RawMessage) (Inspect, error)
DecodeInspect decodes the reply to an inspect of workflowID; the returned State always names workflowID. A syntax error, a type error in any decoded field, a missing state, or a reply naming another run, none, or two disagreeing ones answers a not-OK Inspect and the reason.
type InspectResult ¶
type InspectResult struct {
State *State `json:"state"`
WorkflowID string `json:"workflowId"`
// PendingSteps is the queued replace_remaining plan, which KAS answers from its persisted
// pending-step-update.json even for a run it has not loaded. It stays raw so a shape change in
// this advisory key never fails the state's decode.
PendingSteps json.RawMessage `json:"pendingSteps"`
}
InspectResult is `_kiro/workflow/inspect`'s reply, decoded to the parts marotte reads. `nodePlan` rides through undecoded — see the package comment.
type RunLog ¶ added in v0.15.0
type RunLog struct {
// Steps is keyed by step session id.
Steps map[string]StepLog
// Epoch keys an ask whose step marotte saw no turn_start for this boot.
Epoch string
// Stopping: a marotte cancel or delete is queued on the run.
Stopping bool
// Pending: marotte has a prompt on the run not yet settled.
Pending bool
// Quiet: nothing on the run moved for the settle window.
Quiet bool
}
RunLog is what marotte itself observed or did on a run, the second input of OpenAsks.
type State ¶
type State struct {
Root *node `json:"root"`
WorkflowID string `json:"workflowId"`
Status string `json:"status"`
ParentSessionID string `json:"parentSessionId"`
RunLabel string `json:"runLabel"`
WorkflowName string `json:"workflowName"`
// PauseReason is KAS's sentence for the run's latest park, whichever step parked.
PauseReason string `json:"pauseReason"`
CreatedAt string `json:"createdAt"`
}
State is the run state `inspect` returns, decoded only as far as step identification needs.
type StepLog ¶ added in v0.15.0
type StepLog struct {
// Marker is the newest turn_start's marker, "" when none was seen. A turn_end never moves it,
// so an ask's id is fixed for the life of its parking turn.
Marker string
// Asked is the warning text of the newest turn that ended, "" when that turn sent none.
Asked string
// Said is the parking turn's last agent words from the run's own record.
Said string
// Open is true while the newest edge is a turn_start with no turn_end after it.
Open bool
}
StepLog is one step session's turn record as marotte saw it this boot.
type StepRecord ¶ added in v0.15.0
type StepRecord struct {
Status string
// CompletionSignal is "" when the step signalled nothing.
CompletionSignal string
}
StepRecord is KAS's own record of how one step node stands: its status and completion signal, verbatim.
func (StepRecord) Completed ¶ added in v0.15.0
func (r StepRecord) Completed() bool
Completed reports whether KAS's node status is `completed`, signalled or not.
func (StepRecord) Succeeded ¶ added in v0.15.0
func (r StepRecord) Succeeded() bool
Succeeded reports whether KAS completed the step on a success signal: a send_message success, or update_workflow's recorded handoff (writeHandoffCompletion, kiro-cli 2.32.0).
type StepSession ¶
type StepSession struct {
NodeID string
SessionID string
// Status is KAS's node status word, verbatim.
Status string
// CompletionSignal is the signal KAS recorded on the node, verbatim; "" for none.
CompletionSignal string
// Path is the node path from the root to this step in KAS's WIRE spelling (see pathSegment).
Path []string
}
StepSession names one step node, its ACP session and its PATH. The path addresses one EXECUTION (a repeat's iterations share a node id), so callers naming a step key on it.
func ParkedSteps ¶ added in v0.15.0
func ParkedSteps(reply Inspect) []StepSession
ParkedSteps lists the steps that satisfy the wait predicate in pre-order, none for a terminal or unreadable reply. OpenAsks answers exactly these.
func StepSessions ¶
func StepSessions(s *State) []StepSession
StepSessions walks a run's state tree depth-first and returns every step with a session, in declaration order (a `parallel` node's branches are not time-ordered).
func Steps ¶
func Steps(s *State) []StepSession
Steps returns EVERY step node in the same order, run or not, so a caller can tell "no such step" from "not started".
func (*StepSession) EndSignalled ¶ added in v0.16.0
func (s *StepSession) EndSignalled() bool
EndSignalled reports whether KAS recorded a success or an error signal on the step.