mesedi 0.2.0 → 0.7.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 (99) hide show
  1. package/README.md +57 -5
  2. package/dist/_errorClassesGenerated.d.ts +18 -0
  3. package/dist/_errorClassesGenerated.d.ts.map +1 -0
  4. package/dist/_errorClassesGenerated.js +24 -0
  5. package/dist/_errorClassesGenerated.js.map +1 -0
  6. package/dist/anthropic_integration.d.ts.map +1 -1
  7. package/dist/anthropic_integration.js +51 -10
  8. package/dist/anthropic_integration.js.map +1 -1
  9. package/dist/client.d.ts +26 -6
  10. package/dist/client.d.ts.map +1 -1
  11. package/dist/client.js +35 -7
  12. package/dist/client.js.map +1 -1
  13. package/dist/cohere_integration.d.ts +42 -0
  14. package/dist/cohere_integration.d.ts.map +1 -0
  15. package/dist/cohere_integration.js +456 -0
  16. package/dist/cohere_integration.js.map +1 -0
  17. package/dist/compress.d.ts +69 -0
  18. package/dist/compress.d.ts.map +1 -0
  19. package/dist/compress.js +75 -0
  20. package/dist/compress.js.map +1 -0
  21. package/dist/context.d.ts +11 -2
  22. package/dist/context.d.ts.map +1 -1
  23. package/dist/context.js +13 -3
  24. package/dist/context.js.map +1 -1
  25. package/dist/errors.d.ts +137 -0
  26. package/dist/errors.d.ts.map +1 -0
  27. package/dist/errors.js +462 -0
  28. package/dist/errors.js.map +1 -0
  29. package/dist/events.d.ts +13 -0
  30. package/dist/events.d.ts.map +1 -1
  31. package/dist/events.js +26 -1
  32. package/dist/events.js.map +1 -1
  33. package/dist/gemini_integration.d.ts +33 -0
  34. package/dist/gemini_integration.d.ts.map +1 -0
  35. package/dist/gemini_integration.js +334 -0
  36. package/dist/gemini_integration.js.map +1 -0
  37. package/dist/halt_stream.d.ts.map +1 -1
  38. package/dist/halt_stream.js +11 -1
  39. package/dist/halt_stream.js.map +1 -1
  40. package/dist/index.d.ts +15 -2
  41. package/dist/index.d.ts.map +1 -1
  42. package/dist/index.js +9 -1
  43. package/dist/index.js.map +1 -1
  44. package/dist/integrations/langchain.d.ts +95 -0
  45. package/dist/integrations/langchain.d.ts.map +1 -0
  46. package/dist/integrations/langchain.js +549 -0
  47. package/dist/integrations/langchain.js.map +1 -0
  48. package/dist/integrations/langgraph.d.ts +99 -0
  49. package/dist/integrations/langgraph.d.ts.map +1 -0
  50. package/dist/integrations/langgraph.js +572 -0
  51. package/dist/integrations/langgraph.js.map +1 -0
  52. package/dist/integrations/mastra.d.ts +114 -0
  53. package/dist/integrations/mastra.d.ts.map +1 -0
  54. package/dist/integrations/mastra.js +354 -0
  55. package/dist/integrations/mastra.js.map +1 -0
  56. package/dist/integrations/openai_agents.d.ts +66 -0
  57. package/dist/integrations/openai_agents.d.ts.map +1 -0
  58. package/dist/integrations/openai_agents.js +243 -0
  59. package/dist/integrations/openai_agents.js.map +1 -0
  60. package/dist/integrations/promptfoo.d.ts +62 -0
  61. package/dist/integrations/promptfoo.d.ts.map +1 -0
  62. package/dist/integrations/promptfoo.js +76 -0
  63. package/dist/integrations/promptfoo.js.map +1 -0
  64. package/dist/integrations/ragas.d.ts +65 -0
  65. package/dist/integrations/ragas.d.ts.map +1 -0
  66. package/dist/integrations/ragas.js +78 -0
  67. package/dist/integrations/ragas.js.map +1 -0
  68. package/dist/integrations/vectara.d.ts +60 -0
  69. package/dist/integrations/vectara.d.ts.map +1 -0
  70. package/dist/integrations/vectara.js +59 -0
  71. package/dist/integrations/vectara.js.map +1 -0
  72. package/dist/observe.d.ts +355 -0
  73. package/dist/observe.d.ts.map +1 -1
  74. package/dist/observe.js +532 -0
  75. package/dist/observe.js.map +1 -1
  76. package/dist/ollama_integration.d.ts +126 -0
  77. package/dist/ollama_integration.d.ts.map +1 -0
  78. package/dist/ollama_integration.js +404 -0
  79. package/dist/ollama_integration.js.map +1 -0
  80. package/dist/openai_integration.d.ts +67 -0
  81. package/dist/openai_integration.d.ts.map +1 -0
  82. package/dist/openai_integration.js +574 -0
  83. package/dist/openai_integration.js.map +1 -0
  84. package/dist/tool.d.ts.map +1 -1
  85. package/dist/tool.js +189 -6
  86. package/dist/tool.js.map +1 -1
  87. package/dist/truncate.d.ts +84 -0
  88. package/dist/truncate.d.ts.map +1 -0
  89. package/dist/truncate.js +134 -0
  90. package/dist/truncate.js.map +1 -0
  91. package/dist/vertex_gemini_integration.d.ts +27 -0
  92. package/dist/vertex_gemini_integration.d.ts.map +1 -0
  93. package/dist/vertex_gemini_integration.js +229 -0
  94. package/dist/vertex_gemini_integration.js.map +1 -0
  95. package/dist/wrap.d.ts +36 -0
  96. package/dist/wrap.d.ts.map +1 -1
  97. package/dist/wrap.js +5 -2
  98. package/dist/wrap.js.map +1 -1
  99. package/package.json +36 -3
