asyncmachine-go

https://github.com/pancsta/asyncmachine-go
Admin
Asyncmachine Go is a distributed workflow engine implementing aspect-oriented programming and actor...
Tokens:483,089
Snippets:3,353
Trust Score:8
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start Demo - Setup and Run Commands

Source: https://github.com/pancsta/asyncmachine-go/blob/main/examples/wasm_workflow/README.md

Clones the repository, installs dependencies, and runs the demo in three terminals (dbg, traces, start). Unset EXIT_ON_COMPLETED to keep the workflow alive after completion.

```bash
git clone https://github.com/pancsta/asyncmachine-go.git
./scripts/dep-taskfile.sh
go mod tidy
cd examples/wasm_workflow
task dbg #tty1
task traces #tty2
task start #tty3
```

--------------------------------

### RPC Client setup and start

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/cookbook.md

Creates an RPC client with arpc.NewClient, starts it, and waits for the Ready state within 2 seconds.

```go
client, err := arpc.NewClient(ctx, addr, "clientid", schema, &arpc.ClientOpts{
    Consumer: consumer,
    Parent: machParent,
})

// start
client.Start()
err := amhelp.WaitForAll(ctx, 2*time.Second,
    c.Mach.When1(ssrpc.ClientStates.Ready, ctx))
if ctx.Err() != nil {
    return
}
```

--------------------------------

### RPC Server setup and start

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/cookbook.md

Creates an RPC server with arpc.NewServer, starts it, and waits for the RpcReady state within 2 seconds.

```go
srv, err := arpc.NewServer(ctx, addr, "server", sourceMach, &arpc.ServerOpts{
    Parent: machParent,
})
if err != nil {
    panic(err)
}

// start
srv.Start()
err = amhelp.WaitForAll(ctx, 2*time.Second,
    srv.Mach.When1(ssrpc.ServerStates.RpcReady, ctx))
if ctx.Err() != nil {
    return
}
if err != nil {
    return err
}
```

--------------------------------

### RPC Multiplexer setup and start

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/cookbook.md

Creates an RPC multiplexer with arpc.NewMux, sets a listener or address, starts it, and waits for the Ready state.

```go
mux, err := arpc.NewMux(ctx, addr, source.Id()), sourceMach, &arpc.MuxOpts{
    Parent: parentMach,
}
mux.Listener = listener // or mux.Addr := ":1234"
mux.Start()
err := amhelp.WaitForAll(ctx, 2*time.Second,
    mux.Mach.When1(ssrpc.MuxStates.Ready, ctx))
```

--------------------------------

### Machine Setup with Schema and Handlers

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/manual.md

Creates a machine with a schema where adding Foo implies Bar, and binds handlers. This is the setup for the transition calculation example.

```go
// machine

mach := am.New(ctx, am.Schema{
  "Foo": {
    Add: am.S{"Bar"},
  },
  "Bar": {}
}, nil)
_ = mach.HandlersBind(&Handlers{})
```

--------------------------------

### Run test cases for the Start state

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/getting-started.md

Navigate into the generated project and run the provided test case for the Start state using Go's verbose test mode.

```bash
cd my_mach
go test -v .
```

--------------------------------

### Supervisor initialization and start

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/node/README.md

Creates a Supervisor with the worker binary path and schema, then starts it on a local address and waits for the PoolReady state. The supervisor uses exec.Command to manage workers and exposes states like Ready, PoolReady, and WorkersAvailable.

```go
import (
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    amnode "github.com/pancsta/asyncmachine-go/pkg/node"
)

// ...

// var names am.S
// var schema am.Schema
// var workerKind string
// var workerBin []string

// supervisor
super, err := amnode.NewSupervisor(ctx, workerKind, workerBin, schema, nil)
if err != nil {
    t.Fatal(err)
}
super.Start("localhost:1234")
err := amhelp.WaitForAll(ctx, 2*time.Second,
    super.When1(ssnode.SupervisorStates.PoolReady, ctx))
```

--------------------------------

### Install asyncmachine-go CLI tools (am-gen, am-dbg, arpc)

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/getting-started.md

Install the required command-line tools for the tutorial: am-gen for schema and boilerplate generation, am-dbg for debugging, and arpc for remote state modification.

```bash
go install github.com/pancsta/asyncmachine-go/tools/cmd/am-gen@latest
go install github.com/pancsta/asyncmachine-go/tools/cmd/am-dbg@latest
go install github.com/pancsta/asyncmachine-go/tools/cmd/arpc@latest
```

--------------------------------

### Create main.go to modify state via CLI

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/getting-started.md

Creates a simple program using the new machine. It starts the machine, adds the Start state, and waits until Start is no longer active. Run with `go run ./cmd` and it will appear in the debugger.

```go
package main

import (
  "context"

  "mymach"
  "mymach/states"
)

var ss = states.MyMachStates

func main() {
  ctx := context.Background()
  h, _ := mymach.New(ctx)
  h.Mach.Add1(ss.Start, nil)
  <-h.Mach.WhenNot1(ss.Start, nil)
}
```

--------------------------------

