mesedi 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +137 -0
- package/dist/anthropic_integration.d.ts +52 -0
- package/dist/anthropic_integration.d.ts.map +1 -0
- package/dist/anthropic_integration.js +226 -0
- package/dist/anthropic_integration.js.map +1 -0
- package/dist/client.d.ts +99 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +258 -0
- package/dist/client.js.map +1 -0
- package/dist/context.d.ts +63 -0
- package/dist/context.d.ts.map +1 -0
- package/dist/context.js +84 -0
- package/dist/context.js.map +1 -0
- package/dist/events.d.ts +95 -0
- package/dist/events.d.ts.map +1 -0
- package/dist/events.js +103 -0
- package/dist/events.js.map +1 -0
- package/dist/halt.d.ts +165 -0
- package/dist/halt.d.ts.map +1 -0
- package/dist/halt.js +229 -0
- package/dist/halt.js.map +1 -0
- package/dist/halt_stream.d.ts +77 -0
- package/dist/halt_stream.d.ts.map +1 -0
- package/dist/halt_stream.js +214 -0
- package/dist/halt_stream.js.map +1 -0
- package/dist/index.d.ts +41 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +34 -0
- package/dist/index.js.map +1 -0
- package/dist/integrations/vercel_ai.d.ts +120 -0
- package/dist/integrations/vercel_ai.d.ts.map +1 -0
- package/dist/integrations/vercel_ai.js +381 -0
- package/dist/integrations/vercel_ai.js.map +1 -0
- package/dist/observe.d.ts +50 -0
- package/dist/observe.d.ts.map +1 -0
- package/dist/observe.js +97 -0
- package/dist/observe.js.map +1 -0
- package/dist/tool.d.ts +27 -0
- package/dist/tool.d.ts.map +1 -0
- package/dist/tool.js +138 -0
- package/dist/tool.js.map +1 -0
- package/dist/wrap.d.ts +69 -0
- package/dist/wrap.d.ts.map +1 -0
- package/dist/wrap.js +168 -0
- package/dist/wrap.js.map +1 -0
- package/package.json +70 -0
|
@@ -0,0 +1,381 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Vercel AI SDK integration — wrap `generateText` to emit Mesedi
|
|
3
|
+
* telemetry.
|
|
4
|
+
*
|
|
5
|
+
* Usage:
|
|
6
|
+
*
|
|
7
|
+
* import { wrap } from "mesedi";
|
|
8
|
+
* import { wrapGenerateText } from "mesedi/integrations/vercel_ai";
|
|
9
|
+
* import { generateText } from "ai";
|
|
10
|
+
* import { openai } from "@ai-sdk/openai";
|
|
11
|
+
*
|
|
12
|
+
* const generateTextM = wrapGenerateText(generateText);
|
|
13
|
+
*
|
|
14
|
+
* export const runAgent = wrap(
|
|
15
|
+
* { agentName: "support-triage" },
|
|
16
|
+
* async (question: string) => {
|
|
17
|
+
* const result = await generateTextM({
|
|
18
|
+
* model: openai("gpt-4o"),
|
|
19
|
+
* prompt: question,
|
|
20
|
+
* tools: { lookup, search },
|
|
21
|
+
* maxSteps: 5,
|
|
22
|
+
* });
|
|
23
|
+
* return result.text;
|
|
24
|
+
* },
|
|
25
|
+
* );
|
|
26
|
+
*
|
|
27
|
+
* Design:
|
|
28
|
+
*
|
|
29
|
+
* `wrapGenerateText` is a higher-order function that takes the real
|
|
30
|
+
* Vercel `generateText` and returns a drop-in replacement with the
|
|
31
|
+
* same signature plus telemetry side effects. Customers don't have
|
|
32
|
+
* to refactor their agent code — they just swap the import.
|
|
33
|
+
*
|
|
34
|
+
* Multi-step (ReAct) generation is the common case for agent
|
|
35
|
+
* workflows: `generateText({ maxSteps: 5, tools: { ... } })` makes
|
|
36
|
+
* up to 5 LLM calls, with tool calls between each. Vercel exposes
|
|
37
|
+
* the per-step record on `result.steps`. We iterate that array and
|
|
38
|
+
* emit one `llm_call` event per step plus one `tool_call` event per
|
|
39
|
+
* tool invocation within the step. Detectors (drift, identical /
|
|
40
|
+
* similar-call loops, tool-failures, cost-velocity,
|
|
41
|
+
* prompt-injection) see the same wire format as a hand-written
|
|
42
|
+
* Mesedi instrumentation produces.
|
|
43
|
+
*
|
|
44
|
+
* Out of scope for this slice:
|
|
45
|
+
* - `streamText` / `streamObject` — emit-on-stream-end variant
|
|
46
|
+
* would need to drain the stream first or instrument the
|
|
47
|
+
* stream's transform. Deferred to a later slice.
|
|
48
|
+
* - `generateObject` — structured output. The shape is similar to
|
|
49
|
+
* `generateText`'s but the response field is `.object` not
|
|
50
|
+
* `.text`. Will compose well with the same wrapper pattern.
|
|
51
|
+
* - OpenTelemetry-based instrumentation via `experimental_telemetry`.
|
|
52
|
+
* Heavier integration, requires @opentelemetry/api as a peer
|
|
53
|
+
* dependency. Vercel's docs note it's experimental, so we use
|
|
54
|
+
* the wrapper pattern instead for now.
|
|
55
|
+
*/
|
|
56
|
+
import { getClient } from "../client.js";
|
|
57
|
+
import { currentExecutionContext, newEventId } from "../context.js";
|
|
58
|
+
import { EventType, utcNowRfc3339 } from "../events.js";
|
|
59
|
+
// Truncation budgets — kept in sync with the Python emit_llm_call and
|
|
60
|
+
// the TS Anthropic patch so wire-format payloads from this adapter and
|
|
61
|
+
// from hand-written code are byte-indistinguishable.
|
|
62
|
+
const MAX_SYSTEM = 1000;
|
|
63
|
+
const MAX_USER_MSG = 1000;
|
|
64
|
+
const MAX_RESPONSE = 1000;
|
|
65
|
+
const MAX_TOOL_INPUT_REPR = 200;
|
|
66
|
+
const MAX_TOOL_OUTPUT_REPR = 500;
|
|
67
|
+
const MAX_EXC_MSG = 500;
|
|
68
|
+
/**
|
|
69
|
+
* Wrap a Vercel `generateText` (or any function with that shape) so
|
|
70
|
+
* each invocation emits Mesedi telemetry. Returns a function with
|
|
71
|
+
* the same signature.
|
|
72
|
+
*
|
|
73
|
+
* Outside a `wrap()` execution, the events silently no-op — same
|
|
74
|
+
* fail-open pattern as every other Mesedi primitive.
|
|
75
|
+
*/
|
|
76
|
+
export function wrapGenerateText(generateTextFn) {
|
|
77
|
+
const wrapped = async (options) => {
|
|
78
|
+
const startedAt = Date.now();
|
|
79
|
+
const modelId = extractModelId(options.model);
|
|
80
|
+
const userMessage = extractLastUserMessage(options);
|
|
81
|
+
const systemPrompt = typeof options.system === "string" ? options.system : "";
|
|
82
|
+
let result;
|
|
83
|
+
try {
|
|
84
|
+
result = await generateTextFn(options);
|
|
85
|
+
}
|
|
86
|
+
catch (err) {
|
|
87
|
+
const durationMs = Date.now() - startedAt;
|
|
88
|
+
emitLlmCallEvent({
|
|
89
|
+
model: modelId,
|
|
90
|
+
userMessage,
|
|
91
|
+
systemPrompt,
|
|
92
|
+
responseText: "",
|
|
93
|
+
inputTokens: 0,
|
|
94
|
+
outputTokens: 0,
|
|
95
|
+
durationMs,
|
|
96
|
+
status: "failed",
|
|
97
|
+
});
|
|
98
|
+
throw err;
|
|
99
|
+
}
|
|
100
|
+
const durationMs = Date.now() - startedAt;
|
|
101
|
+
const ctx = currentExecutionContext();
|
|
102
|
+
if (!ctx) {
|
|
103
|
+
// No active execution — nothing to attach events to. Return
|
|
104
|
+
// the result unchanged.
|
|
105
|
+
return result;
|
|
106
|
+
}
|
|
107
|
+
// If the result has multiple steps (ReAct loop), iterate them
|
|
108
|
+
// and emit one llm_call per step + each step's tool calls.
|
|
109
|
+
// Otherwise treat the whole result as a single step.
|
|
110
|
+
const steps = result.steps && result.steps.length > 0
|
|
111
|
+
? result.steps
|
|
112
|
+
: [
|
|
113
|
+
{
|
|
114
|
+
text: result.text,
|
|
115
|
+
toolCalls: result.toolCalls,
|
|
116
|
+
toolResults: result.toolResults,
|
|
117
|
+
usage: result.usage,
|
|
118
|
+
},
|
|
119
|
+
];
|
|
120
|
+
for (let i = 0; i < steps.length; i++) {
|
|
121
|
+
const step = steps[i];
|
|
122
|
+
const isLastStep = i === steps.length - 1;
|
|
123
|
+
const [inputTokens, outputTokens] = extractStepTokens(step);
|
|
124
|
+
emitLlmCallEvent({
|
|
125
|
+
model: modelId,
|
|
126
|
+
userMessage,
|
|
127
|
+
systemPrompt,
|
|
128
|
+
responseText: step.text ?? "",
|
|
129
|
+
inputTokens,
|
|
130
|
+
outputTokens,
|
|
131
|
+
// Only the last step gets the full duration; intermediate
|
|
132
|
+
// steps are attributed to the same total wall-clock for
|
|
133
|
+
// now (Vercel doesn't expose per-step durations).
|
|
134
|
+
durationMs: isLastStep ? durationMs : 0,
|
|
135
|
+
status: "ok",
|
|
136
|
+
});
|
|
137
|
+
const toolCalls = step.toolCalls ?? [];
|
|
138
|
+
const toolResults = step.toolResults ?? [];
|
|
139
|
+
for (const tc of toolCalls) {
|
|
140
|
+
const tr = toolResults.find((r) => r.toolCallId !== undefined && r.toolCallId === tc.toolCallId);
|
|
141
|
+
emitToolCallEvent(tc, tr);
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
return result;
|
|
145
|
+
};
|
|
146
|
+
return wrapped;
|
|
147
|
+
}
|
|
148
|
+
/**
|
|
149
|
+
* Inline emit_llm_call helper — direct equivalent of the Python
|
|
150
|
+
* `mesedi.observe.emit_llm_call`. Drift / similar-call /
|
|
151
|
+
* identical-call / cost-velocity / prompt-injection detectors all
|
|
152
|
+
* read from the resulting event payload, so a manually-emitted
|
|
153
|
+
* llm_call event from this adapter is detector-complete the same
|
|
154
|
+
* way an auto-instrumented Anthropic-patch one is.
|
|
155
|
+
*/
|
|
156
|
+
function emitLlmCallEvent(args) {
|
|
157
|
+
const ctx = currentExecutionContext();
|
|
158
|
+
if (!ctx)
|
|
159
|
+
return;
|
|
160
|
+
// Halt-safe boundary — matches @mesedi.tool, the Anthropic patch,
|
|
161
|
+
// and the Python emit_llm_call.
|
|
162
|
+
ctx.checkBudget();
|
|
163
|
+
if (ctx.budgetTracker) {
|
|
164
|
+
ctx.budgetTracker.incrementSteps();
|
|
165
|
+
if (args.inputTokens > 0 || args.outputTokens > 0) {
|
|
166
|
+
ctx.budgetTracker.addTokens(args.inputTokens, args.outputTokens);
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
const payload = {
|
|
170
|
+
model: args.model,
|
|
171
|
+
system_prompt: truncate(args.systemPrompt, MAX_SYSTEM),
|
|
172
|
+
user_message: truncate(args.userMessage, MAX_USER_MSG),
|
|
173
|
+
status: args.status,
|
|
174
|
+
};
|
|
175
|
+
if (args.status === "ok") {
|
|
176
|
+
payload["response_text"] = truncate(args.responseText, MAX_RESPONSE);
|
|
177
|
+
payload["input_tokens"] = args.inputTokens;
|
|
178
|
+
payload["output_tokens"] = args.outputTokens;
|
|
179
|
+
}
|
|
180
|
+
const event = {
|
|
181
|
+
event_id: newEventId(),
|
|
182
|
+
execution_id: ctx.executionId,
|
|
183
|
+
event_type: EventType.LLM_CALL,
|
|
184
|
+
sequence: ctx.nextSequence(),
|
|
185
|
+
timestamp: utcNowRfc3339(),
|
|
186
|
+
duration_ms: args.durationMs,
|
|
187
|
+
payload,
|
|
188
|
+
};
|
|
189
|
+
getClient().submitEvent(event);
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* Emit a tool_call event matching the wire format of `@mesedi.tool`.
|
|
193
|
+
* Tool failures: Vercel exposes the result; if a tool errored, the
|
|
194
|
+
* result entry will typically be undefined OR an object with an
|
|
195
|
+
* `error` field. We detect failure mode duck-typed.
|
|
196
|
+
*/
|
|
197
|
+
function emitToolCallEvent(tc, tr) {
|
|
198
|
+
const ctx = currentExecutionContext();
|
|
199
|
+
if (!ctx)
|
|
200
|
+
return;
|
|
201
|
+
ctx.checkBudget();
|
|
202
|
+
if (ctx.budgetTracker) {
|
|
203
|
+
ctx.budgetTracker.incrementSteps();
|
|
204
|
+
}
|
|
205
|
+
const toolName = tc.toolName || "unknown_tool";
|
|
206
|
+
// Vercel tool args are typically a flat object; mimic the
|
|
207
|
+
// @mesedi.tool wire shape ({args: [...], kwargs: {...}}). The
|
|
208
|
+
// structured-args object goes into kwargs; args[] stays empty.
|
|
209
|
+
const kwargs = {};
|
|
210
|
+
if (tc.args && typeof tc.args === "object" && !Array.isArray(tc.args)) {
|
|
211
|
+
for (const [k, v] of Object.entries(tc.args)) {
|
|
212
|
+
kwargs[k] = truncate(reprValue(v), MAX_TOOL_INPUT_REPR);
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
else if (tc.args !== undefined) {
|
|
216
|
+
kwargs["input"] = truncate(reprValue(tc.args), MAX_TOOL_INPUT_REPR);
|
|
217
|
+
}
|
|
218
|
+
const argumentsObj = {
|
|
219
|
+
args: [],
|
|
220
|
+
kwargs,
|
|
221
|
+
};
|
|
222
|
+
// Determine status from the matched tool result. Vercel surfaces
|
|
223
|
+
// tool errors as either a missing result OR a result with an
|
|
224
|
+
// `error` property; we treat both as failed.
|
|
225
|
+
let status = "ok";
|
|
226
|
+
let resultSummary = "";
|
|
227
|
+
let exceptionType = "";
|
|
228
|
+
let exceptionMessage = "";
|
|
229
|
+
if (tr === undefined) {
|
|
230
|
+
status = "failed";
|
|
231
|
+
exceptionType = "ToolExecutionError";
|
|
232
|
+
exceptionMessage = "tool did not return a result";
|
|
233
|
+
}
|
|
234
|
+
else if (tr.result &&
|
|
235
|
+
typeof tr.result === "object" &&
|
|
236
|
+
tr.result !== null &&
|
|
237
|
+
"error" in tr.result) {
|
|
238
|
+
status = "failed";
|
|
239
|
+
const errObj = tr.result.error;
|
|
240
|
+
exceptionType =
|
|
241
|
+
errObj && typeof errObj === "object" && "name" in errObj
|
|
242
|
+
? String(errObj.name)
|
|
243
|
+
: "ToolExecutionError";
|
|
244
|
+
exceptionMessage = truncate(reprValue(errObj), MAX_EXC_MSG);
|
|
245
|
+
}
|
|
246
|
+
else {
|
|
247
|
+
resultSummary = truncate(reprValue(tr.result), MAX_TOOL_OUTPUT_REPR);
|
|
248
|
+
}
|
|
249
|
+
const payload = {
|
|
250
|
+
tool_name: toolName,
|
|
251
|
+
arguments: argumentsObj,
|
|
252
|
+
status,
|
|
253
|
+
};
|
|
254
|
+
if (status === "ok") {
|
|
255
|
+
payload["result_summary"] = resultSummary;
|
|
256
|
+
}
|
|
257
|
+
else {
|
|
258
|
+
payload["exception_type"] = exceptionType;
|
|
259
|
+
payload["exception_message"] = exceptionMessage;
|
|
260
|
+
}
|
|
261
|
+
const event = {
|
|
262
|
+
event_id: newEventId(),
|
|
263
|
+
execution_id: ctx.executionId,
|
|
264
|
+
event_type: EventType.TOOL_CALL,
|
|
265
|
+
sequence: ctx.nextSequence(),
|
|
266
|
+
timestamp: utcNowRfc3339(),
|
|
267
|
+
payload,
|
|
268
|
+
};
|
|
269
|
+
getClient().submitEvent(event);
|
|
270
|
+
}
|
|
271
|
+
/**
|
|
272
|
+
* Extract a stable model identifier from a Vercel model object.
|
|
273
|
+
*
|
|
274
|
+
* Vercel provider models expose either `.modelId` (newer) or
|
|
275
|
+
* `.id` (older). For unknown shapes we try toString() — most
|
|
276
|
+
* providers stringify to a human-readable label. Last resort:
|
|
277
|
+
* "unknown".
|
|
278
|
+
*/
|
|
279
|
+
function extractModelId(model) {
|
|
280
|
+
if (typeof model === "string")
|
|
281
|
+
return model;
|
|
282
|
+
if (model && typeof model === "object") {
|
|
283
|
+
const m = model;
|
|
284
|
+
if (typeof m["modelId"] === "string")
|
|
285
|
+
return m["modelId"];
|
|
286
|
+
if (typeof m["id"] === "string")
|
|
287
|
+
return m["id"];
|
|
288
|
+
if (typeof m["name"] === "string")
|
|
289
|
+
return m["name"];
|
|
290
|
+
try {
|
|
291
|
+
const s = String(model);
|
|
292
|
+
if (s && s !== "[object Object]")
|
|
293
|
+
return s;
|
|
294
|
+
}
|
|
295
|
+
catch {
|
|
296
|
+
// fall through
|
|
297
|
+
}
|
|
298
|
+
}
|
|
299
|
+
return "unknown";
|
|
300
|
+
}
|
|
301
|
+
/**
|
|
302
|
+
* Pull the last user message out of a Vercel generateText options
|
|
303
|
+
* object. Vercel accepts either a flat `prompt: string` or a
|
|
304
|
+
* `messages: Array<{role, content}>` (chat-style); we handle both.
|
|
305
|
+
*/
|
|
306
|
+
function extractLastUserMessage(opts) {
|
|
307
|
+
if (typeof opts.prompt === "string" && opts.prompt) {
|
|
308
|
+
return opts.prompt;
|
|
309
|
+
}
|
|
310
|
+
if (Array.isArray(opts.messages)) {
|
|
311
|
+
for (let i = opts.messages.length - 1; i >= 0; i--) {
|
|
312
|
+
const msg = opts.messages[i];
|
|
313
|
+
if (!msg)
|
|
314
|
+
continue;
|
|
315
|
+
if (msg["role"] !== "user")
|
|
316
|
+
continue;
|
|
317
|
+
const content = msg["content"];
|
|
318
|
+
if (typeof content === "string")
|
|
319
|
+
return content;
|
|
320
|
+
if (Array.isArray(content)) {
|
|
321
|
+
const parts = [];
|
|
322
|
+
for (const block of content) {
|
|
323
|
+
if (typeof block === "string")
|
|
324
|
+
parts.push(block);
|
|
325
|
+
else if (block &&
|
|
326
|
+
typeof block === "object" &&
|
|
327
|
+
block["type"] === "text" &&
|
|
328
|
+
typeof block["text"] === "string") {
|
|
329
|
+
parts.push(block["text"]);
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
return parts.join(" ");
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
}
|
|
336
|
+
return "";
|
|
337
|
+
}
|
|
338
|
+
/**
|
|
339
|
+
* Extract (input_tokens, output_tokens) from a step's usage block.
|
|
340
|
+
* Vercel renamed `promptTokens` → `inputTokens` and
|
|
341
|
+
* `completionTokens` → `outputTokens` between SDK versions; try both.
|
|
342
|
+
*/
|
|
343
|
+
function extractStepTokens(step) {
|
|
344
|
+
const usage = step.usage;
|
|
345
|
+
if (!usage)
|
|
346
|
+
return [0, 0];
|
|
347
|
+
const inTokens = (typeof usage.inputTokens === "number" ? usage.inputTokens : 0) ||
|
|
348
|
+
(typeof usage.promptTokens === "number" ? usage.promptTokens : 0) ||
|
|
349
|
+
0;
|
|
350
|
+
const outTokens = (typeof usage.outputTokens === "number" ? usage.outputTokens : 0) ||
|
|
351
|
+
(typeof usage.completionTokens === "number" ? usage.completionTokens : 0) ||
|
|
352
|
+
0;
|
|
353
|
+
return [inTokens, outTokens];
|
|
354
|
+
}
|
|
355
|
+
function truncate(s, max) {
|
|
356
|
+
if (s.length <= max)
|
|
357
|
+
return s;
|
|
358
|
+
return s.slice(0, max - 3) + "...";
|
|
359
|
+
}
|
|
360
|
+
/**
|
|
361
|
+
* Safe `repr` for arbitrary values. Strings pass through;
|
|
362
|
+
* everything else gets JSON.stringify with a fallback to String().
|
|
363
|
+
*/
|
|
364
|
+
function reprValue(v) {
|
|
365
|
+
if (typeof v === "string")
|
|
366
|
+
return v;
|
|
367
|
+
if (v === undefined || v === null)
|
|
368
|
+
return String(v);
|
|
369
|
+
try {
|
|
370
|
+
return JSON.stringify(v);
|
|
371
|
+
}
|
|
372
|
+
catch {
|
|
373
|
+
try {
|
|
374
|
+
return String(v);
|
|
375
|
+
}
|
|
376
|
+
catch {
|
|
377
|
+
return "<unrepresentable>";
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
}
|
|
381
|
+
//# sourceMappingURL=vercel_ai.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"vercel_ai.js","sourceRoot":"","sources":["../../src/integrations/vercel_ai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACpE,OAAO,EAAS,SAAS,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE/D,sEAAsE;AACtE,uEAAuE;AACvE,qDAAqD;AACrD,MAAM,UAAU,GAAG,IAAI,CAAC;AACxB,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAChC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AACjC,MAAM,WAAW,GAAG,GAAG,CAAC;AAqExB;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAC9B,cAAiB;IAEjB,MAAM,OAAO,GAAG,KAAK,EACnB,OAAgC,EACC,EAAE;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,cAAc,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QAC9C,MAAM,WAAW,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;QACpD,MAAM,YAAY,GAChB,OAAO,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAE3D,IAAI,MAA8B,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,gBAAgB,CAAC;gBACf,KAAK,EAAE,OAAO;gBACd,WAAW;gBACX,YAAY;gBACZ,YAAY,EAAE,EAAE;gBAChB,WAAW,EAAE,CAAC;gBACd,YAAY,EAAE,CAAC;gBACf,UAAU;gBACV,MAAM,EAAE,QAAQ;aACjB,CAAC,CAAC;YACH,MAAM,GAAG,CAAC;QACZ,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAC1C,MAAM,GAAG,GAAG,uBAAuB,EAAE,CAAC;QACtC,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,4DAA4D;YAC5D,wBAAwB;YACxB,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,8DAA8D;QAC9D,2DAA2D;QAC3D,qDAAqD;QACrD,MAAM,KAAK,GACT,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;YACrC,CAAC,CAAC,MAAM,CAAC,KAAK;YACd,CAAC,CAAC;gBACE;oBACE,IAAI,EAAE,MAAM,CAAC,IAAI;oBACjB,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,WAAW,EAAE,MAAM,CAAC,WAAW;oBAC/B,KAAK,EAAE,MAAM,CAAC,KAAK;iBACpB;aACF,CAAC;QAER,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAa,CAAC;YAClC,MAAM,UAAU,GAAG,CAAC,KAAK,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;YAC1C,MAAM,CAAC,WAAW,EAAE,YAAY,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;YAE5D,gBAAgB,CAAC;gBACf,KAAK,EAAE,OAAO;gBACd,WAAW;gBACX,YAAY;gBACZ,YAAY,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;gBAC7B,WAAW;gBACX,YAAY;gBACZ,0DAA0D;gBAC1D,wDAAwD;gBACxD,kDAAkD;gBAClD,UAAU,EAAE,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;gBACvC,MAAM,EAAE,IAAI;aACb,CAAC,CAAC;YAEH,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;YACvC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;YAC3C,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;gBAC3B,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CACzB,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,UAAU,KAAK,SAAS,IAAI,CAAC,CAAC,UAAU,KAAK,EAAE,CAAC,UAAU,CAC/D,CAAC;gBACF,iBAAiB,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC5B,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;IACF,OAAO,OAAY,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,IASzB;IACC,MAAM,GAAG,GAAG,uBAAuB,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO;IAEjB,kEAAkE;IAClE,gCAAgC;IAChC,GAAG,CAAC,WAAW,EAAE,CAAC;IAClB,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QACtB,GAAG,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC;QACnC,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC,IAAI,IAAI,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAA4B;QACvC,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,aAAa,EAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC;QACtD,YAAY,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,CAAC;QACtD,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CAAC;IACF,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;QACzB,OAAO,CAAC,eAAe,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QACrE,OAAO,CAAC,cAAc,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC;QAC3C,OAAO,CAAC,eAAe,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC;IAC/C,CAAC;IAED,MAAM,KAAK,GAAU;QACnB,QAAQ,EAAE,UAAU,EAAE;QACtB,YAAY,EAAE,GAAG,CAAC,WAAW;QAC7B,UAAU,EAAE,SAAS,CAAC,QAAQ;QAC9B,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE;QAC5B,SAAS,EAAE,aAAa,EAAE;QAC1B,WAAW,EAAE,IAAI,CAAC,UAAU;QAC5B,OAAO;KACR,CAAC;IACF,SAAS,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC;AAED;;;;;GAKG;AACH,SAAS,iBAAiB,CACxB,EAAgB,EAChB,EAA8B;IAE9B,MAAM,GAAG,GAAG,uBAAuB,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO;IAEjB,GAAG,CAAC,WAAW,EAAE,CAAC;IAClB,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QACtB,GAAG,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,QAAQ,GAAG,EAAE,CAAC,QAAQ,IAAI,cAAc,CAAC;IAE/C,0DAA0D;IAC1D,8DAA8D;IAC9D,+DAA+D;IAC/D,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,IAAI,EAAE,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACtE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,IAA+B,CAAC,EAAE,CAAC;YACxE,MAAM,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,mBAAmB,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;SAAM,IAAI,EAAE,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,CAAC,OAAO,CAAC,GAAG,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,mBAAmB,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,YAAY,GAA4B;QAC5C,IAAI,EAAE,EAAE;QACR,MAAM;KACP,CAAC;IAEF,iEAAiE;IACjE,6DAA6D;IAC7D,6CAA6C;IAC7C,IAAI,MAAM,GAAoB,IAAI,CAAC;IACnC,IAAI,aAAa,GAAG,EAAE,CAAC;IACvB,IAAI,aAAa,GAAG,EAAE,CAAC;IACvB,IAAI,gBAAgB,GAAG,EAAE,CAAC;IAE1B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,MAAM,GAAG,QAAQ,CAAC;QAClB,aAAa,GAAG,oBAAoB,CAAC;QACrC,gBAAgB,GAAG,8BAA8B,CAAC;IACpD,CAAC;SAAM,IACL,EAAE,CAAC,MAAM;QACT,OAAO,EAAE,CAAC,MAAM,KAAK,QAAQ;QAC7B,EAAE,CAAC,MAAM,KAAK,IAAI;QAClB,OAAO,IAAK,EAAE,CAAC,MAAkC,EACjD,CAAC;QACD,MAAM,GAAG,QAAQ,CAAC;QAClB,MAAM,MAAM,GAAI,EAAE,CAAC,MAAkC,CAAC,KAAK,CAAC;QAC5D,aAAa;YACX,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,IAAI,MAAM;gBACtD,CAAC,CAAC,MAAM,CAAE,MAAkC,CAAC,IAAI,CAAC;gBAClD,CAAC,CAAC,oBAAoB,CAAC;QAC3B,gBAAgB,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9D,CAAC;SAAM,CAAC;QACN,aAAa,GAAG,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC,CAAC;IACvE,CAAC;IAED,MAAM,OAAO,GAA4B;QACvC,SAAS,EAAE,QAAQ;QACnB,SAAS,EAAE,YAAY;QACvB,MAAM;KACP,CAAC;IACF,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,CAAC,gBAAgB,CAAC,GAAG,aAAa,CAAC;IAC5C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,gBAAgB,CAAC,GAAG,aAAa,CAAC;QAC1C,OAAO,CAAC,mBAAmB,CAAC,GAAG,gBAAgB,CAAC;IAClD,CAAC;IAED,MAAM,KAAK,GAAU;QACnB,QAAQ,EAAE,UAAU,EAAE;QACtB,YAAY,EAAE,GAAG,CAAC,WAAW;QAC7B,UAAU,EAAE,SAAS,CAAC,SAAS;QAC/B,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE;QAC5B,SAAS,EAAE,aAAa,EAAE;QAC1B,OAAO;KACR,CAAC;IACF,SAAS,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,CAAC,GAAG,KAAgC,CAAC;QAC3C,IAAI,OAAO,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,SAAS,CAAW,CAAC;QACpE,IAAI,OAAO,CAAC,CAAC,IAAI,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,IAAI,CAAW,CAAC;QAC1D,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,QAAQ;YAAE,OAAO,CAAC,CAAC,MAAM,CAAW,CAAC;QAC9D,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACxB,IAAI,CAAC,IAAI,CAAC,KAAK,iBAAiB;gBAAE,OAAO,CAAC,CAAC;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,SAAS,sBAAsB,CAAC,IAA6B;IAC3D,IAAI,OAAO,IAAI,CAAC,MAAM,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QACnD,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACjC,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YACnD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAwC,CAAC;YACpE,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,MAAM;gBAAE,SAAS;YACrC,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,CAAC,CAAC;YAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ;gBAAE,OAAO,OAAO,CAAC;YAChD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC3B,MAAM,KAAK,GAAa,EAAE,CAAC;gBAC3B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;oBAC5B,IAAI,OAAO,KAAK,KAAK,QAAQ;wBAAE,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;yBAC5C,IACH,KAAK;wBACL,OAAO,KAAK,KAAK,QAAQ;wBACxB,KAAiC,CAAC,MAAM,CAAC,KAAK,MAAM;wBACrD,OAAQ,KAAiC,CAAC,MAAM,CAAC,KAAK,QAAQ,EAC9D,CAAC;wBACD,KAAK,CAAC,IAAI,CAAE,KAAiC,CAAC,MAAM,CAAW,CAAC,CAAC;oBACnE,CAAC;gBACH,CAAC;gBACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;GAIG;AACH,SAAS,iBAAiB,CAAC,IAAc;IACvC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IACzB,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1B,MAAM,QAAQ,GACZ,CAAC,OAAO,KAAK,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QAC/D,CAAC,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,CAAC,CAAC;IACJ,MAAM,SAAS,GACb,CAAC,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QACjE,CAAC,OAAO,KAAK,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;QACzE,CAAC,CAAC;IACJ,OAAO,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;AAC/B,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS,EAAE,GAAW;IACtC,IAAI,CAAC,CAAC,MAAM,IAAI,GAAG;QAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,SAAS,SAAS,CAAC,CAAU;IAC3B,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACpC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACpD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IAC3B,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YACH,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;QACnB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,mBAAmB,CAAC;QAC7B,CAAC;IACH,CAAC;AACH,CAAC"}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Direct-emission helpers for events that don't fit the HOF pattern.
|
|
3
|
+
*
|
|
4
|
+
* `wrap()` and `tool()` wrap functions; `checkpoint()` and
|
|
5
|
+
* `validatorResult()` are markers inserted at points of interest
|
|
6
|
+
* inside agent code, often inside the same function `wrap()` already
|
|
7
|
+
* covers. For those, a plain function call is the right API:
|
|
8
|
+
*
|
|
9
|
+
* checkpoint("after_retrieval", { documents: 5, used_cache: true });
|
|
10
|
+
*
|
|
11
|
+
* if (!result) {
|
|
12
|
+
* validatorResult("non-empty-response", false, {
|
|
13
|
+
* message: "LLM returned empty content",
|
|
14
|
+
* severity: "error",
|
|
15
|
+
* });
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* Both helpers no-op silently when called outside an active wrap()
|
|
19
|
+
* execution context — same fail-open pattern as `tool()`.
|
|
20
|
+
*/
|
|
21
|
+
/**
|
|
22
|
+
* Emit a `checkpoint` event marking a notable point in execution.
|
|
23
|
+
*
|
|
24
|
+
* A checkpoint is a free-form marker: a name + arbitrary metadata.
|
|
25
|
+
* Typical uses: "after_retrieval", "before_synthesis", "cache_hit".
|
|
26
|
+
* Useful both for Phase 3+ detector hooks (drift, cost-velocity)
|
|
27
|
+
* and for ad-hoc debugging — replay UI in a future phase will
|
|
28
|
+
* render checkpoints as anchored markers on the execution timeline.
|
|
29
|
+
*
|
|
30
|
+
* Outside `wrap()`: silent no-op.
|
|
31
|
+
*/
|
|
32
|
+
export declare function checkpoint(name: string, metadata?: Record<string, unknown>): void;
|
|
33
|
+
export type ValidatorSeverity = "warning" | "error" | "critical";
|
|
34
|
+
export interface ValidatorResultOptions {
|
|
35
|
+
message?: string;
|
|
36
|
+
severity?: ValidatorSeverity;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* Report a validator outcome as a `validator_result` event.
|
|
40
|
+
*
|
|
41
|
+
* Validators are checks the agent (or its framework) runs against
|
|
42
|
+
* intermediate or final outputs: schema conformance, factuality,
|
|
43
|
+
* relevance, safety. The result — pass or fail — becomes a discrete
|
|
44
|
+
* event so Phase-3 detection can spot patterns like "validator X
|
|
45
|
+
* has been failing 90% of the time on this model."
|
|
46
|
+
*
|
|
47
|
+
* Outside `wrap()`: silent no-op.
|
|
48
|
+
*/
|
|
49
|
+
export declare function validatorResult(name: string, passed: boolean, opts?: ValidatorResultOptions): void;
|
|
50
|
+
//# sourceMappingURL=observe.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAQH;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,IAAI,CAuBN;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAEjE,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,EACf,IAAI,GAAE,sBAA2B,GAChC,IAAI,CA8BN"}
|
package/dist/observe.js
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Direct-emission helpers for events that don't fit the HOF pattern.
|
|
3
|
+
*
|
|
4
|
+
* `wrap()` and `tool()` wrap functions; `checkpoint()` and
|
|
5
|
+
* `validatorResult()` are markers inserted at points of interest
|
|
6
|
+
* inside agent code, often inside the same function `wrap()` already
|
|
7
|
+
* covers. For those, a plain function call is the right API:
|
|
8
|
+
*
|
|
9
|
+
* checkpoint("after_retrieval", { documents: 5, used_cache: true });
|
|
10
|
+
*
|
|
11
|
+
* if (!result) {
|
|
12
|
+
* validatorResult("non-empty-response", false, {
|
|
13
|
+
* message: "LLM returned empty content",
|
|
14
|
+
* severity: "error",
|
|
15
|
+
* });
|
|
16
|
+
* }
|
|
17
|
+
*
|
|
18
|
+
* Both helpers no-op silently when called outside an active wrap()
|
|
19
|
+
* execution context — same fail-open pattern as `tool()`.
|
|
20
|
+
*/
|
|
21
|
+
import { getClient } from "./client.js";
|
|
22
|
+
import { currentExecutionContext, newEventId } from "./context.js";
|
|
23
|
+
import { EventType, utcNowRfc3339 } from "./events.js";
|
|
24
|
+
const MAX_VALIDATOR_MSG = 500;
|
|
25
|
+
/**
|
|
26
|
+
* Emit a `checkpoint` event marking a notable point in execution.
|
|
27
|
+
*
|
|
28
|
+
* A checkpoint is a free-form marker: a name + arbitrary metadata.
|
|
29
|
+
* Typical uses: "after_retrieval", "before_synthesis", "cache_hit".
|
|
30
|
+
* Useful both for Phase 3+ detector hooks (drift, cost-velocity)
|
|
31
|
+
* and for ad-hoc debugging — replay UI in a future phase will
|
|
32
|
+
* render checkpoints as anchored markers on the execution timeline.
|
|
33
|
+
*
|
|
34
|
+
* Outside `wrap()`: silent no-op.
|
|
35
|
+
*/
|
|
36
|
+
export function checkpoint(name, metadata = {}) {
|
|
37
|
+
const ctx = currentExecutionContext();
|
|
38
|
+
if (!ctx)
|
|
39
|
+
return;
|
|
40
|
+
// Halt-safe boundary: checkpoint is the canonical place for users
|
|
41
|
+
// to insert their own "ok to halt here" markers. Budget check runs
|
|
42
|
+
// first so a halt fires before the event is emitted; the user's
|
|
43
|
+
// checkpoint call effectively becomes a yield point for halt.
|
|
44
|
+
ctx.checkBudget();
|
|
45
|
+
if (ctx.budgetTracker) {
|
|
46
|
+
ctx.budgetTracker.incrementSteps();
|
|
47
|
+
}
|
|
48
|
+
const client = getClient();
|
|
49
|
+
const event = {
|
|
50
|
+
event_id: newEventId(),
|
|
51
|
+
execution_id: ctx.executionId,
|
|
52
|
+
event_type: EventType.CHECKPOINT,
|
|
53
|
+
sequence: ctx.nextSequence(),
|
|
54
|
+
timestamp: utcNowRfc3339(),
|
|
55
|
+
payload: { name, metadata },
|
|
56
|
+
};
|
|
57
|
+
client.submitEvent(event);
|
|
58
|
+
}
|
|
59
|
+
/**
|
|
60
|
+
* Report a validator outcome as a `validator_result` event.
|
|
61
|
+
*
|
|
62
|
+
* Validators are checks the agent (or its framework) runs against
|
|
63
|
+
* intermediate or final outputs: schema conformance, factuality,
|
|
64
|
+
* relevance, safety. The result — pass or fail — becomes a discrete
|
|
65
|
+
* event so Phase-3 detection can spot patterns like "validator X
|
|
66
|
+
* has been failing 90% of the time on this model."
|
|
67
|
+
*
|
|
68
|
+
* Outside `wrap()`: silent no-op.
|
|
69
|
+
*/
|
|
70
|
+
export function validatorResult(name, passed, opts = {}) {
|
|
71
|
+
const ctx = currentExecutionContext();
|
|
72
|
+
if (!ctx)
|
|
73
|
+
return;
|
|
74
|
+
let severity = opts.severity ?? "error";
|
|
75
|
+
if (severity !== "warning" &&
|
|
76
|
+
severity !== "error" &&
|
|
77
|
+
severity !== "critical") {
|
|
78
|
+
// Don't throw — the caller's agent shouldn't fail because of an
|
|
79
|
+
// SDK-side validation. Coerce to the safest default.
|
|
80
|
+
severity = "error";
|
|
81
|
+
}
|
|
82
|
+
const payload = { name, passed, severity };
|
|
83
|
+
if (opts.message) {
|
|
84
|
+
payload["message"] = opts.message.slice(0, MAX_VALIDATOR_MSG);
|
|
85
|
+
}
|
|
86
|
+
const client = getClient();
|
|
87
|
+
const event = {
|
|
88
|
+
event_id: newEventId(),
|
|
89
|
+
execution_id: ctx.executionId,
|
|
90
|
+
event_type: EventType.VALIDATOR_RESULT,
|
|
91
|
+
sequence: ctx.nextSequence(),
|
|
92
|
+
timestamp: utcNowRfc3339(),
|
|
93
|
+
payload,
|
|
94
|
+
};
|
|
95
|
+
client.submitEvent(event);
|
|
96
|
+
}
|
|
97
|
+
//# sourceMappingURL=observe.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAS,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE9D,MAAM,iBAAiB,GAAG,GAAG,CAAC;AAE9B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,WAAoC,EAAE;IAEtC,MAAM,GAAG,GAAG,uBAAuB,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO;IAEjB,kEAAkE;IAClE,mEAAmE;IACnE,gEAAgE;IAChE,8DAA8D;IAC9D,GAAG,CAAC,WAAW,EAAE,CAAC;IAClB,IAAI,GAAG,CAAC,aAAa,EAAE,CAAC;QACtB,GAAG,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAU;QACnB,QAAQ,EAAE,UAAU,EAAE;QACtB,YAAY,EAAE,GAAG,CAAC,WAAW;QAC7B,UAAU,EAAE,SAAS,CAAC,UAAU;QAChC,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE;QAC5B,SAAS,EAAE,aAAa,EAAE;QAC1B,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC5B,CAAC;IACF,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC;AASD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAY,EACZ,MAAe,EACf,OAA+B,EAAE;IAEjC,MAAM,GAAG,GAAG,uBAAuB,EAAE,CAAC;IACtC,IAAI,CAAC,GAAG;QAAE,OAAO;IAEjB,IAAI,QAAQ,GAAsB,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC;IAC3D,IACE,QAAQ,KAAK,SAAS;QACtB,QAAQ,KAAK,OAAO;QACpB,QAAQ,KAAK,UAAU,EACvB,CAAC;QACD,gEAAgE;QAChE,qDAAqD;QACrD,QAAQ,GAAG,OAAO,CAAC;IACrB,CAAC;IAED,MAAM,OAAO,GAA4B,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACpE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACjB,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAChE,CAAC;IAED,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,KAAK,GAAU;QACnB,QAAQ,EAAE,UAAU,EAAE;QACtB,YAAY,EAAE,GAAG,CAAC,WAAW;QAC7B,UAAU,EAAE,SAAS,CAAC,gBAAgB;QACtC,QAAQ,EAAE,GAAG,CAAC,YAAY,EAAE;QAC5B,SAAS,EAAE,aAAa,EAAE;QAC1B,OAAO;KACR,CAAC;IACF,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}
|
package/dist/tool.d.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* tool() — wraps an async function as an instrumented agent tool.
|
|
3
|
+
*
|
|
4
|
+
* Mirrors the Python `@mesedi.tool` decorator, but as a higher-order
|
|
5
|
+
* function (TS doesn't have stable decorators yet). When the
|
|
6
|
+
* wrapped function is called from INSIDE a `wrap()`'d execution,
|
|
7
|
+
* each invocation emits a `tool_call` event with:
|
|
8
|
+
*
|
|
9
|
+
* - tool_name (from options or the function's .name)
|
|
10
|
+
* - arguments (sanitized + truncated)
|
|
11
|
+
* - status ("ok" or "failed")
|
|
12
|
+
* - result_summary (truncated) on success
|
|
13
|
+
* - exception_type / exception_message on failure
|
|
14
|
+
* - duration_ms
|
|
15
|
+
*
|
|
16
|
+
* Outside a wrap() context: runs unobserved (same fail-open as Python).
|
|
17
|
+
* Exceptions propagate to the caller unchanged.
|
|
18
|
+
*/
|
|
19
|
+
export interface ToolOptions {
|
|
20
|
+
/** Override the tool name (defaults to fn.name). */
|
|
21
|
+
name?: string;
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Decorate an async function as an observable agent tool.
|
|
25
|
+
*/
|
|
26
|
+
export declare function tool<TArgs extends unknown[], TResult>(fnOrOpts: ToolOptions | ((...args: TArgs) => Promise<TResult>), maybeFn?: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult>;
|
|
27
|
+
//# sourceMappingURL=tool.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAaH,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,wBAAgB,IAAI,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EACnD,QAAQ,EAAE,WAAW,GAAG,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,EAC9D,OAAO,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,GAC7C,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAyFtC"}
|