@@ -0,0 +1,59 @@
1
+ /**
2
+ * Vectara HHEM (Hughes Hallucination Evaluation Model) helper
3
+ * (Mesedi #14, Wave 1.3).
4
+ *
5
+ * Vectara HHEM
6
+ * (https://huggingface.co/vectara/hallucination_evaluation_model)
7
+ * is a small open-source model that detects hallucinations in RAG
8
+ * agent outputs. Customers running HHEM against their answers can
9
+ * use this helper to report scores into Mesedi without hand-writing
10
+ * the boilerplate around {@link emitEvalScore}.
11
+ *
12
+ * IMPORTANT — direction note. HHEM scores have INVERTED semantics
13
+ * compared to Ragas / Promptfoo metrics: HIGHER means MORE faithful
14
+ * to context (less hallucination). The helper passes
15
+ * `higherIsBetter: true` to the backend and the parameter is named
16
+ * `faithfulnessScore` to mirror HHEM's documented output. Some HHEM
17
+ * consumers transform the output into a "hallucination_score" where
18
+ * LOWER is better — if your pipeline does that transformation,
19
+ * invert your value before calling this helper (i.e. pass
20
+ * `1 - hallucinationScore`).
21
+ *
22
+ * Report-only design: Mesedi does NOT import the vectara /
23
+ * transformers packages as dependencies. The customer runs HHEM on
24
+ * their side; this helper accepts the resulting score and emits a
25
+ * correctly-shaped `eval_score` event.
26
+ *
27
+ * Typical usage:
28
+ *
29
+ * import { wrap } from "mesedi";
30
+ * import { reportHhem } from "mesedi/integrations/vectara";
31
+ *
32
+ * export const myAgent = wrap(async (question: string) => {
33
+ * const { answer, contexts } = await runRag(question);
34
+ * const hhemScore = await runHhem(answer, contexts); // 0-1, higher = better
35
+ * reportHhem(hhemScore, { threshold: 0.5 });
36
+ * return answer;
37
+ * });
38
+ */
39
+ import { emitEvalScore } from "../observe.js";
40
+ /**
41
+ * Report a Vectara HHEM faithfulness score.
42
+ *
43
+ * HHEM produces a faithfulness probability in [0, 1]; HIGHER means
44
+ * more faithful to the retrieved context (i.e. LESS hallucinated).
45
+ * Read the module docstring for direction-sensitivity notes.
46
+ *
47
+ * @param faithfulnessScore HHEM's faithfulness probability in [0, 1].
48
+ * HIGHER is better.
49
+ * @param opts Threshold + reason.
50
+ */
51
+ export function reportHhem(faithfulnessScore, opts = {}) {
52
+ const threshold = opts.threshold ?? 0.5;
53
+ emitEvalScore("vectara/hhem", "hallucination", faithfulnessScore, faithfulnessScore >= threshold, {
54
+ threshold,
55
+ higherIsBetter: true,
56
+ reason: opts.reason,
57
+ });
58
+ }
59
+ //# sourceMappingURL=vectara.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"vectara.js","sourceRoot":"","sources":["../../src/integrations/vectara.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAY9C;;;;;;;;;;GAUG;AACH,MAAM,UAAU,UAAU,CACxB,iBAAyB,EACzB,OAA6B,EAAE;IAE/B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAC;IACxC,aAAa,CACX,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,iBAAiB,IAAI,SAAS,EAC9B;QACE,SAAS;QACT,cAAc,EAAE,IAAI;QACpB,MAAM,EAAE,IAAI,CAAC,MAAM;KACpB,CACF,CAAC;AACJ,CAAC"}
package/dist/observe.d.ts CHANGED
@@ -34,6 +34,18 @@ export type ValidatorSeverity = "warning" | "error" | "critical";
34
34
  export interface ValidatorResultOptions {
35
35
  message?: string;
36
36
  severity?: ValidatorSeverity;
37
+ /**
38
+ * Optional sub-classification of WHY the validator failed (e.g.
39
+ * "schema_mismatch", "hallucination", "missing_required_field").
40
+ * Granular-signature wave: when supplied, the backend concatenates
41
+ * it into the failure_group signature as "<name>:<category>" so a
42
+ * single `quality_check` validator failing for 50 different reasons
43
+ * surfaces as 50 clusters instead of one impossibly-coarse cluster.
44
+ * Truncated to 80 chars client-side + control characters stripped
45
+ * backend-side. Backward-compat: omitting `category` (the default)
46
+ * preserves the original "<name>"-only signature shape.
47
+ */
48
+ category?: string;
37
49
  }
