|
| 1 | +--- |
| 2 | +title: Actions |
| 3 | +description: Named, registered, invokable units of work — the capability map of every Core instance. |
| 4 | +--- |
| 5 | + |
| 6 | +Actions are the atomic unit of work in `core/go`. Named, registered, invokable, |
| 7 | +inspectable. The Action registry **is** the capability map. |
| 8 | + |
| 9 | +## Register |
| 10 | + |
| 11 | +```go |
| 12 | +c.Action("git.log", func(ctx core.Context, opts core.Options) core.Result { |
| 13 | + dir := opts.String("dir") |
| 14 | + return c.Process().RunIn(ctx, dir, "git", "log") |
| 15 | +}) |
| 16 | +``` |
| 17 | + |
| 18 | +The signature is invariant across every action: |
| 19 | + |
| 20 | +```go |
| 21 | +type ActionHandler func(core.Context, core.Options) core.Result |
| 22 | +``` |
| 23 | + |
| 24 | +## Invoke |
| 25 | + |
| 26 | +```go |
| 27 | +r := c.Action("git.log").Run(ctx, core.NewOptions( |
| 28 | + core.Option{Key: "dir", Value: "/path/to/repo"}, |
| 29 | +)) |
| 30 | +``` |
| 31 | + |
| 32 | +## Lifecycle — Enable / Disable |
| 33 | + |
| 34 | +Actions are enabled at registration. Disable to soft-stop without unregistering: |
| 35 | + |
| 36 | +```go |
| 37 | +c.Action("dangerous.purge").Disable() |
| 38 | +// ...later... |
| 39 | +c.Action("dangerous.purge").Enable() |
| 40 | + |
| 41 | +if c.Action("dangerous.purge").Enabled() { /* will fire */ } |
| 42 | +``` |
| 43 | + |
| 44 | +`Run()` on a disabled action returns `Result{OK: false}` with code `"action.disabled"`. |
| 45 | +The capability stays queryable via `Exists()`. |
| 46 | + |
| 47 | +## Inspect |
| 48 | + |
| 49 | +| Method | What it returns | |
| 50 | +|---|---| |
| 51 | +| `c.Action(name).Exists()` | `true` if a handler is registered | |
| 52 | +| `c.Action(name).Enabled()` | `true` if it will run when invoked | |
| 53 | +| `c.Actions()` | All registered action names in registration order | |
| 54 | + |
| 55 | +## Background — `PerformAsync` |
| 56 | + |
| 57 | +For long-running work that shouldn't block the request path: |
| 58 | + |
| 59 | +```go |
| 60 | +r := c.PerformAsync("agentic.dispatch", opts) |
| 61 | +taskID := r.Value.(string) |
| 62 | +// ActionTaskStarted / ActionTaskProgress / ActionTaskCompleted broadcast on IPC |
| 63 | +``` |
| 64 | + |
| 65 | +`Progress` updates a running task: |
| 66 | + |
| 67 | +```go |
| 68 | +c.Progress(taskID, 0.5, "halfway done", "agentic.dispatch") |
| 69 | +``` |
| 70 | + |
| 71 | +## Composition — Tasks |
| 72 | + |
| 73 | +A `Task` is a named sequence of action steps: |
| 74 | + |
| 75 | +```go |
| 76 | +c.Task("agent.completion", core.Task{ |
| 77 | + Steps: []core.Step{ |
| 78 | + {Action: "agentic.qa"}, |
| 79 | + {Action: "agentic.auto-pr"}, |
| 80 | + {Action: "agentic.verify", Input: "previous"}, |
| 81 | + {Action: "agentic.poke", Async: true}, |
| 82 | + }, |
| 83 | +}) |
| 84 | + |
| 85 | +r := c.Task("agent.completion").Run(ctx, c, opts) |
| 86 | +``` |
| 87 | + |
| 88 | +Sync steps run sequentially — failure stops the chain. Async steps fire-and-forget. |
| 89 | +`Input: "previous"` pipes the last sync step's output as `_input` on the next. |
| 90 | + |
| 91 | +## Why named actions |
| 92 | + |
| 93 | +The registry IS the capability map. Auditable, testable, swappable. Permission |
| 94 | +boundaries (entitlements) and observability (broadcast events) attach at a single |
| 95 | +choke point — `Action.Run` — instead of being threaded through every call site. |
| 96 | + |
| 97 | +## Source |
| 98 | + |
| 99 | +[`action.go`](https://github.com/dappcore/go/blob/main/action.go) — full |
| 100 | +implementation including the panic recovery, entitlement check, and Task runner. |
0 commit comments