a2a

import "github.com/jbcom/radioactive-ralph/internal/a2a"

Package a2a is a thin adoption layer over github.com/a2aproject/a2a-go/v2’s core vocabulary (github.com/a2aproject/a2a-go/v2/a2a), per .agent-state/decisions.ndjson (“a2a-comms-layer”) and spec §12.

We import ONLY the a2a-go core-types package (a2a/), which is stdlib-only (plus github.com/google/uuid) — never a2asrv/a2agrpc/a2apb, which pull in grpc/protobuf. This package re-exports the TaskState constants radioactive -ralph actually uses, and defines Evidence: the structured result a worker submits to the orchestrator, carried as an a2a.Message so worker<-> orchestrator communication uses the standard vocabulary.

The a2a_messages store table (see internal/store/schema/0002_a2a.up.sql) is a message/evidence LOG, not a parallel task store — the store’s existing tasks table is the durable DAG (§ decision “a2a-comms-layer”: “Don’t create a parallel task store — the plan DAG IS the task store”).

Critically: nothing in this package marks a task done. A worker submitting Evidence via an a2a.Message is a proposal for the orchestrator to verify (see internal/orch.VerifyAndComplete) — never a self-assertion of completion.

Index

• Constants

• func MarshalEvidence(ev Evidence) (string, error)

• type Evidence

  • func EvidenceFromMessage(msg *Message) (Evidence, error)

  • func UnmarshalEvidence(raw string) (Evidence, error)

• type Message

  • func NewEvidenceMessage(role a2a.MessageRole, taskID, contextID string, ev Evidence) *Message

• type Part

• type TaskState

Constants

The TaskState values radioactive-ralph uses to describe a worker’s progress against one store task. The orchestrator drives these transitions; a worker only ever SUGGESTS one via submitted Evidence.

const (
    // StateSubmitted: the task has been claimed and dispatched to a worker
    // but the worker has not yet reported evidence.
    StateSubmitted = a2a.TaskStateSubmitted
    // StateWorking: the worker is actively executing.
    StateWorking = a2a.TaskStateWorking
    // StateInputRequired is the never-block signal: a worker that would
    // otherwise block waiting for input is in this TASK STATE, which the
    // orchestrator handles by re-dispatching with an answer or by
    // kill+reclaim — never by waiting on a blocked pty.
    StateInputRequired = a2a.TaskStateInputRequired
    // StateCompleted: ORCHESTRATOR-VERIFIED completion only. Never set
    // directly from a worker's self-report or from process termination.
    StateCompleted = a2a.TaskStateCompleted
    // StateFailed: verification rejected the evidence, or the worker
    // reported failure.
    StateFailed = a2a.TaskStateFailed
)

Role constants used when constructing evidence messages.

const (
    RoleAgent = a2a.MessageRoleAgent
    RoleUser  = a2a.MessageRoleUser
)

func MarshalEvidence

func MarshalEvidence(ev Evidence) (string, error)

MarshalEvidence serializes Evidence to a JSON string for storage in the store’s evidence/payload columns (e.g. MarkDone’s evidenceJSON parameter).

type Evidence

Evidence is what a worker submits after it believes it has completed a task: what it ran, what happened, and what changed. This is a PROPOSAL — the orchestrator’s VerifyAndComplete re-checks it against the task’s acceptance criteria before ever marking the task done in the store.

type Evidence struct {
    // Ran is the mechanical check the worker believes satisfies the task's
    // acceptance criterion (e.g. "go test ./..." or a file path). Advisory
    // only — the orchestrator re-runs the real check itself rather than
    // trusting this string.
    Ran string `json:"ran,omitempty"`

    // ExitCode is the exit status the worker observed when it ran Ran, if
    // applicable. Advisory only, same caveat as Ran.
    ExitCode int `json:"exit_code"`

    // Output is a bounded capture of what Ran produced (stdout/stderr),
    // kept for the audit trail and for judgment-based acceptance criteria.
    Output string `json:"output,omitempty"`

    // Diff is the worker's summary/patch of what it changed, if any.
    Diff string `json:"diff,omitempty"`

    // FilesChanged lists paths the worker believes it modified.
    FilesChanged []string `json:"files_changed,omitempty"`
}

func EvidenceFromMessage

func EvidenceFromMessage(msg *Message) (Evidence, error)

EvidenceFromMessage extracts Evidence from an a2a.Message’s first Data part. Returns an error if the message carries no data part.

func UnmarshalEvidence

func UnmarshalEvidence(raw string) (Evidence, error)

UnmarshalEvidence parses a JSON string back into Evidence. Used when reloading a worker’s submitted evidence (e.g. from an a2a_messages row or a stored event payload) for (re-)verification.

type Message

Message re-exports a2a.Message, the core type used to carry Evidence.

type Message = a2a.Message

func NewEvidenceMessage

func NewEvidenceMessage(role a2a.MessageRole, taskID, contextID string, ev Evidence) *Message

NewEvidenceMessage wraps Evidence as an a2a.Message with a single JSON data Part, tagged with the given plan/task context. role is typically RoleAgent (a worker reporting evidence to the orchestrator).

type Part

Part re-exports a2a.Part, one content part of a Message.

type Part = a2a.Part

type TaskState

TaskState re-exports a2a.TaskState so callers need not import the upstream package directly for the states radioactive-ralph drives.

type TaskState = a2a.TaskState

Generated by gomarkdoc