### Initialize Node Client and Request Worker

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/node/README.md

Shows how to create a Node client by merging a custom schema with the Node client schema, adding custom states, and initializing the client with ClientOpts. After starting, it waits for SuperReady, requests a worker, waits for WorkerReady, and sends a WorkRequested state with input.

```go
import (
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    amnode "github.com/pancsta/asyncmachine-go/pkg/node"
)

// ...

// var workerKind string
// var workerSchema am.Schema
// var superAddrs []string

// inherit from Node client
schema := am.SchemaMerge(ssnode.ClientSchema, am.Schema{
    "Foo": {Require: am.S{"Bar"}},
    "Bar": {},
})
names := am.SAdd(ssnode.ClientStates.Names(), am.S{"Foo", "Bar"})

// describe client
opts := &amnode.ClientOpts{
    ClientSchema:  schema,
    ClientStates:  names,
}

// init
client, err := amnode.NewClient(ctx, "myclient", workerKind, workerSchema, opts)
client.Start(superAddrs)
err := amhelp.WaitForAll(ctx, 2*time.Second,
    super.When1(ssnode.ClientStates.SuperReady, ctx))

// request a worker
client.ReqWorker(ctx)
err := amhelp.WaitForAll(ctx, 2*time.Second,
    super.When1(ssnode.ClientStates.WorkerReady, ctx))
worker := client.WorkerRpc.NetMach
worker.Add1(ssnode.WorkerStates.WorkRequested, am.A{"input": 2})
```

--------------------------------

### List available tasks with task --list-all

Source: https://github.com/pancsta/asyncmachine-go/blob/main/examples/wasm/README.md

Displays the available Taskfile tasks for this project, including build, build-prod, deps, deps-graph, repl, and start. The output shows the task names and descriptions.

```bash
$ task --list-all

task: Available tasks for this project:
* build:            Development build
* build-prod:       Optimized build
* deps:             List dependencies in deps.md
* deps-graph:       Render dependencies graph in deps-graph.svg
* repl:             Start REPL for both server and browser
* start:            Build and start server
```

--------------------------------

### MachDebug

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/helpers/README.md

Starts a debug server for the state machine. Useful for inspecting machine state and transitions.

```APIDOC
## MachDebug

### Description
Starts a debug server for the state machine. Useful for inspecting machine state and transitions.

### Method
Function

### Signature
`MachDebug(mach am.Api, amDbgAddr string, logLvl am.LogLevel, stdout bool, semConfig *am.SemConfig) error`

### Parameters
- **mach** (am.Api) - Required - The state machine instance.
- **amDbgAddr** (string) - Required - The debug server address.
- **logLvl** (am.LogLevel) - Required - The log level.
- **stdout** (bool) - Required - Whether to output to stdout.
- **semConfig** (*am.SemConfig) - Optional - Semantic configuration.

### Returns
- **error** - An error if the debug server fails to start.

```

--------------------------------

### Setup and start RPC server and client for a worker state machine

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/rpc/HOWTO.md

Simplified version of NewTest() showing how to set up and start both server and client to expose a worker state machine. Handles environment-based debugging but does not include an RPC getter function. The main function starts the server and client, waits for the server to be ready, then adds a Foo state to the worker and checks if the client sees it.

```go
import (
    "github.com/pancsta/asyncmachine-go/internal/testing/utils"
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    arpc "github.com/pancsta/asyncmachine-go/pkg/rpc"
    arpcstates "github.com/pancsta/asyncmachine-go/pkg/rpc/states"

    "owner/project/states"
)


var ssC = arpcstates.ClientStates
var ssS = arpcstates.ServerStates
var ssW = workerstates.WorkerStates

func main() {
    ctx := context.TODO()
    id := "example"
    worker := am.New(ctx, states.WorkerStruct, nil)
    s := startServer(ctx, ":1234", worker)
    c := startClient(ctx, ":1234", worker)
    <-s.Mach.When1(ssS.Ready, nil)

    // ready, test it

    worker.Add1(ssW.Foo, nil)
    if c.Worker.Is1(ssW.Foo) {
        log.Println("OK")
    }
}

func startServer(ctx context.Context, addr string, worker *am.Machine) (*Server) {

    // server init
    s, err := arpc.NewServer(ctx, addr, id, worker, nil)
    if err != nil {
        panic(err)
    }
    utils.MachDebugEnv(s.Mach)

    // server start
    s.Start()
    <-s.Mach.When1(ssS.RpcReady, nil)

    return s
}

func startClient(ctx context.Context, addr string) (*Client) {

    // client init
    c, err := arpc.NewClient(ctx, addr, id, states.WorkerStruct, ssW.Names())
    if err != nil {
        panic(err)
    }
    utils.MachDebugEnv(c.Mach)

    // client ready
    c.Start()
    <-c.Mach.When1(ssC.Ready, nil)

    return c
}
```

--------------------------------

### Install am-gen via go install

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/am-gen/README.md

Installs the am-gen tool from the asyncmachine-go repository.

```bash
go install github.com/pancsta/asyncmachine-go/tools/cmd/am-gen@latest
```

