workflow

package
v0.17.4 Latest Latest
Warning

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

Go to latest
Published: Nov 11, 2026 License: AGPL-3.0 Imports: 9 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrJustClaimed = errors.New("another claim on this run is in flight")

ErrJustClaimed means another claim on the run is in flight right now.

View Source
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

func Classify(err error) error

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

func PathKey(path []string) string

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

func PausedOnAsks(reply Inspect) bool

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

func OpenAsks(reply Inspect, log RunLog) []Ask

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

type Inspect struct {
	State   *State
	Pending int
	OK      bool
}

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.

func (*State) UpdatedAt added in v0.17.0

func (s *State) UpdatedAt() string

UpdatedAt is the run's last activity as `_kiro/workflow/list` derives its row's updatedAt from this same state: the root's end, else its start, else the state's creation; "" when none is recorded.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL