@backendkit-labs/agent-core 0.27.0 → 0.28.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 +1238 -1168
- package/dist/engine/AgentEngine.d.ts +16 -0
- package/dist/engine/AgentEngine.d.ts.map +1 -1
- package/dist/engine/AgentEngine.js +250 -19
- package/dist/engine/AgentEngine.js.map +1 -1
- package/dist/engine/ContextManager.d.ts +88 -0
- package/dist/engine/ContextManager.d.ts.map +1 -0
- package/dist/engine/ContextManager.js +238 -0
- package/dist/engine/ContextManager.js.map +1 -0
- package/dist/engine/HistoryManager.d.ts +8 -0
- package/dist/engine/HistoryManager.d.ts.map +1 -1
- package/dist/engine/HistoryManager.js +19 -0
- package/dist/engine/HistoryManager.js.map +1 -1
- package/dist/engine/createBaseEngine.d.ts +26 -0
- package/dist/engine/createBaseEngine.d.ts.map +1 -1
- package/dist/engine/createBaseEngine.js +3 -0
- package/dist/engine/createBaseEngine.js.map +1 -1
- package/dist/guardrails/GuardrailRunner.d.ts +13 -0
- package/dist/guardrails/GuardrailRunner.d.ts.map +1 -0
- package/dist/guardrails/GuardrailRunner.js +64 -0
- package/dist/guardrails/GuardrailRunner.js.map +1 -0
- package/dist/guardrails/builtins.d.ts +82 -0
- package/dist/guardrails/builtins.d.ts.map +1 -0
- package/dist/guardrails/builtins.js +232 -0
- package/dist/guardrails/builtins.js.map +1 -0
- package/dist/guardrails/index.d.ts +5 -0
- package/dist/guardrails/index.d.ts.map +1 -0
- package/dist/guardrails/index.js +15 -0
- package/dist/guardrails/index.js.map +1 -0
- package/dist/guardrails/types.d.ts +70 -0
- package/dist/guardrails/types.d.ts.map +1 -0
- package/dist/guardrails/types.js +3 -0
- package/dist/guardrails/types.js.map +1 -0
- package/dist/index.d.ts +4 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +16 -2
- package/dist/index.js.map +1 -1
- package/dist/observability/MetricsCollector.d.ts +2 -0
- package/dist/observability/MetricsCollector.d.ts.map +1 -1
- package/dist/observability/MetricsCollector.js +15 -0
- package/dist/observability/MetricsCollector.js.map +1 -1
- package/dist/observability/ObservabilityManager.d.ts +9 -0
- package/dist/observability/ObservabilityManager.d.ts.map +1 -1
- package/dist/observability/ObservabilityManager.js +59 -1
- package/dist/observability/ObservabilityManager.js.map +1 -1
- package/dist/observability/Tracer.d.ts +12 -0
- package/dist/observability/Tracer.d.ts.map +1 -1
- package/dist/observability/Tracer.js +19 -0
- package/dist/observability/Tracer.js.map +1 -1
- package/dist/observability/types.d.ts +6 -0
- package/dist/observability/types.d.ts.map +1 -1
- package/dist/observability/types.js.map +1 -1
- package/dist/types/index.d.ts +56 -2
- package/dist/types/index.d.ts.map +1 -1
- package/package.json +1 -1
|
@@ -97,6 +97,10 @@ export declare class AgentEngine {
|
|
|
97
97
|
private readonly bus;
|
|
98
98
|
private readonly skillActivator;
|
|
99
99
|
private readonly history;
|
|
100
|
+
private readonly contextManager?;
|
|
101
|
+
private readonly guardrails?;
|
|
102
|
+
/** Uncalibrated token estimate of the last request sent by runLoop, to calibrate against real usage. */
|
|
103
|
+
private lastRequestEstimate;
|
|
100
104
|
private readonly auditLogger;
|
|
101
105
|
private currentAgentId;
|
|
102
106
|
private aborted;
|
|
@@ -180,6 +184,18 @@ export declare class AgentEngine {
|
|
|
180
184
|
/** Delete persisted history file and reset in-memory conversation. */
|
|
181
185
|
clearHistory(): void;
|
|
182
186
|
private saveHistory;
|
|
187
|
+
/**
|
|
188
|
+
* Runs the guardrails of `phase` over `content`, reports what happened (transport event + audit log)
|
|
189
|
+
* and returns the outcome. `replacement` lets output checks attach the corrected text to the event.
|
|
190
|
+
*/
|
|
191
|
+
private guard;
|
|
192
|
+
/** Checks a model answer. Returns the (possibly corrected) message and the text to show. */
|
|
193
|
+
private guardOutput;
|
|
194
|
+
private blockedText;
|
|
195
|
+
/** Token-aware compaction first (when configured), then the message-count cap. */
|
|
196
|
+
private prepareContext;
|
|
197
|
+
/** One summarization call, billed through `metrics` events like any other LLM call. */
|
|
198
|
+
private summarizeForContext;
|
|
183
199
|
private trimHistory;
|
|
184
200
|
private ensureAgentsLoaded;
|
|
185
201
|
private _loadAgentsOnce;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"AgentEngine.d.ts","sourceRoot":"","sources":["../../src/engine/AgentEngine.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"AgentEngine.d.ts","sourceRoot":"","sources":["../../src/engine/AgentEngine.ts"],"names":[],"mappings":"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"}
|
|
@@ -4,6 +4,8 @@ exports.AgentEngine = void 0;
|
|
|
4
4
|
const ApprovalGate_1 = require("./ApprovalGate");
|
|
5
5
|
const AuditLogger_1 = require("./AuditLogger");
|
|
6
6
|
const HistoryManager_1 = require("./HistoryManager");
|
|
7
|
+
const ContextManager_1 = require("./ContextManager");
|
|
8
|
+
const GuardrailRunner_1 = require("../guardrails/GuardrailRunner");
|
|
7
9
|
const MCPRegistrar_1 = require("./MCPRegistrar");
|
|
8
10
|
const DelegationBus_1 = require("../delegation/DelegationBus");
|
|
9
11
|
const SessionMemory_1 = require("../memory/SessionMemory");
|
|
@@ -30,11 +32,16 @@ const ASK_AGENT_TOOL = {
|
|
|
30
32
|
};
|
|
31
33
|
const generateObject_1 = require("../structured/generateObject");
|
|
32
34
|
/** `metrics` event; cache fields are included only when the provider reported them. */
|
|
33
|
-
function metricsEvent(inputTokens, outputTokens, usage) {
|
|
35
|
+
function metricsEvent(inputTokens, outputTokens, usage, extra) {
|
|
34
36
|
return {
|
|
35
37
|
type: 'metrics',
|
|
36
38
|
input_tokens: inputTokens,
|
|
37
39
|
output_tokens: outputTokens,
|
|
40
|
+
...(extra?.agentId ? { agent_id: extra.agentId } : {}),
|
|
41
|
+
...(extra?.provider ? { provider: extra.provider } : {}),
|
|
42
|
+
...(extra?.model ? { model: extra.model } : {}),
|
|
43
|
+
...(extra?.purpose ? { purpose: extra.purpose } : {}),
|
|
44
|
+
...(extra?.startedAt !== undefined ? { started_at: extra.startedAt, duration_ms: Math.max(0, Date.now() - extra.startedAt) } : {}),
|
|
38
45
|
...(usage?.cacheReadTokens !== undefined ? { cache_read_tokens: usage.cacheReadTokens } : {}),
|
|
39
46
|
...(usage?.cacheWriteTokens !== undefined ? { cache_write_tokens: usage.cacheWriteTokens } : {}),
|
|
40
47
|
};
|
|
@@ -45,6 +52,10 @@ class AgentEngine {
|
|
|
45
52
|
bus;
|
|
46
53
|
skillActivator = new activator_1.SkillActivator();
|
|
47
54
|
history;
|
|
55
|
+
contextManager;
|
|
56
|
+
guardrails;
|
|
57
|
+
/** Uncalibrated token estimate of the last request sent by runLoop, to calibrate against real usage. */
|
|
58
|
+
lastRequestEstimate = 0;
|
|
48
59
|
auditLogger;
|
|
49
60
|
currentAgentId;
|
|
50
61
|
aborted = false;
|
|
@@ -70,6 +81,15 @@ class AgentEngine {
|
|
|
70
81
|
historyPath: opts.historyPath,
|
|
71
82
|
maxContextMessages: opts.maxContextMessages,
|
|
72
83
|
});
|
|
84
|
+
if (opts.guardrails?.length)
|
|
85
|
+
this.guardrails = new GuardrailRunner_1.GuardrailRunner(opts.guardrails);
|
|
86
|
+
if (opts.context) {
|
|
87
|
+
this.contextManager = new ContextManager_1.ContextManager(opts.context, {
|
|
88
|
+
history: this.history,
|
|
89
|
+
summarize: (transcript, previous) => this.summarizeForContext(transcript, previous),
|
|
90
|
+
emit: (event) => this.opts.transport.emit(event),
|
|
91
|
+
});
|
|
92
|
+
}
|
|
73
93
|
this.auditLogger = new AuditLogger_1.AuditLogger(opts.auditLog);
|
|
74
94
|
this.mcpRegistrar = new MCPRegistrar_1.MCPRegistrar({
|
|
75
95
|
mcpManager: opts.mcpManager,
|
|
@@ -104,12 +124,18 @@ class AgentEngine {
|
|
|
104
124
|
const profile = this.opts.agents.get(agentId);
|
|
105
125
|
if (!profile)
|
|
106
126
|
throw new Error(`Agent "${agentId}" not registered`);
|
|
107
|
-
|
|
127
|
+
const provider = this.getProviderForProfile(profile);
|
|
128
|
+
let attemptStart = Date.now();
|
|
129
|
+
return (0, generateObject_1.generateObject)(provider, prompt, schema, {
|
|
108
130
|
retries: opts.retries,
|
|
109
131
|
name: opts.name,
|
|
110
132
|
model: profile.model,
|
|
111
133
|
onMetrics: (inputTokens, outputTokens, usage) => {
|
|
112
|
-
this.opts.transport.emit(metricsEvent(inputTokens, outputTokens, usage
|
|
134
|
+
this.opts.transport.emit(metricsEvent(inputTokens, outputTokens, usage, {
|
|
135
|
+
agentId, provider: profile.provider ?? this.opts.defaultProvider,
|
|
136
|
+
model: profile.model ?? provider.modelId, purpose: 'structured_output', startedAt: attemptStart,
|
|
137
|
+
}));
|
|
138
|
+
attemptStart = Date.now();
|
|
113
139
|
},
|
|
114
140
|
});
|
|
115
141
|
}
|
|
@@ -248,6 +274,18 @@ class AgentEngine {
|
|
|
248
274
|
this.opts.transport.emit({ type: 'done' });
|
|
249
275
|
return;
|
|
250
276
|
}
|
|
277
|
+
if (this.guardrails?.has('input')) {
|
|
278
|
+
const checked = await this.guard('input', input, this.currentAgentId);
|
|
279
|
+
if (checked.blocked) {
|
|
280
|
+
this.opts.transport.emit({
|
|
281
|
+
type: 'error',
|
|
282
|
+
message: `Input blocked by guardrail "${checked.blocked.guardrail}": ${checked.blocked.reason}`,
|
|
283
|
+
});
|
|
284
|
+
this.opts.transport.emit({ type: 'done' });
|
|
285
|
+
return;
|
|
286
|
+
}
|
|
287
|
+
input = checked.content;
|
|
288
|
+
}
|
|
251
289
|
await this.mcpRegistrar.ensureInitialized();
|
|
252
290
|
await this.ensureAgentsLoaded();
|
|
253
291
|
// Direct MCP routing: bypass general when input matches a configured trigger
|
|
@@ -348,6 +386,105 @@ class AgentEngine {
|
|
|
348
386
|
saveHistory() {
|
|
349
387
|
this.history.save();
|
|
350
388
|
}
|
|
389
|
+
/**
|
|
390
|
+
* Runs the guardrails of `phase` over `content`, reports what happened (transport event + audit log)
|
|
391
|
+
* and returns the outcome. `replacement` lets output checks attach the corrected text to the event.
|
|
392
|
+
*/
|
|
393
|
+
async guard(phase, content, agentId, toolName, replacement) {
|
|
394
|
+
if (!this.guardrails?.has(phase))
|
|
395
|
+
return { content, changed: false, events: [] };
|
|
396
|
+
const sessionId = this.opts.sessionId ?? 'default';
|
|
397
|
+
const secrets = this.opts.agents.get(agentId)?.secrets;
|
|
398
|
+
const secretValues = this.opts.agents.getAll().flatMap(a => Object.values(a.secrets ?? {}));
|
|
399
|
+
const outcome = await this.guardrails.run({
|
|
400
|
+
phase, agentId, sessionId, content,
|
|
401
|
+
...(toolName ? { toolName } : {}),
|
|
402
|
+
...(secrets ? { secrets } : {}),
|
|
403
|
+
secretValues,
|
|
404
|
+
});
|
|
405
|
+
const replaced = replacement?.(outcome);
|
|
406
|
+
outcome.events.forEach((info, i) => {
|
|
407
|
+
this.opts.transport.emit({
|
|
408
|
+
type: 'guardrail',
|
|
409
|
+
name: info.name, phase: info.phase, action: info.action, reason: info.reason,
|
|
410
|
+
agent_id: info.agentId,
|
|
411
|
+
...(info.tool ? { tool: info.tool } : {}),
|
|
412
|
+
...(info.dryRun ? { dry_run: true } : {}),
|
|
413
|
+
...(replaced !== undefined && !info.dryRun && i === outcome.events.length - 1 ? { replacement: replaced } : {}),
|
|
414
|
+
});
|
|
415
|
+
void this.auditLogger.log({
|
|
416
|
+
agentId: info.agentId,
|
|
417
|
+
tool: `guardrail:${info.phase}:${info.name}`,
|
|
418
|
+
inputPreview: `${info.action}${info.dryRun ? ' (dry-run)' : ''}: ${info.reason}`,
|
|
419
|
+
success: info.action === 'redact',
|
|
420
|
+
durationMs: 0,
|
|
421
|
+
sessionId,
|
|
422
|
+
});
|
|
423
|
+
});
|
|
424
|
+
return outcome;
|
|
425
|
+
}
|
|
426
|
+
/** Checks a model answer. Returns the (possibly corrected) message and the text to show. */
|
|
427
|
+
async guardOutput(message, agentId) {
|
|
428
|
+
const original = message.content ?? '';
|
|
429
|
+
if (!original || !this.guardrails?.has('output'))
|
|
430
|
+
return { message, text: original, touched: false };
|
|
431
|
+
const buffered = this.opts.guardrailOutputMode === 'buffer';
|
|
432
|
+
const outcome = await this.guard('output', original, agentId, undefined, buffered ? undefined : (o) => o.blocked ? this.blockedText(o) : (o.changed ? o.content : undefined));
|
|
433
|
+
if (outcome.blocked) {
|
|
434
|
+
const text = this.blockedText(outcome);
|
|
435
|
+
return { message: { ...message, content: text }, text, touched: true };
|
|
436
|
+
}
|
|
437
|
+
if (outcome.changed)
|
|
438
|
+
return { message: { ...message, content: outcome.content }, text: outcome.content, touched: true };
|
|
439
|
+
return { message, text: original, touched: false };
|
|
440
|
+
}
|
|
441
|
+
blockedText(outcome) {
|
|
442
|
+
return `[Response withheld by guardrail "${outcome.blocked?.guardrail}": ${outcome.blocked?.reason}]`;
|
|
443
|
+
}
|
|
444
|
+
/** Token-aware compaction first (when configured), then the message-count cap. */
|
|
445
|
+
async prepareContext() {
|
|
446
|
+
if (this.contextManager) {
|
|
447
|
+
try {
|
|
448
|
+
const report = await this.contextManager.compact();
|
|
449
|
+
if (report && report.summarizedMessages + report.droppedMessages + report.truncatedToolResults > 0) {
|
|
450
|
+
this.opts.transport.emit({
|
|
451
|
+
type: 'system', level: 'info',
|
|
452
|
+
text: `[Context] ~${report.tokensBefore} → ~${report.tokensAfter} tokens ` +
|
|
453
|
+
`(truncated ${report.truncatedToolResults} tool results, summarized ${report.summarizedMessages}, dropped ${report.droppedMessages} messages)`,
|
|
454
|
+
});
|
|
455
|
+
}
|
|
456
|
+
}
|
|
457
|
+
catch (err) {
|
|
458
|
+
// Compaction is best-effort: a bug here must never stop the agent.
|
|
459
|
+
this.opts.transport.emit({ type: 'system', level: 'warn', text: `[Context] Compaction failed: ${err instanceof Error ? err.message : String(err)}` });
|
|
460
|
+
}
|
|
461
|
+
}
|
|
462
|
+
this.trimHistory();
|
|
463
|
+
}
|
|
464
|
+
/** One summarization call, billed through `metrics` events like any other LLM call. */
|
|
465
|
+
summarizeForContext(transcript, previousSummary) {
|
|
466
|
+
const cfg = this.opts.context?.summarizer;
|
|
467
|
+
const provider = this.opts.providers.resolve(cfg?.provider, this.opts.defaultProvider);
|
|
468
|
+
const startedAt = Date.now();
|
|
469
|
+
return new Promise((resolve, reject) => {
|
|
470
|
+
const chunks = [];
|
|
471
|
+
Promise.resolve(provider.chat([
|
|
472
|
+
{ role: 'system', content: ContextManager_1.SUMMARY_SYSTEM_PROMPT },
|
|
473
|
+
{ role: 'user', content: (0, ContextManager_1.buildSummaryPrompt)(transcript, previousSummary) },
|
|
474
|
+
], [], {
|
|
475
|
+
onChunk: (delta) => { chunks.push(delta); },
|
|
476
|
+
onDone: (msg) => resolve(msg.content ?? chunks.join('')),
|
|
477
|
+
onError: reject,
|
|
478
|
+
onMetrics: (inputTokens, outputTokens, usage) => {
|
|
479
|
+
this.opts.transport.emit(metricsEvent(inputTokens, outputTokens, usage, {
|
|
480
|
+
provider: cfg?.provider ?? this.opts.defaultProvider,
|
|
481
|
+
model: cfg?.model ?? provider.modelId, purpose: 'context_summary', startedAt,
|
|
482
|
+
}));
|
|
483
|
+
},
|
|
484
|
+
...(cfg?.model ? { model: cfg.model } : {}),
|
|
485
|
+
})).catch(reject);
|
|
486
|
+
});
|
|
487
|
+
}
|
|
351
488
|
trimHistory() {
|
|
352
489
|
const max = this.opts.maxContextMessages;
|
|
353
490
|
if (!max)
|
|
@@ -532,20 +669,34 @@ class AgentEngine {
|
|
|
532
669
|
const shouldContinue = await iterManager.advance();
|
|
533
670
|
if (!shouldContinue)
|
|
534
671
|
break;
|
|
535
|
-
this.
|
|
672
|
+
await this.prepareContext();
|
|
536
673
|
const systemMsg = { role: 'system', content: this.buildSystemPrompt(currentProfile, orchestrationResult) };
|
|
537
674
|
const tools = this.getToolsForAgent(currentProfile);
|
|
538
675
|
const safeHistory = this.history.sanitized();
|
|
676
|
+
if (this.contextManager) {
|
|
677
|
+
this.lastRequestEstimate =
|
|
678
|
+
this.contextManager.estimateText(systemMsg.content ?? '') +
|
|
679
|
+
this.contextManager.estimateText(JSON.stringify(tools.map(t => [t.name, t.description, t.parameters]))) +
|
|
680
|
+
this.contextManager.estimateRaw(safeHistory);
|
|
681
|
+
}
|
|
539
682
|
let streamBuffer = '';
|
|
683
|
+
// `buffer` mode: hold tokens until the output guardrails have seen the whole answer.
|
|
684
|
+
const holdOutput = !!this.guardrails?.has('output') && this.opts.guardrailOutputMode === 'buffer';
|
|
685
|
+
const heldTokens = [];
|
|
540
686
|
const askAgentCalls = [];
|
|
541
687
|
const otherCalls = [];
|
|
542
688
|
let finalMessage = null;
|
|
543
689
|
this.abortController = new AbortController();
|
|
544
690
|
const signal = this.abortController.signal;
|
|
545
|
-
|
|
691
|
+
const chatProvider = this.getProviderForProfile(currentProfile);
|
|
692
|
+
const llmStartedAt = Date.now();
|
|
693
|
+
await chatProvider.chat([systemMsg, ...safeHistory], tools, {
|
|
546
694
|
onChunk: (delta) => {
|
|
547
695
|
streamBuffer += delta;
|
|
548
|
-
|
|
696
|
+
if (holdOutput)
|
|
697
|
+
heldTokens.push(delta);
|
|
698
|
+
else
|
|
699
|
+
this.opts.transport.emit({ type: 'token', content: delta, agent_id: currentProfile.id });
|
|
549
700
|
},
|
|
550
701
|
onToolCall: (name, args, id) => {
|
|
551
702
|
this.opts.transport.emit({ type: 'tool_call', name, args_preview: args.slice(0, 200) });
|
|
@@ -568,7 +719,14 @@ class AgentEngine {
|
|
|
568
719
|
this.opts.transport.emit({ type: 'error', message: err.message });
|
|
569
720
|
},
|
|
570
721
|
onMetrics: (inputTokens, outputTokens, usage) => {
|
|
571
|
-
|
|
722
|
+
// Anthropic reports cached tokens apart from input_tokens; the request still carried them.
|
|
723
|
+
this.contextManager?.observeUsage(inputTokens + (usage?.cacheReadTokens ?? 0) + (usage?.cacheWriteTokens ?? 0), this.lastRequestEstimate);
|
|
724
|
+
this.opts.transport.emit(metricsEvent(inputTokens, outputTokens, usage, {
|
|
725
|
+
agentId: currentProfile.id,
|
|
726
|
+
provider: currentProfile.provider ?? this.opts.defaultProvider,
|
|
727
|
+
model: currentProfile.model ?? chatProvider.modelId,
|
|
728
|
+
startedAt: llmStartedAt,
|
|
729
|
+
}));
|
|
572
730
|
},
|
|
573
731
|
signal,
|
|
574
732
|
model: currentProfile.model,
|
|
@@ -578,6 +736,15 @@ class AgentEngine {
|
|
|
578
736
|
break;
|
|
579
737
|
if (!finalMessage)
|
|
580
738
|
break;
|
|
739
|
+
const guardedOut = await this.guardOutput(finalMessage, currentProfile.id);
|
|
740
|
+
finalMessage = guardedOut.message;
|
|
741
|
+
if (guardedOut.touched)
|
|
742
|
+
streamBuffer = guardedOut.text;
|
|
743
|
+
if (holdOutput) {
|
|
744
|
+
const shown = guardedOut.touched ? guardedOut.text : heldTokens.join('');
|
|
745
|
+
if (shown)
|
|
746
|
+
this.opts.transport.emit({ type: 'token', content: shown, agent_id: currentProfile.id });
|
|
747
|
+
}
|
|
581
748
|
this.history.push(finalMessage);
|
|
582
749
|
const toolResults = [];
|
|
583
750
|
// ── ask_agent: parallel if 2+ calls ──────────────────────────────
|
|
@@ -626,13 +793,13 @@ class AgentEngine {
|
|
|
626
793
|
for (let i = 0; i < wave.length; i++)
|
|
627
794
|
iterManager.recordToolCall();
|
|
628
795
|
if (wave.length === 1) {
|
|
629
|
-
const result = await this.executeToolCall(first, currentProfile, 0);
|
|
796
|
+
const result = await this.executeToolCall(first, currentProfile, 0, undefined, () => this.history.redactToolCallArgs(first.id));
|
|
630
797
|
toolResults.push({ role: 'tool', tool_call_id: first.id, content: result });
|
|
631
798
|
continue;
|
|
632
799
|
}
|
|
633
800
|
// Parallel wave: events buffered per call, flushed in call order.
|
|
634
801
|
const buffers = wave.map(() => []);
|
|
635
|
-
const results = await Promise.all(wave.map((call, i) => this.executeToolCall(call, currentProfile, 0, e => buffers[i].push(e))));
|
|
802
|
+
const results = await Promise.all(wave.map((call, i) => this.executeToolCall(call, currentProfile, 0, e => buffers[i].push(e), () => this.history.redactToolCallArgs(call.id))));
|
|
636
803
|
wave.forEach((call, i) => {
|
|
637
804
|
for (const e of buffers[i])
|
|
638
805
|
this.opts.transport.emit(e);
|
|
@@ -725,12 +892,18 @@ class AgentEngine {
|
|
|
725
892
|
while (iter < maxIter && !this.aborted) {
|
|
726
893
|
iter++;
|
|
727
894
|
let streamContent = '';
|
|
895
|
+
const holdOutput = !!this.guardrails?.has('output') && this.opts.guardrailOutputMode === 'buffer';
|
|
896
|
+
const heldTokens = [];
|
|
728
897
|
const toolCalls = [];
|
|
729
898
|
let finalMessage = null;
|
|
730
|
-
|
|
899
|
+
const chatProvider = this.getProviderForProfile(profile);
|
|
900
|
+
const llmStartedAt = Date.now();
|
|
901
|
+
await chatProvider.chat(messages, this.getToolsForAgent(profile), {
|
|
731
902
|
onChunk: (delta) => {
|
|
732
903
|
streamContent += delta;
|
|
733
|
-
if (
|
|
904
|
+
if (holdOutput)
|
|
905
|
+
heldTokens.push(delta);
|
|
906
|
+
else if (!profile.suppressDefaultOutput) {
|
|
734
907
|
emit({ type: 'token', content: delta, agent_id: profile.id });
|
|
735
908
|
}
|
|
736
909
|
},
|
|
@@ -745,12 +918,26 @@ class AgentEngine {
|
|
|
745
918
|
onMetrics: (inputTokens, outputTokens, usage) => {
|
|
746
919
|
totalInputTokens += inputTokens;
|
|
747
920
|
totalOutputTokens += outputTokens;
|
|
748
|
-
emit(metricsEvent(inputTokens, outputTokens, usage
|
|
921
|
+
emit(metricsEvent(inputTokens, outputTokens, usage, {
|
|
922
|
+
agentId: profile.id,
|
|
923
|
+
provider: profile.provider ?? this.opts.defaultProvider,
|
|
924
|
+
model: profile.model ?? chatProvider.modelId,
|
|
925
|
+
startedAt: llmStartedAt,
|
|
926
|
+
}));
|
|
749
927
|
},
|
|
750
928
|
model: profile.model,
|
|
751
929
|
});
|
|
752
930
|
if (!finalMessage)
|
|
753
931
|
break;
|
|
932
|
+
const guardedOut = await this.guardOutput(finalMessage, profile.id);
|
|
933
|
+
finalMessage = guardedOut.message;
|
|
934
|
+
if (guardedOut.touched)
|
|
935
|
+
streamContent = guardedOut.text;
|
|
936
|
+
if (holdOutput && !profile.suppressDefaultOutput) {
|
|
937
|
+
const shown = guardedOut.touched ? guardedOut.text : heldTokens.join('');
|
|
938
|
+
if (shown)
|
|
939
|
+
emit({ type: 'token', content: shown, agent_id: profile.id });
|
|
940
|
+
}
|
|
754
941
|
if (streamContent)
|
|
755
942
|
finalContent = streamContent;
|
|
756
943
|
messages.push(finalMessage);
|
|
@@ -758,7 +945,14 @@ class AgentEngine {
|
|
|
758
945
|
break;
|
|
759
946
|
const toolResults = [];
|
|
760
947
|
for (const call of toolCalls) {
|
|
761
|
-
const result = await this.executeToolCall(call, profile, depth, emit)
|
|
948
|
+
const result = await this.executeToolCall(call, profile, depth, emit, () => {
|
|
949
|
+
// Sub-agent history is the local `messages` array: blank the refused arguments there too.
|
|
950
|
+
for (const m of messages) {
|
|
951
|
+
const tc = m.role === 'assistant' ? m.tool_calls?.find(c => c.id === call.id) : undefined;
|
|
952
|
+
if (tc)
|
|
953
|
+
tc.function = { ...tc.function, arguments: '{"redacted":"blocked by guardrail"}' };
|
|
954
|
+
}
|
|
955
|
+
});
|
|
762
956
|
toolResults.push({ role: 'tool', tool_call_id: call.id, content: result });
|
|
763
957
|
}
|
|
764
958
|
messages.push(...toolResults);
|
|
@@ -771,7 +965,9 @@ class AgentEngine {
|
|
|
771
965
|
* runAgentInternal (sub-agents via ask_agent).
|
|
772
966
|
* Handles: allowedTools authorization → onToolApproval gate → execute → audit → transport.
|
|
773
967
|
*/
|
|
774
|
-
async executeToolCall(call, profile, depth = 0, emit
|
|
968
|
+
async executeToolCall(call, profile, depth = 0, emit,
|
|
969
|
+
/** Called when a guardrail refused the arguments, so the caller can scrub them from its history. */
|
|
970
|
+
onArgsRefused) {
|
|
775
971
|
const emitEvent = emit ?? ((e) => this.opts.transport.emit(e));
|
|
776
972
|
const callStart = Date.now();
|
|
777
973
|
const toolDef = this.opts.tools.get(call.name);
|
|
@@ -788,20 +984,55 @@ class AgentEngine {
|
|
|
788
984
|
success = false;
|
|
789
985
|
}
|
|
790
986
|
else {
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
987
|
+
// Guardrails on the arguments run before approval: nobody is asked to approve a blocked call.
|
|
988
|
+
let effective = call;
|
|
989
|
+
let withheld;
|
|
990
|
+
if (this.guardrails?.has('tool_call')) {
|
|
991
|
+
const checked = await this.guard('tool_call', call.args, profile.id, call.name);
|
|
992
|
+
if (checked.blocked) {
|
|
993
|
+
withheld = `Tool call "${call.name}" blocked by guardrail "${checked.blocked.guardrail}": ${checked.blocked.reason}`;
|
|
994
|
+
}
|
|
995
|
+
else if (checked.changed) {
|
|
996
|
+
try {
|
|
997
|
+
JSON.parse(checked.content);
|
|
998
|
+
effective = { name: call.name, args: checked.content };
|
|
999
|
+
}
|
|
1000
|
+
catch {
|
|
1001
|
+
withheld = `Tool call "${call.name}" blocked by guardrails: redaction left the arguments invalid`;
|
|
1002
|
+
}
|
|
1003
|
+
}
|
|
1004
|
+
}
|
|
1005
|
+
if (withheld) {
|
|
1006
|
+
result = withheld;
|
|
794
1007
|
success = false;
|
|
1008
|
+
onArgsRefused?.();
|
|
795
1009
|
}
|
|
796
1010
|
else {
|
|
797
|
-
|
|
1011
|
+
const gateDecision = await this.checkGateSerial(effective, profile.id);
|
|
1012
|
+
if (gateDecision === 'rejected') {
|
|
1013
|
+
result = `Tool call "${call.name}" was rejected by the user.`;
|
|
1014
|
+
success = false;
|
|
1015
|
+
}
|
|
1016
|
+
else {
|
|
1017
|
+
({ result, success } = await this.runToolDef(effective, toolDef, profile.id, depth));
|
|
1018
|
+
if (this.guardrails?.has('tool_result')) {
|
|
1019
|
+
const checked = await this.guard('tool_result', result, profile.id, call.name);
|
|
1020
|
+
result = checked.blocked
|
|
1021
|
+
? `[Tool result withheld by guardrail "${checked.blocked.guardrail}": ${checked.blocked.reason}]`
|
|
1022
|
+
: checked.content;
|
|
1023
|
+
}
|
|
1024
|
+
}
|
|
798
1025
|
}
|
|
1026
|
+
call = effective;
|
|
799
1027
|
}
|
|
800
1028
|
await this.auditLogger.log({ agentId: profile.id, tool: call.name, inputPreview: call.args, success, durationMs: Date.now() - callStart, sessionId: this.opts.sessionId });
|
|
801
1029
|
// Strip ANSI before slicing to avoid partial escape sequences in the preview
|
|
802
1030
|
// eslint-disable-next-line no-control-regex
|
|
803
1031
|
const cleanPreview = result.replace(/\x1b\[[0-9;?]*[A-Za-z]/g, '');
|
|
804
|
-
emitEvent({
|
|
1032
|
+
emitEvent({
|
|
1033
|
+
type: 'tool_result', name: call.name, success, preview: cleanPreview.slice(0, 120),
|
|
1034
|
+
agent_id: profile.id, started_at: callStart, duration_ms: Date.now() - callStart,
|
|
1035
|
+
});
|
|
805
1036
|
return result;
|
|
806
1037
|
}
|
|
807
1038
|
/** Approval checks never overlap and run in call order, even inside a parallel wave. */
|