--------------------------------

### Generate project boilerplate with am-gen starter-kit

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/getting-started.md

Generates a starter kit project from schema.yml with name MyMach and URI mymach. Creates the file structure shown in the following tree output.

```bash
am-gen starter-kit schema.yml --name MyMach --uri mymach
```

--------------------------------

### Create and start an RPC server

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/rpc/README.md

Initializes an RPC server with a source machine, starts it, waits for the RpcReady state, and reacts to client state changes. The server handles one client at a time and pushes local machine time changes every PushInterval.

```go
import (
    amhelp "github.com/pancsta/asyncmachine-go/pkg/helpers"
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    arpc "github.com/pancsta/asyncmachine-go/pkg/rpc"
    ssrpc "github.com/pancsta/asyncmachine-go/pkg/rpc/states"
)

// ...

var addr string
var netMach *am.Machine

// init
s, err := arpc.NewServer(ctx, addr, "server", sourceMach, &arpc.ServerOpts{
    Parent: machParent,
})
if err != nil {
    panic(err)
}

// start
s.Start()
err = amhelp.WaitForAll(ctx, 2*time.Second,
    s.Mach.When1(ssrpc.ServerStates.RpcReady, ctx))
if ctx.Err() != nil {
    return
}
if err != nil {
    return err
}

// react to the client
<-netMach.When1("Foo", nil)
print("Client added Foo")
netMach.Add1("Bar", nil)
```

--------------------------------

### Installation imports for helpers and testing

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/helpers/README.md

Import the helpers package for production code and the testing subpackage for tests. Use the amhelp alias for both.

```go
// prod
import amhelp "github.com/pancsta/asyncmachine-go/pkg/helpers"
// tests
import amhelp "github.com/pancsta/asyncmachine-go/pkg/helpers/testing"
```

--------------------------------

### Peer Init: Create and connect a PubSub topic peer

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/pubsub/README.md

Initializes a new PubSub topic peer with ampubsub.NewTopic, sets the connection address of an existing peer, starts the peer, waits for the Connected state, and then adds the Joining state. Requires importing the pubsub package and its states, and defining the TopicStates variable.

```go
import (
    ma "github.com/multiformats/go-multiaddr"
    ampubsub "github.com/pancsta/asyncmachine-go/pkg/pubsub"
    ssps "github.com/pancsta/asyncmachine-go/pkg/pubsub/states"
)

var ss = states.TopicStates

// ...

// new pubsub peer
ps, _ := ampubsub.NewTopic(ctx, t.Name(), name, machs, nil)
// address of an existing peer
a, _ := ma.NewMultiaddr("/ip4/127.0.0.1/udp/75343/quic-v1")
addrs := []ma.Multiaddr{a}

// connect
ps.ConnAddrs = addrs
ps.Start()
<-ps.Mach.When1(ss.Connected, ctx)
ps.Mach.Add1(ss.Joining, nil)
```

--------------------------------

### MachDebugEnv

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/helpers/README.md

Starts a debug server for the state machine using environment variables for configuration. Useful for inspecting machine state and transitions.

```APIDOC
## MachDebugEnv

### Description
Starts a debug server for the state machine using environment variables for configuration. Useful for inspecting machine state and transitions.

### Method
Function

### Signature
`MachDebugEnv(mach am.Api) error`

### Parameters
- **mach** (am.Api) - Required - The state machine instance.

### Returns
- **error** - An error if the debug server fails to start.

```

--------------------------------

### New (MCP)

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/integrations/README.md

Creates a new MCP server for a state machine. The example shows how to create an MCP server with custom options and start it on a port.

```APIDOC
## New (MCP)

### Description
Creates a new MCP server for a state machine. The example shows how to create an MCP server with custom options and start it on a port.

### Method
New

### Endpoint
ammcp.New(mach, opts)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **mach** (am.Api) - Required - The state machine API.
- **opts** (ammcp.Opts) - Required - Options for the MCP server.

### Response
#### Success Response
- **srv** (*ammcp.Server) - The MCP server.
- **error** (error) - Returns an error if creation fails.

### Request Example
```go
import ammcp "github.com/pancsta/asyncmachine-go/pkg/integrations/mcp-go"

// ...

var mach am.Api

srv, err := ammcp.New(mach, ammcp.Opts{
    Name: "am-dbg",
    Desc: "MCP to control the asyncmachine-go TUI debugger." +
        " The double-line border panel is currently focused. Most features are accessible via ToggleTool.",
    MutCallback: func(ctx context.Context) error {
        ok := d.Mach.Eval("MCPTool", func() {
            d.hRedrawFull(false)
        }, ctx)
        if !ok {
            return am.ErrEvalTimeout
        }
        return nil
    },
    StatesInclude:  states.DebuggerGroups.Mcp,
    StatesReadonly: states.DebuggerGroups.McpReadonly,
    Args:           types.ARpc{},
    ParseRpc:       types.ParseRpc,
    StateCalls:     types.StateCalls,
    Version:        d.params.Version,
})
if err != nil {
    return nil, err
}
srv.Http.Start(":8753")
```
```

