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.
Files changed (47) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +137 -0
  3. package/dist/anthropic_integration.d.ts +52 -0
  4. package/dist/anthropic_integration.d.ts.map +1 -0
  5. package/dist/anthropic_integration.js +226 -0
  6. package/dist/anthropic_integration.js.map +1 -0
  7. package/dist/client.d.ts +99 -0
  8. package/dist/client.d.ts.map +1 -0
  9. package/dist/client.js +258 -0
  10. package/dist/client.js.map +1 -0
  11. package/dist/context.d.ts +63 -0
  12. package/dist/context.d.ts.map +1 -0
  13. package/dist/context.js +84 -0
  14. package/dist/context.js.map +1 -0
  15. package/dist/events.d.ts +95 -0
  16. package/dist/events.d.ts.map +1 -0
  17. package/dist/events.js +103 -0
  18. package/dist/events.js.map +1 -0
  19. package/dist/halt.d.ts +165 -0
  20. package/dist/halt.d.ts.map +1 -0
  21. package/dist/halt.js +229 -0
  22. package/dist/halt.js.map +1 -0
  23. package/dist/halt_stream.d.ts +77 -0
  24. package/dist/halt_stream.d.ts.map +1 -0
  25. package/dist/halt_stream.js +214 -0
  26. package/dist/halt_stream.js.map +1 -0
  27. package/dist/index.d.ts +41 -0
  28. package/dist/index.d.ts.map +1 -0
  29. package/dist/index.js +34 -0
  30. package/dist/index.js.map +1 -0
  31. package/dist/integrations/vercel_ai.d.ts +120 -0
  32. package/dist/integrations/vercel_ai.d.ts.map +1 -0
  33. package/dist/integrations/vercel_ai.js +381 -0
  34. package/dist/integrations/vercel_ai.js.map +1 -0
  35. package/dist/observe.d.ts +50 -0
  36. package/dist/observe.d.ts.map +1 -0
  37. package/dist/observe.js +97 -0
  38. package/dist/observe.js.map +1 -0
  39. package/dist/tool.d.ts +27 -0
  40. package/dist/tool.d.ts.map +1 -0
  41. package/dist/tool.js +138 -0
  42. package/dist/tool.js.map +1 -0
  43. package/dist/wrap.d.ts +69 -0
  44. package/dist/wrap.d.ts.map +1 -0
  45. package/dist/wrap.js +168 -0
  46. package/dist/wrap.js.map +1 -0
  47. 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":"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"}
@@ -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"}
@@ -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"}