@aid-framework/runtime 0.0.0 → 0.1.39

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 (188) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +53 -0
  3. package/dist/.tsbuildinfo +1 -0
  4. package/dist/agents/deep_agents.d.ts +78 -0
  5. package/dist/agents/deep_agents.d.ts.map +1 -0
  6. package/dist/agents/deep_agents.js +477 -0
  7. package/dist/agents/deep_agents.js.map +1 -0
  8. package/dist/agents/engine.d.ts +85 -0
  9. package/dist/agents/engine.d.ts.map +1 -0
  10. package/dist/agents/engine.js +129 -0
  11. package/dist/agents/engine.js.map +1 -0
  12. package/dist/agents/gateway_chat_model.d.ts +151 -0
  13. package/dist/agents/gateway_chat_model.d.ts.map +1 -0
  14. package/dist/agents/gateway_chat_model.js +350 -0
  15. package/dist/agents/gateway_chat_model.js.map +1 -0
  16. package/dist/agents/guardrail_middleware.d.ts +57 -0
  17. package/dist/agents/guardrail_middleware.d.ts.map +1 -0
  18. package/dist/agents/guardrail_middleware.js +85 -0
  19. package/dist/agents/guardrail_middleware.js.map +1 -0
  20. package/dist/agents/guardrails.d.ts +124 -0
  21. package/dist/agents/guardrails.d.ts.map +1 -0
  22. package/dist/agents/guardrails.js +336 -0
  23. package/dist/agents/guardrails.js.map +1 -0
  24. package/dist/agents/index.d.ts +15 -0
  25. package/dist/agents/index.d.ts.map +1 -0
  26. package/dist/agents/index.js +15 -0
  27. package/dist/agents/index.js.map +1 -0
  28. package/dist/agents/ir.d.ts +144 -0
  29. package/dist/agents/ir.d.ts.map +1 -0
  30. package/dist/agents/ir.js +513 -0
  31. package/dist/agents/ir.js.map +1 -0
  32. package/dist/agents/loop.d.ts +145 -0
  33. package/dist/agents/loop.d.ts.map +1 -0
  34. package/dist/agents/loop.js +1025 -0
  35. package/dist/agents/loop.js.map +1 -0
  36. package/dist/agents/memory.d.ts +115 -0
  37. package/dist/agents/memory.d.ts.map +1 -0
  38. package/dist/agents/memory.js +258 -0
  39. package/dist/agents/memory.js.map +1 -0
  40. package/dist/agents/state.d.ts +137 -0
  41. package/dist/agents/state.d.ts.map +1 -0
  42. package/dist/agents/state.js +255 -0
  43. package/dist/agents/state.js.map +1 -0
  44. package/dist/concurrency.d.ts +36 -0
  45. package/dist/concurrency.d.ts.map +1 -0
  46. package/dist/concurrency.js +86 -0
  47. package/dist/concurrency.js.map +1 -0
  48. package/dist/control.d.ts +116 -0
  49. package/dist/control.d.ts.map +1 -0
  50. package/dist/control.js +281 -0
  51. package/dist/control.js.map +1 -0
  52. package/dist/cost.d.ts +95 -0
  53. package/dist/cost.d.ts.map +1 -0
  54. package/dist/cost.js +161 -0
  55. package/dist/cost.js.map +1 -0
  56. package/dist/errors.d.ts +213 -0
  57. package/dist/errors.d.ts.map +1 -0
  58. package/dist/errors.js +316 -0
  59. package/dist/errors.js.map +1 -0
  60. package/dist/evals/dataset.d.ts +45 -0
  61. package/dist/evals/dataset.d.ts.map +1 -0
  62. package/dist/evals/dataset.js +147 -0
  63. package/dist/evals/dataset.js.map +1 -0
  64. package/dist/evals/gate.d.ts +236 -0
  65. package/dist/evals/gate.d.ts.map +1 -0
  66. package/dist/evals/gate.js +572 -0
  67. package/dist/evals/gate.js.map +1 -0
  68. package/dist/evals/metrics.d.ts +141 -0
  69. package/dist/evals/metrics.d.ts.map +1 -0
  70. package/dist/evals/metrics.js +364 -0
  71. package/dist/evals/metrics.js.map +1 -0
  72. package/dist/evals/predicate.d.ts +79 -0
  73. package/dist/evals/predicate.d.ts.map +1 -0
  74. package/dist/evals/predicate.js +178 -0
  75. package/dist/evals/predicate.js.map +1 -0
  76. package/dist/evals/runner.d.ts +94 -0
  77. package/dist/evals/runner.d.ts.map +1 -0
  78. package/dist/evals/runner.js +202 -0
  79. package/dist/evals/runner.js.map +1 -0
  80. package/dist/gateway.d.ts +118 -0
  81. package/dist/gateway.d.ts.map +1 -0
  82. package/dist/gateway.js +250 -0
  83. package/dist/gateway.js.map +1 -0
  84. package/dist/index.d.ts +83 -0
  85. package/dist/index.d.ts.map +1 -0
  86. package/dist/index.js +59 -0
  87. package/dist/index.js.map +1 -0
  88. package/dist/internal/json.d.ts +44 -0
  89. package/dist/internal/json.d.ts.map +1 -0
  90. package/dist/internal/json.js +90 -0
  91. package/dist/internal/json.js.map +1 -0
  92. package/dist/internal/text.d.ts +17 -0
  93. package/dist/internal/text.d.ts.map +1 -0
  94. package/dist/internal/text.js +22 -0
  95. package/dist/internal/text.js.map +1 -0
  96. package/dist/pipeline.d.ts +80 -0
  97. package/dist/pipeline.d.ts.map +1 -0
  98. package/dist/pipeline.js +159 -0
  99. package/dist/pipeline.js.map +1 -0
  100. package/dist/policy.d.ts +52 -0
  101. package/dist/policy.d.ts.map +1 -0
  102. package/dist/policy.js +199 -0
  103. package/dist/policy.js.map +1 -0
  104. package/dist/prompts.d.ts +86 -0
  105. package/dist/prompts.d.ts.map +1 -0
  106. package/dist/prompts.js +337 -0
  107. package/dist/prompts.js.map +1 -0
  108. package/dist/providers/base.d.ts +19 -0
  109. package/dist/providers/base.d.ts.map +1 -0
  110. package/dist/providers/base.js +13 -0
  111. package/dist/providers/base.js.map +1 -0
  112. package/dist/providers/fake.d.ts +98 -0
  113. package/dist/providers/fake.d.ts.map +1 -0
  114. package/dist/providers/fake.js +181 -0
  115. package/dist/providers/fake.js.map +1 -0
  116. package/dist/providers/http.d.ts +62 -0
  117. package/dist/providers/http.d.ts.map +1 -0
  118. package/dist/providers/http.js +245 -0
  119. package/dist/providers/http.js.map +1 -0
  120. package/dist/retrieval/chunking.d.ts +88 -0
  121. package/dist/retrieval/chunking.d.ts.map +1 -0
  122. package/dist/retrieval/chunking.js +188 -0
  123. package/dist/retrieval/chunking.js.map +1 -0
  124. package/dist/retrieval/citations.d.ts +98 -0
  125. package/dist/retrieval/citations.d.ts.map +1 -0
  126. package/dist/retrieval/citations.js +134 -0
  127. package/dist/retrieval/citations.js.map +1 -0
  128. package/dist/retrieval/connectors.d.ts +74 -0
  129. package/dist/retrieval/connectors.d.ts.map +1 -0
  130. package/dist/retrieval/connectors.js +218 -0
  131. package/dist/retrieval/connectors.js.map +1 -0
  132. package/dist/retrieval/embedding.d.ts +116 -0
  133. package/dist/retrieval/embedding.d.ts.map +1 -0
  134. package/dist/retrieval/embedding.js +282 -0
  135. package/dist/retrieval/embedding.js.map +1 -0
  136. package/dist/retrieval/gate.d.ts +52 -0
  137. package/dist/retrieval/gate.d.ts.map +1 -0
  138. package/dist/retrieval/gate.js +91 -0
  139. package/dist/retrieval/gate.js.map +1 -0
  140. package/dist/retrieval/hybrid.d.ts +76 -0
  141. package/dist/retrieval/hybrid.d.ts.map +1 -0
  142. package/dist/retrieval/hybrid.js +150 -0
  143. package/dist/retrieval/hybrid.js.map +1 -0
  144. package/dist/retrieval/metrics.d.ts +126 -0
  145. package/dist/retrieval/metrics.d.ts.map +1 -0
  146. package/dist/retrieval/metrics.js +200 -0
  147. package/dist/retrieval/metrics.js.map +1 -0
  148. package/dist/retrieval/pgvector.d.ts +62 -0
  149. package/dist/retrieval/pgvector.d.ts.map +1 -0
  150. package/dist/retrieval/pgvector.js +262 -0
  151. package/dist/retrieval/pgvector.js.map +1 -0
  152. package/dist/retrieval/rerank.d.ts +61 -0
  153. package/dist/retrieval/rerank.d.ts.map +1 -0
  154. package/dist/retrieval/rerank.js +105 -0
  155. package/dist/retrieval/rerank.js.map +1 -0
  156. package/dist/retrieval/retriever.d.ts +125 -0
  157. package/dist/retrieval/retriever.d.ts.map +1 -0
  158. package/dist/retrieval/retriever.js +281 -0
  159. package/dist/retrieval/retriever.js.map +1 -0
  160. package/dist/retrieval/stores.d.ts +106 -0
  161. package/dist/retrieval/stores.d.ts.map +1 -0
  162. package/dist/retrieval/stores.js +142 -0
  163. package/dist/retrieval/stores.js.map +1 -0
  164. package/dist/retrieval/types.d.ts +314 -0
  165. package/dist/retrieval/types.d.ts.map +1 -0
  166. package/dist/retrieval/types.js +388 -0
  167. package/dist/retrieval/types.js.map +1 -0
  168. package/dist/steps.d.ts +156 -0
  169. package/dist/steps.d.ts.map +1 -0
  170. package/dist/steps.js +199 -0
  171. package/dist/steps.js.map +1 -0
  172. package/dist/structured.d.ts +91 -0
  173. package/dist/structured.d.ts.map +1 -0
  174. package/dist/structured.js +155 -0
  175. package/dist/structured.js.map +1 -0
  176. package/dist/tools.d.ts +100 -0
  177. package/dist/tools.d.ts.map +1 -0
  178. package/dist/tools.js +201 -0
  179. package/dist/tools.js.map +1 -0
  180. package/dist/tracing.d.ts +104 -0
  181. package/dist/tracing.d.ts.map +1 -0
  182. package/dist/tracing.js +155 -0
  183. package/dist/tracing.js.map +1 -0
  184. package/dist/types.d.ts +240 -0
  185. package/dist/types.d.ts.map +1 -0
  186. package/dist/types.js +357 -0
  187. package/dist/types.js.map +1 -0
  188. package/package.json +80 -14
