@backendkit-labs/agent-core 0.41.0 → 0.43.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 (116) hide show
  1. package/README.md +27 -0
  2. package/dist/engine/AgentEngine.d.ts +22 -2
  3. package/dist/engine/AgentEngine.d.ts.map +1 -1
  4. package/dist/engine/AgentEngine.js +92 -48
  5. package/dist/engine/AgentEngine.js.map +1 -1
  6. package/dist/engine/createBaseEngine.d.ts +2 -0
  7. package/dist/engine/createBaseEngine.d.ts.map +1 -1
  8. package/dist/engine/createBaseEngine.js +21 -4
  9. package/dist/engine/createBaseEngine.js.map +1 -1
  10. package/dist/engine/error-code.d.ts +7 -0
  11. package/dist/engine/error-code.d.ts.map +1 -0
  12. package/dist/engine/error-code.js +23 -0
  13. package/dist/engine/error-code.js.map +1 -0
  14. package/dist/engine/run-recorder.d.ts +13 -0
  15. package/dist/engine/run-recorder.d.ts.map +1 -0
  16. package/dist/engine/run-recorder.js +49 -0
  17. package/dist/engine/run-recorder.js.map +1 -0
  18. package/dist/flow/adapter.d.ts +20 -0
  19. package/dist/flow/adapter.d.ts.map +1 -0
  20. package/dist/flow/adapter.js +81 -0
  21. package/dist/flow/adapter.js.map +1 -0
  22. package/dist/flow/approval-handler.d.ts +59 -0
  23. package/dist/flow/approval-handler.d.ts.map +1 -0
  24. package/dist/flow/approval-handler.js +79 -0
  25. package/dist/flow/approval-handler.js.map +1 -0
  26. package/dist/flow/approval.d.ts +39 -0
  27. package/dist/flow/approval.d.ts.map +1 -0
  28. package/dist/flow/approval.js +58 -0
  29. package/dist/flow/approval.js.map +1 -0
  30. package/dist/flow/convert.d.ts +44 -0
  31. package/dist/flow/convert.d.ts.map +1 -0
  32. package/dist/flow/convert.js +34 -0
  33. package/dist/flow/convert.js.map +1 -0
  34. package/dist/flow/file-journal.d.ts +34 -0
  35. package/dist/flow/file-journal.d.ts.map +1 -0
  36. package/dist/flow/file-journal.js +176 -0
  37. package/dist/flow/file-journal.js.map +1 -0
  38. package/dist/flow/handler.d.ts +35 -0
  39. package/dist/flow/handler.d.ts.map +1 -0
  40. package/dist/flow/handler.js +51 -0
  41. package/dist/flow/handler.js.map +1 -0
  42. package/dist/flow/host.d.ts +79 -0
  43. package/dist/flow/host.d.ts.map +1 -0
  44. package/dist/flow/host.js +148 -0
  45. package/dist/flow/host.js.map +1 -0
  46. package/dist/flow/index.d.ts +27 -0
  47. package/dist/flow/index.d.ts.map +1 -0
  48. package/dist/flow/index.js +55 -0
  49. package/dist/flow/index.js.map +1 -0
  50. package/dist/flow/interpolate.d.ts +6 -0
  51. package/dist/flow/interpolate.d.ts.map +1 -0
  52. package/dist/flow/interpolate.js +18 -0
  53. package/dist/flow/interpolate.js.map +1 -0
  54. package/dist/flow/journal.d.ts +105 -0
  55. package/dist/flow/journal.d.ts.map +1 -0
  56. package/dist/flow/journal.js +89 -0
  57. package/dist/flow/journal.js.map +1 -0
  58. package/dist/flow/limiter.d.ts +21 -0
  59. package/dist/flow/limiter.d.ts.map +1 -0
  60. package/dist/flow/limiter.js +45 -0
  61. package/dist/flow/limiter.js.map +1 -0
  62. package/dist/flow/loader.d.ts +24 -0
  63. package/dist/flow/loader.d.ts.map +1 -0
  64. package/dist/flow/loader.js +172 -0
  65. package/dist/flow/loader.js.map +1 -0
  66. package/dist/flow/planner.d.ts +50 -0
  67. package/dist/flow/planner.d.ts.map +1 -0
  68. package/dist/flow/planner.js +131 -0
  69. package/dist/flow/planner.js.map +1 -0
  70. package/dist/flow/run.d.ts +106 -0
  71. package/dist/flow/run.d.ts.map +1 -0
  72. package/dist/flow/run.js +354 -0
  73. package/dist/flow/run.js.map +1 -0
  74. package/dist/flow/tools.d.ts +27 -0
  75. package/dist/flow/tools.d.ts.map +1 -0
  76. package/dist/flow/tools.js +71 -0
  77. package/dist/flow/tools.js.map +1 -0
  78. package/dist/flow/types.d.ts +112 -0
  79. package/dist/flow/types.d.ts.map +1 -0
  80. package/dist/flow/types.js +63 -0
  81. package/dist/flow/types.js.map +1 -0
  82. package/dist/governance/types.d.ts +6 -0
  83. package/dist/governance/types.d.ts.map +1 -1
  84. package/dist/index.d.ts +21 -4
  85. package/dist/index.d.ts.map +1 -1
  86. package/dist/index.js +53 -3
  87. package/dist/index.js.map +1 -1
  88. package/dist/learning/index.d.ts +2 -1
  89. package/dist/learning/index.d.ts.map +1 -1
  90. package/dist/learning/index.js +339 -63
  91. package/dist/learning/index.js.map +1 -1
  92. package/dist/learning/signal.d.ts +69 -0
  93. package/dist/learning/signal.d.ts.map +1 -0
  94. package/dist/learning/signal.js +201 -0
  95. package/dist/learning/signal.js.map +1 -0
  96. package/dist/learning/types.d.ts +203 -1
  97. package/dist/learning/types.d.ts.map +1 -1
  98. package/dist/learning/units.d.ts +46 -0
  99. package/dist/learning/units.d.ts.map +1 -0
  100. package/dist/learning/units.js +137 -0
  101. package/dist/learning/units.js.map +1 -0
  102. package/dist/tools/defineTool.d.ts +4 -1
  103. package/dist/tools/defineTool.d.ts.map +1 -1
  104. package/dist/tools/defineTool.js +5 -2
  105. package/dist/tools/defineTool.js.map +1 -1
  106. package/dist/tools/services.d.ts +13 -0
  107. package/dist/tools/services.d.ts.map +1 -1
  108. package/dist/tools/services.js +12 -0
  109. package/dist/tools/services.js.map +1 -1
  110. package/dist/tools/tool-error.d.ts +19 -0
  111. package/dist/tools/tool-error.d.ts.map +1 -0
  112. package/dist/tools/tool-error.js +33 -0
  113. package/dist/tools/tool-error.js.map +1 -0
  114. package/dist/types/index.d.ts +39 -0
  115. package/dist/types/index.d.ts.map +1 -1
  116. package/package.json +94 -89
