@lloyal-labs/lloyal-agents 1.2.2 → 1.3.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/dist/Agent.d.ts +165 -0
- package/dist/Agent.d.ts.map +1 -0
- package/dist/Agent.js +160 -0
- package/dist/Agent.js.map +1 -0
- package/dist/AgentPolicy.d.ts +125 -0
- package/dist/AgentPolicy.d.ts.map +1 -0
- package/dist/AgentPolicy.js +109 -0
- package/dist/AgentPolicy.js.map +1 -0
- package/dist/agent-pool.d.ts.map +1 -1
- package/dist/agent-pool.js +184 -117
- package/dist/agent-pool.js.map +1 -1
- package/dist/context.d.ts +15 -0
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +15 -1
- package/dist/context.js.map +1 -1
- package/dist/diverge.js +1 -1
- package/dist/diverge.js.map +1 -1
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +13 -1
- package/dist/index.js.map +1 -1
- package/dist/prompt.d.ts +77 -0
- package/dist/prompt.d.ts.map +1 -0
- package/dist/prompt.js +55 -0
- package/dist/prompt.js.map +1 -0
- package/dist/shared-root.d.ts +22 -25
- package/dist/shared-root.d.ts.map +1 -1
- package/dist/shared-root.js +32 -31
- package/dist/shared-root.js.map +1 -1
- package/dist/types.d.ts +31 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +3 -2
package/dist/Agent.d.ts
ADDED
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
import type { Branch } from '@lloyal-labs/sdk';
|
|
2
|
+
import type { GrammarTrigger } from '@lloyal-labs/sdk';
|
|
3
|
+
import type { TraceToken } from './types';
|
|
4
|
+
/**
|
|
5
|
+
* Agent status — domain language for where the agent is in its lifecycle.
|
|
6
|
+
*
|
|
7
|
+
* - `idle`: created but not yet generating, OR finished but branch still
|
|
8
|
+
* alive (extraction window for scratchpad)
|
|
9
|
+
* - `active`: generating tokens (between PRODUCE start and stop token)
|
|
10
|
+
* - `awaiting_tool`: tool call parsed, waiting for result in SETTLE
|
|
11
|
+
* - `disposed`: branch pruned, agent no longer usable
|
|
12
|
+
*
|
|
13
|
+
* @category Agents
|
|
14
|
+
*/
|
|
15
|
+
export type AgentStatus = 'idle' | 'active' | 'awaiting_tool' | 'disposed';
|
|
16
|
+
/**
|
|
17
|
+
* How the agent's findings were produced — provenance for trace/debugging.
|
|
18
|
+
*
|
|
19
|
+
* @category Agents
|
|
20
|
+
*/
|
|
21
|
+
export type FindingsSource = 'report_tool' | 'free_text' | 'scratchpad' | 'nudge' | 'tool_error';
|
|
22
|
+
/**
|
|
23
|
+
* Immutable prompt format configuration set at agent creation.
|
|
24
|
+
* Derived from `formatChatSync()` output.
|
|
25
|
+
*
|
|
26
|
+
* @category Agents
|
|
27
|
+
*/
|
|
28
|
+
export interface FormatConfig {
|
|
29
|
+
format: number;
|
|
30
|
+
reasoningFormat: number;
|
|
31
|
+
thinkingForcedOpen: boolean;
|
|
32
|
+
parser: string;
|
|
33
|
+
grammar: string;
|
|
34
|
+
grammarLazy: boolean;
|
|
35
|
+
grammarTriggers: GrammarTrigger[];
|
|
36
|
+
}
|
|
37
|
+
/**
|
|
38
|
+
* Metadata for a single tool invocation — what was called, how expensive
|
|
39
|
+
* it was, and what context remained after. Content is in the branch KV;
|
|
40
|
+
* this is the metadata the policy reads for informed decisions.
|
|
41
|
+
*
|
|
42
|
+
* @category Agents
|
|
43
|
+
*/
|
|
44
|
+
export interface ToolHistoryEntry {
|
|
45
|
+
/** Tool name (e.g. 'web_search', 'fetch_page') */
|
|
46
|
+
name: string;
|
|
47
|
+
/** Summarized arguments (e.g. query string, URL) */
|
|
48
|
+
args: string;
|
|
49
|
+
/** Number of tokens prefilled for this tool's result */
|
|
50
|
+
resultTokenCount: number;
|
|
51
|
+
/** Context available percent after this result settled */
|
|
52
|
+
contextAfterPercent: number;
|
|
53
|
+
/** Timestamp (performance.now) when result was recorded */
|
|
54
|
+
timestamp: number;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* An agent is a branch with intent.
|
|
58
|
+
*
|
|
59
|
+
* A Branch is a forkable KV cache sequence — it stores every token the
|
|
60
|
+
* model has seen and generated. An Agent adds: a task to accomplish,
|
|
61
|
+
* a policy for how to accomplish it, and a record of what it has done.
|
|
62
|
+
*
|
|
63
|
+
* The branch is the ground truth. The agent is the interpretation layer
|
|
64
|
+
* that gives meaning to what's in the branch and makes decisions about
|
|
65
|
+
* what to do next.
|
|
66
|
+
*
|
|
67
|
+
* Agents are plain classes — not Effection resources, not spawned
|
|
68
|
+
* concurrently. The pool creates agents, manages their scope, and runs
|
|
69
|
+
* the tick loop. The agent encapsulates state, policy, and findings.
|
|
70
|
+
*
|
|
71
|
+
* @category Agents
|
|
72
|
+
*/
|
|
73
|
+
export declare class Agent {
|
|
74
|
+
/** Stable identifier — equals branch.handle */
|
|
75
|
+
readonly id: number;
|
|
76
|
+
/** Parent branch handle — trace metadata for UI tree reconstruction */
|
|
77
|
+
readonly parentId: number;
|
|
78
|
+
/** The KV sequence this agent owns */
|
|
79
|
+
readonly branch: Branch;
|
|
80
|
+
/** Immutable prompt format configuration */
|
|
81
|
+
readonly fmt: FormatConfig;
|
|
82
|
+
private _status;
|
|
83
|
+
private _rawOutput;
|
|
84
|
+
private _tokenCount;
|
|
85
|
+
private _toolCallCount;
|
|
86
|
+
private _turns;
|
|
87
|
+
private _nudged;
|
|
88
|
+
private _findings;
|
|
89
|
+
private _findingsSource;
|
|
90
|
+
private _toolHistory;
|
|
91
|
+
private _childFindings;
|
|
92
|
+
private _traceBuffer;
|
|
93
|
+
/** The agent that called the tool which spawned this agent's pool (null for top-level) */
|
|
94
|
+
readonly parent: Agent | null;
|
|
95
|
+
constructor(opts: {
|
|
96
|
+
id: number;
|
|
97
|
+
parentId: number;
|
|
98
|
+
branch: Branch;
|
|
99
|
+
fmt: FormatConfig;
|
|
100
|
+
parent?: Agent | null;
|
|
101
|
+
});
|
|
102
|
+
get status(): AgentStatus;
|
|
103
|
+
/**
|
|
104
|
+
* Transition to a new status. Enforces valid transitions:
|
|
105
|
+
* - idle → active (first produce)
|
|
106
|
+
* - active → awaiting_tool (tool call parsed)
|
|
107
|
+
* - active → idle (stop token, report, or kill)
|
|
108
|
+
* - awaiting_tool → active (tool result settled)
|
|
109
|
+
* - awaiting_tool → idle (settle reject + kill)
|
|
110
|
+
* - idle → disposed (branch pruned)
|
|
111
|
+
*/
|
|
112
|
+
transition(to: AgentStatus): void;
|
|
113
|
+
get rawOutput(): string;
|
|
114
|
+
get tokenCount(): number;
|
|
115
|
+
get toolCallCount(): number;
|
|
116
|
+
get turns(): number;
|
|
117
|
+
get nudged(): boolean;
|
|
118
|
+
get traceBuffer(): TraceToken[];
|
|
119
|
+
/** Accumulate generated token text into the current turn */
|
|
120
|
+
accumulateToken(text: string): void;
|
|
121
|
+
/** Accumulate token with trace data */
|
|
122
|
+
accumulateTokenWithTrace(text: string, entropy: number, surprisal: number): void;
|
|
123
|
+
/** Reset per-turn output after tool result is settled */
|
|
124
|
+
resetTurn(): void;
|
|
125
|
+
/** Increment turn counter */
|
|
126
|
+
incrementTurns(): void;
|
|
127
|
+
/** Increment tool call counter */
|
|
128
|
+
incrementToolCalls(): void;
|
|
129
|
+
/** Mark agent as nudged (second offense kills) */
|
|
130
|
+
markNudged(): void;
|
|
131
|
+
get toolHistory(): readonly ToolHistoryEntry[];
|
|
132
|
+
/** Record metadata for a completed tool invocation */
|
|
133
|
+
recordToolResult(entry: ToolHistoryEntry): void;
|
|
134
|
+
/** Findings collected from recursive tool results (inner sub-agent findings) */
|
|
135
|
+
get childFindings(): readonly string[];
|
|
136
|
+
/** Collect inner findings from a recursive tool's result */
|
|
137
|
+
addChildFindings(findings: string[]): void;
|
|
138
|
+
/**
|
|
139
|
+
* Walk the agent lineage (self → caller → caller's caller → ...),
|
|
140
|
+
* collecting results from each ancestor via the provided function.
|
|
141
|
+
*
|
|
142
|
+
* Self is visited first, then the calling agent, then its caller, etc.
|
|
143
|
+
* Iterative — no stack overflow on deep recursion chains.
|
|
144
|
+
*
|
|
145
|
+
* @example Check if any ancestor fetched a URL
|
|
146
|
+
* ```typescript
|
|
147
|
+
* const fetched = agent.walkLineage(a => a.toolHistory)
|
|
148
|
+
* .some(h => h.name === 'fetch_page' && h.args === url);
|
|
149
|
+
* ```
|
|
150
|
+
*/
|
|
151
|
+
walkLineage<T>(fn: (agent: Agent) => readonly T[]): T[];
|
|
152
|
+
get findings(): string | null;
|
|
153
|
+
get findingsSource(): FindingsSource | null;
|
|
154
|
+
/** Set findings with provenance tracking — single write path */
|
|
155
|
+
reportFindings(content: string, source: FindingsSource): void;
|
|
156
|
+
get position(): number;
|
|
157
|
+
get forkHead(): number;
|
|
158
|
+
/** Number of unique KV cells this agent owns above the fork point */
|
|
159
|
+
get uniqueCells(): number;
|
|
160
|
+
/** Whether the grammar allows free text output (not tool-call-only) */
|
|
161
|
+
get grammarAllowsFreeText(): boolean;
|
|
162
|
+
/** Mark agent as disposed — called by pool when branch is pruned */
|
|
163
|
+
dispose(): void;
|
|
164
|
+
}
|
|
165
|
+
//# sourceMappingURL=Agent.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../src/Agent.ts"],"names":[],"mappings":"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"}
|
package/dist/Agent.js
ADDED
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.Agent = void 0;
|
|
4
|
+
// ── Agent ───────────────────────────────────────────────────
|
|
5
|
+
/**
|
|
6
|
+
* An agent is a branch with intent.
|
|
7
|
+
*
|
|
8
|
+
* A Branch is a forkable KV cache sequence — it stores every token the
|
|
9
|
+
* model has seen and generated. An Agent adds: a task to accomplish,
|
|
10
|
+
* a policy for how to accomplish it, and a record of what it has done.
|
|
11
|
+
*
|
|
12
|
+
* The branch is the ground truth. The agent is the interpretation layer
|
|
13
|
+
* that gives meaning to what's in the branch and makes decisions about
|
|
14
|
+
* what to do next.
|
|
15
|
+
*
|
|
16
|
+
* Agents are plain classes — not Effection resources, not spawned
|
|
17
|
+
* concurrently. The pool creates agents, manages their scope, and runs
|
|
18
|
+
* the tick loop. The agent encapsulates state, policy, and findings.
|
|
19
|
+
*
|
|
20
|
+
* @category Agents
|
|
21
|
+
*/
|
|
22
|
+
class Agent {
|
|
23
|
+
// ── Identity ────────────────────────────────────────────
|
|
24
|
+
/** Stable identifier — equals branch.handle */
|
|
25
|
+
id;
|
|
26
|
+
/** Parent branch handle — trace metadata for UI tree reconstruction */
|
|
27
|
+
parentId;
|
|
28
|
+
/** The KV sequence this agent owns */
|
|
29
|
+
branch;
|
|
30
|
+
/** Immutable prompt format configuration */
|
|
31
|
+
fmt;
|
|
32
|
+
// ── Mutable state ───────────────────────────────────────
|
|
33
|
+
_status = 'idle';
|
|
34
|
+
_rawOutput = '';
|
|
35
|
+
_tokenCount = 0;
|
|
36
|
+
_toolCallCount = 0;
|
|
37
|
+
_turns = 0;
|
|
38
|
+
_nudged = false;
|
|
39
|
+
_findings = null;
|
|
40
|
+
_findingsSource = null;
|
|
41
|
+
_toolHistory = [];
|
|
42
|
+
_childFindings = [];
|
|
43
|
+
_traceBuffer = [];
|
|
44
|
+
/** The agent that called the tool which spawned this agent's pool (null for top-level) */
|
|
45
|
+
parent = null;
|
|
46
|
+
// ── Constructor ─────────────────────────────────────────
|
|
47
|
+
constructor(opts) {
|
|
48
|
+
this.id = opts.id;
|
|
49
|
+
this.parentId = opts.parentId;
|
|
50
|
+
this.branch = opts.branch;
|
|
51
|
+
this.fmt = opts.fmt;
|
|
52
|
+
this.parent = opts.parent ?? null;
|
|
53
|
+
}
|
|
54
|
+
// ── Status ──────────────────────────────────────────────
|
|
55
|
+
get status() { return this._status; }
|
|
56
|
+
/**
|
|
57
|
+
* Transition to a new status. Enforces valid transitions:
|
|
58
|
+
* - idle → active (first produce)
|
|
59
|
+
* - active → awaiting_tool (tool call parsed)
|
|
60
|
+
* - active → idle (stop token, report, or kill)
|
|
61
|
+
* - awaiting_tool → active (tool result settled)
|
|
62
|
+
* - awaiting_tool → idle (settle reject + kill)
|
|
63
|
+
* - idle → disposed (branch pruned)
|
|
64
|
+
*/
|
|
65
|
+
transition(to) {
|
|
66
|
+
const from = this._status;
|
|
67
|
+
const valid = (from === 'idle' && (to === 'active' || to === 'disposed')) ||
|
|
68
|
+
(from === 'active' && (to === 'awaiting_tool' || to === 'idle')) ||
|
|
69
|
+
(from === 'awaiting_tool' && (to === 'active' || to === 'idle'));
|
|
70
|
+
if (!valid) {
|
|
71
|
+
throw new Error(`Invalid agent status transition: ${from} → ${to}`);
|
|
72
|
+
}
|
|
73
|
+
this._status = to;
|
|
74
|
+
}
|
|
75
|
+
// ── Token accounting ────────────────────────────────────
|
|
76
|
+
get rawOutput() { return this._rawOutput; }
|
|
77
|
+
get tokenCount() { return this._tokenCount; }
|
|
78
|
+
get toolCallCount() { return this._toolCallCount; }
|
|
79
|
+
get turns() { return this._turns; }
|
|
80
|
+
get nudged() { return this._nudged; }
|
|
81
|
+
get traceBuffer() { return this._traceBuffer; }
|
|
82
|
+
/** Accumulate generated token text into the current turn */
|
|
83
|
+
accumulateToken(text) {
|
|
84
|
+
this._rawOutput += text;
|
|
85
|
+
this._tokenCount++;
|
|
86
|
+
}
|
|
87
|
+
/** Accumulate token with trace data */
|
|
88
|
+
accumulateTokenWithTrace(text, entropy, surprisal) {
|
|
89
|
+
this._rawOutput += text;
|
|
90
|
+
this._tokenCount++;
|
|
91
|
+
this._traceBuffer.push({ text, entropy, surprisal });
|
|
92
|
+
}
|
|
93
|
+
/** Reset per-turn output after tool result is settled */
|
|
94
|
+
resetTurn() { this._rawOutput = ''; }
|
|
95
|
+
/** Increment turn counter */
|
|
96
|
+
incrementTurns() { this._turns++; }
|
|
97
|
+
/** Increment tool call counter */
|
|
98
|
+
incrementToolCalls() { this._toolCallCount++; }
|
|
99
|
+
/** Mark agent as nudged (second offense kills) */
|
|
100
|
+
markNudged() { this._nudged = true; }
|
|
101
|
+
// ── Tool history ────────────────────────────────────────
|
|
102
|
+
get toolHistory() { return this._toolHistory; }
|
|
103
|
+
/** Record metadata for a completed tool invocation */
|
|
104
|
+
recordToolResult(entry) {
|
|
105
|
+
this._toolHistory.push(entry);
|
|
106
|
+
}
|
|
107
|
+
// ── Child findings ─────────────────────────────────────────
|
|
108
|
+
/** Findings collected from recursive tool results (inner sub-agent findings) */
|
|
109
|
+
get childFindings() { return this._childFindings; }
|
|
110
|
+
/** Collect inner findings from a recursive tool's result */
|
|
111
|
+
addChildFindings(findings) {
|
|
112
|
+
this._childFindings.push(...findings);
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Walk the agent lineage (self → caller → caller's caller → ...),
|
|
116
|
+
* collecting results from each ancestor via the provided function.
|
|
117
|
+
*
|
|
118
|
+
* Self is visited first, then the calling agent, then its caller, etc.
|
|
119
|
+
* Iterative — no stack overflow on deep recursion chains.
|
|
120
|
+
*
|
|
121
|
+
* @example Check if any ancestor fetched a URL
|
|
122
|
+
* ```typescript
|
|
123
|
+
* const fetched = agent.walkLineage(a => a.toolHistory)
|
|
124
|
+
* .some(h => h.name === 'fetch_page' && h.args === url);
|
|
125
|
+
* ```
|
|
126
|
+
*/
|
|
127
|
+
walkLineage(fn) {
|
|
128
|
+
const result = [...fn(this)];
|
|
129
|
+
let current = this.parent;
|
|
130
|
+
while (current) {
|
|
131
|
+
result.push(...fn(current));
|
|
132
|
+
current = current.parent;
|
|
133
|
+
}
|
|
134
|
+
return result;
|
|
135
|
+
}
|
|
136
|
+
// ── Findings ────────────────────────────────────────────
|
|
137
|
+
get findings() { return this._findings; }
|
|
138
|
+
get findingsSource() { return this._findingsSource; }
|
|
139
|
+
/** Set findings with provenance tracking — single write path */
|
|
140
|
+
reportFindings(content, source) {
|
|
141
|
+
this._findings = content;
|
|
142
|
+
this._findingsSource = source;
|
|
143
|
+
}
|
|
144
|
+
// ── Branch-derived readings ─────────────────────────────
|
|
145
|
+
get position() { return this.branch.position; }
|
|
146
|
+
get forkHead() { return this.branch.forkHead; }
|
|
147
|
+
/** Number of unique KV cells this agent owns above the fork point */
|
|
148
|
+
get uniqueCells() { return this.branch.position - this.branch.forkHead; }
|
|
149
|
+
/** Whether the grammar allows free text output (not tool-call-only) */
|
|
150
|
+
get grammarAllowsFreeText() {
|
|
151
|
+
return !this.fmt.grammarLazy || !this.fmt.grammar;
|
|
152
|
+
}
|
|
153
|
+
// ── Lifecycle ───────────────────────────────────────────
|
|
154
|
+
/** Mark agent as disposed — called by pool when branch is pruned */
|
|
155
|
+
dispose() {
|
|
156
|
+
this._status = 'disposed';
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
exports.Agent = Agent;
|
|
160
|
+
//# sourceMappingURL=Agent.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"Agent.js","sourceRoot":"","sources":["../src/Agent.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,125 @@
|
|
|
1
|
+
import type { Agent, ToolHistoryEntry } from './Agent';
|
|
2
|
+
import type { ContextPressure } from './agent-pool';
|
|
3
|
+
import type { ParsedToolCall } from '@lloyal-labs/sdk';
|
|
4
|
+
/**
|
|
5
|
+
* A declarative guard that rejects tool calls based on agent lineage.
|
|
6
|
+
* Guards are checked in order before any tool is dispatched.
|
|
7
|
+
*
|
|
8
|
+
* @category Agents
|
|
9
|
+
*/
|
|
10
|
+
export interface ToolGuard {
|
|
11
|
+
/** Tool names this guard applies to */
|
|
12
|
+
tools: string[];
|
|
13
|
+
/** Return true to reject the call. Receives parsed args, full lineage history, and the agent itself. */
|
|
14
|
+
reject: (args: Record<string, unknown>, lineageHistory: ToolHistoryEntry[], agent: Agent) => boolean;
|
|
15
|
+
/** Error message sent back to the agent as a tool result */
|
|
16
|
+
message: string;
|
|
17
|
+
}
|
|
18
|
+
/** Default guards for deduplication and recursion discipline */
|
|
19
|
+
export declare const defaultToolGuards: ToolGuard[];
|
|
20
|
+
/**
|
|
21
|
+
* Why the agent entered idle status.
|
|
22
|
+
* @category Agents
|
|
23
|
+
*/
|
|
24
|
+
export type IdleReason = 'reported' | 'pressure_critical' | 'pressure_softcut' | 'pressure_settle_reject' | 'max_turns' | 'free_text_stop' | 'tool_error';
|
|
25
|
+
/**
|
|
26
|
+
* Action returned by policy.onProduced — tells the pool what to do.
|
|
27
|
+
* @category Agents
|
|
28
|
+
*/
|
|
29
|
+
export type ProduceAction = {
|
|
30
|
+
type: 'tool_call';
|
|
31
|
+
tc: ParsedToolCall;
|
|
32
|
+
} | {
|
|
33
|
+
type: 'report';
|
|
34
|
+
findings: string;
|
|
35
|
+
} | {
|
|
36
|
+
type: 'nudge';
|
|
37
|
+
message?: string;
|
|
38
|
+
} | {
|
|
39
|
+
type: 'idle';
|
|
40
|
+
reason: IdleReason;
|
|
41
|
+
} | {
|
|
42
|
+
type: 'free_text_report';
|
|
43
|
+
content: string;
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* Action returned by policy.onSettleReject.
|
|
47
|
+
* @category Agents
|
|
48
|
+
*/
|
|
49
|
+
export type SettleAction = {
|
|
50
|
+
type: 'nudge';
|
|
51
|
+
} | {
|
|
52
|
+
type: 'idle';
|
|
53
|
+
reason: IdleReason;
|
|
54
|
+
};
|
|
55
|
+
/**
|
|
56
|
+
* Agent lifecycle policy — injected strategy for pressure, nudge,
|
|
57
|
+
* recursion, report timing, and findings quality decisions.
|
|
58
|
+
*
|
|
59
|
+
* The pool consults the policy at PRODUCE and SETTLE boundaries.
|
|
60
|
+
* Policy sees the agent's full state (status, tool history, pressure,
|
|
61
|
+
* grammar config) and returns an action. Pool executes the action.
|
|
62
|
+
*
|
|
63
|
+
* @category Agents
|
|
64
|
+
*/
|
|
65
|
+
export interface AgentPolicy {
|
|
66
|
+
/**
|
|
67
|
+
* PRODUCE phase: agent hit stop token — what should happen?
|
|
68
|
+
*
|
|
69
|
+
* Called after parseChatOutput extracts content and/or tool calls.
|
|
70
|
+
* Policy decides based on: parsed output, pressure, agent history,
|
|
71
|
+
* terminal tool config, grammar constraints.
|
|
72
|
+
*/
|
|
73
|
+
onProduced(agent: Agent, parsed: {
|
|
74
|
+
content: string | null;
|
|
75
|
+
toolCalls: ParsedToolCall[];
|
|
76
|
+
}, pressure: ContextPressure, config: PolicyConfig): ProduceAction;
|
|
77
|
+
/**
|
|
78
|
+
* SETTLE phase: tool result won't fit in KV — what should happen?
|
|
79
|
+
*
|
|
80
|
+
* Called when prefillTokens.length > headroom. Policy decides whether
|
|
81
|
+
* to nudge (inject "report now" error) or kill (transition to idle).
|
|
82
|
+
*/
|
|
83
|
+
onSettleReject(agent: Agent, resultTokens: number, pressure: ContextPressure, config: PolicyConfig): SettleAction;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Pool-level configuration passed to policy methods.
|
|
87
|
+
* @category Agents
|
|
88
|
+
*/
|
|
89
|
+
export interface PolicyConfig {
|
|
90
|
+
maxTurns: number;
|
|
91
|
+
terminalTool?: string;
|
|
92
|
+
hasNonTerminalTools: boolean;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Default policy replicating the current inline if-logic from agent-pool.ts.
|
|
96
|
+
*
|
|
97
|
+
* This is a 1:1 behavioral match — same pressure thresholds, same nudge
|
|
98
|
+
* logic, same terminal tool interception. Extracted for testability and
|
|
99
|
+
* future customization.
|
|
100
|
+
*
|
|
101
|
+
* @category Agents
|
|
102
|
+
*/
|
|
103
|
+
/**
|
|
104
|
+
* Configuration for {@link DefaultAgentPolicy}.
|
|
105
|
+
* @category Agents
|
|
106
|
+
*/
|
|
107
|
+
export interface DefaultAgentPolicyOpts {
|
|
108
|
+
/** Min non-terminal tool calls before report is accepted without nudge. @default 2 */
|
|
109
|
+
minToolCallsBeforeReport?: number;
|
|
110
|
+
/** Replace default tool guards entirely. */
|
|
111
|
+
guards?: ToolGuard[];
|
|
112
|
+
/** Append additional guards to the defaults. */
|
|
113
|
+
extraGuards?: ToolGuard[];
|
|
114
|
+
}
|
|
115
|
+
export declare class DefaultAgentPolicy implements AgentPolicy {
|
|
116
|
+
private _minToolCalls;
|
|
117
|
+
private _guards;
|
|
118
|
+
constructor(opts?: DefaultAgentPolicyOpts);
|
|
119
|
+
onProduced(agent: Agent, parsed: {
|
|
120
|
+
content: string | null;
|
|
121
|
+
toolCalls: ParsedToolCall[];
|
|
122
|
+
}, pressure: ContextPressure, config: PolicyConfig): ProduceAction;
|
|
123
|
+
onSettleReject(agent: Agent, _resultTokens: number, _pressure: ContextPressure, config: PolicyConfig): SettleAction;
|
|
124
|
+
}
|
|
125
|
+
//# sourceMappingURL=AgentPolicy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"AgentPolicy.d.ts","sourceRoot":"","sources":["../src/AgentPolicy.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,109 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
+
exports.DefaultAgentPolicy = exports.defaultToolGuards = void 0;
|
|
4
|
+
/** Default guards for deduplication and recursion discipline */
|
|
5
|
+
exports.defaultToolGuards = [
|
|
6
|
+
{
|
|
7
|
+
tools: ['fetch_page'],
|
|
8
|
+
reject: (args, history) => {
|
|
9
|
+
const url = args.url;
|
|
10
|
+
return !!url && history.some(h => h.name === 'fetch_page' && h.args === url);
|
|
11
|
+
},
|
|
12
|
+
message: 'This URL was already fetched. Try a different source.',
|
|
13
|
+
},
|
|
14
|
+
{
|
|
15
|
+
tools: ['web_search'],
|
|
16
|
+
reject: (args, history) => {
|
|
17
|
+
const query = args.query?.toLowerCase();
|
|
18
|
+
return !!query && history.some(h => h.name === 'web_search' && h.args.toLowerCase() === query);
|
|
19
|
+
},
|
|
20
|
+
message: 'This query was already searched. Refine your search or report findings.',
|
|
21
|
+
},
|
|
22
|
+
{
|
|
23
|
+
tools: ['web_research', 'research'],
|
|
24
|
+
reject: (_args, _lineage, agent) => {
|
|
25
|
+
// Agent-local history: each agent must do its own research before delegating,
|
|
26
|
+
// regardless of what ancestors did. Lineage history would let children bypass
|
|
27
|
+
// this by inheriting parent's search+fetch — producing blind relay chains.
|
|
28
|
+
const local = agent.toolHistory;
|
|
29
|
+
const hasSearch = local.some(h => h.name === 'web_search' || h.name === 'search');
|
|
30
|
+
const hasFetch = local.some(h => h.name === 'fetch_page' || h.name === 'read_file');
|
|
31
|
+
return !hasSearch || !hasFetch;
|
|
32
|
+
},
|
|
33
|
+
message: 'Read your search results with fetch_page before spawning sub-agents.',
|
|
34
|
+
},
|
|
35
|
+
];
|
|
36
|
+
class DefaultAgentPolicy {
|
|
37
|
+
_minToolCalls;
|
|
38
|
+
_guards;
|
|
39
|
+
constructor(opts) {
|
|
40
|
+
this._minToolCalls = opts?.minToolCallsBeforeReport ?? 2;
|
|
41
|
+
this._guards = opts?.guards ?? [
|
|
42
|
+
...exports.defaultToolGuards,
|
|
43
|
+
...(opts?.extraGuards ?? []),
|
|
44
|
+
];
|
|
45
|
+
}
|
|
46
|
+
onProduced(agent, parsed, pressure, config) {
|
|
47
|
+
const tc = parsed.toolCalls[0];
|
|
48
|
+
// No tool call — natural stop
|
|
49
|
+
if (!tc) {
|
|
50
|
+
if (!agent.findings && agent.toolCallCount > 0 && parsed.content) {
|
|
51
|
+
return { type: 'free_text_report', content: parsed.content };
|
|
52
|
+
}
|
|
53
|
+
return { type: 'idle', reason: 'free_text_stop' };
|
|
54
|
+
}
|
|
55
|
+
// Over budget check: turns exceeded or headroom negative, non-terminal tool
|
|
56
|
+
const overBudget = (agent.turns >= config.maxTurns || pressure.headroom < 0)
|
|
57
|
+
&& (!config.terminalTool || tc.name !== config.terminalTool);
|
|
58
|
+
if (overBudget) {
|
|
59
|
+
// First offense: nudge if conditions met
|
|
60
|
+
if (config.terminalTool && !agent.nudged && agent.toolCallCount > 0 && !pressure.critical) {
|
|
61
|
+
return { type: 'nudge' };
|
|
62
|
+
}
|
|
63
|
+
// Second offense or no terminal tool: kill
|
|
64
|
+
return { type: 'idle', reason: agent.turns >= config.maxTurns ? 'max_turns' : 'pressure_softcut' };
|
|
65
|
+
}
|
|
66
|
+
// Terminal tool — intercept and extract findings
|
|
67
|
+
if (config.terminalTool && tc.name === config.terminalTool) {
|
|
68
|
+
// Prevent reporting without sufficient research (minimum 2 non-report tool calls).
|
|
69
|
+
// Nudged agents bypass — they may have only 1 tool call but were told to report.
|
|
70
|
+
if (agent.toolCallCount < this._minToolCalls && config.hasNonTerminalTools && !agent.nudged) {
|
|
71
|
+
return { type: 'nudge', message: 'You must conduct research before reporting. Use web_search or fetch_page to find evidence first.' };
|
|
72
|
+
}
|
|
73
|
+
let findings;
|
|
74
|
+
try {
|
|
75
|
+
findings = JSON.parse(tc.arguments).findings;
|
|
76
|
+
}
|
|
77
|
+
catch {
|
|
78
|
+
findings = tc.arguments;
|
|
79
|
+
}
|
|
80
|
+
return { type: 'report', findings };
|
|
81
|
+
}
|
|
82
|
+
// Check declarative guards against full lineage
|
|
83
|
+
const lineageHistory = agent.walkLineage(a => a.toolHistory);
|
|
84
|
+
let toolArgs;
|
|
85
|
+
try {
|
|
86
|
+
toolArgs = JSON.parse(tc.arguments);
|
|
87
|
+
}
|
|
88
|
+
catch {
|
|
89
|
+
toolArgs = {};
|
|
90
|
+
}
|
|
91
|
+
for (const guard of this._guards) {
|
|
92
|
+
if (guard.tools.includes(tc.name) && guard.reject(toolArgs, lineageHistory, agent)) {
|
|
93
|
+
return { type: 'nudge', message: guard.message };
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
// Normal tool call
|
|
97
|
+
return { type: 'tool_call', tc };
|
|
98
|
+
}
|
|
99
|
+
onSettleReject(agent, _resultTokens, _pressure, config) {
|
|
100
|
+
// First offense: nudge if conditions met
|
|
101
|
+
if (config.terminalTool && !agent.nudged && agent.toolCallCount > 0) {
|
|
102
|
+
return { type: 'nudge' };
|
|
103
|
+
}
|
|
104
|
+
// Second offense: kill
|
|
105
|
+
return { type: 'idle', reason: 'pressure_settle_reject' };
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
exports.DefaultAgentPolicy = DefaultAgentPolicy;
|
|
109
|
+
//# sourceMappingURL=AgentPolicy.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"AgentPolicy.js","sourceRoot":"","sources":["../src/AgentPolicy.ts"],"names":[],"mappings":"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"}
|
package/dist/agent-pool.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agent-pool.d.ts","sourceRoot":"","sources":["../src/agent-pool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,WAAW,CAAC;AAEpD,OAAO,EAA+G,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"agent-pool.d.ts","sourceRoot":"","sources":["../src/agent-pool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAW,MAAM,WAAW,CAAC;AAEpD,OAAO,EAA+G,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AASpK,OAAO,KAAK,EACV,kBAAkB,EAElB,gBAAgB,EAChB,eAAe,EAEhB,MAAM,SAAS,CAAC;AAiBjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,eAAe;IAC1B,kEAAkE;IAClE,MAAM,CAAC,QAAQ,CAAC,kBAAkB,QAAQ;IAC1C,2DAA2D;IAC3D,MAAM,CAAC,QAAQ,CAAC,kBAAkB,OAAO;IAEzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,GAAG,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,kBAAkB;IAO1D;;;;OAIG;IACH,IAAI,QAAQ,IAAI,MAAM,CAA4C;IAElE,qEAAqE;IACrE,IAAI,QAAQ,IAAI,OAAO,CAA4C;IAEnE,iEAAiE;IACjE,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;CACpC;AAsDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAAC,eAAe,CAAC,CA2hB/E"}
|