--------------------------------

### Run am-dbg with pre-generated data

Source: https://github.com/pancsta/asyncmachine-go/blob/main/examples/wasm/README.md

Starts the TUI debugger with data pre-generated by this example, connecting to the server-foo machine. Uses the am-dbg tool and imports data from a remote URL.

```bash
go run github.com/pancsta/asyncmachine-go/tools/cmd/am-dbg@latest \
  --import-data https://assets.asyncmachine.dev/am-dbg-exports/wasm.gob.br \
  mach://server-foo
```

--------------------------------

### Transaction sequence diagram example (ASCII)

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/release-notes.md

Example ASCII sequence diagram generated by am-vis for transitions with handlers. Shows interactions between ReplaceStories, Start, and Ready states.

```text
┌────────────────┐     ┌───────┐     ┌───────┐
│ ReplaceStories │     │ Start │     │ Ready │
└────────┬───────┘     └───┬───┘     └───┬───┘
         │                 │             │
         │ called          │             │
         ├──┐              │             │
         │  │              │             │
         │◄─┘              │             │
         │                 │             │
         │ activate        │             │
         ├──┐              │             │
         │  │              │             │
         │◄─┘              │             │
         │                 │             │
         │                 │ require     │
         │                 │◄────────────┤
         │                 │             │
         │                 │ require     │
         │                 │◄────────────┤
         │                 │             │
         │ ReplaceStoriesState           │
         ├──┐              │             │
         │  │              │             │
         │◄─┘              │             │
         │                 │             │
```

--------------------------------

### Generated project file tree

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/getting-started.md

Output of `tree my_mach` showing the generated project structure: go.mod, handlers.go, my_mach.go, my_mach_test.go, and states/ss_my_mach.go.

```bash
$ tree my_mach
my_mach
├── go.mod
├── handlers.go
├── my_mach.go
├── my_mach_test.go
└── states
    └── ss_my_mach.go

2 directories, 5 files
```

--------------------------------

### Mux.Start

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/rpc/README.md

Starts the multiplexer, beginning to accept client connections. The multiplexer becomes ready when its `Ready` state is active.

```APIDOC
## Mux.Start

### Description
Starts the multiplexer, beginning to accept client connections. The multiplexer becomes ready when its `Ready` state is active.

### Method
Start

### Signature
`func (m *Mux) Start()`

### Parameters
None

### Returns
None

### Example
```go
mux.Start()
```
```

--------------------------------

### arpc help output

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/arpc/README.md

Shows the full help text for the arpc command, including usage, examples, available commands, and flags. Use this to understand the CLI structure and available options.

```text
aRPC REPL for asyncmachine.dev

Usage:
  arpc ADDR [flags]
  arpc [command]

Examples:
- REPL from an addr
  $ arpc localhost:6452
- REPL from a file
  $ arpc -f mymach.addr
- CLI add states with args
  $ arpc localhost:6452 -- add mach1 Foo Bar \
    --arg name1 --val val1
- CLI add states with args to the first machine
    $ arpc localhost:6452 -- add . Foo Bar \
    --arg name1 --val val1
- CLI wait on 2 states to be active
  $ arpc localhost:6452 -- when mach1 Foo Bar
- CLI add states to a group of machines
  $ arpc localhost:6452 -- group-add -r ma.\* Foo Bar

Mutations
  add          Add states to a single machine
  group-add    Add states to a group of machines
  group-remove Remove states from a group of machines
  remove       Removed states from a single machine

Waiting
  when         Wait for active states of a single machine
  when-not     Wait for inactive states of a single machine
  when-time    Wait for a specific machine time of a single machine

Checking
  inspect      Inspect a single machine
  mach         Show states of a single machine
  time         Show the time of a single machine

REPL
  cheatsheet   Show cheatsheet
  exit         Exit the REPL
  help         Help about any command
  list         List connected machines
  script       Execute a REPL script from a file
  status       Show the connection status

Additional Commands:
  completion   Generate the autocompletion script for the specified shell

Flags:
  -d, --dir    Load *.addr files from a directory
  -f, --file   Load addresses from a file
  -h, --help   help for arpc

Use "arpc [command] --help" for more information about a command.
```

--------------------------------

### am-gen help output

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/am-gen/README.md

Displays the full usage information, including commands, options, and examples for schema, starter-kit, schema-from-file, and grafana.

```bash
am-gen generates state files and Grafana dashboards for asyncmachine-go state machines.

Example:
$ am-gen schema --state State1 --state State2:multi \
	--inherit basic --inherit connected \
	--group Group1 --group Group2 \
	--name MyMach

Example:
$ am-gen starter-kit schema.yml --name MyMach --uri github.com/my/project

Example:
$ am-gen schema-from-file schema.yml --name MyMach

Example:
$ am-gen grafana --IDs MyMach1,MyMach2 \
	--sync grafana-host.com

Valid for --inherit:
- basic
- connected
- disposed
- rpc/statesrc
- node/worker

Usage: am-gen [--version] <command> [<args>]

Options:
  --version, -v          Print version and exit
  --help, -h             display this help and exit

Commands:
  starter-kit            Generate a starter project from schema.yml / mach.yml
  schema                 Generate state schema from CLI params
  schema-from-file       Generate state schema from schema.yml / mach.yml
  grafana                Generate Grafana dashboards
  states-file            Deprecated, use schema
```