@@ -1,6 +1,7 @@
1
1
  import type { Learning, LearningOptions } from './types';
2
2
  export { FileLessonStore, FileRuleStore, MemoryLessonStore, MemoryRuleStore } from './stores';
3
- export type { AddRuleInput, ApprovedRule, Experience, ExperienceInput, LearnedPattern, Learning, LearningOptions, LessonStore, RuleStore, Severity, TaughtLesson, TeachInput, ToolRule, } from './types';
3
+ export type { AddRuleInput, ApprovedRule, Experience, ExperienceInput, LearnedPattern, Learning, PatternRecord, LearningOptions, LessonStore, LessonUnitInfo, LearnedRulesView, OutcomeInput, RuleStore, Severity, TaughtLesson, TeachInput, ToolRule, } from './types';
4
+ export { ENGINE_ERROR_CODES, ENGINE_HINTS, GENERAL_UNIT } from './units';
4
5
  /**
5
6
  * Learning from what happens to the agents (SPEC-0017 F6). Experiences come from the audit events of the tool calls
6
7
  * and from whatever a vertical records; the same failure seen `threshold` times becomes a lesson in the prompt of
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/learning/index.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACiE,QAAQ,EAAE,eAAe,EAErG,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC9F,YAAY,EACR,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,eAAe,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EACpI,YAAY,EAAE,UAAU,EAAE,QAAQ,GACrC,MAAM,SAAS,CAAC;AAoFjB;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA4NtE"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/learning/index.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EACiE,QAAQ,EAAmC,eAAe,EAEtI,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC9F,YAAY,EACR,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAE,QAAQ,EAAE,aAAa,EAAE,eAAe,EAAE,WAAW,EAAE,cAAc,EAC9I,gBAAgB,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,GAC1F,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAyIzE;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA4btE"}
@@ -1,29 +1,52 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.MemoryRuleStore = exports.MemoryLessonStore = exports.FileRuleStore = exports.FileLessonStore = void 0;
3
+ exports.GENERAL_UNIT = exports.ENGINE_HINTS = exports.ENGINE_ERROR_CODES = exports.MemoryRuleStore = exports.MemoryLessonStore = exports.FileRuleStore = exports.FileLessonStore = void 0;
4
4
  exports.createLearning = createLearning;
5
5
  const node_crypto_1 = require("node:crypto");
6
+ const node_path_1 = require("node:path");
6
7
  const InMemoryStore_1 = require("../agent-memory/stores/InMemoryStore");
8
+ const JsonFileStore_1 = require("../agent-memory/stores/JsonFileStore");
7
9
  const approval_store_1 = require("../governance/approval-store");
8
10
  const policy_1 = require("../governance/policy");
9
11
  const sources_1 = require("../sources");
10
12
  const stores_1 = require("./stores");
13
+ const signal_1 = require("./signal");
14
+ const units_1 = require("./units");
11
15
  var stores_2 = require("./stores");
12
16
  Object.defineProperty(exports, "FileLessonStore", { enumerable: true, get: function () { return stores_2.FileLessonStore; } });
13
17
  Object.defineProperty(exports, "FileRuleStore", { enumerable: true, get: function () { return stores_2.FileRuleStore; } });
14
18
  Object.defineProperty(exports, "MemoryLessonStore", { enumerable: true, get: function () { return stores_2.MemoryLessonStore; } });
15
19
  Object.defineProperty(exports, "MemoryRuleStore", { enumerable: true, get: function () { return stores_2.MemoryRuleStore; } });
20
+ var units_2 = require("./units");
21
+ Object.defineProperty(exports, "ENGINE_ERROR_CODES", { enumerable: true, get: function () { return units_2.ENGINE_ERROR_CODES; } });
22
+ Object.defineProperty(exports, "ENGINE_HINTS", { enumerable: true, get: function () { return units_2.ENGINE_HINTS; } });
23
+ Object.defineProperty(exports, "GENERAL_UNIT", { enumerable: true, get: function () { return units_2.GENERAL_UNIT; } });
16
24
  const SEVERITIES = ['low', 'medium', 'high', 'critical'];
17
25
  const TOOL_FAILURES = new Set(['tool_error', 'tool_timeout', 'tool_too_large']);
18
26
  const MAX_TAUGHT_CHARS = 500;
27
+ const LESSON_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
28
+ function cleanLessonText(raw) {
29
+ const text = raw?.replace(/\s+/g, ' ').trim();
30
+ if (!text)
31
+ throw new Error('A lesson needs a text');
32
+ if (text.length > MAX_TAUGHT_CHARS)
33
+ throw new Error(`A lesson is at most ${MAX_TAUGHT_CHARS} characters; this one has ${text.length}`);
34
+ return text;
35
+ }
19
36
  const PROPOSER = { agentId: 'learning', sessionId: 'learning', chain: ['learning'] };
20
- const patternKey = (e) => `${e.domain}:${e.kind}:${e.subject ?? ''}`;
37
+ // A fingerprint is part of the key only when there is one, so the keys (and the proposals) of before it existed do not change.
38
+ // A context and a fingerprint are part of the key only when there is one, so the keys (and the proposals) of before they existed
39
+ // do not change.
40
+ const patternKey = (e) => `${e.domain}:${e.kind}:${e.subject ?? ''}${e.context ? `@${e.context}` : ''}${e.fingerprint ? `#${e.fingerprint}` : ''}`;
21
41
  /** Patterns never mix tenants: the group is the tenant plus the pattern key. */
