acpx

package module
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 10 Imported by: 0

README

acpx-go

Go-native ACPX durable-format compatibility library.

acpx-go reads and validates ACPX flow run bundles without requiring a TypeScript runtime. It targets the durable replay/archive surface used by ACPX-compatible tools:

  • manifest.json
  • flow.json
  • trace.ndjson
  • projections/run.json
  • projections/live.json
  • projections/steps.json
  • sessions/*
  • artifacts/*

The package is intentionally small. It does not execute .flow.ts files and it does not implement an ACP transport. Hosts such as ratchet-cli remain responsible for agent execution, policy decisions, and CLI UX.

Install

go get github.com/GoCodeAlone/acpx-go

Example

bundle, err := acpx.LoadBundle(ctx, "/path/to/run")
if err != nil {
    return err
}
fmt.Println(bundle.Manifest.RunID)

Compatibility

This repository tracks upstream ACPX durable bundle compatibility through typed Go validators and golden fixtures. Optional upstream TypeScript fixture generation lives in compatibility tests only; normal Go tests do not require Node or pnpm.

Documentation

Index

Constants

View Source 
const (
	SchemaFlowRunBundleV1          = "acpx.flow-run-bundle.v1"
	SchemaFlowDefinitionSnapshotV1 = "acpx.flow-definition-snapshot.v1"
	SchemaFlowTraceEventV1         = "acpx.flow-trace-event.v1"
	SchemaSessionV1                = "acpx.session.v1"
)
View Source 
const (
	DefaultFlowPath            = "flow.json"
	DefaultTracePath           = "trace.ndjson"
	DefaultRunProjectionPath   = "projections/run.json"
	DefaultLiveProjectionPath  = "projections/live.json"
	DefaultStepsProjectionPath = "projections/steps.json"
	DefaultSessionsDir         = "sessions"
	DefaultArtifactsDir        = "artifacts"
)

Variables

View Source 
var (
	ErrInvalidBundle = errors.New("invalid acpx bundle")
	ErrUnsafePath    = errors.New("unsafe acpx bundle path")
)

Functions

func ValidateArtifactRef 

func ValidateArtifactRef(ref ArtifactRef) error

func ValidateBundle 

func ValidateBundle(ctx context.Context, root string) error

func ValidateBundlePath 

func ValidateBundlePath(value string) error

func ValidateFlowSnapshot 

func ValidateFlowSnapshot(snapshot FlowSnapshot) error

func ValidateManifest 

func ValidateManifest(m Manifest) error

func ValidateTrace 

func ValidateTrace(events []TraceEvent, status RunStatus) error

Types

type ArtifactRef 

type ArtifactRef struct {
	Path      string `json:"path"`
	MediaType string `json:"mediaType"`
	Bytes     int64  `json:"bytes,omitzero"`
	SHA256    string `json:"sha256"`
}

type Bundle 

type Bundle struct {
	Root     string
	Manifest Manifest
	Flow     *FlowSnapshot
	Trace    []TraceEvent
}

func LoadBundle 

func LoadBundle(ctx context.Context, root string) (*Bundle, error)

type FlowEdge 

type FlowEdge struct {
	From   string      `json:"from"`
	To     string      `json:"to,omitzero"`
	Switch *SwitchEdge `json:"switch,omitzero"`
}

type FlowNodeResult 

type FlowNodeResult struct {
	AttemptID  string          `json:"attemptId"`
	NodeID     string          `json:"nodeId"`
	NodeType   NodeType        `json:"nodeType"`
	Outcome    NodeOutcome     `json:"outcome"`
	StartedAt  string          `json:"startedAt"`
	FinishedAt string          `json:"finishedAt"`
	DurationMs float64         `json:"durationMs"`
	Output     json.RawMessage `json:"output,omitzero"`
	Error      string          `json:"error,omitzero"`
}

type FlowRunSnapshot 

type FlowRunSnapshot struct {
	HasTitle bool `json:"hasTitle,omitzero"`
}

type FlowRunState 

type FlowRunState struct {
	RunID                string                        `json:"runId"`
	FlowName             string                        `json:"flowName"`
	RunTitle             string                        `json:"runTitle,omitzero"`
	FlowPath             string                        `json:"flowPath,omitzero"`
	StartedAt            string                        `json:"startedAt"`
	FinishedAt           string                        `json:"finishedAt,omitzero"`
	UpdatedAt            string                        `json:"updatedAt"`
	Status               RunStatus                     `json:"status"`
	Input                json.RawMessage               `json:"input,omitzero"`
	Outputs              map[string]json.RawMessage    `json:"outputs,omitzero"`
	Results              map[string]FlowNodeResult     `json:"results,omitzero"`
	Steps                []FlowStepRecord              `json:"steps,omitzero"`
	SessionBindings      map[string]FlowSessionBinding `json:"sessionBindings,omitzero"`
	CurrentNode          string                        `json:"currentNode,omitzero"`
	CurrentAttemptID     string                        `json:"currentAttemptId,omitzero"`
	CurrentNodeType      NodeType                      `json:"currentNodeType,omitzero"`
	CurrentNodeStartedAt string                        `json:"currentNodeStartedAt,omitzero"`
	LastHeartbeatAt      string                        `json:"lastHeartbeatAt,omitzero"`
	StatusDetail         string                        `json:"statusDetail,omitzero"`
	WaitingOn            string                        `json:"waitingOn,omitzero"`
	Error                string                        `json:"error,omitzero"`
}

type FlowSessionBinding 

type FlowSessionBinding struct {
	Key            string `json:"key"`
	Handle         string `json:"handle"`
	BundleID       string `json:"bundleId"`
	Name           string `json:"name"`
	Profile        string `json:"profile,omitzero"`
	AgentName      string `json:"agentName"`
	AgentCommand   string `json:"agentCommand"`
	CWD            string `json:"cwd"`
	AcpXRecordID   string `json:"acpxRecordId"`
	ACPSessionID   string `json:"acpSessionId"`
	AgentSessionID string `json:"agentSessionId,omitzero"`
}

type FlowSnapshot 

type FlowSnapshot struct {
	Schema      string                  `json:"schema"`
	Name        string                  `json:"name"`
	Run         *FlowRunSnapshot        `json:"run,omitzero"`
	Permissions json.RawMessage         `json:"permissions,omitzero"`
	StartAt     string                  `json:"startAt"`
	Nodes       map[string]NodeSnapshot `json:"nodes"`
	Edges       []FlowEdge              `json:"edges"`
}

type FlowStepRecord 

type FlowStepRecord struct {
	AttemptID  string              `json:"attemptId"`
	NodeID     string              `json:"nodeId"`
	NodeType   NodeType            `json:"nodeType"`
	Outcome    NodeOutcome         `json:"outcome"`
	StartedAt  string              `json:"startedAt"`
	FinishedAt string              `json:"finishedAt"`
	PromptText *string             `json:"promptText"`
	RawText    *string             `json:"rawText"`
	Output     json.RawMessage     `json:"output,omitzero"`
	Error      string              `json:"error,omitzero"`
	Session    *FlowSessionBinding `json:"session"`
	Agent      json.RawMessage     `json:"agent,omitzero"`
	Trace      json.RawMessage     `json:"trace,omitzero"`
}

type Manifest 

type Manifest struct {
	Schema      string                 `json:"schema"`
	RunID       string                 `json:"runId"`
	FlowName    string                 `json:"flowName"`
	RunTitle    string                 `json:"runTitle,omitzero"`
	FlowPath    string                 `json:"flowPath,omitzero"`
	StartedAt   string                 `json:"startedAt"`
	FinishedAt  string                 `json:"finishedAt,omitzero"`
	Status      RunStatus              `json:"status"`
	TraceSchema string                 `json:"traceSchema"`
	Paths       ManifestPaths          `json:"paths"`
	Sessions    []ManifestSessionEntry `json:"sessions,omitzero"`
}

type ManifestPaths 

type ManifestPaths struct {
	Flow            string `json:"flow"`
	Trace           string `json:"trace"`
	RunProjection   string `json:"runProjection"`
	LiveProjection  string `json:"liveProjection"`
	StepsProjection string `json:"stepsProjection"`
	SessionsDir     string `json:"sessionsDir"`
	ArtifactsDir    string `json:"artifactsDir"`
}

type ManifestSessionEntry 

type ManifestSessionEntry struct {
	ID          string `json:"id"`
	Handle      string `json:"handle"`
	BindingPath string `json:"bindingPath"`
	RecordPath  string `json:"recordPath"`
	EventsPath  string `json:"eventsPath"`
}

type NodeCWD 

type NodeCWD struct {
	Mode  string `json:"mode"`
	Value string `json:"value,omitzero"`
}

type NodeOutcome 

type NodeOutcome string
const (
	NodeOutcomeOK        NodeOutcome = "ok"
	NodeOutcomeTimedOut  NodeOutcome = "timed_out"
	NodeOutcomeFailed    NodeOutcome = "failed"
	NodeOutcomeCancelled NodeOutcome = "cancelled"
)

type NodeSession 

type NodeSession struct {
	Handle   string `json:"handle,omitzero"`
	Isolated bool   `json:"isolated,omitzero"`
}

type NodeSnapshot 

type NodeSnapshot struct {
	NodeType        NodeType     `json:"nodeType"`
	TimeoutMs       float64      `json:"timeoutMs,omitzero"`
	HeartbeatMs     float64      `json:"heartbeatMs,omitzero"`
	StatusDetail    string       `json:"statusDetail,omitzero"`
	Profile         string       `json:"profile,omitzero"`
	Session         *NodeSession `json:"session,omitzero"`
	CWD             *NodeCWD     `json:"cwd,omitzero"`
	Summary         string       `json:"summary,omitzero"`
	ActionExecution string       `json:"actionExecution,omitzero"`
	HasPrompt       bool         `json:"hasPrompt,omitzero"`
	HasParse        bool         `json:"hasParse,omitzero"`
	HasRun          bool         `json:"hasRun,omitzero"`
	HasExec         bool         `json:"hasExec,omitzero"`
}

type NodeType 

type NodeType string
const (
	NodeTypeACP        NodeType = "acp"
	NodeTypeCompute    NodeType = "compute"
	NodeTypeAction     NodeType = "action"
	NodeTypeCheckpoint NodeType = "checkpoint"
)

type RunStatus 

type RunStatus string
const (
	RunStatusRunning  RunStatus = "running"
	RunStatusWaiting  RunStatus = "waiting"
	RunStatusComplete RunStatus = "completed"
	RunStatusFailed   RunStatus = "failed"
	RunStatusTimedOut RunStatus = "timed_out"
)

type SessionEvent 

type SessionEvent struct {
	Seq       int64           `json:"seq"`
	At        string          `json:"at"`
	Direction string          `json:"direction"`
	Message   json.RawMessage `json:"message"`
}

type SwitchEdge 

type SwitchEdge struct {
	On    string            `json:"on"`
	Cases map[string]string `json:"cases"`
}

type TraceAttempt 

type TraceAttempt struct {
	NodeID      string
	Started     bool
	Completed   bool
	OutcomeType string
}

type TraceEvent 

type TraceEvent struct {
	Seq       int64                      `json:"seq"`
	At        string                     `json:"at"`
	Scope     TraceScope                 `json:"scope"`
	Type      string                     `json:"type"`
	RunID     string                     `json:"runId"`
	NodeID    string                     `json:"nodeId,omitzero"`
	AttemptID string                     `json:"attemptId,omitzero"`
	SessionID string                     `json:"sessionId,omitzero"`
	Artifact  *ArtifactRef               `json:"artifact,omitzero"`
	Payload   map[string]json.RawMessage `json:"payload"`
}

func ReadTrace 

func ReadTrace(ctx context.Context, r io.Reader) ([]TraceEvent, error)

func ReadTraceFile 

func ReadTraceFile(ctx context.Context, filePath string) ([]TraceEvent, error)

type TraceProjection 

type TraceProjection struct {
	RunID         string
	EventCount    int
	SessionCount  int
	ArtifactCount int
	Attempts      map[string]TraceAttempt
}

func RebuildTraceProjection 

func RebuildTraceProjection(events []TraceEvent) (TraceProjection, error)

type TraceScope 

type TraceScope string
const (
	TraceScopeRun      TraceScope = "run"
	TraceScopeNode     TraceScope = "node"
	TraceScopeACP      TraceScope = "acp"
	TraceScopeAction   TraceScope = "action"
	TraceScopeSession  TraceScope = "session"
	TraceScopeArtifact TraceScope = "artifact"
)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.