--------------------------------

### Run WASM integration test

Source: https://github.com/pancsta/asyncmachine-go/blob/main/examples/wasm/README.md

Runs the integration test that builds the WASM, starts the server, opens the relay address in a headless browser, and asserts bidirectional mutations over aRPC. Requires headless Chrome/Brave (override with AM_WASM_BROWSER) and a bindable RELAY_HTTP_ADDR; skipped with -short.

```bash
go test ./examples/wasm
```

--------------------------------

### BadgerDB history backend example

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/history/README.md

Shows how to set up the BadgerDB key-value history backend with msgpack or JSON encoding. Requires a machine instance and context. The onErr handler is injected for error reporting. The example creates a database, memory instance, mutates the machine, and queries activation history.

```go
import (
    amhist "github.com/pancsta/asyncmachine-go/pkg/history"
    amhistb "github.com/pancsta/asyncmachine-go/pkg/history/badger"
)

// ...

// var mach *am.Machine
// var ctx context.Context

// injected err handler
onErr := func(err error) {
    log.Print(err.Error())
}

// backend and base configs
cfg := Config{
    BaseConfig: amhist.Config{
        MaxRecords: 10 ^ 6,
        TrackedStates: am.S{"A", "C"},
    },
    EncJson: true,
}

// create amhist.db
db, err := amhistb.NewDb("")
defer db.Close()

mem, err := amhistb.NewMemory(ctx, db, mach, cfg, onErr)

// mutate and query
mach.Add1("A", nil)
now := time.Now().UTC()
mem.Sync()
time.Sleep(100 * time.Millisecond)
mem.ActivatedBetween(ctx, "A", now.Add(-time.Second), now) // true
```

--------------------------------

### Initialize and use RPC client (pkg/rpc)

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/release-notes.md

Shows how to create and start an RPC client, wait for the 'Ready' state, and invoke a remote worker method. The client is initialized with a context, address, client ID, and state definitions/names. After starting, it waits for the 'Ready' state before using the remote worker to add 'Foo' and wait for 'Bar'.

```go
// init
c, err := NewClient(ctx, addr, "clientid", ss.States, ss.Names)
if err != nil {
    panic(err)
}

// start
c.Start()
<-c.Mach.When1("Ready", nil)

// use the remote worker
c.Worker.Add1("Foo", nil)
<-c.Worker.When1("Bar", nil)
print("Server added Bar")
```

--------------------------------

### Install arpc with go install

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/arpc/README.md

Installs the arpc binary from the latest release using Go's module tooling. Requires Go installed and configured.

```bash
go install github.com/pancsta/asyncmachine-go/tools/cmd/arpc@latest
```

--------------------------------

### arpc add --help output

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/arpc/README.md

Shows the help text for the `arpc add` command, including usage, an example, and flags for passing arguments. Use this to add states to a single machine with optional named arguments.

```bash
Add states to a single machine

Usage:
  arpc add MACH STATES [flags]

Examples:
$ add mach1 Foo Bar \
  --arg name1 --val val1 \
  --arg name2 --val val2

Flags:
      --arg stringArray   Argument name (repeatable)
  -h, --help              help for add
      --val stringArray   Argument value (repeatable)
```

--------------------------------

### EnableDebugging

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/helpers/README.md

Enables debugging telemetry using conventional environment variables. This is a one-line setup for activating debugging for a single machine or the whole process.

```go
amhelp.EnableDebugging(true)
```

--------------------------------

### arpc list --help output

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/arpc/README.md

Shows the help text for the `arpc list` command, including usage, an example, and all filtering flags. Use this to filter connected machines by active/inactive states, machine time, ID patterns, and more.

```bash
List connected machines

Usage:
  arpc list [flags]

Examples:
list -a Foo -a Bar --mtime-min 1631

Flags:
  -a, --active stringArray         Filter by an active state (repeatable)
  -d, --disconn                    Show disconnected (default true)
  -f, --from int                   Start from this index
  -h, --help                       help for list
  -I, --id-partial string          Substring to match machine IDs
  -p, --id-prefix string           Prefix to match machine IDs
  -r, --id-regexp string           Regexp to match machine IDs
  -s, --id-suffix string           Suffix to match machine IDs
  -i, --inactive stringArray       Filter by an inactive state (repeatable)
  -l, --limit int                  Mutate up to N machines
  -T, --mtime-max uint             Max machine time, e.g. "1631616000"
  -t, --mtime-min uint             Min machine time, e.g. "1631616000"
  -m, --mtime-states stringArray   Take machine time only from these states (repeatable)
  -P, --parent string              Filter by parent ID
  -z, --states                     Print states (default true)
  -Z, --states-all                 Print all states (requires --states)
```

--------------------------------

### Create an MCP server for a state machine with ammcp.New

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/integrations/README.md