38
50
  /**
39
51
  * Report a validator outcome as a `validator_result` event.
@@ -47,4 +59,347 @@ export interface ValidatorResultOptions {
47
59
  * Outside `wrap()`: silent no-op.
48
60
  */
49
61
  export declare function validatorResult(name: string, passed: boolean, opts?: ValidatorResultOptions): void;
62
+ /**
63
+ * Options for emitInfrastructureEvent. Mirrors the Go
64
+ * InfrastructureEventPayload struct in
65
+ * backend/internal/events/types.go field-for-field, omitting `reason`
66
+ * which is the positional first arg of the emitter.
67
+ */
68
+ export interface InfrastructureEventOptions {
69
+ /** Short provider identifier ("anthropic", "openai", "google"...). */
70
+ provider?: string;
71
+ /** Provider URL path that triggered the event. */
72
+ endpoint?: string;
73
+ /** HTTP status returned (429, 503...). */
74
+ statusCode?: number;
75
+ /** Server-suggested backoff window in ms (from Retry-After). */
76
+ retryAfterMs?: number;
77
+ /** Calls / tokens still available, from x-ratelimit-remaining. */
78
+ quotaRemaining?: number;
79
+ /** Maximum on this quota, from x-ratelimit-limit. */
80
+ quotaLimit?: number;
81
+ /**
82
+ * Stable string identifier for the quota dimension that breached
83
+ * ("tokens_per_minute", "requests_per_second", etc.). Used as a
84
+ * signature dimension by the backend's infrastructure_throttled
85
+ * detector.
86
+ */
87
+ quotaDimension?: string;
88
+ /** How long the caller actually waited before retrying. */
89
+ backoffAppliedMs?: number;
90
+ /**
91
+ * When reason="circuit_breaker", one of "open" / "half_open" /
92
+ * "closed". Empty defaults to "open" in the backend signature
93
+ * assembly.
94
+ */
95
+ circuitState?: string;
96
+ }
97
+ /**
98
+ * Reason codes recognized by ThrottlingSignature on the backend.
99
+ * Other strings are accepted (they cluster as "<reason>:<provider>")
100
+ * so SDKs can emit forward-compatible reasons before the detector
101
+ * adds explicit support.
102
+ */
103
+ export type InfrastructureReason = "rate_limit" | "circuit_breaker" | "quota_exhausted" | (string & {});
104
+ /**
105
+ * If the canonical error_class is a throttling signal, emit an
106
+ * infrastructure_event alongside the failed llm_call so the backend's
107
+ * infrastructure_throttled detector picks up the per-tenant
108
+ * backpressure pattern. No-op for non-throttling errors. Internal
109
+ * helper used by the four instrument_* modules (anthropic, openai,
110
+ * cohere, gemini) so the throttling-class filter and reason mapping
111
+ * live in one place.
112
+ */
113
+ export declare function _maybeEmitThrottlingEvent(args: {
114
+ provider: string;
115
+ errorClass: string;
116
+ httpStatus?: number;
117
+ retryAfterSeconds?: number;
118
+ endpoint?: string;
119
+ quotaDimension?: string;
120
+ }): void;
121
+ /**
122
+ * Emit an `infrastructure_event` for transport-plane backpressure.
123
+ *
124
+ * Used when the SDK or caller observes an HTTP 429, hits a provider
125
+ * quota header, trips a local circuit breaker, or otherwise gets a
126
+ * signal from the network plane that the agent's logic is fine but
127
+ * the underlying infrastructure is pushing back. The Mesedi backend's
128
+ * `infrastructure_throttled` detector consumes these events and
129
+ * clusters them by (reason, provider, quota_dimension) so SRE teams
130
+ * get a single page per affected provider instead of one page per
131
+ * request.
132
+ *
133
+ * Typical caller pattern (Vercel AI SDK / OpenAI / Anthropic):
134
+ *
135
+ * try {
136
+ * const res = await fetch(endpoint, { method: "POST", body });
137
+ * if (res.status === 429) {
138
+ * emitInfrastructureEvent("rate_limit", {
139
+ * provider: "anthropic",
140
+ * endpoint: "/v1/messages",
141
+ * statusCode: 429,
142
+ * retryAfterMs: Number(
143
+ * res.headers.get("retry-after-ms") ?? 0,
144
+ * ),
145
+ * quotaDimension: "tokens_per_minute",
146
+ * quotaRemaining: Number(
147
+ * res.headers.get("x-ratelimit-remaining") ?? 0,
148
+ * ),
149
+ * });
150
+ * }
151
+ * } catch (err) {
152
+ * // ...
153
+ * }
154
+ *
155
+ * Outside `wrap()`: silent no-op. Mirrors the fail-open pattern of
156
+ * every other observe-layer primitive. The SDK does NOT retry on
157
+ * its own; emitting this event is purely observational.
158
+ */
159
+ export declare function emitInfrastructureEvent(reason: InfrastructureReason, opts?: InfrastructureEventOptions): void;
160
+ /**
161
+ * Options for emitMcpCall. Mirrors the Go MCPCallPayload struct in
162
+ * backend/internal/events/types.go field-for-field, omitting
163
+ * `serverName` and `method` which are positional args.
164
+ */
165
+ export interface McpCallOptions {
166
+ /** Optional server URL or stdio target for the expanded view. */
167
+ serverUrl?: string;
168
+ /** Method arguments (any JSON-serializable value). */
169
+ arguments?: unknown;
170
+ /** Successful return value; omit on error. */
171
+ returnValue?: unknown;
172
+ /** Wall-clock duration in milliseconds. */
173
+ latencyMs?: number;
174
+ /** Error message when the call failed. */
175
+ error?: string;
176
+ /** Failure classifier: "hard_error" / "soft_error" / "timeout" / "server_unreachable" / "method_not_found". */
177
+ errorClass?: string;
178
+ }
179
+ /**
180
+ * Emit an `mcp_call` event for one Model Context Protocol server
181
+ * invocation.
182
+ *
183
+ * Use this when your agent talks to an MCP server (Anthropic's
184
+ * filesystem / github servers, a customer-hosted MCP server, etc.).
185
+ * The dashboard renders MCP calls in a distinct chip so cost
186
+ * attribution can break down by server identity, and the existing
187
+ * tool_failures detector picks up failed MCP calls when `error` or
188
+ * `errorClass` is non-empty.
189
+ *
190
+ * Outside `wrap()`: silent no-op.
191
+ */
192
+ export declare function emitMcpCall(serverName: string, method: string, opts?: McpCallOptions): void;
193
+ /** Options for emitEvalScore beyond the required core fields. */
194
+ export interface EvalScoreOptions {
195
+ /** Optional cutoff value the evaluator used. */
196
+ threshold?: number;
197
+ /**
198
+ * True for faithfulness / relevance / correctness; false for
199
+ * inverse metrics like hallucination_rate. Default true.
200
+ */
201
+ higherIsBetter?: boolean;
202
+ /** Optional explanation the evaluator returned. */
203
+ reason?: string;
204
+ /** Optional [0, 1] self-confidence the evaluator reports. */
205
+ confidence?: number;
206
+ }
207
+ /**
208
+ * Emit an `eval_score` event recording one external evaluator
209
+ * verdict on an execution's output.
210
+ *
211
+ * Use this when you run Ragas, Promptfoo, Vectara HHEM, or a custom
212
+ * judge against an execution's output and want Mesedi to track the
213
+ * score over time. Mesedi #14 aggregates these into
214
+ * grounding_failure clusters when scores trend below threshold.
215
+ *
216
+ * Outside `wrap()`: silent no-op.
217
+ */
218
+ export declare function emitEvalScore(evaluatorId: string, metricType: string, score: number, passed: boolean, opts?: EvalScoreOptions): void;
219
+ /** Options for emitMemoryOperation. */
220
+ export interface MemoryOperationOptions {
221
+ storeType?: string;
222
+ storeName?: string;
223
+ query?: string;
224
+ documentCount?: number;
225
+ tokenCount?: number;
226
+ topScore?: number;
227
+ latencyMs?: number;
228
+ cacheHit?: boolean;
229
+ error?: string;
230
+ errorClass?: string;
231
+ }
232
+ /**
233
+ * Emit a `memory_operation` event for one external memory store
234
+ * read / write / search.
235
+ */
236
+ export declare function emitMemoryOperation(operation: "read" | "write" | "search" | "delete" | (string & {}), opts?: MemoryOperationOptions): void;
237
+ /**
238
+ * Options for {@link emitAgentHandoff}.
239
+ *
240
+ * Mesedi #11. Use this at the moment one agent invokes another
241
+ * (supervisor/worker, plan/execute, role-based router). The
242
+ * downstream cascading_failure detector (#12) joins this event
243
+ * back to the topology graph (#10) so that a handoff whose child
244
+ * execution crashes within a short window can be surfaced as
245
+ * one logical failure rather than two unrelated ones.
246
+ *
247
+ * Well-known handoffKind values:
248
+ *
249
+ * - "delegate" one-shot, expects a return value
250
+ * - "spawn" fire-and-forget background sub-agent
251
+ * - "transfer" control transferred (no return)
252
+ * - "consult" short Q&A, return text only
253
+ */
254
+ export interface AgentHandoffOptions {
255
+ handoffKind?: "delegate" | "spawn" | "transfer" | "consult" | (string & {});
256
+ taskSummary?: string;
257
+ childExecutionId?: string;
258
+ latencyMs?: number;
259
+ error?: string;
260
+ errorClass?: string;
261
+ }
262
+ /**
263
+ * Object-form options for the new {@link emitAgentHandoff} overload
264
+ * (Wave 1.2.b). Use this when calling inside a `wrap()` whose
265
+ * `agentName` option supplies the source agent — the `fromAgent`
266
+ * field becomes optional and falls back to the wrapped execution's
267
+ * agent name.
268
+ */
269
+ export interface EmitAgentHandoffArgs extends AgentHandoffOptions {
270
+ fromAgent?: string;
271
+ toAgent: string;
272
+ }
273
+ /**
274
+ * Emit an `agent_handoff` event marking that the current agent
275
+ * delegated work to another agent.
276
+ *
277
+ * Two call shapes (Wave 1.2.b):
278
+ *
279
+ * Positional (original, fully backward-compatible):
280
+ *
281
+ * emitAgentHandoff("planner", "reviewer", { handoffKind: "delegate" });
282
+ *
283
+ * Object-form (new, terser when `wrap({ agentName: "planner" }, ...)`
284
+ * already declared the source agent):
285
+ *
286
+ * emitAgentHandoff({ toAgent: "reviewer", handoffKind: "delegate" });
287
+ *
288
+ * Resolution of the source agent:
289
+ *
290
+ * 1. Explicit `fromAgent` argument wins if supplied (positional or
291
+ * in the object form).
292
+ * 2. Otherwise, the `agentName` set on the active
293
+ * `wrap({ agentName: ... }, fn)` is used.
294
+ * 3. If neither is supplied while inside `wrap()`, this function
295
+ * throws Error rather than silently emitting an `unknown` source
296
+ * agent — polluting the topology graph would degrade
297
+ * cascading_failure / coordination_deadlock clustering at scale.
298
+ *
299
+ * Outside `wrap()` / `runInExecutionContext`: no-op (matches the
300
+ * existing fail-open contract).
301
+ */
302
+ export declare function emitAgentHandoff(args: EmitAgentHandoffArgs): void;
303
+ export declare function emitAgentHandoff(fromAgent: string, toAgent: string, opts?: AgentHandoffOptions): void;
304
+ /**
305
+ * Synchronously transition the current execution to
306
+ * `awaiting_human` (Mesedi #18).
307
+ *
308
+ * Call this from inside a `wrap()`-ed function at the moment the
309
+ * agent reaches a decision that requires a human in the loop. The
310
+ * backend records the pause timestamp, increments pause_count, and
311
+ * starts the HITL clock. A subsequent {@link resumeForAgent} call
312
+ * adds the elapsed time to total_paused_ms so a long HITL wait
313
+ * does not falsely trip the agent's time budget.
314
+ *
315
+ * The host application is responsible for actually blocking the
316
+ * agent until the human responds (typically the wrap()-ed function
317
+ * body itself awaits a queue / websocket / database row). This
318
+ * helper only updates Mesedi's lifecycle state; it does not block.
319
+ *
320
+ * Outside `wrap()`: no-op.
321
+ *
322
+ * Important: this is a SYNCHRONOUS PATCH (await) rather than the
323
+ * asynchronous shipper path that events take. The pause / resume
324
+ * transitions must be committed before the host application
325
+ * suspends the agent, so async-only delivery would race against
326
+ * the human responding.
327
+ */
328
+ export declare function pauseForHuman(): Promise<void>;
329
+ /**
330
+ * Synchronously transition the current execution from
331
+ * `awaiting_human` back to `started` (Mesedi #18).
332
+ *
333
+ * Call this from the host application's HITL response handler the
334
+ * moment the human's decision lands and the agent is about to be
335
+ * unblocked. The backend computes the wait duration and adds it
336
+ * to total_paused_ms so the time-budget detector reads only the
337
+ * agent's actual working time.
338
+ *
339
+ * Outside `wrap()`: no-op.
340
+ */
341
+ export declare function resumeForAgent(): Promise<void>;
342
+ /**
343
+ * Serializable handle to an in-flight HITL request (Mesedi #19).
344
+ *
345
+ * Returned by {@link requestHumanIntervention}. The shape is plain
346
+ * JSON so the host application can stash it in Redis, a database
347
+ * row, a websocket session, or a queue payload while waiting for
348
+ * the human response, then reconstruct a working handle from the
349
+ * stored data via {@link rehydrateHumanInterventionHandle}.
350
+ */
351
+ export interface HumanInterventionHandleData {
352
+ executionId: string;
353
+ requestId: string;
354
+ question: string;
355
+ slaSeconds: number;
356
+ requestedAt: string;
357
+ metadata?: Record<string, unknown>;
358
+ }
359
+ /**
360
+ * Options for completing a HITL request via
361
+ * {@link completeHumanIntervention}.
362
+ *
363
+ * Well-known {@link responseKind} values: `"approved"`, `"rejected"`,
364
+ * `"edited"`, `"timeout"`, `"cancelled"`. Custom strings are
365
+ * accepted but downstream HITL detectors (#20, #21) only recognize
366
+ * the five well-known values.
367
+ */
368
+ export interface CompleteHumanInterventionOptions {
369
+ responseKind: string;
370
+ responsePayload?: Record<string, unknown>;
371
+ decidedBy?: string;
372
+ }
373
+ /**
374
+ * Pause the current execution and return a handle (Mesedi #19).
375
+ *
376
+ * Synchronously transitions the execution into `awaiting_human`
377
+ * and returns a {@link HumanInterventionHandleData} carrying the
378
+ * correlation data needed to complete the cycle later. The host
379
+ * application is responsible for actually waiting on the human
380
+ * response (queue, websocket, DB poll) and then calling
381
+ * {@link completeHumanIntervention} with the answer.
382
+ *
383
+ * Outside `wrap()`: no-op, returns `null`.
384
+ *
385
+ * `slaSeconds` is optional metadata describing the customer's own
386
+ * SLA expectation. The hitl_timeout detector (#20) reads this to
387
+ * fire when the actual wait exceeds the configured SLA. Customers
388
+ * without an explicit SLA can omit it and #20 will fall back to a
389
+ * project-level default.
390
+ */
391
+ export declare function requestHumanIntervention(question: string, options?: {
392
+ slaSeconds?: number;
393
+ metadata?: Record<string, unknown>;
394
+ }): Promise<HumanInterventionHandleData | null>;
395
+ /**
396
+ * Complete a HITL request (Mesedi #19).
397
+ *
398
+ * Emits the `human_intervention` event with the full ask/answer
399
+ * payload, then synchronously transitions the execution from
400
+ * `awaiting_human` back to `started` so the agent code can
401
+ * continue. Idempotent only insofar as a re-call from `started`
402
+ * is a no-op resume (the backend rejects illegal transitions).
403
+ */
404
+ export declare function completeHumanIntervention(handle: HumanInterventionHandleData, opts: CompleteHumanInterventionOptions): Promise<void>;
50
405
  //# sourceMappingURL=observe.d.ts.map
@@ -1 +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"}
1
+ {"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"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"}