@tagma/sdk 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +139 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1 +1,139 @@
|
|
|
1
|
-
# tagma
|
|
1
|
+
# @tagma/sdk
|
|
2
|
+
|
|
3
|
+
A local AI task orchestration SDK for [Bun](https://bun.sh). Define multi-track pipelines in YAML, run AI coding agents (Claude Code, Codex, OpenCode) and shell commands in parallel with dependency resolution, approval gates, and lifecycle hooks.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
bun add @tagma/sdk
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
**1. Define a pipeline** (`pipeline.yaml`)
|
|
14
|
+
|
|
15
|
+
```yaml
|
|
16
|
+
pipeline:
|
|
17
|
+
name: build-and-test
|
|
18
|
+
tracks:
|
|
19
|
+
- id: backend
|
|
20
|
+
name: Backend
|
|
21
|
+
driver: claude-code
|
|
22
|
+
permissions: { read: true, write: true, execute: false }
|
|
23
|
+
tasks:
|
|
24
|
+
- id: implement
|
|
25
|
+
name: Implement feature
|
|
26
|
+
prompt: "Add a /health endpoint to src/server.ts"
|
|
27
|
+
output: ./output/implement.txt
|
|
28
|
+
- id: test
|
|
29
|
+
name: Run tests
|
|
30
|
+
command: "bun test"
|
|
31
|
+
depends_on: [implement]
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
**2. Run it programmatically**
|
|
35
|
+
|
|
36
|
+
```ts
|
|
37
|
+
import {
|
|
38
|
+
bootstrapBuiltins,
|
|
39
|
+
loadPipeline,
|
|
40
|
+
runPipeline,
|
|
41
|
+
InMemoryApprovalGateway,
|
|
42
|
+
} from '@tagma/sdk';
|
|
43
|
+
|
|
44
|
+
// Register built-in drivers, triggers, completions
|
|
45
|
+
bootstrapBuiltins();
|
|
46
|
+
|
|
47
|
+
const yaml = await Bun.file('pipeline.yaml').text();
|
|
48
|
+
const config = await loadPipeline(yaml, process.cwd());
|
|
49
|
+
|
|
50
|
+
const result = await runPipeline(config, process.cwd());
|
|
51
|
+
console.log(result.success ? 'Done' : 'Failed');
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Features
|
|
55
|
+
|
|
56
|
+
- **Multi-track DAG execution** -- tasks run in parallel across tracks, respecting `depends_on` ordering
|
|
57
|
+
- **Driver plugins** -- built-in `claude-code` driver; install `@tagma/driver-codex` or `@tagma/driver-opencode` for other agents
|
|
58
|
+
- **Session handoff** -- `continue_from` passes context between tasks (session resume or text injection)
|
|
59
|
+
- **Approval gates** -- trigger-based approval with stdin and WebSocket adapters
|
|
60
|
+
- **Lifecycle hooks** -- `pipeline_start`, `task_start`, `task_success`, `task_failure`, `pipeline_complete`, `pipeline_error`
|
|
61
|
+
- **Middleware** -- enrich prompts before execution (e.g. inject static context)
|
|
62
|
+
- **Completion checks** -- validate task output with `exit_code`, `file_exists`, or `output_check` plugins
|
|
63
|
+
- **Template expansion** -- reusable task templates with parameterized `use` / `with`
|
|
64
|
+
|
|
65
|
+
## Pipeline YAML Reference
|
|
66
|
+
|
|
67
|
+
```yaml
|
|
68
|
+
pipeline:
|
|
69
|
+
name: my-pipeline
|
|
70
|
+
driver: claude-code # default driver for all tasks
|
|
71
|
+
timeout: 30m # pipeline-level timeout
|
|
72
|
+
plugins: # load external driver plugins
|
|
73
|
+
- "@tagma/driver-codex"
|
|
74
|
+
hooks:
|
|
75
|
+
pipeline_start: "echo starting"
|
|
76
|
+
task_failure: "notify-slack.sh"
|
|
77
|
+
tracks:
|
|
78
|
+
- id: track-1
|
|
79
|
+
name: Track One
|
|
80
|
+
model_tier: high # high | medium | low
|
|
81
|
+
permissions:
|
|
82
|
+
read: true
|
|
83
|
+
write: true
|
|
84
|
+
execute: false
|
|
85
|
+
on_failure: skip_downstream # skip_downstream | stop_all | ignore
|
|
86
|
+
tasks:
|
|
87
|
+
- id: task-a
|
|
88
|
+
name: Do something
|
|
89
|
+
prompt: "Your prompt here"
|
|
90
|
+
output: ./output/task-a.txt
|
|
91
|
+
timeout: 10m
|
|
92
|
+
- id: task-b
|
|
93
|
+
name: Follow up
|
|
94
|
+
prompt: "Continue the work"
|
|
95
|
+
continue_from: task-a
|
|
96
|
+
depends_on: [task-a]
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## API
|
|
100
|
+
|
|
101
|
+
### `bootstrapBuiltins()`
|
|
102
|
+
|
|
103
|
+
Registers all built-in plugins (claude-code driver, file/manual triggers, completion checks, static-context middleware).
|
|
104
|
+
|
|
105
|
+
### `loadPipeline(yaml: string, workDir: string): Promise<PipelineConfig>`
|
|
106
|
+
|
|
107
|
+
Parses YAML, resolves inheritance, expands templates, and validates the configuration.
|
|
108
|
+
|
|
109
|
+
### `runPipeline(config, workDir, options?): Promise<EngineResult>`
|
|
110
|
+
|
|
111
|
+
Executes the pipeline. Returns `{ success, summary, states }`.
|
|
112
|
+
|
|
113
|
+
Options:
|
|
114
|
+
- `approvalGateway` -- custom `ApprovalGateway` instance (defaults to `InMemoryApprovalGateway`)
|
|
115
|
+
|
|
116
|
+
### `loadPlugins(names: string[]): Promise<void>`
|
|
117
|
+
|
|
118
|
+
Dynamically loads and registers external plugin packages.
|
|
119
|
+
|
|
120
|
+
### `attachStdinApprovalAdapter(gateway): StdinApprovalAdapter`
|
|
121
|
+
|
|
122
|
+
Attaches an interactive stdin-based approval handler.
|
|
123
|
+
|
|
124
|
+
### `attachWebSocketApprovalAdapter(gateway, options?): WebSocketApprovalAdapter`
|
|
125
|
+
|
|
126
|
+
Starts a WebSocket server for remote approval decisions.
|
|
127
|
+
|
|
128
|
+
## Related Packages
|
|
129
|
+
|
|
130
|
+
| Package | Description |
|
|
131
|
+
|---|---|
|
|
132
|
+
| [@tagma/types](https://www.npmjs.com/package/@tagma/types) | Shared TypeScript types |
|
|
133
|
+
| [@tagma/driver-codex](https://www.npmjs.com/package/@tagma/driver-codex) | Codex CLI driver plugin |
|
|
134
|
+
| [@tagma/driver-opencode](https://www.npmjs.com/package/@tagma/driver-opencode) | OpenCode CLI driver plugin |
|
|
135
|
+
| [@tagma/cli](https://www.npmjs.com/package/@tagma/cli) | CLI runner |
|
|
136
|
+
|
|
137
|
+
## License
|
|
138
|
+
|
|
139
|
+
MIT
|