Sets up an MCP server for a state machine with typed args using mcp-go. The example configures the server name, description, mutation callback, state filters, and RPC parsing. The server is started on port 8753.

```go
import ammcp "github.com/pancsta/asyncmachine-go/pkg/integrations/mcp-go"

// ...

var mach am.Api

srv, err := ammcp.New(mach, ammcp.Opts{
    Name: "am-dbg",
    Desc: "MCP to control the asyncmachine-go TUI debugger." +
        " The double-line border panel is currently focused. Most features are accessible via ToggleTool.",
    MutCallback: func(ctx context.Context) error {
        ok := d.Mach.Eval("MCPTool", func() {
            d.hRedrawFull(false)
        }, ctx)
        if !ok {
            return am.ErrEvalTimeout
        }
        return nil
    },
    StatesInclude:  states.DebuggerGroups.Mcp,
    StatesReadonly: states.DebuggerGroups.McpReadonly,
    Args:           types.ARpc{},
    ParseRpc:       types.ParseRpc,
    StateCalls:     types.StateCalls,
    Version:        d.params.Version,
})
if err != nil {
    return nil, err
}
srv.Http.Start(":8753")
```

--------------------------------

### arpc when-time --help output

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/arpc/README.md

Shows the help text for the `arpc when-time` command, including usage, an example, and flags for specifying states and times. Use this to wait for a specific machine time of a single state machine.

```bash
Wait for a specific machine time of a single machine

Usage:
  arpc when-time MACH STATES TIMES [flags]

Examples:
when-time mach1 -s Foo -t 1000 -s Bar -t 2000

Flags:
  -h, --help                help for when-time
  -s, --state stringArray   State name (repeatable)
  -t, --time stringArray    Machine time (repeatable)
```

--------------------------------

### Go example using TimeIndexAfter for negotiation

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/release-notes.md

Shows how to use TimeIndexAfter to include relations in negotiation. Previously only shallow called states were processed; now relations are included. The example checks if the transition's TimeIndexAfter does not contain the Start state, and if so, allows exit; otherwise checks for UserNarrowLayout.

```go
func (d *Debugger) NarrowLayoutExit(e *am.Event) bool {
    // always allow to exit
    after := e.Transition().TimeIndexAfter()
    if after.Not1(ss.Start) {
        return true
    }

    return after.Not1(ss.UserNarrowLayout)
}
```

--------------------------------

### RPC Multiplexer with custom server

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/cookbook.md

Creates a multiplexer with a custom NewServerFn that configures a default server with instant push and starts it.

```go
mux, err := arpc.NewMux(ctx, cfg.Web.AddrAgent(), "server-"+mach.Id(), mach, &arpc.MuxOpts{
    Parent: mach,
    NewServerFn: func(mux *arpc.Mux, id string, conn net.Conn) (*arpc.Server, error) {
        srv, err := mux.NewDefaultServer(id)
        if err != nil {
            return nil, err
        }

        // instant push
        srv.PushInterval.Store(new(10 * time.Millisecond))
        srv.Conn = conn
        srv.Start(e)

        return srv, nil
    },
})
```

--------------------------------

### Common init (am.NewCommon)

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/editors/mini.md

Initializes a new asyncmachine machine using am.NewCommon with the provided states, names, and options. Requires importing the machine package and a states package (replace PACKAGE with the actual import path). The example sets LogLevel to am.LogChanges and passes a parent machine.

```go
import (
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    ss "PACKAGE/states"
)
// ...
mach, err := am.NewCommon(ctx, "mach1", ss.States, ss.Names, nil, nil, &am.Opts{
  LogLevel: am.LogChanges,
  Parent: machParent,
})
```

--------------------------------

### Render machine diagram with am-vis

Source: https://github.com/pancsta/asyncmachine-go/blob/main/examples/wasm/README.md

Renders the machine diagram from the am-dbg dump file using the am-vis tool. The command is run from the example directory.

```bash
# render
am-vis --bird render-dump am-dbg-dump.gob.br
```

--------------------------------

### Example Schema File (Go)

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/am-gen/README.md

Defines states, groups, and schema for a state machine using asyncmachine-go. Inherits from built-in states and groups, and includes a constructor function.

