@action-llama/action-llama 0.13.6 → 0.14.1

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.
Files changed (221) hide show
  1. package/agent-docs/AGENTS.md +123 -207
  2. package/dist/agents/container-entry.d.ts +1 -3
  3. package/dist/agents/container-entry.d.ts.map +1 -1
  4. package/dist/agents/container-entry.js +208 -154
  5. package/dist/agents/container-entry.js.map +1 -1
  6. package/dist/agents/container-runner.d.ts.map +1 -1
  7. package/dist/agents/container-runner.js +19 -8
  8. package/dist/agents/container-runner.js.map +1 -1
  9. package/dist/agents/context-injection.d.ts +7 -0
  10. package/dist/agents/context-injection.d.ts.map +1 -0
  11. package/dist/agents/context-injection.js +27 -0
  12. package/dist/agents/context-injection.js.map +1 -0
  13. package/dist/agents/execution-engine.d.ts.map +1 -1
  14. package/dist/agents/execution-engine.js +99 -109
  15. package/dist/agents/execution-engine.js.map +1 -1
  16. package/dist/agents/model-fallback.d.ts +18 -0
  17. package/dist/agents/model-fallback.d.ts.map +1 -0
  18. package/dist/agents/model-fallback.js +40 -0
  19. package/dist/agents/model-fallback.js.map +1 -0
  20. package/dist/agents/prompt.d.ts +9 -2
  21. package/dist/agents/prompt.d.ts.map +1 -1
  22. package/dist/agents/prompt.js +21 -49
  23. package/dist/agents/prompt.js.map +1 -1
  24. package/dist/agents/runner.d.ts +2 -0
  25. package/dist/agents/runner.d.ts.map +1 -1
  26. package/dist/agents/runner.js +142 -124
  27. package/dist/agents/runner.js.map +1 -1
  28. package/dist/agents/session-factory.d.ts +13 -0
  29. package/dist/agents/session-factory.d.ts.map +1 -0
  30. package/dist/agents/session-factory.js +27 -0
  31. package/dist/agents/session-factory.js.map +1 -0
  32. package/dist/build-info.json +1 -1
  33. package/dist/cli/commands/agent.d.ts.map +1 -1
  34. package/dist/cli/commands/agent.js +43 -23
  35. package/dist/cli/commands/agent.js.map +1 -1
  36. package/dist/cli/commands/chat.d.ts.map +1 -1
  37. package/dist/cli/commands/chat.js +26 -43
  38. package/dist/cli/commands/chat.js.map +1 -1
  39. package/dist/cli/commands/claude.d.ts +4 -0
  40. package/dist/cli/commands/claude.d.ts.map +1 -0
  41. package/dist/cli/commands/claude.js +8 -0
  42. package/dist/cli/commands/claude.js.map +1 -0
  43. package/dist/cli/commands/doctor.d.ts.map +1 -1
  44. package/dist/cli/commands/doctor.js +24 -6
  45. package/dist/cli/commands/doctor.js.map +1 -1
  46. package/dist/cli/commands/mcp.d.ts +8 -0
  47. package/dist/cli/commands/mcp.d.ts.map +1 -0
  48. package/dist/cli/commands/mcp.js +31 -0
  49. package/dist/cli/commands/mcp.js.map +1 -0
  50. package/dist/cli/commands/new.d.ts.map +1 -1
  51. package/dist/cli/commands/new.js +15 -6
  52. package/dist/cli/commands/new.js.map +1 -1
  53. package/dist/cli/commands/run.js +1 -1
  54. package/dist/cli/commands/run.js.map +1 -1
  55. package/dist/cli/commands/start.js +2 -2
  56. package/dist/cli/commands/start.js.map +1 -1
  57. package/dist/cli/commands/stats.d.ts +9 -0
  58. package/dist/cli/commands/stats.d.ts.map +1 -0
  59. package/dist/cli/commands/stats.js +149 -0
  60. package/dist/cli/commands/stats.js.map +1 -0
  61. package/dist/cli/commands/status.d.ts.map +1 -1
  62. package/dist/cli/commands/status.js +3 -0
  63. package/dist/cli/commands/status.js.map +1 -1
  64. package/dist/cli/main.js +50 -3
  65. package/dist/cli/main.js.map +1 -1
  66. package/dist/gateway/index.d.ts +3 -0
  67. package/dist/gateway/index.d.ts.map +1 -1
  68. package/dist/gateway/index.js +7 -1
  69. package/dist/gateway/index.js.map +1 -1
  70. package/dist/gateway/lock-store.d.ts +10 -0
  71. package/dist/gateway/lock-store.d.ts.map +1 -1
  72. package/dist/gateway/lock-store.js +38 -0
  73. package/dist/gateway/lock-store.js.map +1 -1
  74. package/dist/gateway/routes/dashboard.d.ts +2 -1
  75. package/dist/gateway/routes/dashboard.d.ts.map +1 -1
  76. package/dist/gateway/routes/dashboard.js +26 -6
  77. package/dist/gateway/routes/dashboard.js.map +1 -1
  78. package/dist/gateway/routes/locks.d.ts.map +1 -1
  79. package/dist/gateway/routes/locks.js +39 -0
  80. package/dist/gateway/routes/locks.js.map +1 -1
  81. package/dist/gateway/routes/logs.d.ts.map +1 -1
  82. package/dist/gateway/routes/logs.js +4 -5
  83. package/dist/gateway/routes/logs.js.map +1 -1
  84. package/dist/gateway/routes/stats.d.ts +4 -0
  85. package/dist/gateway/routes/stats.d.ts.map +1 -0
  86. package/dist/gateway/routes/stats.js +25 -0
  87. package/dist/gateway/routes/stats.js.map +1 -0
  88. package/dist/gateway/views/agent-detail-page.d.ts +12 -0
  89. package/dist/gateway/views/agent-detail-page.d.ts.map +1 -0
  90. package/dist/gateway/views/agent-detail-page.js +303 -0
  91. package/dist/gateway/views/agent-detail-page.js.map +1 -0
  92. package/dist/gateway/views/dashboard-page.d.ts.map +1 -1
  93. package/dist/gateway/views/dashboard-page.js +179 -245
  94. package/dist/gateway/views/dashboard-page.js.map +1 -1
  95. package/dist/gateway/views/instance-detail-page.d.ts +24 -0
  96. package/dist/gateway/views/instance-detail-page.d.ts.map +1 -0
  97. package/dist/gateway/views/instance-detail-page.js +277 -0
  98. package/dist/gateway/views/instance-detail-page.js.map +1 -0
  99. package/dist/gateway/views/layout.d.ts +17 -0
  100. package/dist/gateway/views/layout.d.ts.map +1 -0
  101. package/dist/gateway/views/layout.js +153 -0
  102. package/dist/gateway/views/layout.js.map +1 -0
  103. package/dist/gateway/views/login-page.d.ts.map +1 -1
  104. package/dist/gateway/views/login-page.js +24 -37
  105. package/dist/gateway/views/login-page.js.map +1 -1
  106. package/dist/hooks/runner.d.ts +12 -0
  107. package/dist/hooks/runner.d.ts.map +1 -0
  108. package/dist/hooks/runner.js +32 -0
  109. package/dist/hooks/runner.js.map +1 -0
  110. package/dist/mcp/server.d.ts +5 -0
  111. package/dist/mcp/server.d.ts.map +1 -0
  112. package/dist/mcp/server.js +336 -0
  113. package/dist/mcp/server.js.map +1 -0
  114. package/dist/remote/push.d.ts.map +1 -1
  115. package/dist/remote/push.js +6 -1
  116. package/dist/remote/push.js.map +1 -1
  117. package/dist/scheduler/call-dispatcher.d.ts +2 -2
  118. package/dist/scheduler/call-dispatcher.js +3 -3
  119. package/dist/scheduler/call-dispatcher.js.map +1 -1
  120. package/dist/scheduler/execution.d.ts +5 -2
  121. package/dist/scheduler/execution.d.ts.map +1 -1
  122. package/dist/scheduler/execution.js +75 -4
  123. package/dist/scheduler/execution.js.map +1 -1
  124. package/dist/scheduler/gateway-setup.d.ts +2 -0
  125. package/dist/scheduler/gateway-setup.d.ts.map +1 -1
  126. package/dist/scheduler/gateway-setup.js +3 -2
  127. package/dist/scheduler/gateway-setup.js.map +1 -1
  128. package/dist/scheduler/image-builder.js +3 -3
  129. package/dist/scheduler/image-builder.js.map +1 -1
  130. package/dist/scheduler/index.d.ts.map +1 -1
  131. package/dist/scheduler/index.js +16 -3
  132. package/dist/scheduler/index.js.map +1 -1
  133. package/dist/scheduler/shutdown.d.ts +2 -0
  134. package/dist/scheduler/shutdown.d.ts.map +1 -1
  135. package/dist/scheduler/shutdown.js +4 -1
  136. package/dist/scheduler/shutdown.js.map +1 -1
  137. package/dist/scheduler/validation.d.ts.map +1 -1
  138. package/dist/scheduler/validation.js +5 -3
  139. package/dist/scheduler/validation.js.map +1 -1
  140. package/dist/scheduler/watcher.d.ts +1 -1
  141. package/dist/scheduler/watcher.js +1 -1
  142. package/dist/scheduler/webhook-setup.d.ts +2 -0
  143. package/dist/scheduler/webhook-setup.d.ts.map +1 -1
  144. package/dist/scheduler/webhook-setup.js +2 -0
  145. package/dist/scheduler/webhook-setup.js.map +1 -1
  146. package/dist/setup/prompts.d.ts.map +1 -1
  147. package/dist/setup/prompts.js +35 -6
  148. package/dist/setup/prompts.js.map +1 -1
  149. package/dist/setup/scaffold.d.ts +6 -0
  150. package/dist/setup/scaffold.d.ts.map +1 -1
  151. package/dist/setup/scaffold.js +185 -7
  152. package/dist/setup/scaffold.js.map +1 -1
  153. package/dist/shared/config.d.ts +16 -5
  154. package/dist/shared/config.d.ts.map +1 -1
  155. package/dist/shared/config.js +75 -18
  156. package/dist/shared/config.js.map +1 -1
  157. package/dist/shared/credential-refs.d.ts.map +1 -1
  158. package/dist/shared/credential-refs.js +9 -5
  159. package/dist/shared/credential-refs.js.map +1 -1
  160. package/dist/shared/environment.d.ts +0 -1
  161. package/dist/shared/environment.d.ts.map +1 -1
  162. package/dist/shared/environment.js +19 -3
  163. package/dist/shared/environment.js.map +1 -1
  164. package/dist/shared/frontmatter.d.ts +11 -0
  165. package/dist/shared/frontmatter.d.ts.map +1 -0
  166. package/dist/shared/frontmatter.js +30 -0
  167. package/dist/shared/frontmatter.js.map +1 -0
  168. package/dist/shared/paths.d.ts +1 -0
  169. package/dist/shared/paths.d.ts.map +1 -1
  170. package/dist/shared/paths.js +3 -0
  171. package/dist/shared/paths.js.map +1 -1
  172. package/dist/stats/index.d.ts +3 -0
  173. package/dist/stats/index.d.ts.map +1 -0
  174. package/dist/stats/index.js +2 -0
  175. package/dist/stats/index.js.map +1 -0
  176. package/dist/stats/store.d.ts +89 -0
  177. package/dist/stats/store.d.ts.map +1 -0
  178. package/dist/stats/store.js +242 -0
  179. package/dist/stats/store.js.map +1 -0
  180. package/dist/tui/status-tracker.d.ts +6 -1
  181. package/dist/tui/status-tracker.d.ts.map +1 -1
  182. package/dist/tui/status-tracker.js +11 -1
  183. package/dist/tui/status-tracker.js.map +1 -1
  184. package/docker/bin/{al-call → al-subagent} +2 -2
  185. package/docker/bin/{al-check → al-subagent-check} +2 -2
  186. package/docker/bin/{al-wait → al-subagent-wait} +2 -2
  187. package/package.json +8 -21
  188. package/LICENSE +0 -21
  189. package/README.md +0 -192
  190. package/dist/gateway/views/logs-page.d.ts +0 -2
  191. package/dist/gateway/views/logs-page.d.ts.map +0 -1
  192. package/dist/gateway/views/logs-page.js +0 -280
  193. package/dist/gateway/views/logs-page.js.map +0 -1
  194. package/dist/preflight/interpolate.d.ts +0 -10
  195. package/dist/preflight/interpolate.d.ts.map +0 -1
  196. package/dist/preflight/interpolate.js +0 -33
  197. package/dist/preflight/interpolate.js.map +0 -1
  198. package/dist/preflight/providers/git-clone.d.ts +0 -3
  199. package/dist/preflight/providers/git-clone.d.ts.map +0 -1
  200. package/dist/preflight/providers/git-clone.js +0 -36
  201. package/dist/preflight/providers/git-clone.js.map +0 -1
  202. package/dist/preflight/providers/http.d.ts +0 -3
  203. package/dist/preflight/providers/http.d.ts.map +0 -1
  204. package/dist/preflight/providers/http.js +0 -36
  205. package/dist/preflight/providers/http.js.map +0 -1
  206. package/dist/preflight/providers/shell.d.ts +0 -3
  207. package/dist/preflight/providers/shell.d.ts.map +0 -1
  208. package/dist/preflight/providers/shell.js +0 -28
  209. package/dist/preflight/providers/shell.js.map +0 -1
  210. package/dist/preflight/registry.d.ts +0 -4
  211. package/dist/preflight/registry.d.ts.map +0 -1
  212. package/dist/preflight/registry.js +0 -20
  213. package/dist/preflight/registry.js.map +0 -1
  214. package/dist/preflight/runner.d.ts +0 -7
  215. package/dist/preflight/runner.d.ts.map +0 -1
  216. package/dist/preflight/runner.js +0 -28
  217. package/dist/preflight/runner.js.map +0 -1
  218. package/dist/preflight/schema.d.ts +0 -21
  219. package/dist/preflight/schema.d.ts.map +0 -1
  220. package/dist/preflight/schema.js +0 -9
  221. package/dist/preflight/schema.js.map +0 -1
@@ -1,6 +1,6 @@
1
1
  # Action Llama Reference
2
2
 
3
- CLI for running LLM agents on cron/webhooks. Docker isolation, ACTIONS.md prompt, credentials. Gateway: webhooks, locking, agent calls, dashboard.
3
+ CLI for running LLM agents on cron/webhooks. Docker isolation, SKILL.md prompt, credentials. Gateway: webhooks, locking, agent calls, dashboard.
4
4
 
5
5
  Package: `@action-llama/action-llama`. CLI binary: `al`.
6
6
 
@@ -8,20 +8,19 @@ Package: `@action-llama/action-llama`. CLI binary: `al`.
8
8
 
9
9
  ```
10
10
  my-project/
11
- config.toml # Project config — model, local, gateway, webhooks, telemetry (committed)
11
+ config.toml # Project config — models, local, gateway, webhooks, telemetry (committed)
12
12
  .env.toml # Environment binding — selects an environment, can override config (gitignored)
13
13
  Dockerfile # Project base Docker image — shared tools for all agents (committed)
14
14
  AGENTS.md # Shared instructions loaded by `al chat` (interactive only)
15
15
  CLAUDE.md # Instructions for AI dev tools — not read by Action Llama at runtime
16
16
  <agent>/
17
- agent-config.toml # Agent config credentials, schedule, webhooks, model, preflight, params
18
- ACTIONS.md # System prompt — the instructions the LLM follows each run (required)
17
+ SKILL.md # Agent config (YAML frontmatter) + instructions (markdown body)
19
18
  Dockerfile # Custom Docker image for this agent (optional)
20
19
  ```
21
20
 
22
21
  Agent names derive from directory name. `"default"` is reserved.
23
22
 
24
- ### ACTIONS.md — Writing Tips
23
+ ### SKILL.md — Writing Tips
25
24
 
26
25
  - Direct LLM instructions; numbered steps; reference `<agent-config>` for params
27
26
  - `al-status` at milestones, `al-rerun` when backlog remains; keep concise
@@ -32,7 +31,7 @@ The LLM receives two messages:
32
31
 
33
32
  ### System message
34
33
 
35
- `ACTIONS.md` is the system prompt. With gateway, **skill blocks** appended:
34
+ The SKILL.md body is the system prompt. With gateway, **skill blocks** appended:
36
35
 
37
36
  #### Locking skill block (injected when gateway is available)
38
37
 
@@ -82,32 +81,32 @@ rlock-heartbeat "github issue acme/app#42"
82
81
  </skill-lock>
83
82
  ```
84
83
 
85
- #### Calling skill block (injected when gateway is available)
84
+ #### Subagent skill block (injected when gateway is available)
86
85
 
87
86
  ```xml
88
- <skill-call>
89
- ## Skill: Agent-to-Agent Calls
87
+ <skill-subagent>
88
+ ## Skill: Subagents
90
89
 
91
90
  Call other agents and retrieve their results. Calls are **non-blocking** — fire a call, continue working, then check or wait for results.
92
91
 
93
92
  ### Commands
94
93
 
95
- **`al-call <agent>`** — Call another agent. Pass the context via stdin. Returns a call ID.
94
+ **`al-subagent <agent>`** — Call another agent. Pass the context via stdin. Returns a call ID.
96
95
  ```
97
- CALL_ID=$(echo "find competitors for Acme" | al-call researcher | jq -r .callId)
96
+ CALL_ID=$(echo "find competitors for Acme" | al-subagent researcher | jq -r .callId)
98
97
  ```
99
98
 
100
- **`al-check <callId>`** — Check the status of a call. Never blocks.
99
+ **`al-subagent-check <callId>`** — Check the status of a call. Never blocks.
101
100
  ```
102
- al-check "$CALL_ID"
101
+ al-subagent-check "$CALL_ID"
103
102
  ```
104
103
  - Running: `{"status":"running"}`
105
104
  - Completed: `{"status":"completed","returnValue":"..."}`
106
105
  - Error: `{"status":"error","errorMessage":"..."}`
107
106
 
108
- **`al-wait <callId> [callId...] [--timeout N]`** — Wait for one or more calls to complete. Default timeout: 900s.
107
+ **`al-subagent-wait <callId> [callId...] [--timeout N]`** — Wait for one or more calls to complete. Default timeout: 900s.
109
108
  ```
110
- RESULTS=$(al-wait "$CALL_ID1" "$CALL_ID2" --timeout 600)
109
+ RESULTS=$(al-subagent-wait "$CALL_ID1" "$CALL_ID2" --timeout 600)
111
110
  ```
112
111
  Returns a JSON object keyed by call ID with each call's final status.
113
112
 
@@ -124,11 +123,11 @@ echo "Line 1\nLine 2" | al-return
124
123
 
125
124
  ### Guidelines
126
125
  - Calls are non-blocking — fire multiple calls then wait for all at once
127
- - Use `al-wait` to wait for multiple calls efficiently
128
- - Use `al-check` for polling when you want to do work between checks
126
+ - Use `al-subagent-wait` to wait for multiple calls efficiently
127
+ - Use `al-subagent-check` for polling when you want to do work between checks
129
128
  - Called agents cannot call back to the calling agent (no cycles)
130
129
  - There is a depth limit on nested calls to prevent infinite chains
131
- </skill-call>
130
+ </skill-subagent>
132
131
  ```
133
132
 
134
133
  ### User message
@@ -170,7 +169,7 @@ Use standard tools directly: `gh` CLI, `git`, `curl`.
170
169
  <environment>
171
170
  **Filesystem:** The root filesystem is read-only. `/tmp` is the only writable directory.
172
171
  Use `/tmp` for cloning repos, writing scratch files, and any other disk I/O.
173
- Your working directory is `/app/static` which contains your agent files (ACTIONS.md, agent-config.json).
172
+ Your working directory is `/app/static` which contains your agent files (SKILL.md, agent-config.json).
174
173
  All write operations (git clone, file creation, etc.) must target `/tmp`.
175
174
  </environment>
176
175
  ```
@@ -222,13 +221,18 @@ Project root. All sections optional — sensible defaults apply.
222
221
  ### Full Annotated Example
223
222
 
224
223
  ```toml
225
- # Default model for all agents (agents can override in their own agent-config.toml)
226
- [model]
224
+ # Named models define once, reference by name in SKILL.md
225
+ [models.sonnet]
227
226
  provider = "anthropic"
228
227
  model = "claude-sonnet-4-20250514"
229
228
  thinkingLevel = "medium"
230
229
  authType = "api_key"
231
230
 
231
+ [models.haiku]
232
+ provider = "anthropic"
233
+ model = "claude-haiku-4-5-20251001"
234
+ authType = "api_key"
235
+
232
236
  # Local Docker container settings
233
237
  [local]
234
238
  image = "al-agent:latest" # Base image name (default: "al-agent:latest")
@@ -239,7 +243,6 @@ timeout = 900 # Default max container runtime in seconds (default:
239
243
  # Gateway HTTP server settings
240
244
  [gateway]
241
245
  port = 8080 # Gateway port (default: 8080)
242
- lockTimeout = 1800 # Lock TTL in seconds (default: 1800 / 30 minutes)
243
246
 
244
247
  # Webhook sources — named webhook endpoints with provider type and credential
245
248
  [webhooks.my-github]
@@ -262,6 +265,7 @@ credential = "MintlifyMain" # credential instance (mintlify_webhook_secret
262
265
  type = "github" # no credential — accepts unsigned webhooks
263
266
 
264
267
  # Scheduler settings
268
+ resourceLockTimeout = 1800 # Lock TTL in seconds (default: 1800 / 30 minutes)
265
269
  maxReruns = 10 # Max consecutive reruns for successful agent runs (default: 10)
266
270
  maxCallDepth = 3 # Max depth for agent-to-agent call chains (default: 3)
267
271
  workQueueSize = 100 # Max queued work items (webhooks + calls) per agent (default: 100)
@@ -280,10 +284,11 @@ endpoint = "https://telemetry.example.com/v1" # OpenTelemetry endpoint
280
284
  | `maxCallDepth` | number | `3` | Maximum depth for agent-to-agent call chains (A calls B calls C = depth 2) |
281
285
  | `workQueueSize` | number | `100` | Maximum queued work items (webhook events + agent calls) per agent when all runners are busy |
282
286
  | `scale` | number | _(unlimited)_ | Project-wide cap on total concurrent runners across all agents |
287
+ | `resourceLockTimeout` | number | `1800` | Default lock TTL in seconds. Locks expire automatically after this duration unless refreshed via heartbeat. |
283
288
 
284
- ### `[model]` — Default LLM
289
+ ### `[models.<name>]` — Named Models
285
290
 
286
- Default for agents without `[model]` in agent-config.
291
+ Define models once, reference by name in SKILL.md `models:` list. First in list is primary; rest are fallbacks tried in order on rate limits.
287
292
 
288
293
  | Field | Type | Required | Description |
289
294
  |-------|------|----------|-------------|
@@ -301,7 +306,7 @@ Local Docker container settings.
301
306
  | `image` | string | `"al-agent:latest"` | Base Docker image name |
302
307
  | `memory` | string | `"4g"` | Memory limit per container (e.g. `"4g"`, `"8g"`) |
303
308
  | `cpus` | number | `2` | CPU limit per container |
304
- | `timeout` | number | `900` | Default max container runtime in seconds. Individual agents can override this with `timeout` in their `agent-config.toml`. |
309
+ | `timeout` | number | `900` | Default max container runtime in seconds. Individual agents can override this with `timeout` in their SKILL.md frontmatter. |
305
310
 
306
311
  ### `[gateway]` — HTTP Server
307
312
 
@@ -310,7 +315,6 @@ Starts automatically when Docker mode or webhooks enabled.
310
315
  | Field | Type | Default | Description |
311
316
  |-------|------|---------|-------------|
312
317
  | `port` | number | `8080` | Port for the gateway HTTP server |
313
- | `lockTimeout` | number | `1800` | Default lock TTL in seconds. Locks expire automatically after this duration unless refreshed via heartbeat. |
314
318
 
315
319
  ### `[webhooks.<name>]` — Webhook Sources
316
320
 
@@ -335,111 +339,80 @@ events = ["issues"]
335
339
  |-------|------|----------|-------------|
336
340
  | `endpoint` | string | Yes | OpenTelemetry collector endpoint URL |
337
341
 
338
- ## agent-config.toml
342
+ ## SKILL.md
339
343
 
340
- Per-agent config. Name derives from directory.
344
+ Single-file agent configuration. YAML frontmatter contains config, markdown body contains instructions.
341
345
 
342
346
  ### Full Annotated Example
343
347
 
344
- ```toml
345
- # Required: credential types the agent needs at runtime
346
- # Use "type" for default instance, "type:instance" for named instance
347
- credentials = ["github_token", "git_ssh", "sentry_token"]
348
-
349
- # Optional: cron schedule (standard cron syntax)
350
- # Agent must have at least one of: schedule, webhooks
351
- schedule = "*/5 * * * *"
352
-
353
- # Optional: number of concurrent runs allowed (default: 1)
354
- # When scale > 1, use rlock/runlock in your actions to coordinate
355
- # and prevent instances from working on the same resource.
356
- scale = 2
357
-
358
- # Optional: max runtime in seconds (default: falls back to [local].timeout, then 900)
359
- timeout = 600
360
-
361
- # Required: LLM model configuration
362
- [model]
363
- provider = "anthropic" # LLM provider
364
- model = "claude-sonnet-4-20250514" # Model ID
365
- thinkingLevel = "medium" # Optional: off | minimal | low | medium | high | xhigh
366
- authType = "api_key" # api_key | oauth_token | pi_auth
367
-
368
- # Optional: webhook triggers (instead of or in addition to schedule)
369
- # Each source references a named webhook defined in the project's config.toml
370
- [[webhooks]]
371
- source = "my-github" # Required: references [webhooks.my-github] in config.toml
372
- repos = ["acme/app"] # Filter to specific repos (optional)
373
- events = ["issues"] # GitHub event types (optional)
374
- actions = ["labeled"] # GitHub event actions (optional)
375
- labels = ["agent"] # Only trigger on issues with these labels (optional)
376
-
377
- [[webhooks]]
378
- source = "my-sentry"
379
- resources = ["error", "event_alert"] # Sentry resource types (optional)
380
-
381
- [[webhooks]]
382
- source = "my-linear"
383
- events = ["issues"] # Linear event types (optional)
384
- actions = ["create", "update"] # Linear event actions (optional)
385
- labels = ["bug"] # Filter by Linear labels (optional)
386
-
387
- [[webhooks]]
388
- source = "my-mintlify"
389
- events = ["build"] # Mintlify event types (optional)
390
- actions = ["failed"] # Mintlify event actions (optional)
391
-
392
- # Optional: preflight steps — run before the LLM session starts
393
- # Each step runs a built-in provider to stage data the agent will reference
394
- [[preflight]]
395
- provider = "git-clone" # Clone a repo into the workspace
396
- required = true # If true (default), abort if this step fails
397
- [preflight.params]
398
- repo = "acme/app" # Short "owner/repo" or full URL
399
- dest = "/tmp/repo"
400
- depth = 1 # Optional: shallow clone
401
-
402
- [[preflight]]
403
- provider = "http" # Fetch a URL and write the response to a file
404
- required = false # Optional step — warn and continue on failure
405
- [preflight.params]
406
- url = "https://api.internal/v1/flags"
407
- output = "/tmp/context/flags.json"
408
- headers = { Authorization = "Bearer ${INTERNAL_TOKEN}" }
409
-
410
- [[preflight]]
411
- provider = "shell" # Run a shell command
412
- [preflight.params]
413
- command = "gh issue list --repo acme/app --label P1 --json number,title,body --limit 20"
414
- output = "/tmp/context/issues.json" # Optional: capture stdout to file
415
-
416
- # Optional: custom parameters injected into the agent prompt
417
- [params]
418
- repos = ["acme/app", "acme/api"]
419
- triggerLabel = "agent"
420
- assignee = "bot-user"
421
- sentryOrg = "acme"
422
- sentryProjects = ["web-app", "api"]
348
+ ```yaml
349
+ ---
350
+ description: Solves GitHub issues by writing and testing code
351
+ metadata:
352
+ credentials:
353
+ - github_token
354
+ - git_ssh
355
+ - sentry_token
356
+ schedule: "*/5 * * * *"
357
+ scale: 2
358
+ timeout: 600
359
+ models:
360
+ - sonnet
361
+ - haiku
362
+ webhooks:
363
+ - source: my-github
364
+ repos: [acme/app]
365
+ events: [issues]
366
+ actions: [labeled]
367
+ labels: [agent]
368
+ - source: my-sentry
369
+ resources: [error, event_alert]
370
+ - source: my-linear
371
+ events: [issues]
372
+ actions: [create, update]
373
+ labels: [bug]
374
+ - source: my-mintlify
375
+ events: [build]
376
+ actions: [failed]
377
+ hooks:
378
+ pre:
379
+ - "gh repo clone acme/app /tmp/repo --depth 1"
380
+ - "curl -o /tmp/flags.json https://api.internal/v1/flags"
381
+ post:
382
+ - "upload-artifacts.sh"
383
+ params:
384
+ repos:
385
+ - acme/app
386
+ - acme/api
387
+ triggerLabel: agent
388
+ assignee: bot-user
389
+ sentryOrg: acme
390
+ sentryProjects:
391
+ - web-app
392
+ - api
393
+ ---
394
+
395
+ # Dev Agent
396
+
397
+ You are a development agent. Pick the highest priority issue and fix it.
423
398
  ```
424
399
 
425
400
  ### Field Reference
426
401
 
427
402
  | Field | Type | Required | Description |
428
403
  |-------|------|----------|-------------|
429
- | `credentials` | string[] | Yes | Credential refs: `"type"` for default instance, `"type:instance"` for named instance. |
430
- | `schedule` | string | No* | Cron expression for polling |
431
- | `scale` | number | No | Number of concurrent runs allowed (default: 1). Set to `0` to disable the agent. |
432
- | `timeout` | number | No | Max runtime in seconds. Falls back to `[local].timeout` in project config, then `900`. |
433
- | `model` | table | No | LLM model configuration (falls back to `[model]` in project `config.toml`) |
434
- | `model.provider` | string | Yes* | LLM provider (`"anthropic"`, `"openai"`, `"groq"`, `"google"`, `"xai"`, `"mistral"`, `"openrouter"`, or `"custom"`) |
435
- | `model.model` | string | Yes* | Model ID |
436
- | `model.thinkingLevel` | string | No | Thinking budget level: off, minimal, low, medium, high, xhigh. Only relevant for Anthropic models. |
437
- | `model.authType` | string | Yes* | Auth method for the provider |
438
- | `webhooks` | array | No* | Array of webhook trigger objects. |
439
- | `preflight` | array | No | Array of preflight steps that run before the LLM session. |
440
- | `params` | table | No | Custom key-value params injected into the prompt as `<agent-config>` |
441
-
442
- *Need `schedule` or `webhooks` (unless `scale=0`). *Required in `[model]` if defined.
404
+ | `description` | string | No | Short description of what the agent does (top-level) |
405
+ | `metadata.credentials` | string[] | Yes | Credential refs: `"type"` for default instance, `"type:instance"` for named instance. |
406
+ | `metadata.schedule` | string | No* | Cron expression for polling |
407
+ | `metadata.scale` | number | No | Number of concurrent runs allowed (default: 1). Set to `0` to disable the agent. |
408
+ | `metadata.timeout` | number | No | Max runtime in seconds. Falls back to `[local].timeout` in project config, then `900`. |
409
+ | `metadata.models` | string[] | Yes | Named model references from `config.toml [models.*]`. First is primary; rest are fallbacks. |
410
+ | `metadata.webhooks` | array | No* | Array of webhook trigger objects. |
411
+ | `metadata.hooks.pre` | string[] | No | Shell commands to run before LLM session |
412
+ | `metadata.hooks.post` | string[] | No | Shell commands to run after LLM session |
413
+ | `metadata.params` | object | No | Custom key-value params injected into the prompt as `<agent-config>` |
414
+
415
+ *Need `schedule` or `webhooks` (unless `scale=0`).
443
416
 
444
417
  ### Scale
445
418
 
@@ -451,82 +424,25 @@ Max runtime per invocation. Container terminated with exit 124 on expiry.
451
424
 
452
425
  Resolves: agent -> project `[local].timeout` -> `900`.
453
426
 
454
- ### Preflight
455
-
456
- Stage data after credentials load, before LLM session.
457
-
458
- Sequential, inside container. `${VAR_NAME}` interpolation in params.
427
+ ### Hooks
459
428
 
460
- Fields:
429
+ Shell commands that run before and after the LLM session, inside the container.
461
430
 
462
- | Field | Type | Required | Description |
463
- |-------|------|----------|-------------|
464
- | `provider` | string | Yes | Provider name: `shell`, `http`, or `git-clone` |
465
- | `required` | boolean | No | If `true` (default), the agent aborts on failure. If `false`, logs a warning and continues. |
466
- | `params` | table | Yes | Provider-specific parameters (see below) |
431
+ **`hooks.pre`** Run before context injection and LLM session. Use for cloning repos, fetching data, creating directories.
467
432
 
468
- #### `shell` provider
433
+ **`hooks.post`** Run after LLM session completes. Use for cleanup, artifact upload, reporting.
469
434
 
470
- Runs a command via `/bin/sh`.
471
-
472
- | Param | Type | Required | Description |
473
- |-------|------|----------|-------------|
474
- | `command` | string | Yes | Shell command to execute |
475
- | `output` | string | No | File path to write stdout to. Parent directories are created automatically. |
435
+ Sequential execution. If a command fails (non-zero exit), the run aborts with error. Commands run via `/bin/sh -c "..."`.
476
436
 