@@ -0,0 +1,336 @@
1
+ /**
2
+ * The guardrails engine: the IR's `guardrails` collection, actually evaluated.
3
+ *
4
+ * The IR already carries the *declaration* -- stages, policy kinds, an action, the fields
5
+ * a redaction may touch. This module is the missing other half: something that looks at
6
+ * text and decides. It is deliberately small and offline. Every detector is a regular
7
+ * expression, so the answer for a given input does not depend on a model, a network call,
8
+ * or a random seed, and a spec that passes here will pass here again tomorrow.
9
+ *
10
+ * Four stages, in the order a run meets them:
11
+ *
12
+ * - `input` -- before the model sees the user's turn.
13
+ * - `retrieval` -- around the chunks a retriever would splice into the prompt.
14
+ * - `tool-call` -- before a tool's handler body runs, over the call's arguments.
15
+ * - `output` -- after the model answers.
16
+ *
17
+ * Three decisions this module owns:
18
+ *
19
+ * **Undecidable is a block.** A guardrail naming a policy with no evaluator, or whose
20
+ * `redact` fields do not cover the text it matched, raises {@link GuardrailBlockedError}.
21
+ * There is no path from "the check could not run" to "no violation found".
22
+ *
23
+ * **Evaluation order is declaration order, except that `block` outranks it.** At one stage
24
+ * the engine walks the agent's guardrails in the order the IR declared them and collects
25
+ * every guardrail that fired. If *any* of them is a `block`, the first such guardrail
26
+ * decides -- a later `flag` cannot talk an earlier `block` down. Otherwise the first
27
+ * guardrail that fired decides.
28
+ *
29
+ * **`flag` cannot be ignored, but it does not stop anything.** A flag is recorded on the
30
+ * run (`RunResult.guardrails`) and the guarded text passes through unchanged. The consumer
31
+ * is whoever reads the run result -- an eval, a log shipper, a reviewer. It is *not* an
32
+ * allow: a flag means a detector matched, and the run carried on because the spec said the
33
+ * run may.
34
+ */
35
+ import { ConfigurationError, GuardrailBlockedError } from '../errors.js';
36
+ import { repr } from '../internal/json.js';
37
+ export const ACTION_BLOCK = 'block';
38
+ export const ACTION_REDACT = 'redact';
39
+ export const ACTION_FLAG = 'flag';
40
+ export const ACTION_ESCALATE = 'escalate';
41
+ export const GUARDRAIL_STAGES = [
42
+ 'input',
43
+ 'retrieval',
44
+ 'tool-call',
45
+ 'output',
46
+ ];
47
+ export const GUARDRAIL_ACTIONS = [
48
+ ACTION_BLOCK,
49
+ ACTION_REDACT,
50
+ ACTION_FLAG,
51
+ ACTION_ESCALATE,
52
+ ];
53
+ /** What a redacted span is replaced with. Carrying the policy name says *why* it vanished. */
54
+ const REDACTION = '[REDACTED:{policy}]';
55
+ /** Whether any guardrail matched, whatever it decided to do about it. */
56
+ export function fired(verdict) {
57
+ return verdict.records.length > 0;
58
+ }
59
+ function escapeRegExp(text) {
60
+ return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
61
+ }
62
+ function phrase(...phrases) {
63
+ const joined = phrases.map((item) => escapeRegExp(item)).join('|');
64
+ return new RegExp(`\\b(?:${joined})\\b`, 'i');
65
+ }
66
+ /**
67
+ * One entry per `GuardrailPolicyKind` in `packages/ir/src/shapes.ts`.
68
+ *
69
+ * These are *heuristics*, and saying so is the honest description. They catch the shapes a
70
+ * red-team corpus is built from -- an instruction-override phrase, a well-formed email or
71
+ * card-like digit run, a jailbreak persona -- and they will not catch a paraphrase.
72
+ */
73
+ export const DETECTORS = {
74
+ 'prompt-injection': [
75
+ phrase('ignore previous instructions', 'ignore all previous instructions', 'ignore the previous instructions', 'ignore your instructions', 'disregard previous instructions', 'disregard your instructions', 'forget your instructions', 'override your instructions', 'ignore the system prompt', 'reveal the system prompt', 'reveal your system prompt', 'print the system prompt', 'show me your system prompt'),
76
+ /\byou are now (?:a|an|the|in|no longer)\b/i,
77
+ /<\|\s*im_start\s*\|>/i,
78
+ ],
79
+ jailbreak: [
80
+ phrase('do anything now', 'developer mode', 'jailbreak mode', 'dan mode', 'without any restrictions', 'no ethical guidelines', 'no restrictions apply'),
81
+ /\bpretend (?:that )?you (?:have no|are not bound)/i,
82
+ /\bact as (?:an? )?(?:unrestricted|uncensored)\b/i,
83
+ ],
84
+ 'pii-detect': [
85
+ /[\w.+-]+@[\w-]+\.[\w.-]+/,
86
+ /(?<!\d)(?:\+?\d{1,3}[ -]?)?(?:\(\d{3}\)[ -]?|\d{3}[ -])\d{3}[ -]\d{4}(?!\d)/,
87
+ /(?<!\d)\d{3}-\d{2}-\d{4}(?!\d)/,
88
+ /(?<!\d)(?:\d[ -]?){13,19}(?!\d)/,
89
+ ],
90
+ 'pii-redact': [
91
+ /[\w.+-]+@[\w-]+\.[\w.-]+/,
92
+ /(?<!\d)(?:\+?\d{1,3}[ -]?)?(?:\(\d{3}\)[ -]?|\d{3}[ -])\d{3}[ -]\d{4}(?!\d)/,
93
+ /(?<!\d)\d{3}-\d{2}-\d{4}(?!\d)/,
94
+ /(?<!\d)(?:\d[ -]?){13,19}(?!\d)/,
95
+ ],
96
+ 'secret-scan': [
97
+ /\bAKIA[0-9A-Z]{16}\b/,
98
+ /\bgh[pousr]_[A-Za-z0-9]{16,}\b/,
99
+ /\bsk-[A-Za-z0-9]{16,}\b/,
100
+ /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
101
+ /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/,
102
+ ],
103
+ moderation: [
104
+ phrase('how to build a bomb', 'how to make a bomb', 'build an explosive device', 'synthesize sarin', 'make nerve agent'),
105
+ ],
106
+ toxicity: [phrase('kill yourself', 'go die', 'you should die', 'subhuman')],
107
+ };
108
+ /**
109
+ * Policy kinds whose detection is about a *value* that a redaction can erase. The others
110
+ * match intent, and masking an intent phrase would not make the request safe -- which is
111
+ * why a `redact` guardrail over them fails closed below.
112
+ */
113
+ const REDACTABLE = new Set(['pii-detect', 'pii-redact', 'secret-scan']);
114
+ /**
115
+ * Every match of `policy` in `text`, in document order.
116
+ *
117
+ * Raises {@link ConfigurationError} for an unknown policy: that is a caller bug, not
118
+ * untrusted input, and the engine reports it as a block before it ever gets here.
119
+ */
120
+ export function detect(policy, text) {
121
+ const patterns = DETECTORS[policy];
122
+ if (patterns === undefined) {
123
+ throw new ConfigurationError(`no detector for guardrail policy ${repr(policy)}; known policies: ` +
124
+ `[${Object.keys(DETECTORS)
125
+ .sort()
126
+ .map((name) => repr(name))
127
+ .join(', ')}]`);
128
+ }
129
+ const hits = [];
130
+ for (const pattern of patterns) {
131
+ // A fresh global copy per call: a shared RegExp carries `lastIndex` between calls,
132
+ // which would make the second evaluation of the same text miss a match.
133
+ const flags = pattern.flags.includes('g') ? pattern.flags : `${pattern.flags}g`;
134
+ for (const match of text.matchAll(new RegExp(pattern.source, flags))) {
135
+ const start = match.index ?? 0;
136
+ hits.push({ policy, start, end: start + match[0].length });
137
+ }
138
+ }
139
+ hits.sort((left, right) => left.start - right.start || left.end - right.end);
140
+ return hits;
141
+ }
142
+ function mask(policy, text) {
143
+ const hits = detect(policy, text);
144
+ const replacement = REDACTION.replace('{policy}', policy);
145
+ let masked = text;
146
+ // Right to left, so an earlier replacement cannot move a later span's offsets.
147
+ for (const hit of [...hits].reverse()) {
148
+ masked = `${masked.slice(0, hit.start)}${replacement}${masked.slice(hit.end)}`;
149
+ }
150
+ return masked;
151
+ }
152
+ /**
153
+ * The `(field, value)` pairs a detector may look at.
154
+ *
155
+ * Only strings: a detector that coerced a number or a nested object to text would fire on
156
+ * payloads a redaction cannot edit, and the redaction's fail-closed re-check below would
157
+ * then block a run it could have repaired.
158
+ */
159
+ function texts(payload) {
160
+ const pairs = [];
161
+ for (const [name, value] of Object.entries(payload)) {
162
+ if (typeof value === 'string' && value !== '')
163
+ pairs.push([name, value]);
164
+ }
165
+ return pairs;
166
+ }
167
+ /** Evaluates an agent's guardrails at one stage. */
168
+ export class GuardrailEngine {
169
+ #declared;
170
+ constructor(guardrails) {
171
+ this.#declared = new Map(guardrails ?? []);
172
+ }
173
+ declared(guardrailId) {
174
+ return this.#declared.get(guardrailId);
175
+ }
176
+ checkInput(guardrails, text) {
177
+ return this.check('input', guardrails, { text }, undefined);
178
+ }
179
+ checkOutput(guardrails, text) {
180
+ return this.check('output', guardrails, { text }, undefined);
181
+ }
182
+ /**
183
+ * Guard what a retriever would splice into the prompt.
184
+ *
185
+ * Only the *results* are in the payload, not the query. The stage is about the text a
186
+ * model is handed, and putting the user's question in the same payload would let a
187
+ * `redact` guardrail over the `text` field fire on a violation it cannot remove -- which
188
+ * fails closed as a block and hides the real cause. The query's own checks belong to the
189
+ * `input` stage.
190
+ */
191
+ checkRetrieval(guardrails, results) {
192
+ return this.check('retrieval', guardrails, { text: results.join('\n') }, undefined);
193
+ }
194
+ checkToolCall(guardrails, toolId, arguments_) {
195
+ return this.check('tool-call', guardrails, { ...arguments_ }, toolId);
196
+ }
197
+ check(stage, guardrails, payload, toolId) {
198
+ const applicable = guardrails.filter((guardrail) => guardrail.stages.includes(stage) && covers(guardrail, stage, toolId));
199
+ const records = [];
200
+ const firedGuardrails = [];
201
+ for (const guardrail of applicable) {
202
+ const policies = firingPolicies(guardrail, stage, payload);
203
+ if (policies.length === 0)
204
+ continue;
205
+ firedGuardrails.push(guardrail);
206
+ records.push({
207
+ guardrail: guardrail.id,
208
+ stage,
209
+ action: actionOf(guardrail),
210
+ policies,
211
+ message: guardrail.message,
212
+ });
213
+ }
214
+ const deciding = decide(records);
215
+ if (deciding === undefined) {
216
+ return {
217
+ stage,
218
+ records: [],
219
+ action: undefined,
220
+ deciding: undefined,
221
+ text: textOf(payload),
222
+ arguments: { ...payload },
223
+ };
224
+ }
225
+ let redacted = payload;
226
+ if (deciding.action === ACTION_REDACT) {
227
+ redacted = redact(stage, firedGuardrails.filter((guardrail) => guardrail.action === ACTION_REDACT), payload);
228
+ }
229
+ return {
230
+ stage,
231
+ records,
232
+ action: deciding.action,
233
+ deciding,
234
+ text: textOf(redacted),
235
+ arguments: { ...redacted },
236
+ };
237
+ }
238
+ }
239
+ /**
240
+ * Whether `guardrail` applies to this particular call.
241
+ *
242
+ * `tools` is only meaningful on a `tool-call` guardrail, and an empty list means "every
243
+ * tool that reaches the stage" -- absent and empty are the same thing in the IR, and
244
+ * reading them differently here would be a second, undocumented meaning for an empty array.
245
+ */
246
+ function covers(guardrail, stage, toolId) {
247
+ if (stage !== 'tool-call' || guardrail.tools.length === 0)
248
+ return true;
249
+ return toolId !== undefined && guardrail.tools.includes(toolId);
250
+ }
251
+ function textOf(payload) {
252
+ const value = payload.text;
253
+ return typeof value === 'string' ? value : '';
254
+ }
255
+ function firingPolicies(guardrail, stage, payload) {
256
+ const fields = texts(payload);
257
+ const hits = [];
258
+ for (const policy of guardrail.policies) {
259
+ if (DETECTORS[policy] === undefined) {
260
+ // Fail closed: a policy the engine cannot evaluate is a block, and it is reported
261
+ // with the guardrail that named it so an operator knows which declaration to fix.
262
+ throw new GuardrailBlockedError(guardrail.id, stage, `policy ${repr(policy)} has no evaluator in this runtime`);
263
+ }
264
+ if (fields.some(([, text]) => detect(policy, text).length > 0))
265
+ hits.push(policy);
266
+ }
267
+ return hits;
268
+ }
269
+ /**
270
+ * The guardrail's action, refused if it is outside the closed vocabulary.
271
+ *
272
+ * `GuardrailDefinition.action` is a `string` because the IR layer reads it out of JSON, so
273
+ * this is where the closed set is enforced. It has to be enforced rather than assumed:
274
+ * `decide` looks for `block` by equality, so an unrecognised action could not decide a
275
+ * block and would otherwise fall through to whatever the caller does with "not block" -- an
276
+ * allow nobody declared.
277
+ */
278
+ function actionOf(guardrail) {
279
+ const action = guardrail.action;
280
+ if (!GUARDRAIL_ACTIONS.includes(action)) {
281
+ throw new ConfigurationError(`guardrail ${repr(guardrail.id)} declares unknown action ${repr(action)}; ` +
282
+ `expected one of ${GUARDRAIL_ACTIONS.join(', ')}`);
283
+ }
284
+ return action;
285
+ }
286
+ /**
287
+ * The deciding record: the first `block`, else the first record.
288
+ *
289
+ * `block` outranks declaration order deliberately. Ordering is about which of two
290
+ * *comparable* actions wins, and "stop the run" is not comparable to "let it continue with
291
+ * a note"; if declaration order could overrule a block, an author could neuter a strict
292
+ * guardrail by declaring a permissive one first.
293
+ */
294
+ function decide(records) {
295
+ for (const record of records) {
296
+ if (record.action === ACTION_BLOCK)
297
+ return record;
298
+ }
299
+ return records.length > 0 ? records[0] : undefined;
300
+ }
301
+ /**
302
+ * Mask the declared fields, then prove nothing the detectors saw survived.
303
+ *
304
+ * The re-check is the part that matters. A spec that declares `redact: [answer]` for a
305
+ * payload whose violation is in some other field would otherwise "redact" successfully
306
+ * while shipping the violation, so this raises instead of returning a payload it could not
307
+ * clean.
308
+ */
309
+ function redact(stage, guardrails, payload) {
310
+ const redacted = { ...payload };
311
+ for (const guardrail of guardrails) {
312
+ for (const name of guardrail.redact) {
313
+ const current = redacted[name];
314
+ if (typeof current !== 'string')
315
+ continue;
316
+ let value = current;
317
+ for (const policy of guardrail.policies) {
318
+ if (!REDACTABLE.has(policy)) {
319
+ throw new GuardrailBlockedError(guardrail.id, stage, `policy ${repr(policy)} detects intent, which masking field ${repr(name)} ` +
320
+ "cannot remove; use 'block', 'flag' or 'escalate'");
321
+ }
322
+ value = mask(policy, value);
323
+ }
324
+ redacted[name] = value;
325
+ }
326
+ }
327
+ for (const guardrail of guardrails) {
328
+ const remaining = firingPolicies(guardrail, stage, redacted);
329
+ if (remaining.length > 0) {
330
+ throw new GuardrailBlockedError(guardrail.id, stage, `redacting [${guardrail.redact.map((field) => repr(field)).join(', ')}] left a ` +
331
+ `${repr(remaining[0] ?? '')} match; the declared fields do not cover the payload`);
332
+ }
333
+ }
334
+ return redacted;
335
+ }
336
+ //# sourceMappingURL=guardrails.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"guardrails.js","sourceRoot":"","sources":["../../src/agents/guardrails.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The agent engine: IR, guardrails, memory, and the loop.
3
+ *
4
+ * Mirrors the Python package's `aid_runtime.agents`. Both engines are here: the native
5
+ * loop, and the opt-in `deepagents` backend that runs the harness at the pinned release
6
+ * behind our gateway, guardrails and tool executor. Agent-span tracing is still decision
7
+ * D-7.
8
+ */
9
+ export { checkEngine, DEEPAGENTS, DEEPAGENTS_DISTRIBUTION, DEEPAGENTS_EXTRA, DEEPAGENTS_PIN, ENGINES, installedDeepagentsVersion, NATIVE, } from './engine.js';
10
+ export { ACTION_BLOCK, ACTION_ESCALATE, ACTION_FLAG, ACTION_REDACT, DETECTORS, type Detection, detect, fired, type GuardrailAction, GuardrailEngine, type GuardrailEscalation, type GuardrailRecord, type GuardrailStage, type GuardrailVerdict, } from './guardrails.js';
11
+ export { type AgentDefinition, fromIr, GUARDRAIL_ACTIONS, GUARDRAIL_POLICIES, GUARDRAIL_STAGES, type GuardrailDefinition, type HumanApproval, hasControlTools, type MemoryDefinition, RuntimeSpec, stageGuardrails, type ToolSpec, } from './ir.js';
12
+ export { AgentRuntime, CONTROL_ARGUMENT, DELEGATE_PREFIX, TRANSFER_PREFIX } from './loop.js';
13
+ export { checkMemorySupported, FileMemoryStore, IMPLEMENTED_MEMORY_KINDS, InProcessMemoryStore, MEMORY_SCOPES, type MemoryStore, renderContext, ThreadMemory, } from './memory.js';
14
+ export { type AgentCheckpoint, checkpointFromJson, checkpointsEqual, checkpointToJson, type HumanDecision, type PendingApproval, pendingApprovalFrom, RUN_STATUSES, RunResult, type RunStatus, STEP_KINDS, type StepKind, type StepRecord, } from './state.js';
15
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,OAAO,EACP,0BAA0B,EAC1B,MAAM,GACP,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,SAAS,EACT,KAAK,SAAS,EACd,MAAM,EACN,KAAK,EACL,KAAK,eAAe,EACpB,eAAe,EACf,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,gBAAgB,GACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,eAAe,EACpB,MAAM,EACN,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,eAAe,EACf,KAAK,gBAAgB,EACrB,WAAW,EACX,eAAe,EACf,KAAK,QAAQ,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC7F,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,aAAa,EACb,KAAK,WAAW,EAChB,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,mBAAmB,EACnB,YAAY,EACZ,SAAS,EACT,KAAK,SAAS,EACd,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC"}
@@ -0,0 +1,15 @@
1
+ /**
2
+ * The agent engine: IR, guardrails, memory, and the loop.
3
+ *
4
+ * Mirrors the Python package's `aid_runtime.agents`. Both engines are here: the native
5
+ * loop, and the opt-in `deepagents` backend that runs the harness at the pinned release
6
+ * behind our gateway, guardrails and tool executor. Agent-span tracing is still decision
7
+ * D-7.
8
+ */
9
+ export { checkEngine, DEEPAGENTS, DEEPAGENTS_DISTRIBUTION, DEEPAGENTS_EXTRA, DEEPAGENTS_PIN, ENGINES, installedDeepagentsVersion, NATIVE, } from './engine.js';
10
+ export { ACTION_BLOCK, ACTION_ESCALATE, ACTION_FLAG, ACTION_REDACT, DETECTORS, detect, fired, GuardrailEngine, } from './guardrails.js';
11
+ export { fromIr, GUARDRAIL_ACTIONS, GUARDRAIL_POLICIES, GUARDRAIL_STAGES, hasControlTools, RuntimeSpec, stageGuardrails, } from './ir.js';
12
+ export { AgentRuntime, CONTROL_ARGUMENT, DELEGATE_PREFIX, TRANSFER_PREFIX } from './loop.js';
13
+ export { checkMemorySupported, FileMemoryStore, IMPLEMENTED_MEMORY_KINDS, InProcessMemoryStore, MEMORY_SCOPES, renderContext, ThreadMemory, } from './memory.js';
14
+ export { checkpointFromJson, checkpointsEqual, checkpointToJson, pendingApprovalFrom, RUN_STATUSES, RunResult, STEP_KINDS, } from './state.js';
15
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,WAAW,EACX,UAAU,EACV,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,OAAO,EACP,0BAA0B,EAC1B,MAAM,GACP,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,eAAe,EACf,WAAW,EACX,aAAa,EACb,SAAS,EAET,MAAM,EACN,KAAK,EAEL,eAAe,GAKhB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,MAAM,EACN,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAGhB,eAAe,EAEf,WAAW,EACX,eAAe,GAEhB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC7F,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,wBAAwB,EACxB,oBAAoB,EACpB,aAAa,EAEb,aAAa,EACb,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAEL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAGhB,mBAAmB,EACnB,YAAY,EACZ,SAAS,EAET,UAAU,GAGX,MAAM,YAAY,CAAC"}
@@ -0,0 +1,144 @@
1
+ /**
2
+ * The IR seam: an emitted document in, resolved agent definitions out.
3
+ *
4
+ * The pipeline runtime consumes the IR's *pipeline* shapes and is deliberately unaware of
5
+ * agents; this module is the equivalent seam for them. It reads only the collections an
6
+ * agent can reach -- `agents`, `models`, `prompts`, `tools`, `memory`, `guardrails` -- and
7
+ * resolves every reference at load time, so a loop never runs against a dangling prompt id
8
+ * or an unpriced model.
9
+ *
10
+ * Nothing here invents vocabulary. Field names are the IR's, `instructions` stays the
11
+ * prompt *reference* the IR carries and is resolved to `prompt.template` here, and the
12
+ * scopes are `thread`/`user`/`global`.
13
+ */
14
+ import { ModelSpec } from '../types.js';
15
+ /** The closed vocabularies from `packages/ir/src/shapes.ts`, repeated on purpose. */
16
+ export declare const GUARDRAIL_STAGES: ReadonlySet<string>;
17
+ export declare const GUARDRAIL_ACTIONS: ReadonlySet<string>;
18
+ export declare const GUARDRAIL_POLICIES: ReadonlySet<string>;
19
+ /** An IR tool, as the loop needs it: name, side effects, and its auth policy. */
20
+ export interface ToolSpec {
21
+ readonly id: string;
22
+ readonly name: string;
23
+ readonly description: string;
24
+ readonly requiresConfirmation: boolean;
25
+ readonly sideEffects: string;
26
+ readonly auth: Readonly<Record<string, unknown>> | undefined;
27
+ }
28
+ /**
29
+ * One resolved guardrail: where it runs, what it detects, and what it does.
30
+ *
31
+ * `tools` holds tool *ids*, because that is how the IR scopes a tool-call guardrail; the
32
+ * loop translates a model's tool *name* to the id before asking.
33
+ */
34
+ export interface GuardrailDefinition {
35
+ readonly id: string;
36
+ readonly stages: readonly string[];
37
+ readonly policies: readonly string[];
38
+ readonly action: string;
39
+ readonly redact: readonly string[];
40
+ readonly tools: readonly string[];
41
+ readonly message: string;
42
+ readonly fallbackPrompt: string | undefined;
43
+ readonly log: boolean;
44
+ }
45
+ /** One IR `memory` entry, resolved for the scope rules in `agents/memory`. */
46
+ export interface MemoryDefinition {
47
+ readonly id: string;
48
+ readonly kind: string;
49
+ readonly scope: string;
50
+ readonly tokenBudget: number;
51
+ readonly backend: string | undefined;
52
+ readonly store: string | undefined;
53
+ readonly summarizeModel: string | undefined;
54
+ readonly ttl: string | undefined;
55
+ readonly redact: readonly string[];
56
+ }
57
+ /** The parsed `humanInTheLoop` block: a policy, and a channel to ask on. */
58
+ export interface HumanApproval {
59
+ readonly when: Readonly<Record<string, unknown>>;
60
+ readonly channel: string;
61
+ }
62
+ /** One agent, with every reference resolved. */
63
+ export interface AgentDefinition {
64
+ readonly id: string;
65
+ readonly name: string;
66
+ readonly instructions: string;
67
+ readonly model: string;
68
+ readonly tools: readonly string[];
69
+ readonly memory: readonly MemoryDefinition[];
70
+ readonly maxSteps: number;
71
+ readonly maxTokensBudget: number | undefined;
72
+ readonly maxCostBudget: number | undefined;
73
+ readonly onBudgetExhausted: string;
74
+ readonly handoffs: readonly string[];
75
+ readonly delegates: readonly string[];
76
+ readonly engine: string;
77
+ /**
78
+ * The pinned Deep Agents release, when the engine is `deepagents`. Empty for `native`;
79
+ * the IR gate refuses `deepagents` without a pin, so an empty value here means the
80
+ * document skipped the gate.
81
+ */
82
+ readonly engineVersion: string;
83
+ readonly approval: HumanApproval | undefined;
84
+ readonly guardrails: readonly GuardrailDefinition[];
85
+ }
86
+ /** Whether this agent may move control at all (transfer *or* delegate). */
87
+ export declare function hasControlTools(agent: AgentDefinition): boolean;
88
+ /**
89
+ * Every guardrail declared on this agent that runs at `stage`.
90
+ *
91
+ * Declaration order is the order of `guardrails` in the IR, and that is the order the
92
+ * engine evaluates in. It has to come from the document: an order the runtime invented
93
+ * would make the outcome of two conflicting guardrails depend on which version of the
94
+ * runtime ran the spec.
95
+ */
96
+ export declare function stageGuardrails(agent: AgentDefinition, stage: string): readonly GuardrailDefinition[];
97
+ /** Everything the loop needs, resolved from one IR document. */
98
+ export declare class RuntimeSpec {
99
+ readonly models: ReadonlyMap<string, ModelSpec>;
100
+ readonly fallbacks: ReadonlyMap<string, readonly string[]>;
101
+ readonly prompts: ReadonlyMap<string, string>;
102
+ readonly tools: ReadonlyMap<string, ToolSpec>;
103
+ readonly agents: ReadonlyMap<string, AgentDefinition>;
104
+ readonly guardrails: ReadonlyMap<string, GuardrailDefinition>;
105
+ /**
106
+ * The single concurrency cap, read from the IR's `deployments[].concurrency`. `undefined`
107
+ * means unbounded: the runtime only shares a limiter when a deployment declares one,
108
+ * which keeps plain request/response usage free of surprises.
109
+ */
110
+ readonly concurrency: number | undefined;
111
+ constructor(init: {
112
+ readonly models: ReadonlyMap<string, ModelSpec>;
113
+ readonly fallbacks: ReadonlyMap<string, readonly string[]>;
114
+ readonly prompts: ReadonlyMap<string, string>;
115
+ readonly tools: ReadonlyMap<string, ToolSpec>;
116
+ readonly agents: ReadonlyMap<string, AgentDefinition>;
117
+ readonly guardrails?: ReadonlyMap<string, GuardrailDefinition>;
118
+ readonly concurrency?: number;
119
+ });
120
+ agent(agentId: string): AgentDefinition;
121
+ systemPrompt(agent: AgentDefinition): string;
122
+ fallbacksFor(alias: string): readonly string[];
123
+ toolSpecs(agent: AgentDefinition): readonly ToolSpec[];
124
+ /**
125
+ * Combined price, the same number `agents/budget-degrade` compares.
126
+ *
127
+ * The gate compares `inputPerMTok + outputPerMTok`; keeping the identical sum here means
128
+ * a spec the gate accepted cannot have the runtime pick a "cheaper" alias that the gate
129
+ * would have called more expensive.
130
+ */
131
+ price(alias: string): number;
132
+ /**
133
+ * The first declared fallback that is strictly cheaper than `alias`.
134
+ *
135
+ * One step, in the order the spec declared: this is the alias ladder's next rung, not a
136
+ * search for the cheapest reachable model. `undefined` means there is nowhere to step,
137
+ * which is what makes a `degrade` declaration fail closed instead of pretending to
138
+ * degrade.
139
+ */
140
+ cheaperFallback(alias: string): string | undefined;
141
+ }
142
+ /** Resolve an emitted IR document into a {@link RuntimeSpec}. */
143
+ export declare function fromIr(document: Record<string, unknown>): RuntimeSpec;
144
+ //# sourceMappingURL=ir.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"ir.d.ts","sourceRoot":"","sources":["../../src/agents/ir.ts"],"names":[],"mappings":"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"}