```go
package states

import (
	"context"
	am "github.com/pancsta/asyncmachine-go/pkg/machine"
	ssam "github.com/pancsta/asyncmachine-go/pkg/states"
	. "github.com/pancsta/asyncmachine-go/pkg/states/global"
)

// MyMachStatesDef contains all the states of the [MyMach] state-machine.
type MyMachStatesDef struct {
	*am.StatesBase

	State1 string
	State2 string

	// inherit from BasicStatesDef
	*ssam.BasicStatesDef
	// inherit from ConnectedStatesDef
	*ssam.ConnectedStatesDef
}

// MyMachGroupsDef contains all the state groups [MyMach] state-machine.
type MyMachGroupsDef struct {
	*ssam.ConnectedGroupsDef
	Group1 S
	Group2 S
}

// MyMachSchema represents all relations and properties of [MyMachStates].
var MyMachSchema = am.Schema{}.Merge(
	// inherit from BasicSchema
	ssam.BasicSchema,
	// inherit from ConnectedSchema
	ssam.ConnectedSchema,
	am.Schema{
		ssM.State1: {},
		ssM.State2: {
			Multi: true,
		},
	},
)

// EXPORTS AND GROUPS
var (
	ssM = am.NewStates(MyMachStatesDef{})
	sgM = am.NewStateGroups(MyMachGroupsDef{
		Group1: S{},
		Group2: S{},
	}, ssam.ConnectedGroups)

	// MyMachStates contains all the states for the [MyMach] state-machine.
	MyMachStates = ssM
	// MyMachGroups contains all the state groups for the [MyMach] state-machine.
	MyMachGroups = sgM
)

// NewMyMach creates a new [MyMach] state-machine in the most basic form.
func NewMyMach(ctx context.Context) *am.Machine {
	return am.New(ctx, MyMachSchema, nil)
}

```

--------------------------------

### Manual Loki Setup with promtail and amtele.BindLokiLogger

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/telemetry/README.md

Manually initializes a promtail client and binds it to the machine's logger. Requires a running Loki instance at localhost:3100 and a service name for identifiers.

```go
import (
    "github.com/ic2hrmk/promtail"
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    amtele "github.com/pancsta/asyncmachine-go/pkg/telemetry"
)

// ...

var mach *am.Machine
var service string

// init promtail and bind AM logger
identifiers := map[string]string{
    "service_name": service,
}
promtailClient, err := promtail.NewJSONv1Client("localhost:3100", identifiers)
if err != nil {
    panic(err)
}
defer promtailClient.Close()
amtele.BindLokiLogger(mach, promtailClient)
```

--------------------------------

### am-vis CLI help and usage examples

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/am-vis/README.md

