journalhook

var Begin func(ctx context.Context, j any, runID string, start any) (completed json.RawMessage, done bool, err error)

Begin is a flow drive's first step. It holds the run to start, an agent.RunStart: start is recorded as the run's run:start if it has none, and a drive whose kind, flow, saga flag or input differs from the recorded one is ErrConfig (see agent.RunStart). A run whose completion marker (run:complete) is recorded then returns its Result and done=true, since a finished run is final. A new run costs its header and run:start Inserts (no read of the completion, which a new run cannot hold); an existing run the run:start Insert that finds its recorded start, and one point read of its completion.

var CheckRunID func(ctx context.Context, runID string) error

CheckRunID refuses (ErrConfig) a run ID agent.Run refuses: an empty one, or one of the form the engine reserves for the runs of sub-agents and session turns.

var Complete func(ctx context.Context, j any, runID string, result json.RawMessage) (json.RawMessage, error)

Complete records runID's completion marker in j with result as its Result, and returns the Result the journal holds (another driver's, if it recorded one first).

var Do func(ctx context.Context, j any, runID, name string, fn func(context.Context) (any, error)) (any, error)

Do runs fn as the memoized step name of runID in j, an *agent.Journal, and returns the agent.Record the journal holds for it. fn returns the agent.Record to record.

var DoFresh func(ctx context.Context, j any, runID, name string, fn func(context.Context) (any, error)) (any, error)

DoFresh is Do for a step the caller knows is not recorded (the journal's doFresh: the engine's live model turns and tool results): one Insert and no read, which keeps the record another writer stored first. Tests use it to hold that path to the journal's rules, and plan to record a flow's topology (flow:topology), a pure value, without a read.

var Gate func(ctx context.Context, j any, runID, key, node string, args json.RawMessage, policy any, verifiers any) (approved bool, err error)

Gate evaluates the approval gate policy (an *agent.ApprovalPolicy) of the plan flow node named node, under its node key key, in run runID of j (an *agent.Journal), for the node's input args (JSON). verifiers is the flow's agent.ApproverVerifierFor (nil when it has none). It reports approved=true when the node may run and false when its gate denied it; a gate still waiting returns an *agent.ApprovalPending. It counts with the records and the rule an agent's gated tool call does.

var Marshal func(v any) ([]byte, error)

Marshal encodes v as the journal encodes values: JSON with no HTML escapes (agent's marshalJournal). Package plan encodes every value it records with it.

var SameJSON func(a, b []byte) bool

SameJSON reports whether a and b are the same JSON value under the engine's one comparison rule (agent's canonical JSON: blind to whitespace, key order, number spelling and string escaping); a text that rule refuses (a repeated key, a lone surrogate, invalid UTF-8) equals only itself.

var Step func(ctx context.Context, j any, runID, name string, safety any, fn func(context.Context) (json.RawMessage, error)) (json.RawMessage, error)

Step runs fn as the Step named name of runID in j, an *agent.Journal, with agent.Journal.Step's semantics (an attempt claim before fn unless safety is retry-safe, the not-started record when fn never ran, numbered re-attempts, a halt as *agent.OutcomeUnknown, the pause guard), and returns the JSON value it records. safety is the step's agent.Safety. name must be a plan node key (agent's planNodeKey: "node:<name>" or "node:iter:<n>:<name>"); any other name is ErrConfig, so the hook runs no other reserved key. A Step that fn runs for the same run is recorded under name (see agent.Journal.Step), so each node, and each loop iteration of one, records its own.

var WithClaim func(rec any, claim string) any

WithClaim returns rec, an agent.Record, with its claim id replaced by claim: a marker another driver wrote, for tests.

var WithRaw func(rec any, raw json.RawMessage) any

WithRaw returns rec, an agent.Record, with the bytes Raw returns replaced by raw, for tests of code that reads a record's stored bytes.

var WithSalt func(rec any, salt []byte) any

WithSalt returns rec, an agent.Record, with its salt replaced by salt: a record no journal writes, for tests of code that must refuse one.