22
42
  const groupKey = (e) => `${e.tenantId ?? ''}\u0000${patternKey(e)}`;
23
43
  const proposalId = (key) => `learn-${(0, node_crypto_1.createHash)('sha256').update(key).digest('hex').slice(0, 16)}`;
24
44
  // Sanitized on its own: the text comes from a tool or a policy, and inside a lesson line a role prefix would not be
25
45
  // at the start of the line, where the sanitizer of the whole layer looks for it.
26
46
  const oneLine = (text, max) => (0, sources_1.sanitizeDiskContent)(text.replace(/\s+/g, ' ').trim()).trim().slice(0, max);
47
+ // A unit name ends up in a heading of the prompt. A tool name from an MCP server or the domain of a vertical is external.
48
+ const normUnit = (name) => oneLine(name, 64) || units_1.GENERAL_UNIT;
49
+ const unitNameOf = (p) => normUnit(p.subject ?? p.domain);
27
50
  /** The experience a tool call leaves, or `undefined` when there is nothing to learn from it (a success). */
28
51
  function experienceFromAudit(event) {
29
52
  let kind;
@@ -68,11 +91,13 @@ function experienceFromAudit(event) {
68
91
  action: `${event.tool}#${event.argsHash.slice(0, 8)}`,
69
92
  kind,
70
93
  severity,
94
+ ...(event.errorCode && kind === 'tool_error' ? { fingerprint: event.errorCode } : {}),
71
95
  ...(event.reason ? { detail: event.reason } : {}),
72
96
  };
73
97
  }