Shows the am-vis command-line help, including usage, options, and commands. The examples illustrate rendering diagrams from a debugger dump file with various presets (bird's view, map view) and options like --bird, --map, --render-pipes, --render-inherited, and inspect-dump.

```bash
$ am-vis render-dump --help
```

```bash
Render diagrams of interconnected state machines.

Examples:

# single machine
am-vis render-dump mymach.gob.br mach://MyMach1/t234

# bird's view with distance of 2 from MyMach1
am-vis --bird -d 2 \
        render-dump mymach.gob.br mach://MyMach1/TX-ID

# bird's view with grouped pipes
am-vis --bird --render-pipes --render-detailed-pipes=false \
        render-dump mymach.gob.br mach://MyMach1/TX-ID

# map view with inherited states
am-vis --render-inherited \
        render-dump mymach.gob.br mach://MyMach1/t234

# map view
am-vis --map render-dump mymach.gob.br

# inspect dump as Markdown
am-vis inspect-dump mymach.gob.br

Usage: am-vis [--render-distance RENDER-DISTANCE] [--render-depth RENDER-DEPTH] [--render-start] [--render-ready] [--render-exception] [--render-states] [--render-inherited] [--render-pipes] [--render-detailed-pipes] [--render-relations] [--render-conns] [--render-parent-rel] [--render-half-conns] [--render-half-pipes] [--render-nest-submachines] [--render-tags] [--bird] [--map] [--output-elk] [--output-filename OUTPUT-FILENAME] [--debug] [--version] <command> [<args>]

Options:
  --render-distance RENDER-DISTANCE, -d RENDER-DISTANCE [default: 0]
  --render-depth RENDER-DEPTH [default: 0]
  --render-start [default: false]
  --render-ready [default: false]
  --render-exception [default: false]
  --render-states [default: true]
  --render-inherited [default: true]
  --render-pipes [default: false]
  --render-detailed-pipes [default: true]
  --render-relations [default: true]
  --render-conns [default: true]
  --render-parent-rel [default: true]
  --render-half-conns [default: true]
  --render-half-pipes [default: true]
  --render-nest-submachines [default: false]
  --render-tags [default: false]
  --bird, -b             Use the bird's view preset
  --map, -b              Use the map view preset
  --output-elk           Use ELK layout [default: true]
  --output-filename OUTPUT-FILENAME, -o OUTPUT-FILENAME [default: am-vis]
  --debug                Enable debugging for asyncmachine
  --version, -v          Print version and exit
  --help, -h             display this help and exit

Commands:
  render-dump            Render from a debugger dump file
  inspect-dump           Render text form from a debugger dump file
```

--------------------------------

### Run arpc with go run

Source: https://github.com/pancsta/asyncmachine-go/blob/main/tools/cmd/arpc/README.md

Runs the arpc command directly without installing, useful for quick testing or development.

```bash
go run github.com/pancsta/asyncmachine-go/tools/cmd/arpc@latest
```

--------------------------------

### Prometheus Metrics: Manual setup with BindMach, BindToRegistry, BindToPusher

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/telemetry/README.md

Manually binds machine transitions to metrics and then binds the metrics to either a Prometheus registry or a pusher. Use when you need custom registry or pusher configuration.

```go
import (
    "time"
    am "github.com/pancsta/asyncmachine-go/pkg/machine"
    amprom "github.com/pancsta/asyncmachine-go/pkg/telemetry/prometheus"
    "github.com/prometheus/client_golang/prometheus/push"
)

// ...

var mach *am.Machine
var promRegistry *prometheus.Registry
var promPusher *push.Pusher

// bind transition to metrics
metrics := amprom.BindMach(mach)

// bind metrics either a registry or a pusher
amprom.BindToRegistry(promRegistry)
amprom.BindToPusher(promPusher)
```

--------------------------------

### am-dbg --client-list file.txt output example

Source: https://github.com/pancsta/asyncmachine-go/blob/main/docs/release-notes.md

Example output of the am-dbg --client-list am-dbg.txt command, showing a live detailed dump of clients with tags and peer IDs. The file refreshes automatically to match the current TUI view.

```bash
ps-TestExposingMany-p0-root   R|85+
  #pubsub:TestExposingMany
  #peer:12D3KooWKBTjhWff2Vd1xbW41duMp5hJmZsBnfGrcNz4vL7XNpuy
- ps-rand-p1-0-065a            |0
    #pubsub-worker
    #src-id:rand-p1-0
- ps-rand-p1-1-41b0            |0
    #pubsub-worker
    #src-id:rand-p1-1
- ps-rand-p1-2-ab80            |0
    #pubsub-worker
    #src-id:rand-p1-2
- ps-rand-p3-0-7408            |0
    #pubsub-worker
    #src-id:rand-p3-0
- ps-rand-p3-1-8476            |0
    #pubsub-worker
    #src-id:rand-p3-1
- ps-rand-p3-2-2787            |0
    #pubsub-worker
    #src-id:rand-p3-2
- ps-rand-p4-0-1f7e            |0
    #pubsub-worker
    #src-id:rand-p4-0
- ps-rand-p4-1-5590            |0
    #pubsub-worker
    #src-id:rand-p4-1
- ps-rand-p4-2-74d8            |0
    #pubsub-worker
    #src-id:rand-p4-2
- ps-rand-p5-0-3728            |1
    #pubsub-worker
    #src-id:rand-p5-0
- ps-rand-p5-1-e61a            |1
    #pubsub-worker
    #src-id:rand-p5-1
- ps-rand-p5-2-fc37            |1
    #pubsub-worker
    #src-id:rand-p5-2

ps-TestExposingMany-p1        S|102+
  #pubsub:TestExposingMany
  #peer:12D3KooWJ6a95r7XZrHXJ8YonNH3xnwWgfdEpcPDTTmEv2Ypdh9Z
- ps-rand-p3-0-831a            |0
    #pubsub-worker
    #src-id:rand-p3-0
- ps-rand-p3-1-c081            |0
    #pubsub-worker
    #src-id:rand-p3-1
- ps-rand-p3-2-1248            |0
    #pubsub-worker
    #src-id:rand-p3-2
- ps-rand-p4-0-370b            |0
    #pubsub-worker
    #src-id:rand-p4-0
- ps-rand-p4-1-4909            |0
    #pubsub-worker
    #src-id:rand-p4-1
- ps-rand-p4-2-069f            |0
    #pubsub-worker
    #src-id:rand-p4-2
- ps-rand-p5-0-783d            |1
    #pubsub-worker
    #src-id:rand-p5-0
- ps-rand-p5-1-a73f            |1
    #pubsub-worker
    #src-id:rand-p5-1
- ps-rand-p5-2-9d04            |1
    #pubsub-worker
    #src-id:rand-p5-2
```

--------------------------------

### BoltDB Key-Value History Example

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/history/README.md

Sets up a BoltDB-backed history store with msgpack or JSON encoding, injects an error handler, and demonstrates a mutation and query. Requires an existing machine and context. The example creates amhist.db and uses MaxRecords, TrackedStates, and EncJson config options.

```go
import (
    amhist "github.com/pancsta/asyncmachine-go/pkg/history"
    amhistbb "github.com/pancsta/asyncmachine-go/pkg/history/bbolt"
)

// ...

// var mach *am.Machine
// var ctx context.Context

// injected err handler
onErr := func(err error) {
    log.Print(err.Error())
}

// backend and base configs
cfg := Config{
    BaseConfig: amhist.Config{
        MaxRecords: 10 ^ 6,
        TrackedStates: am.S{"A", "C"},
    },
    EncJson: true,
}

// create amhist.db
db, err := amhistbb.NewDb("")
defer db.Close()

mem, err := amhistbb.NewMemory(ctx, db, mach, cfg, onErr)

// mutate and query
mach.Add1("A", nil)
now := time.Now().UTC()
mem.Sync()
time.Sleep(100 * time.Millisecond)
mem.ActivatedBetween(ctx, "A", now.Add(-time.Second), now) // true
```

--------------------------------

### Import states package

Source: https://github.com/pancsta/asyncmachine-go/blob/main/pkg/states/README.md

Import the asyncmachine-go states package to use common state schema mixins.

```go
import ssam "github.com/pancsta/asyncmachine-go/pkg/states"
```
Tokens:
Raw