477
- ```toml
478
- [[preflight]]
479
- provider = "shell"
480
- [preflight.params]
481
- command = "gh issue list --repo acme/app --label P1 --json number,title,body --limit 20"
482
- output = "/tmp/context/issues.json"
483
- ```
484
-
485
- #### `http` provider
486
-
487
- Fetches a URL, writes response to file.
488
-
489
- | Param | Type | Required | Description |
490
- |-------|------|----------|-------------|
491
- | `url` | string | Yes | URL to fetch |
492
- | `output` | string | Yes | File path to write the response body |
493
- | `method` | string | No | HTTP method (default: `GET`) |
494
- | `headers` | table | No | HTTP headers as key-value pairs |
495
- | `body` | string | No | Request body (for POST/PUT) |
496
-
497
- ```toml
498
- [[preflight]]
499
- provider = "http"
500
- required = false
501
- [preflight.params]
502
- url = "https://api.internal/v1/feature-flags"
503
- output = "/tmp/context/flags.json"
504
- headers = { Authorization = "Bearer ${INTERNAL_TOKEN}" }
437
+ ```yaml
438
+ hooks:
439
+ pre:
440
+ - "gh repo clone acme/app /tmp/repo --depth 1"
441
+ - "curl -o /tmp/flags.json https://api.internal/v1/flags"
442
+ post:
443
+ - "upload-artifacts.sh"
505
444
  ```
506
445
 
507
- #### `git-clone` provider
508
-
509
- `"owner/repo"` expands to `git@github.com:owner/repo.git`.
510
-
511
- | Param | Type | Required | Description |
512
- |-------|------|----------|-------------|
513
- | `repo` | string | Yes | Repository: `"owner/repo"` or full URL |
514
- | `dest` | string | Yes | Local path to clone into |
515
- | `branch` | string | No | Branch to check out |
516
- | `depth` | number | No | Shallow clone depth (e.g., `1`) |
517
-
518
- ```toml
519
- [[preflight]]
520
- provider = "git-clone"
521
- [preflight.params]
522
- repo = "acme/app"
523
- dest = "/tmp/repo"
524
- branch = "main"
525
- depth = 1
526
- ```
527
-
528
- `shell` is the escape hatch. No per-step timeout. Shell env vars don't propagate back (see [Environment variable persistence](#environment-variable-persistence) for a workaround).
529
-
530
446
  ### Webhook Trigger Fields
531
447
 
532
448
  Required `source` from `config.toml`. Filters optional (AND logic).
@@ -588,7 +504,7 @@ Path: `~/.action-llama/credentials/<type>/<instance>/<field>`.
588
504
 
589
505
  ### How credentials work
590
506
 
591
- List in `agent-config.toml`. Mounted at `/credentials/...`, key values as env vars. `git_ssh` sets `GIT_AUTHOR_*`/`GIT_COMMITTER_*`. LLM creds auto-loaded from `[model]`.
507
+ List in SKILL.md frontmatter. Mounted at `/credentials/...`, key values as env vars. `git_ssh` sets `GIT_AUTHOR_*`/`GIT_COMMITTER_*`. LLM creds auto-loaded from `[models.*]`.
592
508
 
593
509
  ### Agent runtime credentials
594
510
 
@@ -647,7 +563,7 @@ CLI only (provisioning, deployment).
647
563
 
648
564
  ## Models
649
565
 
650
- 8 providers. Default in `config.toml [model]`, override per agent.
566
+ 8 providers. Define named models in `config.toml [models.*]`, reference by name in agent SKILL.md.
651
567
 
652
568
  | Provider | Credential | Example Models | Auth Types |
653
569
  |----------|-----------|---------------|------------|
@@ -710,7 +626,7 @@ al-status "found 3 issues to work on"
710
626
 
711
627
  #### `al-return "<value>"`
712
628
 
713
- Return a value to the calling agent (when invoked via `al-call`).
629
+ Return a value to the calling agent (when invoked via `al-subagent`).
714
630
 
715
631
  ```bash
716
632
  al-return "PR looks good. Approved with minor suggestions."
@@ -738,12 +654,12 @@ Codes: 10=auth, 11=perm, 12=rate, 13=config, 14=dep, 15=unrecoverable, 16=abort.
738
654
 
739
655
  Require gateway.
740
656
 
741
- #### `al-call <agent>`
657
+ #### `al-subagent <agent>`
742
658
 
743
659
  Call another agent. Pass context via stdin.
744
660
 
745
661
  ```bash
746
- echo "Review PR #42 on acme/app" | al-call reviewer
662
+ echo "Review PR #42 on acme/app" | al-subagent reviewer
747
663
  ```
748
664
 
749
665
  ```json
@@ -752,12 +668,12 @@ echo "Review PR #42 on acme/app" | al-call reviewer
752
668
  {"ok": false, "error": "queue full"}
753
669
  ```
754
670
 
755
- #### `al-check <callId>`
671
+ #### `al-subagent-check <callId>`
756
672
 
757
673
  Non-blocking status check.
758
674
 
759
675
  ```bash
760
- al-check abc123
676
+ al-subagent-check abc123
761
677
  ```
762
678
 
763
679
  ```json
@@ -766,13 +682,13 @@ al-check abc123
766
682
  {"status": "error", "error": "timeout"}
767
683
  ```
768
684
 
769
- #### `al-wait <callId> [...] [--timeout N]`
685
+ #### `al-subagent-wait <callId> [...] [--timeout N]`
770
686
 
771
687
  Wait for calls. Polls every 5s. Default timeout: 900s.
772
688
 
773
689
  ```bash
774
- al-wait abc123 --timeout 600
775
- al-wait abc123 def456 --timeout 300
690
+ al-subagent-wait abc123 --timeout 600
691
+ al-subagent-wait abc123 def456 --timeout 300
776
692
  ```
777
693
 
778
694
  ```json
@@ -786,13 +702,13 @@ al-wait abc123 def456 --timeout 300
786
702
 
787
703
  ```bash
788
704
  # Fire multiple calls