74
- function detectPatterns(experiences, threshold) {
98
+ function detectPatterns(experiences, threshold, ctx) {
75
99
  const groups = new Map();
100
+ const failuresOf = new Map();
76
101
  for (const e of experiences) {
77
102
  if (e.outcome !== 'failure')
78
103
  continue;
@@ -82,15 +107,38 @@ function detectPatterns(experiences, threshold) {
82
107
  group.push(e);
83
108
  else
84
109
  groups.set(key, [e]);
110
+ if (e.subject) {
111
+ const subjectKey = `${e.tenantId ?? ''}\u0000${e.domain}\u0000${e.subject}\u0000${e.context ?? ''}`;
112
+ failuresOf.set(subjectKey, (failuresOf.get(subjectKey) ?? 0) + 1);
113
+ }
85
114
  }
86
115
  const patterns = [];
87
116
  for (const group of groups.values()) {
88
117
  group.sort((a, b) => a.at.localeCompare(b.at));
89
118
  const last = group[group.length - 1];
119
+ const gk = groupKey(last);
90
120
  if (group.length < threshold(last))
91
121
  continue;
92
- patterns.push({
93
- key: patternKey(last), ...(last.tenantId ? { tenantId: last.tenantId } : {}), domain: last.domain, kind: last.kind, ...(last.subject ? { subject: last.subject } : {}),
122
+ let passes = true;
123
+ let calls;
124
+ if (ctx?.rate && last.subject) {
125
+ calls = ctx.successes(last.tenantId, last.domain, last.subject, ctx.agentId, last.context)
126
+ + (failuresOf.get(`${last.tenantId ?? ''}\u0000${last.domain}\u0000${last.subject}\u0000${last.context ?? ''}`) ?? 0);
127
+ passes = !(calls >= ctx.rate.minCalls && group.length / calls < ctx.rate.minFailureRate);
128
+ }
129
+ // The rate decides when a pattern enters; once in, it stays (SPEC-0022). One a person resolved needs new failures after that, and the rate, to come back.
130
+ const known = ctx?.records.state(gk);
131
+ if (known?.state === 'resolved') {
132
+ if (!passes || group.filter(e => e.at > (known.resolvedAt ?? '')).length < threshold(last))
133
+ continue;
134
+ }
135
+ else if (!passes && known?.state !== 'active')
136
+ continue;
137
+ const pattern = {
138
+ key: patternKey(last), ...(last.tenantId ? { tenantId: last.tenantId } : {}), domain: last.domain, kind: last.kind,
139
+ ...(last.subject ? { subject: last.subject } : {}),
140
+ ...(last.context ? { context: last.context } : {}),
141
+ ...(last.fingerprint ? { fingerprint: last.fingerprint } : {}),
94
142
  count: group.length,
95
143
  firstSeen: group[0].at,
96
144
  lastSeen: last.at,
@@ -99,9 +147,12 @@ function detectPatterns(experiences, threshold) {
99
147
  agentIds: [...new Set(group.map(e => e.agentId))],
100
148
  situation: last.situation,
101
149
  ...(last.detail ? { detail: last.detail } : {}),
102
- });
150
+ ...(calls !== undefined ? { calls } : {}),
151
+ };
152
+ ctx?.records.confirm(gk, pattern);
153
+ patterns.push(pattern);
103
154
  }
104
- return patterns.sort((a, b) => b.count - a.count);
155
+ return patterns.sort((a, b) => b.count - a.count || a.key.localeCompare(b.key));
105
156
  }
106
157
  function isToolRule(value) {
107
158
  const r = value;
@@ -118,20 +169,33 @@ function isToolRule(value) {
118
169
  * ```
119
170
  */
120
171
  function createLearning(options = {}) {
121
- const store = options.store ?? new InMemoryStore_1.InMemoryStore();
122
- const approvals = options.approvals ?? new approval_store_1.MemoryApprovalStore();
123
- const rules = options.rules ?? new stores_1.MemoryRuleStore();
124
- const lessonStore = options.lessonStore ?? new stores_1.MemoryLessonStore();
172
+ const dir = options.dir;
173
+ const store = options.store ?? (dir ? new JsonFileStore_1.JsonFileStore((0, node_path_1.join)(dir, 'experiences.json')) : new InMemoryStore_1.InMemoryStore());
174
+ const approvals = options.approvals ?? (dir ? new approval_store_1.FileApprovalStore((0, node_path_1.join)(dir, 'proposals')) : new approval_store_1.MemoryApprovalStore());
175
+ const rules = options.rules ?? (dir ? new stores_1.FileRuleStore((0, node_path_1.join)(dir, 'rules.json')) : new stores_1.MemoryRuleStore());
176
+ const lessonStore = options.lessonStore ?? (dir ? new stores_1.FileLessonStore((0, node_path_1.join)(dir, 'lessons.json')) : new stores_1.MemoryLessonStore());
125
177
  const base = options.threshold ?? 3;
126
178
  const threshold = options.thresholdFor ?? (() => base);
127
179
  const maxExperiences = options.maxExperiences ?? 1000;
128
180
  const maxChars = options.lessons?.maxChars ?? 1500;
129
181
  const maxLessons = options.lessons?.maxLessons ?? 5;
182
+ const maxPerUnit = options.lessons?.maxPerUnit ?? 3;
183
+ const hints = new Map();
130
184
  const approverKinds = options.approverKinds ?? ['human'];
131
185
  const ruleFor = options.ruleFor ?? defaultRuleFor;
186
+ const now = options.now ?? (() => new Date());
187
+ const useClock = options.stamp === 'clock';
188
+ /** The time an experience carries when it did not come with its own. */
189
+ const stampNow = () => (useClock ? now() : new Date()).toISOString();
190
+ const windowDays = options.window?.days ?? 30;
191
+ const rate = options.rate === false ? false : { ...signal_1.DEFAULT_RATE, ...(options.rate ?? {}) };
192
+ const counterStore = options.counters ?? (dir ? new JsonFileStore_1.JsonFileStore((0, node_path_1.join)(dir, 'counters.json')) : new InMemoryStore_1.InMemoryStore());
193
+ const counters = new signal_1.SuccessCounters(counterStore);
194
+ const records = new signal_1.PatternRecords(counterStore);
195
+ // The calls of a subject are needed as far back as the quiet period; the counters are kept twice that.
196
+ const quietAfterDays = options.quietAfterDays ?? windowDays;
197
+ const retentionDays = Math.max(windowDays, quietAfterDays) * 2;
132
198
  const lessonCache = new Map();
133
- // The line of a lesson is written once: a new failure of the same pattern must not change the system prompt.
134
- const lessonLines = new Map();
135
199
  function defaultRuleFor(p) {
136
200
  if (p.domain !== 'tool' || !p.subject || !TOOL_FAILURES.has(p.kind))
137
201
  return undefined;
@@ -141,6 +205,22 @@ function createLearning(options = {}) {
141
205
  const { createdAt: _createdAt, ...rest } = r;
142
206
  return rest;
143
207
  });
208
+ const dayBefore = (days) => new Date(now().getTime() - days * 86_400_000).toISOString().slice(0, 10);
209
+ /** The experiences still inside the window: the only ones patterns, lessons and proposals look at. */
210
+ const inWindow = () => {
211
+ const since = new Date(now().getTime() - windowDays * 86_400_000).toISOString();
212
+ return all().filter(e => e.at >= since);
213
+ };
214
+ const rateContext = (agentId) => ({
215
+ rate,
216
+ successes: (tenantId, domain, subject, agent, context) => counters.since(dayBefore(windowDays), tenantId, domain, subject, agent, context),
217
+ ...(agentId ? { agentId } : {}),
218
+ // The view of one agent has its own share, so it has its own memory of what passed it.
219
+ records: {
220
+ state: key => records.state(`${agentId ?? ''}|${key}`, dayBefore(windowDays)),
221
+ confirm: (key, pattern) => records.confirm(`${agentId ?? ''}|${key}`, agentId ?? '', pattern),
222
+ },
223
+ });
144
224
  // record() calls run one after another, so two failures at once cannot both propose the same rule.
145
225
  let queue = Promise.resolve();
146
226
  const serialized = (fn) => {
@@ -148,9 +228,21 @@ function createLearning(options = {}) {
148
228
  queue = next.catch(() => undefined);
149
229
  return next;
150
230
  };
231
+ /** What a person sees when deciding on a rule: how many failures, out of how many calls, and since when. */
232
+ function evidenceOf(p) {
233
+ const share = p.calls ? ` (${p.count} of ${p.calls} calls, ${Math.round((p.count / p.calls) * 100)}%)` : '';
234
+ const back = records.list().find(r => r.agentId === '' && r.key === p.key && r.tenantId === p.tenantId)?.reappeared;
235
+ const again = back ? ` (resolved on ${back.resolvedAt.slice(0, 10)}, and it came back)` : '';
236
+ return `${p.count} x ${p.kind}${p.subject ? ` on ${p.subject}` : ''}${share}, ${p.firstSeen} to ${p.lastSeen}${again}`;
237
+ }
151
238
  async function propose(experience) {
152
239
  const key = groupKey(experience);
153
- const pattern = detectPatterns(all().filter(e => groupKey(e) === key), threshold)[0];
240
+ const group = inWindow().filter(e => groupKey(e) === key);
241
+ // The view of each agent has its own share: the moment the failure is recorded is the moment it qualifies, not the first
242
+ // turn that happens to ask for the lessons after a flood of correct calls.
243
+ for (const agentId of new Set(group.map(e => e.agentId)))
244
+ detectPatterns(group.filter(e => e.agentId === agentId), threshold, rateContext(agentId));
245
+ const pattern = detectPatterns(group, threshold, rateContext())[0];
154
246
  if (!pattern)
155
247
  return;
156
248
  const id = proposalId(key);
@@ -165,7 +257,7 @@ function createLearning(options = {}) {
165
257
  subject: {
166
258
  kind: 'rule_proposal',
167
259
  rule,
168
- evidence: `${pattern.count} x ${pattern.kind}${pattern.subject ? ` on ${pattern.subject}` : ''}, ${pattern.firstSeen} to ${pattern.lastSeen}`,
260
+ evidence: evidenceOf(pattern),
169
261
  },
170
262
  reason: `Learned from ${pattern.count} repetitions of ${pattern.key}`,
171
263
  createdAt: new Date().toISOString(),
@@ -174,64 +266,130 @@ function createLearning(options = {}) {
174
266
  const record = (input) => serialized(async () => {
175
267
  const { at, outcome, severity, ...rest } = input;
176
268
  const experience = {
177
- ...rest, id: `exp_${(0, node_crypto_1.randomUUID)()}`, at: at ?? new Date().toISOString(),
269
+ ...rest, id: `exp_${(0, node_crypto_1.randomUUID)()}`, at: at ?? stampNow(),
178
270
  outcome: outcome ?? 'failure', severity: severity ?? 'medium',
179
271
  };
272
+ if (experience.outcome === 'success') {
273
+ // A success is only counted (SPEC-0019 D1): it is the denominator of a failure rate, never a record to keep.
274
+ if (experience.subject)
275
+ counters.add(experience.at, experience.agentId, experience.tenantId, experience.domain, experience.subject, experience.context);
276
+ return experience;
277
+ }
180
278
  store.insert({ ...experience, createdAt: experience.at });
181
279
  if (store.count() > maxExperiences)
182
280
  store.deleteOldest(maxExperiences);
183
- if (experience.outcome === 'failure')
184
- await propose(experience);
281
+ await propose(experience);
282
+ await counters.flush(dayBefore(retentionDays));
185
283
  return experience;
186
284
  });
285
+ /** The experience of a pattern is gone from the window, the record is not: a record says what a lesson needs. */
286
+ const asPattern = (r) => ({
287
+ key: r.key, ...(r.tenantId ? { tenantId: r.tenantId } : {}), domain: r.domain, kind: r.kind,
288
+ ...(r.subject ? { subject: r.subject } : {}), ...(r.context ? { context: r.context } : {}), ...(r.fingerprint ? { fingerprint: r.fingerprint } : {}),
289
+ count: r.count, firstSeen: r.firstSeen, lastSeen: r.lastFailure, severity: r.severity, experienceIds: [], agentIds: [r.agentId],
290
+ situation: r.situation, ...(r.detail ? { detail: r.detail } : {}),
291
+ });
292
+ /**
293
+ * The sentence of a learned lesson: what the tool's author says about the error, what the engine says about the kind of failure,
294
+ * or the plain fact (from the first experience of the pattern). It is written once, in the record of the pattern: a later failure,
295
+ * a hint registered afterwards or a restart do not rewrite it, so the system prompt stays cacheable. A hint a tool's author
296
+ * improves later reaches the patterns that appear after that, not the ones already written.
297
+ */
298
+ function lineFor(r) {
299
+ const p = asPattern(r);
300
+ const fp = p.fingerprint ? oneLine(p.fingerprint, 64) : undefined;
301
+ // What a tool's author says is about the errors it raises. A denial, a block or a timeout is not one: for those the
302
+ // engine speaks, so that a `*` hint never tells the model to retry a call that was refused.
303
+ const toolHints = p.domain === 'tool' && p.kind === 'tool_error' && p.subject ? hints.get(p.subject) : undefined;
304
+ // `(context)` or `(fingerprint)`, or both: what tells this pattern from the others of the same unit.
305
+ const labels = [p.context ? oneLine(p.context, 64) : undefined, fp].filter(Boolean);
306
+ const tag = labels.length ? ` (${labels.join(', ')})` : '';
307
+ const toolError = p.domain === 'tool' && p.kind === 'tool_error';
308
+ // The author of the tool for this very code, then what the engine knows of the code (a malformed call), then the author's
309
+ // fallback, then what the engine knows of the kind of failure.
310
+ const hint = (p.fingerprint ? toolHints?.[p.fingerprint] : undefined)
311
+ ?? (toolError && p.fingerprint ? units_1.ENGINE_ERROR_CODES[p.fingerprint] : undefined)
312
+ ?? toolHints?.['*'] ?? (p.domain === 'tool' ? units_1.ENGINE_HINTS[p.kind] : undefined);
313
+ if (r.line !== undefined)
314
+ return r.line;
315
+ // The advice, when there is one. The situation is the one of the FIRST experience, so it is only used when there is nothing better to say.
316
+ const line = hint
317
+ ? `${fp ?? p.kind}: ${oneLine(hint, 240)}`
318
+ : p.detail
319
+ ? `${p.kind}${tag} keeps happening: ${oneLine(p.detail, 200)}`
320
+ : `${p.kind}${tag} keeps happening. ${oneLine(p.situation, 120)}`;
321
+ records.setLine(r.view, line);
322
+ return line;
323
+ }
324
+ /** The lessons of the view of all the agents that are still in use: what the units show and export. */
325
+ const activeForAll = () => records.list().filter(r => r.agentId === '' && r.state === 'active' && inUse(r));
326
+ /** Is the subject of the record still in use? A subject without calls to count (a signal of a vertical) lives as long as its window. */
327
+ function inUse(r) {
328
+ if (!r.subject)
329
+ return r.lastFailure >= new Date(now().getTime() - windowDays * 86_400_000).toISOString();
330
+ const since = dayBefore(quietAfterDays);
331
+ return r.lastFailure.slice(0, 10) >= since
332
+ || counters.since(since, r.tenantId, r.domain, r.subject, r.agentId || undefined, r.context) > 0;
333
+ }
187
334
  // What the patterns say is cached while the experiences do not change; what people taught is read each time, because
188
335
  // it may be changed from another process.
189
- function learnedText(agentId, tenantId) {
336
+ function learnedItems(agentId, tenantId) {
190
337
  const count = store.count();
338
+ const at = now().getTime();
339
+ const day = new Date(at).toISOString().slice(0, 10);
191
340
  const scope = `${tenantId ?? ''}\u0000${agentId}`;
341
+ // Recomputed when the experiences change, the day changes or a minute passes: the counters of correct calls move all
342
+ // the time, and the lessons must not flap with each call.
192
343
  const cached = lessonCache.get(scope);
193
- if (cached && cached.count === count)
194
- return cached.text;
195
- const own = all().filter(e => e.agentId === agentId && e.tenantId === tenantId);
196
- const lines = detectPatterns(own, threshold).slice(0, maxLessons)
197
- .sort((x, y) => x.key.localeCompare(y.key))
198
- .map(p => {
199
- const id = `${scope}\u0000${p.key}`;
200
- let line = lessonLines.get(id);
201
- if (!line) {
202
- line = `- ${p.subject ? `${p.subject}: ` : ''}${p.kind} keeps happening. ${oneLine(p.situation, 120)}${p.detail ? `: ${oneLine(p.detail, 160)}` : ''}`;
203
- lessonLines.set(id, line);
204
- }
205
- return line;
206
- });
207
- const text = lines.length ? lines.join('\n') : undefined;
208
- lessonCache.set(scope, { count, text });
209
- return text;
344
+ if (cached && cached.count === count && cached.day === day && at - cached.at < 60_000)
345
+ return cached.items;
346
+ const own = inWindow().filter(e => e.agentId === agentId && e.tenantId === tenantId);
347
+ // Seeing the patterns confirms their records (and brings back the ones a person resolved that failed again).
348
+ const current = new Set(detectPatterns(own, threshold, rateContext(agentId)).map(p => p.key));
349
+ const mine = records.list().filter(r => r.agentId === agentId && r.tenantId === tenantId && r.state === 'active' && inUse(r));
350
+ // The ones that fail now come first, so that a lesson that stays because its subject is still called does not take the place of
351
+ // a new problem; inside each group, the most frequent first. The cap per unit and the cap in total keep the first ones.
352
+ mine.sort((x, y) => Number(current.has(y.key)) - Number(current.has(x.key)) || y.count - x.count || x.key.localeCompare(y.key));
353
+ const perUnit = new Map();
354
+ const chosen = [];
355
+ for (const r of mine) {
356
+ const unit = unitNameOf(r);
357
+ if ((perUnit.get(unit) ?? 0) >= maxPerUnit)
358
+ continue;
359
+ if (chosen.length >= maxLessons)
360
+ break;
361
+ perUnit.set(unit, (perUnit.get(unit) ?? 0) + 1);
362
+ chosen.push(r);
363
+ }
364
+ const items = chosen.map(r => ({ unit: unitNameOf(r), source: 'learned', text: lineFor(r), order: r.key }));
365
+ lessonCache.set(scope, { count, day, at, items });
366
+ return items;
210
367
  }
211
- async function taughtText(agentId, tenantId, available) {
212
- const mine = (await lessonStore.list())
368
+ const unitOf = (l) => normUnit(l.unit ?? l.tools?.[0] ?? units_1.GENERAL_UNIT);
369
+ async function taughtItems(agentId, tenantId, available) {
370
+ return (await lessonStore.list())
213
371
  .filter(l => l.tenantId === tenantId
214
372
  && (!l.agentId || l.agentId === agentId)
215
373
  && (!l.tools?.length || (available ?? []).some(t => l.tools.includes(t))))
216
- .sort((x, y) => x.at.localeCompare(y.at) || x.id.localeCompare(y.id));
217
- return mine.length ? mine.map(l => `- ${oneLine(l.text, MAX_TAUGHT_CHARS)}`).join('\n') : undefined;
374
+ .map(l => ({ unit: unitOf(l), source: 'taught', text: oneLine(l.text, MAX_TAUGHT_CHARS), order: `${l.at}\u0000${l.id}` }));
218
375
  }
219
376
  async function lessonsFor(agentId, tenantId, availableTools) {
220
- const layers = [];
221
- const taught = await taughtText(agentId, tenantId, availableTools);
222
- if (taught)
223
- layers.push({ title: 'Taught lessons', content: taught, maxChars });
224
- const learned = learnedText(agentId, tenantId);
225
- if (learned)
226
- layers.push({ title: 'Lessons learned', content: learned, maxChars });
227
- return layers.length ? (0, sources_1.composeInstructionLayers)(layers) : undefined;
377
+ const items = [...await taughtItems(agentId, tenantId, availableTools), ...learnedItems(agentId, tenantId)];
378
+ const text = (0, units_1.fitUnits)((0, units_1.groupEntries)(items), maxChars);
379
+ return text ? (0, sources_1.composeInstructionLayers)([{ title: 'Lessons', content: text }]) : undefined;
228
380
  }
381
+ // Two lessons taught in the same millisecond keep the order in which they were taught.
382
+ let lastAt = 0;
383
+ const nextAt = () => {
384
+ lastAt = Math.max(Date.now(), lastAt + 1);
385
+ return new Date(lastAt).toISOString();
386
+ };
229
387
  function requireAuthor(by, what) {
230
388
  if (!approverKinds.includes(by.kind)) {
231
389
  throw new Error(`${what} needs ${approverKinds.join(' or ')}, not ${by.kind}`);
232
390
  }
233
391
  }
234
- async function resolve(id, by, decision, reason) {
392
+ async function decide(id, by, decision, reason) {
235
393
  if (!approverKinds.includes(by.kind)) {
236
394
  throw new Error(`A learned rule needs approval from ${approverKinds.join(' or ')}, not from ${by.kind}`);
237
395
  }
@@ -256,28 +414,46 @@ function createLearning(options = {}) {
256
414
  return decisions.length ? (0, policy_1.combineDecisions)(decisions) : { effect: 'allow' };
257
415
  },
258
416
  };
259
- return {
417
+ const api = {
260
418
  rules,
261
419
  policy,
262
420
  sink: {
263
421
  write(event) {
422
+ if (event.decision === 'allow' && event.outcome === 'ok') {
423
+ counters.add(useClock ? stampNow() : event.at, event.principal.agentId, event.principal.tenantId, 'tool', event.tool);
424
+ return undefined;
425
+ }
264
426
  const input = experienceFromAudit(event);
265
- return input ? record(input).then(() => undefined) : undefined;
427
+ return input ? record(useClock ? { ...input, at: stampNow() } : input).then(() => undefined) : undefined;
266
428
  },
267
429
  },
268
430
  hooks: {
269
431
  name: 'learning',
270
432
  systemPrompt: (ctx, profile) => lessonsFor(profile.id, ctx.principal.tenantId, profile.allowedTools),
433
+ // The counters of correct calls reach their store at the end of each turn. A failed write must not fail the turn.
434
+ afterRun: async () => { await counters.flush(dayBefore(retentionDays)).catch(() => undefined); },
271
435
  },
272
436
  record,
437
+ trackOutcome(o) {
438
+ if (o.ok && !o.subject?.trim()) {
439
+ return Promise.reject(new Error('A success needs a subject: it is counted against it, and without one it would never be counted'));
440
+ }
441
+ return record({
442
+ agentId: o.agentId, ...(o.tenantId ? { tenantId: o.tenantId } : {}), domain: o.domain, subject: o.subject, ...(o.context ? { context: o.context } : {}),
443
+ kind: o.ok ? 'ok' : (o.kind ?? 'failure'), outcome: o.ok ? 'success' : 'failure',
444
+ ...(o.severity ? { severity: o.severity } : {}), ...(o.detail ? { detail: o.detail } : {}),
445
+ situation: o.situation ?? `${o.domain} ${o.subject}`, action: o.action ?? o.subject,
446
+ ...(o.meta ? { meta: o.meta } : {}), ...(o.at ? { at: o.at } : {}),
447
+ });
448
+ },
273
449
  async experiences(filter = {}) {
274
450
  return all().filter(e => (!filter.agentId || e.agentId === filter.agentId)
275
451
  && (!filter.domain || e.domain === filter.domain)
276
452
  && (filter.tenantId === undefined || e.tenantId === filter.tenantId));
277
453
  },
278
454
  async patterns(filter = {}) {
279
- return detectPatterns(all().filter(e => (!filter.agentId || e.agentId === filter.agentId)
280
- && (filter.tenantId === undefined || e.tenantId === filter.tenantId)), threshold);
455
+ return detectPatterns(inWindow().filter(e => (!filter.agentId || e.agentId === filter.agentId)
456
+ && (filter.tenantId === undefined || e.tenantId === filter.tenantId)), threshold, rateContext(filter.agentId));
281
457
  },
282
458
  lessonsFor,
283
459
  async proposals(filter = {}) {
@@ -286,7 +462,7 @@ function createLearning(options = {}) {
286
462
  && (filter.tenantId === undefined || a.principal.tenantId === filter.tenantId));
287
463
  },
288
464
  async approve(id, by, reason) {
289
- const { request } = await resolve(id, by, 'approve', reason);
465
+ const { request } = await decide(id, by, 'approve', reason);
290
466
  const subject = request.subject;
291
467
  const approved = {
292
468
  id, rule: subject.rule, ...(request.principal.tenantId ? { tenantId: request.principal.tenantId } : {}),
@@ -296,22 +472,121 @@ function createLearning(options = {}) {
296
472
  await rules.add(approved);
297
473
  return approved;
298
474
  },
299
- async reject(id, by, reason) { await resolve(id, by, 'reject', reason); },
475
+ async reject(id, by, reason) { await decide(id, by, 'reject', reason); },
300
476
  retire: id => rules.remove(id),
477
+ rulesView(tenantId) {
478
+ // Copies, and no way back to the store: a tool that reads the rules cannot change them.
479
+ const mine = async () => (await rules.list()).filter(r => r.tenantId === tenantId).map(r => structuredClone(r));
480
+ return Object.freeze({
481
+ list: mine,
482
+ async where(guard) {
483
+ return (await mine()).filter(r => guard(r.rule)).map(r => ({ id: r.id, rule: r.rule, approvedAt: r.approvedAt, approvedBy: r.approvedBy }));
484
+ },
485
+ });
486
+ },
487
+ async resolve(patternKey, by, opts = {}) {
488
+ requireAuthor(by, 'Resolving a lesson');
489
+ const at = now().toISOString();
490
+ const hit = records.list().filter(r => r.key === patternKey && r.tenantId === opts.tenantId);
491
+ if (!hit.length)
492
+ throw new Error(`No pattern "${patternKey}"${opts.tenantId ? ` for tenant "${opts.tenantId}"` : ''}`);
493
+ for (const r of hit)
494
+ records.resolve(r.view, by, at, opts.reason);
495
+ lessonCache.clear();
496
+ },
497
+ async records(filter = {}) {
498
+ return records.list()
499
+ // The view of all the agents (an empty agent) feeds the proposals, not the prompts: it is only listed when asked for.
500
+ .filter(r => (filter.agentId === undefined ? r.agentId !== '' : r.agentId === filter.agentId)
501
+ && (filter.tenantId === undefined || r.tenantId === filter.tenantId)
502
+ && (!filter.state || r.state === filter.state))
503
+ .map(({ view: _view, ...rec }) => structuredClone(rec));
504
+ },
505
+ flush: async () => {
506
+ records.legacyKeep = dayBefore(retentionDays);
507
+ // A record goes when its subject is quiet and its last failure is older than the counters are kept.
508
+ records.prune(r => !inUse(r) && r.lastFailure.slice(0, 10) < dayBefore(retentionDays));
509
+ await counters.flush(dayBefore(retentionDays));
510
+ },
511
+ registerHints(tool, toolHints) { hints.set(tool, { ...(hints.get(tool) ?? {}), ...toolHints }); },
512
+ async units(filter = {}) {
513
+ const out = new Map();
514
+ const slot = (name, tenantId) => {
515
+ const k = `${tenantId ?? ''}\u0000${name}`;
516
+ let u = out.get(k);
517
+ if (!u)
518
+ out.set(k, u = { name, ...(tenantId ? { tenantId } : {}), taught: 0, learned: 0 });
519
+ return u;
520
+ };
521
+ for (const l of await lessonStore.list()) {
522
+ if (filter.tenantId === undefined || l.tenantId === filter.tenantId)
523
+ slot(unitOf(l), l.tenantId).taught++;
524
+ }
525
+ detectPatterns(inWindow().filter(e => filter.tenantId === undefined || e.tenantId === filter.tenantId), threshold, rateContext());
526
+ for (const r of activeForAll()) {
527
+ if (filter.tenantId === undefined || r.tenantId === filter.tenantId)
528
+ slot(r.subject ?? r.domain, r.tenantId).learned++;
529
+ }
530
+ return [...out.values()].sort((a, b) => a.name.localeCompare(b.name) || (a.tenantId ?? '').localeCompare(b.tenantId ?? ''));
531
+ },
532
+ async exportUnit(rawUnit, scope = {}) {
533
+ const unit = normUnit(rawUnit);
534
+ const taught = (await lessonStore.list())
535
+ .filter(l => unitOf(l) === unit && l.tenantId === scope.tenantId && l.agentId === scope.agentId)
536
+ .sort((a, b) => a.at.localeCompare(b.at) || a.id.localeCompare(b.id));
537
+ detectPatterns(inWindow().filter(e => e.tenantId === scope.tenantId && unitNameOf(e) === unit), threshold, rateContext());
538
+ const learned = activeForAll().filter(r => r.tenantId === scope.tenantId && unitNameOf(r) === unit).map(lineFor).sort();
539
+ const tools = [...new Set(taught.flatMap(l => l.tools ?? []))].sort();
540
+ return (0, units_1.unitToMarkdown)({
541
+ unit, tools, ...(scope.agentId ? { agentId: scope.agentId } : {}), ...(scope.tenantId ? { tenantId: scope.tenantId } : {}),
542
+ taught: taught.map(l => l.text), learned,
543
+ });
544
+ },
545
+ async importUnit(markdown, by, opts = {}) {
546
+ requireAuthor(by, 'Importing lessons');
547
+ const doc = (0, units_1.unitFromMarkdown)(markdown);
548
+ // In a product with tenants the caller says which one the file is for; otherwise the front matter decides.
549
+ const tenantId = 'tenantId' in opts ? opts.tenantId : doc.tenantId;
550
+ const unit = normUnit(doc.unit);
551
+ const tools = doc.tools.length ? doc.tools : unit === units_1.GENERAL_UNIT ? [] : [unit];
552
+ // Everything is checked before anything is written: a file is imported whole or not at all.
553
+ const texts = doc.taught.map(cleanLessonText);
554
+ const lessons = [];
555
+ for (const text of texts) {
556
+ lessons.push(await api.teach({
557
+ text, unit, ...(tools.length ? { tools } : {}),
558
+ ...(doc.agentId ? { agentId: doc.agentId } : {}), ...(tenantId ? { tenantId } : {}),
559
+ id: (0, units_1.lessonIdFor)(unit, tenantId, doc.agentId, text),
560
+ }, by));
561
+ }
562
+ if (opts.replace) {
563
+ const keep = new Set(lessons.map(l => l.id));
564
+ for (const l of await lessonStore.list()) {
565
+ if (unitOf(l) === unit && l.tenantId === tenantId && l.agentId === doc.agentId && !keep.has(l.id))
566
+ await lessonStore.remove(l.id);
567
+ }
568
+ }
569
+ return lessons;
570
+ },
301
571
  async teach(input, by) {
302
572
  requireAuthor(by, 'Teaching a lesson');
303
- const text = input.text?.replace(/\s+/g, ' ').trim();
304
- if (!text)
305
- throw new Error('A lesson needs a text');
306
- if (text.length > MAX_TAUGHT_CHARS)
307
- throw new Error(`A lesson is at most ${MAX_TAUGHT_CHARS} characters; this one has ${text.length}`);
308
- const lesson = {
309
- id: `lesson-${(0, node_crypto_1.randomUUID)()}`, text,
573
+ const text = cleanLessonText(input.text);
574
+ if (input.id !== undefined && !LESSON_ID.test(input.id))
575
+ throw new Error('A lesson id is letters, digits, _ and -, up to 128 characters');
576
+ const candidate = {
577
+ text,
578
+ ...(input.unit ? { unit: normUnit(input.unit) } : {}),
310
579
  ...(input.agentId ? { agentId: input.agentId } : {}),
311
580
  ...(input.tenantId ? { tenantId: input.tenantId } : {}),
312
581
  ...(input.tools?.length ? { tools: input.tools } : {}),
313
- by, at: new Date().toISOString(),
314
582
  };
583
+ if (input.id !== undefined) {
584
+ // The same lesson again changes nothing: it keeps its place in the prompt and its first author.
585
+ const existing = (await lessonStore.list()).find(l => l.id === input.id);
586
+ if (existing && JSON.stringify({ ...candidate, id: 0 }) === JSON.stringify({ text: existing.text, ...(existing.unit ? { unit: existing.unit } : {}), ...(existing.agentId ? { agentId: existing.agentId } : {}), ...(existing.tenantId ? { tenantId: existing.tenantId } : {}), ...(existing.tools?.length ? { tools: existing.tools } : {}), id: 0 }))
587
+ return existing;
588
+ }
589
+ const lesson = { id: input.id ?? `lesson-${(0, node_crypto_1.randomUUID)()}`, ...candidate, by, at: nextAt() };
315
590
  await lessonStore.add(lesson);
316
591
  return lesson;
317
592
  },
@@ -342,5 +617,6 @@ function createLearning(options = {}) {
342
617
  return approved;
343
618
  },
344
619
  };
620
+ return api;
345
621
  }
346
622
  //# sourceMappingURL=index.js.map