@lloyal-labs/lloyal-agents 1.7.0 → 2.0.0
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 +81 -97
- package/dist/Agent.d.ts +26 -0
- package/dist/Agent.d.ts.map +1 -1
- package/dist/Agent.js +22 -0
- package/dist/Agent.js.map +1 -1
- package/dist/AgentPolicy.d.ts +27 -10
- package/dist/AgentPolicy.d.ts.map +1 -1
- package/dist/AgentPolicy.js +78 -16
- package/dist/AgentPolicy.js.map +1 -1
- package/dist/agent-pool.d.ts +14 -2
- package/dist/agent-pool.d.ts.map +1 -1
- package/dist/agent-pool.js +415 -148
- package/dist/agent-pool.js.map +1 -1
- package/dist/context.d.ts +18 -1
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +18 -1
- package/dist/context.js.map +1 -1
- package/dist/create-agent-pool.d.ts +33 -15
- package/dist/create-agent-pool.d.ts.map +1 -1
- package/dist/create-agent-pool.js +34 -10
- package/dist/create-agent-pool.js.map +1 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +10 -1
- package/dist/index.js.map +1 -1
- package/dist/orchestrators.d.ts +161 -0
- package/dist/orchestrators.d.ts.map +1 -0
- package/dist/orchestrators.js +173 -0
- package/dist/orchestrators.js.map +1 -0
- package/dist/replay.d.ts +96 -0
- package/dist/replay.d.ts.map +1 -0
- package/dist/replay.js +108 -0
- package/dist/replay.js.map +1 -0
- package/dist/shared-root.d.ts +56 -18
- package/dist/shared-root.d.ts.map +1 -1
- package/dist/shared-root.js +79 -52
- package/dist/shared-root.js.map +1 -1
- package/dist/trace-types.d.ts +22 -2
- package/dist/trace-types.d.ts.map +1 -1
- package/dist/types.d.ts +33 -5
- package/dist/types.d.ts.map +1 -1
- package/dist/use-agent.d.ts.map +1 -1
- package/dist/use-agent.js +13 -17
- package/dist/use-agent.js.map +1 -1
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
# @lloyal-labs/lloyal-agents
|
|
2
2
|
|
|
3
|
-
Continuous Context agent runtime.
|
|
3
|
+
Continuous Context agent runtime for the [lloyal HDK](https://github.com/lloyal-ai/hdk).
|
|
4
4
|
|
|
5
5
|
`lloyal-agents` runs multi-agent inference inside the decode loop. Instead of N independent model calls rebuilding the prompt each step, all agents advance inside one continuous decode process — forked from shared KV cache state, driven through a single GPU forward pass per tick, spawning sub-agents from their own live branches at arbitrary depth.
|
|
6
6
|
|
|
7
|
-
Built on [lloyal.node](https://github.com/lloyal-ai/lloyal.node), which provides forkable decode state and continuous tree batching over llama.cpp. `lloyal-agents` adds structured concurrency, tool dispatch, and a
|
|
7
|
+
Built on [lloyal.node](https://github.com/lloyal-ai/lloyal.node), which provides forkable decode state and continuous tree batching over llama.cpp. `lloyal-agents` adds structured concurrency, tool dispatch, and a five-phase tick loop. Orchestration is not a layer above inference — it is inference.
|
|
8
8
|
|
|
9
9
|
<picture>
|
|
10
|
-
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/lloyal-ai/
|
|
11
|
-
<img src="https://raw.githubusercontent.com/lloyal-ai/
|
|
10
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/lloyal-ai/hdk/main/assets/continuous-context-dark.svg">
|
|
11
|
+
<img src="https://raw.githubusercontent.com/lloyal-ai/hdk/main/assets/continuous-context.svg" alt="Traditional Agents vs Continuous Context Agents — shared KV prefix, tool prefill, sub-agent spawning" width="100%">
|
|
12
12
|
</picture>
|
|
13
13
|
|
|
14
14
|
```bash
|
|
@@ -17,26 +17,25 @@ npm i @lloyal-labs/lloyal-agents @lloyal-labs/lloyal.node
|
|
|
17
17
|
|
|
18
18
|
`lloyal-agents` provides the agent runtime. [`lloyal.node`](https://github.com/lloyal-ai/lloyal.node) provides the native inference backend — prebuilt binaries for macOS (Metal, CPU), Linux (CPU, CUDA, Vulkan), and Windows (CPU, CUDA, Vulkan). Both are required. GPU selection at runtime.
|
|
19
19
|
|
|
20
|
-
|
|
20
|
+
## Public API
|
|
21
21
|
|
|
22
22
|
```typescript
|
|
23
23
|
import {
|
|
24
|
-
initAgents,
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
useAgentPool,
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
24
|
+
initAgents, // bootstrap: session, store, event channel
|
|
25
|
+
useAgent, agent, // single-agent helpers
|
|
26
|
+
agentPool, // multi-agent pool with a swappable orchestrator
|
|
27
|
+
useAgentPool, // lower-level Effection resource (advanced)
|
|
28
|
+
diverge, // multi-branch perplexity selection
|
|
29
|
+
parallel, chain, fanout, dag, reduce, // orchestrators / combinators
|
|
30
|
+
withSharedRoot, // scoped shared KV prefix with guaranteed teardown
|
|
31
|
+
createToolkit, // tool registry from Tool[] → toolMap + toolsJson
|
|
32
|
+
Tool, Source,
|
|
33
|
+
DefaultAgentPolicy,
|
|
34
|
+
Ctx, Store, Events,
|
|
34
35
|
} from "@lloyal-labs/lloyal-agents";
|
|
35
36
|
```
|
|
36
37
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
### Bootstrap
|
|
38
|
+
## Bootstrap
|
|
40
39
|
|
|
41
40
|
```typescript
|
|
42
41
|
import { main, call } from "effection";
|
|
@@ -47,17 +46,16 @@ main(function* () {
|
|
|
47
46
|
const ctx = yield* call(() =>
|
|
48
47
|
createContext({
|
|
49
48
|
modelPath: "model.gguf",
|
|
50
|
-
nCtx:
|
|
49
|
+
nCtx: 32768,
|
|
51
50
|
nSeqMax: 8,
|
|
52
51
|
typeK: "q4_0",
|
|
53
52
|
typeV: "q4_0",
|
|
54
53
|
}),
|
|
55
54
|
);
|
|
56
55
|
|
|
57
|
-
|
|
58
|
-
// Ctx, Store, Events now set —
|
|
59
|
-
//
|
|
60
|
-
// Session + context disposed on scope exit.
|
|
56
|
+
yield* initAgents(ctx);
|
|
57
|
+
// Ctx, Store, Events now set — useAgent(), agentPool(), diverge()
|
|
58
|
+
// find them automatically. Session + context disposed on scope exit.
|
|
61
59
|
});
|
|
62
60
|
```
|
|
63
61
|
|
|
@@ -68,62 +66,52 @@ When agents fork from a common branch, they inherit its KV cache — the full at
|
|
|
68
66
|
Everything before the frontier is shared context. Everything after is independent reasoning. The model doesn't need to be told what the other agents know — it already attended over the same prefix. Communication happened at prefill time, through the attention mechanism, with zero serialization overhead.
|
|
69
67
|
|
|
70
68
|
```typescript
|
|
71
|
-
yield
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
tasks: questions.map((q) => ({
|
|
80
|
-
systemPrompt: RESEARCH_PROMPT,
|
|
69
|
+
yield* withSharedRoot(
|
|
70
|
+
{ systemPrompt: SKILL_CATALOG, toolsJson: toolkit.toolsJson },
|
|
71
|
+
function* (root) {
|
|
72
|
+
// root is a prefilled branch — system prompt + tool schemas already in KV.
|
|
73
|
+
// Every agent forked from root shares that prefix.
|
|
74
|
+
return yield* agentPool({
|
|
75
|
+
orchestrate: parallel(
|
|
76
|
+
questions.map((q) => ({
|
|
81
77
|
content: q,
|
|
82
|
-
|
|
83
|
-
parent: root,
|
|
78
|
+
systemPrompt: WORKER_PROMPT,
|
|
84
79
|
})),
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
80
|
+
),
|
|
81
|
+
tools: [...sourceTools, reportTool],
|
|
82
|
+
parent: root,
|
|
83
|
+
terminalTool: "report",
|
|
84
|
+
});
|
|
85
|
+
},
|
|
86
|
+
);
|
|
89
87
|
```
|
|
90
88
|
|
|
91
89
|
`withSharedRoot` creates the prefix, passes it to the body, and guarantees cleanup via `try/finally` — the root branch cannot leak out of the block. Effection enforces the lifetime.
|
|
92
90
|
|
|
93
|
-
##
|
|
91
|
+
## Orchestrators
|
|
94
92
|
|
|
95
|
-
|
|
93
|
+
`agentPool` accepts an orchestrator that determines how agents are spawned and sequenced:
|
|
96
94
|
|
|
97
|
-
|
|
95
|
+
- **`parallel(specs[])`** — agents run concurrently from the shared root.
|
|
96
|
+
- **`chain(specs[], factory)`** — sequential, with `extendRoot` writing each task's findings onto the spine before the next forks.
|
|
97
|
+
- **`fanout(landscapeSpec, domainSpecs[])`** — landscape pass that informs N parallel domain agents.
|
|
98
|
+
- **`dag(nodes[])`** — arbitrary acyclic graph with multi-parent edges (Task-as-Future pattern).
|
|
98
99
|
|
|
99
|
-
|
|
100
|
+
Same `agentPool` call shape; the orchestrator argument changes the topology.
|
|
100
101
|
|
|
101
|
-
|
|
102
|
+
## In-Loop Orchestration
|
|
102
103
|
|
|
103
|
-
|
|
104
|
+
All active agents advance together in a five-phase tick loop:
|
|
104
105
|
|
|
105
|
-
|
|
106
|
-
// From the tick loop — Phase 1
|
|
107
|
-
const entries: [Branch, number][] = [];
|
|
108
|
-
for (const a of agents) {
|
|
109
|
-
if (a.state !== "generating") continue;
|
|
110
|
-
if (pressure.critical) {
|
|
111
|
-
a.state = "done";
|
|
112
|
-
continue;
|
|
113
|
-
}
|
|
106
|
+
**SPAWN+EXTEND.** The rendezvous point with the orchestrator fiber. Pending agent spawns and `extendRoot` calls are queued via Effection `action()` and drained at the start of each tick — batched into a single `store.prefill()`. Single-fiber discipline preserved across concurrent orchestrator extends.
|
|
114
107
|
|
|
115
|
-
|
|
116
|
-
if (isStop) {
|
|
117
|
-
/* parse tool calls, dispatch or finalize */ continue;
|
|
118
|
-
}
|
|
119
|
-
entries.push([a.branch, token]);
|
|
120
|
-
}
|
|
108
|
+
**PRODUCE.** Every generating agent calls `produceSync()` — synchronous sampling with no async gap between agents. The entire produce phase is a single uninterrupted pass over the active set.
|
|
121
109
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
110
|
+
**COMMIT.** One `store.commit()` call packs all produced tokens into a single `llama_batch` and dispatches once. N branches, one GPU call.
|
|
111
|
+
|
|
112
|
+
**SETTLE.** Tool results that resolved during the prior DISPATCH are drained from a buffer. Each result is tokenized into a delta, budget-checked against a fresh `ContextPressure` snapshot, and batch-prefilled into the agent's branch. Grammar state resets. The agent transitions back to `generating`.
|
|
113
|
+
|
|
114
|
+
**DISPATCH.** Tool calls collected during PRODUCE are executed sequentially via `scoped()` + `call()`. Each tool runs to completion before the next begins. Tools return `Operation<unknown>`, so they can `yield*` into framework primitives like `useAgent` or `agentPool`, spawning recursive sub-agents within the calling agent's scope.
|
|
127
115
|
|
|
128
116
|
When no agent is generating and tools are still pending, the loop yields control until the next tool resolves. No polling. No sleep loops.
|
|
129
117
|
|
|
@@ -143,13 +131,11 @@ function* setupAgent(parent, task, ctx) {
|
|
|
143
131
|
}
|
|
144
132
|
```
|
|
145
133
|
|
|
146
|
-
If the scope exits — error, cancellation, normal completion — the branch is pruned. Orphaned branches are structurally impossible. Tool dispatch uses `scoped()` + `call()
|
|
147
|
-
|
|
148
|
-
`useAgentPool` is an Effection `resource()` — it suspends via `provide()` after all agents complete, but keeps their branches alive. The caller can fork sub-agents from any completed agent's branch. Those sub-agents inherit the parent agent's full KV state — everything it generated, every tool result it consumed, every reasoning step it took. No summarization. No context window management. The sub-agent continues from the parent's frontier.
|
|
134
|
+
If the scope exits — error, cancellation, normal completion — the branch is pruned. Orphaned branches are structurally impossible. Tool dispatch uses `scoped()` + `call()`; each tool executes inside a scoped error boundary within the agent pool scope. If the scope tears down, pending tools are cancelled. The DAG is not imposed on the orchestration. It is intrinsic to the Effection task tree.
|
|
149
135
|
|
|
150
|
-
|
|
136
|
+
`useAgentPool` is an Effection `resource()` — it suspends via `provide()` after all agents complete, but keeps their branches alive. The caller can fork sub-agents from any completed agent's branch. Those sub-agents inherit the parent agent's full KV state — every tool result it consumed, every reasoning step it took. No summarization. No context window management. The sub-agent continues from the parent's frontier.
|
|
151
137
|
|
|
152
|
-
|
|
138
|
+
Recursive agents work at two levels. At the **harness level**, a completed pool's branches can be forked into follow-up pools. At the **model level**, a tool's `execute()` returns `Operation<unknown>`, so it can `yield*` directly into `useAgent` or `agentPool`. An agent that calls such a tool spawns sub-agents mid-generation — inside its own scope, inheriting its KV state, with cleanup guaranteed by structured concurrency. `DelegateTool` (from [`@lloyal-labs/rig`](../rig)) is the canonical implementation.
|
|
153
139
|
|
|
154
140
|
There is nothing in the framework that limits depth. Agents can spawn sub-agents that spawn sub-agents. An agent pool can run inside another agent pool's scope. The structured concurrency guarantees compose at every level.
|
|
155
141
|
|
|
@@ -164,16 +150,14 @@ Enable `trace: true` on agent pools to capture entropy and surprisal on every `a
|
|
|
164
150
|
**Multi-branch semantic comparison.** `diverge()` forks N branches from a shared frontier, generates independently, and returns all outputs with their perplexity scores:
|
|
165
151
|
|
|
166
152
|
```typescript
|
|
167
|
-
const result =
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
params: { temperature: 0.7 },
|
|
173
|
-
});
|
|
153
|
+
const result = yield* diverge({
|
|
154
|
+
parent: root, // shared frontier
|
|
155
|
+
attempts: 3, // fork 3 branches
|
|
156
|
+
params: { temperature: 0.7 },
|
|
157
|
+
});
|
|
174
158
|
// result.best — lowest-perplexity branch, still alive
|
|
175
159
|
// result.attempts — all branches with output, ppl, token count
|
|
176
|
-
// Losers already pruned. Winner's branch is caller's responsibility.
|
|
160
|
+
// Losers already pruned. Winner's branch is the caller's responsibility.
|
|
177
161
|
```
|
|
178
162
|
|
|
179
163
|
The harness decides how to compare. `diverge()` returns all outputs with their perplexity scores — the harness can apply any equivalence measure: bigram overlap, embedding similarity, or model-based evaluation. Where branches agree, the model is confident; where they diverge, hallucination risk is high.
|
|
@@ -182,27 +166,29 @@ This directly operationalizes the semantic entropy work from Farquhar et al. ([N
|
|
|
182
166
|
|
|
183
167
|
## Session Accumulation
|
|
184
168
|
|
|
185
|
-
`Session.
|
|
169
|
+
`Session.commitTurn(query, answer)` extends the trunk with a new query–answer pair. Future queries fork from this trunk — its KV cache already contains everything the prior turn established.
|
|
170
|
+
|
|
171
|
+
A cold query starts from position 0. A warm query starts from an existing trunk. Over multiple queries, the session compounds — each turn advances the frontier, and future agents inherit the accumulated state via attention.
|
|
186
172
|
|
|
187
|
-
|
|
173
|
+
The lower-level building blocks (`prefillUser`, `prefillToolResult`, `promote`) are also exposed for harnesses that orchestrate the trunk lifecycle directly.
|
|
188
174
|
|
|
189
175
|
## Context Pressure
|
|
190
176
|
|
|
191
|
-
KV cache is finite. `ContextPressure` snapshots the remaining budget on every tick and enforces two thresholds:
|
|
177
|
+
KV cache is finite. `ContextPressure` snapshots the remaining budget on every tick and `DefaultAgentPolicy` enforces two thresholds:
|
|
192
178
|
|
|
193
179
|
- **softLimit** (default 1024 tokens remaining): SETTLE rejects tool results that would cross this floor. PRODUCE hard-cuts agents requesting non-terminal tool calls. Terminal tools (e.g. `report`) still pass — agents can always submit findings. INIT drops agents that don't fit above this floor.
|
|
194
180
|
- **hardLimit** (default 128 tokens remaining): agents killed immediately before `produceSync()`. No decode call is made below this line — it would crash.
|
|
195
181
|
|
|
196
|
-
Tool result prefill in the SETTLE phase is budget-gated against a fresh pressure snapshot. If a tool result doesn't fit, the agent is terminated rather than risking a context overflow mid-generation. The softLimit reserves space for downstream work —
|
|
182
|
+
Tool result prefill in the SETTLE phase is budget-gated against a fresh pressure snapshot. If a tool result doesn't fit, the agent is terminated rather than risking a context overflow mid-generation. The softLimit reserves space for downstream work — synthesis passes, verification.
|
|
197
183
|
|
|
198
184
|
```typescript
|
|
199
|
-
yield
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
185
|
+
yield* agentPool({
|
|
186
|
+
orchestrate: parallel(tasks),
|
|
187
|
+
tools, terminalTool: "report",
|
|
188
|
+
policy: new DefaultAgentPolicy({
|
|
189
|
+
budget: { context: { softLimit: 2048 } }, // reserve 2K for downstream
|
|
190
|
+
}),
|
|
191
|
+
});
|
|
206
192
|
```
|
|
207
193
|
|
|
208
194
|
## Tools
|
|
@@ -225,19 +211,13 @@ class SearchTool extends Tool<{ query: string }> {
|
|
|
225
211
|
};
|
|
226
212
|
|
|
227
213
|
*execute(args: { query: string }, context?: ToolContext): Operation<unknown> {
|
|
228
|
-
const results = yield* call(() =>
|
|
229
|
-
this.reranker.rank(args.query, this.chunks),
|
|
230
|
-
);
|
|
231
|
-
context?.onProgress?.({
|
|
232
|
-
filled: results.length,
|
|
233
|
-
total: this.chunks.length,
|
|
234
|
-
});
|
|
214
|
+
const results = yield* call(() => this.reranker.rank(args.query, this.chunks));
|
|
235
215
|
return results.slice(0, 10);
|
|
236
216
|
}
|
|
237
217
|
}
|
|
238
218
|
```
|
|
239
219
|
|
|
240
|
-
`createToolkit(tools)` aggregates tools into a `{ toolMap, toolsJson }` pair — `toolMap` for runtime dispatch, `toolsJson` for prompt formatting.
|
|
220
|
+
`createToolkit(tools)` aggregates tools into a `{ toolMap, toolsJson }` pair — `toolMap` for runtime dispatch, `toolsJson` for prompt formatting. With `withSharedRoot({ systemPrompt, toolsJson })`, the schemas are decoded once at the root and inherited by every fork — see the [skill catalog](https://docs.lloyal.ai/reference/skill-catalog) convention for mixed-role pools.
|
|
241
221
|
|
|
242
222
|
## Events
|
|
243
223
|
|
|
@@ -253,6 +233,10 @@ The runtime emits structured events for TUI, logging, or telemetry:
|
|
|
253
233
|
| `agent:report` | `agentId`, `findings` |
|
|
254
234
|
| `agent:done` | `agentId` |
|
|
255
235
|
|
|
236
|
+
## Documentation
|
|
237
|
+
|
|
238
|
+
Full positioning, mechanics, learn pages, and reference at [docs.lloyal.ai](https://docs.lloyal.ai).
|
|
239
|
+
|
|
256
240
|
## License
|
|
257
241
|
|
|
258
242
|
Apache-2.0
|
package/dist/Agent.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Branch, SessionContext, ParseChatOutputResult } from '@lloyal-labs/sdk';
|
|
2
2
|
import type { GrammarTrigger } from '@lloyal-labs/sdk';
|
|
3
|
+
import { type Signal } from 'effection';
|
|
3
4
|
import type { TraceToken } from './types';
|
|
4
5
|
/**
|
|
5
6
|
* Agent status — domain language for where the agent is in its lifecycle.
|
|
@@ -33,6 +34,15 @@ export interface FormatConfig {
|
|
|
33
34
|
grammar: string;
|
|
34
35
|
grammarLazy: boolean;
|
|
35
36
|
grammarTriggers: GrammarTrigger[];
|
|
37
|
+
/**
|
|
38
|
+
* Whether the template's generation prompt includes `<think>\n` prefill.
|
|
39
|
+
* Must match the value used in every subsequent delta builder call
|
|
40
|
+
* (tool_result, nudge, etc.) for this agent — otherwise the parser's
|
|
41
|
+
* `generation_prompt` diverges from actual KV state and reasoning
|
|
42
|
+
* content leaks into visible content.
|
|
43
|
+
* Captured once at agent setup from the pool's `enableThinking` option.
|
|
44
|
+
*/
|
|
45
|
+
enableThinking: boolean;
|
|
36
46
|
}
|
|
37
47
|
/**
|
|
38
48
|
* Metadata for a single tool invocation — what was called, how expensive
|
|
@@ -82,6 +92,8 @@ export declare class Agent {
|
|
|
82
92
|
/** The task text this agent was assigned — used by echo detection guard */
|
|
83
93
|
readonly task: string;
|
|
84
94
|
private _status;
|
|
95
|
+
private _statusSignal;
|
|
96
|
+
private _startedAt;
|
|
85
97
|
private _rawOutput;
|
|
86
98
|
private _tokenCount;
|
|
87
99
|
private _toolCallCount;
|
|
@@ -105,6 +117,12 @@ export declare class Agent {
|
|
|
105
117
|
task?: string;
|
|
106
118
|
});
|
|
107
119
|
get status(): AgentStatus;
|
|
120
|
+
/**
|
|
121
|
+
* Signal that fires on every status transition. Used by `PoolContext.waitFor`
|
|
122
|
+
* to suspend until the agent reaches a terminal status. Multi-subscriber —
|
|
123
|
+
* every active listener receives every transition.
|
|
124
|
+
*/
|
|
125
|
+
get statusSignal(): Signal<AgentStatus, void>;
|
|
108
126
|
/**
|
|
109
127
|
* Transition to a new status. Enforces valid transitions:
|
|
110
128
|
* - idle → active (first produce)
|
|
@@ -113,8 +131,16 @@ export declare class Agent {
|
|
|
113
131
|
* - awaiting_tool → active (tool result settled)
|
|
114
132
|
* - awaiting_tool → idle (settle reject + kill)
|
|
115
133
|
* - idle → disposed (branch pruned)
|
|
134
|
+
*
|
|
135
|
+
* Emits the new status via `statusSignal` for orchestrator-side observers.
|
|
116
136
|
*/
|
|
117
137
|
transition(to: AgentStatus): void;
|
|
138
|
+
/**
|
|
139
|
+
* Wall-clock timestamp (performance.now) when the agent first became active.
|
|
140
|
+
* Null until the first idle→active transition. Used by policies to measure
|
|
141
|
+
* per-agent elapsed time independent of when the enclosing pool was created.
|
|
142
|
+
*/
|
|
143
|
+
get startedAt(): number | null;
|
|
118
144
|
get rawOutput(): string;
|
|
119
145
|
get tokenCount(): number;
|
|
120
146
|
get toolCallCount(): number;
|
package/dist/Agent.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../src/Agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAI1C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,eAAe,GAAG,UAAU,CAAC;AAE3E;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB,aAAa,GACb,WAAW,GACX,YAAY,GACZ,OAAO,GACP,YAAY,CAAC;AAIjB;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,cAAc,EAAE,CAAC;
|
|
1
|
+
{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../src/Agent.ts"],"names":[],"mappings":"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"}
|
package/dist/Agent.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.Agent = void 0;
|
|
4
|
+
const effection_1 = require("effection");
|
|
4
5
|
// ── Agent ───────────────────────────────────────────────────
|
|
5
6
|
/**
|
|
6
7
|
* An agent is a branch with intent.
|
|
@@ -33,6 +34,8 @@ class Agent {
|
|
|
33
34
|
task;
|
|
34
35
|
// ── Mutable state ───────────────────────────────────────
|
|
35
36
|
_status = 'idle';
|
|
37
|
+
_statusSignal = (0, effection_1.createSignal)();
|
|
38
|
+
_startedAt = null;
|
|
36
39
|
_rawOutput = '';
|
|
37
40
|
_tokenCount = 0;
|
|
38
41
|
_toolCallCount = 0;
|
|
@@ -58,6 +61,12 @@ class Agent {
|
|
|
58
61
|
}
|
|
59
62
|
// ── Status ──────────────────────────────────────────────
|
|
60
63
|
get status() { return this._status; }
|
|
64
|
+
/**
|
|
65
|
+
* Signal that fires on every status transition. Used by `PoolContext.waitFor`
|
|
66
|
+
* to suspend until the agent reaches a terminal status. Multi-subscriber —
|
|
67
|
+
* every active listener receives every transition.
|
|
68
|
+
*/
|
|
69
|
+
get statusSignal() { return this._statusSignal; }
|
|
61
70
|
/**
|
|
62
71
|
* Transition to a new status. Enforces valid transitions:
|
|
63
72
|
* - idle → active (first produce)
|
|
@@ -66,6 +75,8 @@ class Agent {
|
|
|
66
75
|
* - awaiting_tool → active (tool result settled)
|
|
67
76
|
* - awaiting_tool → idle (settle reject + kill)
|
|
68
77
|
* - idle → disposed (branch pruned)
|
|
78
|
+
*
|
|
79
|
+
* Emits the new status via `statusSignal` for orchestrator-side observers.
|
|
69
80
|
*/
|
|
70
81
|
transition(to) {
|
|
71
82
|
const from = this._status;
|
|
@@ -76,7 +87,17 @@ class Agent {
|
|
|
76
87
|
throw new Error(`Invalid agent status transition: ${from} → ${to}`);
|
|
77
88
|
}
|
|
78
89
|
this._status = to;
|
|
90
|
+
if (to === 'active' && this._startedAt === null) {
|
|
91
|
+
this._startedAt = performance.now();
|
|
92
|
+
}
|
|
93
|
+
this._statusSignal.send(to);
|
|
79
94
|
}
|
|
95
|
+
/**
|
|
96
|
+
* Wall-clock timestamp (performance.now) when the agent first became active.
|
|
97
|
+
* Null until the first idle→active transition. Used by policies to measure
|
|
98
|
+
* per-agent elapsed time independent of when the enclosing pool was created.
|
|
99
|
+
*/
|
|
100
|
+
get startedAt() { return this._startedAt; }
|
|
80
101
|
// ── Token accounting ────────────────────────────────────
|
|
81
102
|
get rawOutput() { return this._rawOutput; }
|
|
82
103
|
get tokenCount() { return this._tokenCount; }
|
|
@@ -217,6 +238,7 @@ class Agent {
|
|
|
217
238
|
/** Mark agent as disposed — called by pool when branch is pruned */
|
|
218
239
|
dispose() {
|
|
219
240
|
this._status = 'disposed';
|
|
241
|
+
this._statusSignal.send('disposed');
|
|
220
242
|
}
|
|
221
243
|
}
|
|
222
244
|
exports.Agent = Agent;
|
package/dist/Agent.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../src/Agent.ts"],"names":[],"mappings":";;;
|
|
1
|
+
{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../src/Agent.ts"],"names":[],"mappings":"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"}
|
package/dist/AgentPolicy.d.ts
CHANGED
|
@@ -21,7 +21,7 @@ export declare const defaultToolGuards: ToolGuard[];
|
|
|
21
21
|
* Why the agent entered idle status.
|
|
22
22
|
* @category Agents
|
|
23
23
|
*/
|
|
24
|
-
export type IdleReason = 'reported' | 'pressure_critical' | 'pressure_softcut' | 'pressure_settle_reject' | 'max_turns' | 'free_text_stop' | 'tool_error';
|
|
24
|
+
export type IdleReason = 'reported' | 'pressure_critical' | 'pressure_softcut' | 'pressure_settle_reject' | 'settle_stall_break' | 'max_turns' | 'free_text_stop' | 'tool_error';
|
|
25
25
|
/**
|
|
26
26
|
* Action returned by policy.onProduced — tells the pool what to do.
|
|
27
27
|
* @category Agents
|
|
@@ -90,12 +90,20 @@ export interface AgentPolicy {
|
|
|
90
90
|
toolCalls: ParsedToolCall[];
|
|
91
91
|
}, pressure: ContextPressure, config: PolicyConfig): ProduceAction;
|
|
92
92
|
/**
|
|
93
|
-
* SETTLE
|
|
93
|
+
* SETTLE stall-break: consulted when deferred tool results have no
|
|
94
|
+
* active siblings to free KV — the last-resort moment where a policy
|
|
95
|
+
* decides whether to nudge the agent (replacing the oversized result
|
|
96
|
+
* with a compact error payload) or drop it and let recovery extract.
|
|
94
97
|
*
|
|
95
|
-
*
|
|
96
|
-
*
|
|
97
|
-
*
|
|
98
|
-
*
|
|
98
|
+
* In normal operation, SETTLE defers oversized items across ticks.
|
|
99
|
+
* Siblings completing (parallel) or the spine growing (chain) restores
|
|
100
|
+
* headroom on subsequent ticks — this hook fires only when all agents
|
|
101
|
+
* are `awaiting_tool`/idle and deferral can't resolve on its own.
|
|
102
|
+
*
|
|
103
|
+
* Return `{type: 'nudge'}` to replace the oversized item with a compact
|
|
104
|
+
* error payload (carries the budget in its message). Return
|
|
105
|
+
* `{type: 'idle', reason: 'pressure_settle_reject'}` to drop the agent.
|
|
106
|
+
* If the hook is absent, the pool falls back to `settle_stall_break`.
|
|
99
107
|
*/
|
|
100
108
|
onSettleReject(agent: Agent, resultTokens: number, pressure: ContextPressure, config: PolicyConfig): SettleAction;
|
|
101
109
|
/**
|
|
@@ -145,7 +153,7 @@ export interface AgentPolicy {
|
|
|
145
153
|
*
|
|
146
154
|
* Optional — defaults to skip when absent.
|
|
147
155
|
*/
|
|
148
|
-
onRecovery?(agent: Agent): RecoveryAction;
|
|
156
|
+
onRecovery?(agent: Agent, pressure: ContextPressure): RecoveryAction;
|
|
149
157
|
}
|
|
150
158
|
/**
|
|
151
159
|
* Pool-level configuration passed to policy methods.
|
|
@@ -236,6 +244,15 @@ export declare class DefaultAgentPolicy implements AgentPolicy {
|
|
|
236
244
|
private _terminalTool;
|
|
237
245
|
private _startTime;
|
|
238
246
|
constructor(opts?: DefaultAgentPolicyOpts);
|
|
247
|
+
/**
|
|
248
|
+
* Elapsed wall time for *this agent* (since its first idle→active transition),
|
|
249
|
+
* falling back to the policy's own construction time when the agent hasn't
|
|
250
|
+
* started yet (defensive — shouldn't normally happen).
|
|
251
|
+
*
|
|
252
|
+
* Per-agent timing means orchestrators that spawn agents sequentially (e.g.
|
|
253
|
+
* `chain`) get the correct "how long has this task been running?" semantics
|
|
254
|
+
* without the time budget leaking across iterations.
|
|
255
|
+
*/
|
|
239
256
|
private _elapsed;
|
|
240
257
|
/** KV pressure thresholds for ContextPressure construction.
|
|
241
258
|
* Pool reads this once at setup. */
|
|
@@ -251,14 +268,14 @@ export declare class DefaultAgentPolicy implements AgentPolicy {
|
|
|
251
268
|
private _isOverBudget;
|
|
252
269
|
private _handleOverBudget;
|
|
253
270
|
private _checkGuards;
|
|
254
|
-
onSettleReject(agent: Agent, _resultTokens: number,
|
|
271
|
+
onSettleReject(agent: Agent, _resultTokens: number, pressure: ContextPressure, config: PolicyConfig): SettleAction;
|
|
255
272
|
/**
|
|
256
273
|
* UI-driven override. Harness calls this when the user wants agents
|
|
257
274
|
* to wrap up. Overrides pressure-based logic immediately.
|
|
258
275
|
*/
|
|
259
276
|
setExploitMode(force: boolean): void;
|
|
260
277
|
shouldExit(agent: Agent, pressure: ContextPressure): boolean;
|
|
261
|
-
shouldExplore(
|
|
278
|
+
shouldExplore(agent: Agent, pressure: ContextPressure): boolean;
|
|
262
279
|
/**
|
|
263
280
|
* Trailing stop: at most one agent nudged or killed per tick.
|
|
264
281
|
* The sacrificed agent's findings are extracted and its KV freed,
|
|
@@ -268,6 +285,6 @@ export declare class DefaultAgentPolicy implements AgentPolicy {
|
|
|
268
285
|
private _killedThisTick;
|
|
269
286
|
private _nudgedThisTick;
|
|
270
287
|
resetTick(): void;
|
|
271
|
-
onRecovery(agent: Agent): RecoveryAction;
|
|
288
|
+
onRecovery(agent: Agent, pressure: ContextPressure): RecoveryAction;
|
|
272
289
|
}
|
|
273
290
|
//# sourceMappingURL=AgentPolicy.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"AgentPolicy.d.ts","sourceRoot":"","sources":["../src/AgentPolicy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"AgentPolicy.d.ts","sourceRoot":"","sources":["../src/AgentPolicy.ts"],"names":[],"mappings":"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"}
|