789
- REVIEW_ID=$(echo "Review PR #42 on acme/app" | al-call reviewer | jq -r .callId)
790
- TEST_ID=$(echo "Run full test suite for acme/app" | al-call tester | jq -r .callId)
705
+ REVIEW_ID=$(echo "Review PR #42 on acme/app" | al-subagent reviewer | jq -r .callId)
706
+ TEST_ID=$(echo "Run full test suite for acme/app" | al-subagent tester | jq -r .callId)
791
707
 
792
708
  # ... do other work ...
793
709
 
794
710
  # Collect results
795
- RESULTS=$(al-wait "$REVIEW_ID" "$TEST_ID" --timeout 600)
711
+ RESULTS=$(al-subagent-wait "$REVIEW_ID" "$TEST_ID" --timeout 600)
796
712
  echo "$RESULTS" | jq ".\"$REVIEW_ID\".returnValue"
797
713
  echo "$RESULTS" | jq ".\"$TEST_ID\".returnValue"
798
714
  ```
@@ -849,7 +765,7 @@ rlock-heartbeat "github issue acme/app#42"
849
765
 
850
766
  #### Lock behavior
851
767
 
852
- Per-run secret auth. Auto-release on exit. **One at a time**. Expire after `lockTimeout` (1800s).
768
+ Per-run secret auth. Auto-release on exit. **One at a time**. Expire after `resourceLockTimeout` (1800s).
853
769
 
854
770
  #### Lock graceful degradation
855
771
 
@@ -997,7 +913,7 @@ Read-only root, non-root user, resource limits.
997
913
  | Path | Mode | Contents |
998
914
  |------|------|----------|
999
915
  | `/app` | read-only | Action Llama application + node_modules |
1000
- | `/app/static` | read-only | Agent files baked at build time (ACTIONS.md, agent-config.json, prompt skeleton) |
916
+ | `/app/static` | read-only | Agent files baked at build time (SKILL.md, agent-config.json, prompt skeleton) |
1001
917
  | `/app/bin` | read-only | Shell commands (al-rerun, al-status, rlock, etc.) — added to PATH at startup |
1002
918
  | `/credentials` | read-only | Mounted credential files (`/<type>/<instance>/<field>`) |
1003
919
  | `/tmp` | read-write (tmpfs, 2GB) | Agent working directory — repos, scratch files, SSH keys |
@@ -1098,7 +1014,7 @@ Three-layer config merge (later wins):
1098
1014
 
1099
1015
  | Layer | File | Scope | Contents |
1100
1016
  |-------|------|-------|----------|
1101
- | 1 | `config.toml` | Project (committed) | `[model]`, `[local]`, `[gateway]`, `[webhooks]`, `[telemetry]`, top-level scheduler fields |
1017
+ | 1 | `config.toml` | Project (committed) | `[models.*]`, `[local]`, `[gateway]`, `[webhooks]`, `[telemetry]`, top-level scheduler fields |
1102
1018
  | 2 | `.env.toml` | Project (gitignored) | `environment` field to select env, can override any config value |
1103
1019
  | 3 | `~/.action-llama/environments/<name>.toml` | Machine | `[server]` (SSH push deploy), `gateway.url`, `telemetry.endpoint` |
1104
1020
 
@@ -1146,7 +1062,7 @@ Credentials synced via SSH.
1146
1062
  | 5 | Unavailable | 503 | Service not ready, no gateway configured |
1147
1063
  | 6 | Unreachable | — | Gateway connection failed |
1148
1064
  | 7 | Unexpected | other | Unknown HTTP status |
1149
- | 8 | Timeout | — | `al-wait` only: polling deadline exceeded |
1065
+ | 8 | Timeout | — | `al-subagent-wait` only: polling deadline exceeded |
1150
1066
  | 9 | Usage error | — | Missing argument (local check, never hits network) |
1151
1067
  | 10 | Bad gateway | 502 | Proxy could not reach the gateway |
1152
1068
  | 11 | Gateway timeout | 504 | Proxy timed out reaching the gateway |
@@ -1,4 +1,3 @@
1
- import { getModel } from "@mariozechner/pi-ai";
2
1
  import { DefaultResourceLoader, SettingsManager } from "@mariozechner/pi-coding-agent";
3
2
  import type { AgentConfig } from "../shared/config.js";
4
3
  /**
@@ -7,9 +6,8 @@ import type { AgentConfig } from "../shared/config.js";
7
6
  */
8
7
  export interface AgentInit {
9
8
  agentConfig: AgentConfig;
10
- agentsMd: string;
9
+ skillBody: string;
11
10
  timeoutSeconds: number;
12
- model: ReturnType<typeof getModel>;
13
11
  resourceLoader: InstanceType<typeof DefaultResourceLoader>;
14
12
  settingsManager: ReturnType<typeof SettingsManager.inMemory>;
15
13
  signalDir: string;
@@ -1 +1 @@
1
- {"version":3,"file":"container-entry.d.ts","sourceRoot":"","sources":["../../src/agents/container-entry.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAGL,qBAAqB,EAErB,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAoEvD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC;IACnC,cAAc,EAAE,YAAY,CAAC,OAAO,qBAAqB,CAAC,CAAC;IAC3D,eAAe,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,CA8FpD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAmVvE;AAED;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAGhD"}
1
+ {"version":3,"file":"container-entry.d.ts","sourceRoot":"","sources":["../../src/agents/container-entry.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,qBAAqB,EAErB,eAAe,EAEhB,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAsEvD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,YAAY,CAAC,OAAO,qBAAqB,CAAC,CAAC;IAC3D,eAAe,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;IAC7D,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,IAAI,OAAO,CAAC,SAAS,CAAC,CAiGpD;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,MAAM,CAAC,CAuYvE;AAED;;;GAGG;AACH,wBAAsB,QAAQ,IAAI,OAAO,CAAC,MAAM,CAAC,CAGhD"}