@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.
Files changed (55) hide show
  1. package/README.md +1238 -1168
  2. package/dist/engine/AgentEngine.d.ts +16 -0
  3. package/dist/engine/AgentEngine.d.ts.map +1 -1
  4. package/dist/engine/AgentEngine.js +250 -19
  5. package/dist/engine/AgentEngine.js.map +1 -1
  6. package/dist/engine/ContextManager.d.ts +88 -0
  7. package/dist/engine/ContextManager.d.ts.map +1 -0
  8. package/dist/engine/ContextManager.js +238 -0
  9. package/dist/engine/ContextManager.js.map +1 -0
  10. package/dist/engine/HistoryManager.d.ts +8 -0
  11. package/dist/engine/HistoryManager.d.ts.map +1 -1
  12. package/dist/engine/HistoryManager.js +19 -0
  13. package/dist/engine/HistoryManager.js.map +1 -1
  14. package/dist/engine/createBaseEngine.d.ts +26 -0
  15. package/dist/engine/createBaseEngine.d.ts.map +1 -1
  16. package/dist/engine/createBaseEngine.js +3 -0
  17. package/dist/engine/createBaseEngine.js.map +1 -1
  18. package/dist/guardrails/GuardrailRunner.d.ts +13 -0
  19. package/dist/guardrails/GuardrailRunner.d.ts.map +1 -0
  20. package/dist/guardrails/GuardrailRunner.js +64 -0
  21. package/dist/guardrails/GuardrailRunner.js.map +1 -0
  22. package/dist/guardrails/builtins.d.ts +82 -0
  23. package/dist/guardrails/builtins.d.ts.map +1 -0
  24. package/dist/guardrails/builtins.js +232 -0
  25. package/dist/guardrails/builtins.js.map +1 -0
  26. package/dist/guardrails/index.d.ts +5 -0
  27. package/dist/guardrails/index.d.ts.map +1 -0
  28. package/dist/guardrails/index.js +15 -0
  29. package/dist/guardrails/index.js.map +1 -0
  30. package/dist/guardrails/types.d.ts +70 -0
  31. package/dist/guardrails/types.d.ts.map +1 -0
  32. package/dist/guardrails/types.js +3 -0
  33. package/dist/guardrails/types.js.map +1 -0
  34. package/dist/index.d.ts +4 -0
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +16 -2
  37. package/dist/index.js.map +1 -1
  38. package/dist/observability/MetricsCollector.d.ts +2 -0
  39. package/dist/observability/MetricsCollector.d.ts.map +1 -1
  40. package/dist/observability/MetricsCollector.js +15 -0
  41. package/dist/observability/MetricsCollector.js.map +1 -1
  42. package/dist/observability/ObservabilityManager.d.ts +9 -0
  43. package/dist/observability/ObservabilityManager.d.ts.map +1 -1
  44. package/dist/observability/ObservabilityManager.js +59 -1
  45. package/dist/observability/ObservabilityManager.js.map +1 -1
  46. package/dist/observability/Tracer.d.ts +12 -0
  47. package/dist/observability/Tracer.d.ts.map +1 -1
  48. package/dist/observability/Tracer.js +19 -0
  49. package/dist/observability/Tracer.js.map +1 -1
  50. package/dist/observability/types.d.ts +6 -0
  51. package/dist/observability/types.d.ts.map +1 -1
  52. package/dist/observability/types.js.map +1 -1
  53. package/dist/types/index.d.ts +56 -2
  54. package/dist/types/index.d.ts.map +1 -1
  55. 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":"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"}
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
- return (0, generateObject_1.generateObject)(this.getProviderForProfile(profile), prompt, schema, {
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.trimHistory();
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
- await this.getProviderForProfile(currentProfile).chat([systemMsg, ...safeHistory], tools, {
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
- this.opts.transport.emit({ type: 'token', content: delta, agent_id: currentProfile.id });
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
- this.opts.transport.emit(metricsEvent(inputTokens, outputTokens, usage));
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
- await this.getProviderForProfile(profile).chat(messages, this.getToolsForAgent(profile), {
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 (!profile.suppressDefaultOutput) {
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
- const gateDecision = await this.checkGateSerial(call, profile.id);
792
- if (gateDecision === 'rejected') {
793
- result = `Tool call "${call.name}" was rejected by the user.`;
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
- ({ result, success } = await this.runToolDef(call, toolDef, profile.id, depth));
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({ type: 'tool_result', name: call.name, success, preview: cleanPreview.slice(0, 120) });
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. */