@mongodb-js/agent-engine-runner-shared 0.11.3

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 (220) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/LICENSE.md +201 -0
  3. package/README.md +29 -0
  4. package/dist/agent_config.d.ts +167 -0
  5. package/dist/agent_config.d.ts.map +1 -0
  6. package/dist/agent_config.js +544 -0
  7. package/dist/call_interrupted.d.ts +12 -0
  8. package/dist/call_interrupted.d.ts.map +1 -0
  9. package/dist/call_interrupted.js +11 -0
  10. package/dist/checkpoint_workspace.d.ts +25 -0
  11. package/dist/checkpoint_workspace.d.ts.map +1 -0
  12. package/dist/checkpoint_workspace.js +44 -0
  13. package/dist/context.d.ts +235 -0
  14. package/dist/context.d.ts.map +1 -0
  15. package/dist/context.js +322 -0
  16. package/dist/db_config.d.ts +28 -0
  17. package/dist/db_config.d.ts.map +1 -0
  18. package/dist/db_config.js +66 -0
  19. package/dist/db_naming.d.ts +54 -0
  20. package/dist/db_naming.d.ts.map +1 -0
  21. package/dist/db_naming.js +94 -0
  22. package/dist/error_reporting.d.ts +67 -0
  23. package/dist/error_reporting.d.ts.map +1 -0
  24. package/dist/error_reporting.js +311 -0
  25. package/dist/generated/workflow/v1/activity_pb.d.ts +342 -0
  26. package/dist/generated/workflow/v1/activity_pb.d.ts.map +1 -0
  27. package/dist/generated/workflow/v1/activity_pb.js +115 -0
  28. package/dist/generated/workflow/v1/common_pb.d.ts +184 -0
  29. package/dist/generated/workflow/v1/common_pb.d.ts.map +1 -0
  30. package/dist/generated/workflow/v1/common_pb.js +86 -0
  31. package/dist/generated/workflow/v1/runtime_pb.d.ts +200 -0
  32. package/dist/generated/workflow/v1/runtime_pb.d.ts.map +1 -0
  33. package/dist/generated/workflow/v1/runtime_pb.js +40 -0
  34. package/dist/generated/workflow/v1/state_pb.d.ts +254 -0
  35. package/dist/generated/workflow/v1/state_pb.d.ts.map +1 -0
  36. package/dist/generated/workflow/v1/state_pb.js +68 -0
  37. package/dist/guardrails_evaluator/core.d.ts +23 -0
  38. package/dist/guardrails_evaluator/core.d.ts.map +1 -0
  39. package/dist/guardrails_evaluator/core.js +122 -0
  40. package/dist/guardrails_evaluator/index.d.ts +10 -0
  41. package/dist/guardrails_evaluator/index.d.ts.map +1 -0
  42. package/dist/guardrails_evaluator/index.js +11 -0
  43. package/dist/guardrails_evaluator/regex.d.ts +20 -0
  44. package/dist/guardrails_evaluator/regex.d.ts.map +1 -0
  45. package/dist/guardrails_evaluator/regex.js +233 -0
  46. package/dist/hooks.d.ts +109 -0
  47. package/dist/hooks.d.ts.map +1 -0
  48. package/dist/hooks.js +216 -0
  49. package/dist/http_path.d.ts +18 -0
  50. package/dist/http_path.d.ts.map +1 -0
  51. package/dist/http_path.js +53 -0
  52. package/dist/index.d.ts +35 -0
  53. package/dist/index.d.ts.map +1 -0
  54. package/dist/index.js +41 -0
  55. package/dist/launcher.d.ts +130 -0
  56. package/dist/launcher.d.ts.map +1 -0
  57. package/dist/launcher.js +325 -0
  58. package/dist/logger.d.ts +96 -0
  59. package/dist/logger.d.ts.map +1 -0
  60. package/dist/logger.js +204 -0
  61. package/dist/mcp_oauth.d.ts +51 -0
  62. package/dist/mcp_oauth.d.ts.map +1 -0
  63. package/dist/mcp_oauth.js +389 -0
  64. package/dist/mcp_oauth_secret.d.ts +21 -0
  65. package/dist/mcp_oauth_secret.d.ts.map +1 -0
  66. package/dist/mcp_oauth_secret.js +122 -0
  67. package/dist/mcp_tools.d.ts +71 -0
  68. package/dist/mcp_tools.d.ts.map +1 -0
  69. package/dist/mcp_tools.js +301 -0
  70. package/dist/memory_appbound.d.ts +42 -0
  71. package/dist/memory_appbound.d.ts.map +1 -0
  72. package/dist/memory_appbound.js +159 -0
  73. package/dist/memory_writer.d.ts +49 -0
  74. package/dist/memory_writer.d.ts.map +1 -0
  75. package/dist/memory_writer.js +171 -0
  76. package/dist/metrics.d.ts +84 -0
  77. package/dist/metrics.d.ts.map +1 -0
  78. package/dist/metrics.js +205 -0
  79. package/dist/models.d.ts +1458 -0
  80. package/dist/models.d.ts.map +1 -0
  81. package/dist/models.js +1726 -0
  82. package/dist/node_logger.d.ts +43 -0
  83. package/dist/node_logger.d.ts.map +1 -0
  84. package/dist/node_logger.js +158 -0
  85. package/dist/owner_callback.d.ts +16 -0
  86. package/dist/owner_callback.d.ts.map +1 -0
  87. package/dist/owner_callback.js +40 -0
  88. package/dist/progress.d.ts +57 -0
  89. package/dist/progress.d.ts.map +1 -0
  90. package/dist/progress.js +140 -0
  91. package/dist/runtime.d.ts +131 -0
  92. package/dist/runtime.d.ts.map +1 -0
  93. package/dist/runtime.js +351 -0
  94. package/dist/secure_llm_proxy.d.ts +115 -0
  95. package/dist/secure_llm_proxy.d.ts.map +1 -0
  96. package/dist/secure_llm_proxy.js +922 -0
  97. package/dist/secure_wrapper.d.ts +332 -0
  98. package/dist/secure_wrapper.d.ts.map +1 -0
  99. package/dist/secure_wrapper.js +1249 -0
  100. package/dist/server/aer.d.ts +61 -0
  101. package/dist/server/aer.d.ts.map +1 -0
  102. package/dist/server/aer.js +1124 -0
  103. package/dist/server/auth.d.ts +56 -0
  104. package/dist/server/auth.d.ts.map +1 -0
  105. package/dist/server/auth.js +132 -0
  106. package/dist/server/base.d.ts +104 -0
  107. package/dist/server/base.d.ts.map +1 -0
  108. package/dist/server/base.js +150 -0
  109. package/dist/server/callInterrupt.d.ts +49 -0
  110. package/dist/server/callInterrupt.d.ts.map +1 -0
  111. package/dist/server/callInterrupt.js +68 -0
  112. package/dist/server/callback_delivery.d.ts +14 -0
  113. package/dist/server/callback_delivery.d.ts.map +1 -0
  114. package/dist/server/callback_delivery.js +141 -0
  115. package/dist/server/chunk_types.d.ts +50 -0
  116. package/dist/server/chunk_types.d.ts.map +1 -0
  117. package/dist/server/chunk_types.js +62 -0
  118. package/dist/server/cors.d.ts +52 -0
  119. package/dist/server/cors.d.ts.map +1 -0
  120. package/dist/server/cors.js +107 -0
  121. package/dist/server/drain.d.ts +169 -0
  122. package/dist/server/drain.d.ts.map +1 -0
  123. package/dist/server/drain.js +455 -0
  124. package/dist/server/function.d.ts +77 -0
  125. package/dist/server/function.d.ts.map +1 -0
  126. package/dist/server/function.js +337 -0
  127. package/dist/server/http_retry.d.ts +37 -0
  128. package/dist/server/http_retry.d.ts.map +1 -0
  129. package/dist/server/http_retry.js +157 -0
  130. package/dist/server/index.d.ts +7 -0
  131. package/dist/server/index.d.ts.map +1 -0
  132. package/dist/server/index.js +5 -0
  133. package/dist/server/metadata.d.ts +50 -0
  134. package/dist/server/metadata.d.ts.map +1 -0
  135. package/dist/server/metadata.js +193 -0
  136. package/dist/server/oe_url.d.ts +36 -0
  137. package/dist/server/oe_url.d.ts.map +1 -0
  138. package/dist/server/oe_url.js +50 -0
  139. package/dist/server/owner_url.d.ts +35 -0
  140. package/dist/server/owner_url.d.ts.map +1 -0
  141. package/dist/server/owner_url.js +146 -0
  142. package/dist/server/query.d.ts +42 -0
  143. package/dist/server/query.d.ts.map +1 -0
  144. package/dist/server/query.js +28 -0
  145. package/dist/server/tool.d.ts +138 -0
  146. package/dist/server/tool.d.ts.map +1 -0
  147. package/dist/server/tool.js +1017 -0
  148. package/dist/span_names.d.ts +21 -0
  149. package/dist/span_names.d.ts.map +1 -0
  150. package/dist/span_names.js +31 -0
  151. package/dist/structured_logging/constants.d.ts +17 -0
  152. package/dist/structured_logging/constants.d.ts.map +1 -0
  153. package/dist/structured_logging/constants.js +71 -0
  154. package/dist/structured_logging/env.d.ts +18 -0
  155. package/dist/structured_logging/env.d.ts.map +1 -0
  156. package/dist/structured_logging/env.js +39 -0
  157. package/dist/structured_logging/install.d.ts +56 -0
  158. package/dist/structured_logging/install.d.ts.map +1 -0
  159. package/dist/structured_logging/install.js +107 -0
  160. package/dist/structured_logging/layout.d.ts +9 -0
  161. package/dist/structured_logging/layout.d.ts.map +1 -0
  162. package/dist/structured_logging/layout.js +144 -0
  163. package/dist/structured_logging/serialize.d.ts +27 -0
  164. package/dist/structured_logging/serialize.d.ts.map +1 -0
  165. package/dist/structured_logging/serialize.js +61 -0
  166. package/dist/structured_logging/stdio_capture.d.ts +59 -0
  167. package/dist/structured_logging/stdio_capture.d.ts.map +1 -0
  168. package/dist/structured_logging/stdio_capture.js +164 -0
  169. package/dist/structured_logging/uncaught.d.ts +14 -0
  170. package/dist/structured_logging/uncaught.d.ts.map +1 -0
  171. package/dist/structured_logging/uncaught.js +58 -0
  172. package/dist/structured_logging.d.ts +48 -0
  173. package/dist/structured_logging.d.ts.map +1 -0
  174. package/dist/structured_logging.js +47 -0
  175. package/dist/tls_client.d.ts +61 -0
  176. package/dist/tls_client.d.ts.map +1 -0
  177. package/dist/tls_client.js +298 -0
  178. package/dist/tool_api_error.d.ts +62 -0
  179. package/dist/tool_api_error.d.ts.map +1 -0
  180. package/dist/tool_api_error.js +399 -0
  181. package/dist/tool_memory_ownership.d.ts +10 -0
  182. package/dist/tool_memory_ownership.d.ts.map +1 -0
  183. package/dist/tool_memory_ownership.js +36 -0
  184. package/dist/toolpod_handlers.d.ts +126 -0
  185. package/dist/toolpod_handlers.d.ts.map +1 -0
  186. package/dist/toolpod_handlers.js +1016 -0
  187. package/dist/tracing/exporters.d.ts +51 -0
  188. package/dist/tracing/exporters.d.ts.map +1 -0
  189. package/dist/tracing/exporters.js +327 -0
  190. package/dist/tracing/index.d.ts +3 -0
  191. package/dist/tracing/index.d.ts.map +1 -0
  192. package/dist/tracing/index.js +2 -0
  193. package/dist/tracing/setup.d.ts +76 -0
  194. package/dist/tracing/setup.d.ts.map +1 -0
  195. package/dist/tracing/setup.js +436 -0
  196. package/dist/utils.d.ts +204 -0
  197. package/dist/utils.d.ts.map +1 -0
  198. package/dist/utils.js +867 -0
  199. package/dist/workflow/activity.d.ts +71 -0
  200. package/dist/workflow/activity.d.ts.map +1 -0
  201. package/dist/workflow/activity.js +357 -0
  202. package/dist/workflow/attempt.d.ts +12 -0
  203. package/dist/workflow/attempt.d.ts.map +1 -0
  204. package/dist/workflow/attempt.js +96 -0
  205. package/dist/workflow/client.d.ts +46 -0
  206. package/dist/workflow/client.d.ts.map +1 -0
  207. package/dist/workflow/client.js +299 -0
  208. package/dist/workflow/context.d.ts +37 -0
  209. package/dist/workflow/context.d.ts.map +1 -0
  210. package/dist/workflow/context.js +350 -0
  211. package/dist/workflow/heartbeat.d.ts +15 -0
  212. package/dist/workflow/heartbeat.d.ts.map +1 -0
  213. package/dist/workflow/heartbeat.js +78 -0
  214. package/dist/workflow/index.d.ts +14 -0
  215. package/dist/workflow/index.d.ts.map +1 -0
  216. package/dist/workflow/index.js +10 -0
  217. package/dist/workflow/memory.d.ts +17 -0
  218. package/dist/workflow/memory.d.ts.map +1 -0
  219. package/dist/workflow/memory.js +184 -0
  220. package/package.json +73 -0
@@ -0,0 +1,332 @@
1
+ /**
2
+ * SecureToolWrapper — routes all tool calls through OE for logging and policy enforcement.
3
+ *
4
+ * Provides:
5
+ * SecureToolWrapper: wraps tool execution calls to route through OE
6
+ * createSecureToolFunction: wraps a tool function with runtime context lookup
7
+ * requestOeApproval / reportOeResult: low-level OE HTTP helpers (exported for SecureLLMProxy)
8
+ * PolicyDeniedException / ToolExecutionError / LLMInvocationError: exception classes
9
+ */
10
+ import { type GuardrailMeta, type ToolExecuteResponse } from "./models.js";
11
+ import { type ToolAPIError } from "./tool_api_error.js";
12
+ import { type DurableMemoryState } from "./workflow/index.js";
13
+ /**
14
+ * Normalized usage shape returned by `extractUsage` / `extractPodUsage`.
15
+ * Mirrors Python's dict-shaped return so downstream consumers can pass these
16
+ * fields straight into `reportOeResult`.
17
+ */
18
+ export interface ExtractedUsage {
19
+ prompt_tokens: number | null;
20
+ completion_tokens: number | null;
21
+ total_tokens: number | null;
22
+ model: string | null;
23
+ }
24
+ /**
25
+ * Extract token usage from an LLM response's `response_metadata`.
26
+ *
27
+ * Handles provider-variant key names:
28
+ * - OpenAI: `response_metadata.usage.{prompt_tokens, completion_tokens, total_tokens}`
29
+ * - Anthropic: `response_metadata.usage.{input_tokens, output_tokens}`
30
+ * - Some providers: `response_metadata.token_usage.{...}`
31
+ *
32
+ * Returns an object with keys `prompt_tokens`, `completion_tokens`,
33
+ * `total_tokens`, `model`. All values may be `null` if unavailable.
34
+ *
35
+ * Mirrors Python's `agent_engine_runner_shared.secure_wrapper.extract_usage` 1:1.
36
+ */
37
+ export declare function extractUsage(response: unknown, fallbackModel?: string | null): ExtractedUsage;
38
+ /**
39
+ * Extract token usage from a tool-pod usage dict into `reportOeResult` kwargs.
40
+ *
41
+ * Uses `!= null` checks instead of truthy `||` so a valid `0` token count is
42
+ * not treated as missing. Computes `total_tokens` when the provider omits it.
43
+ *
44
+ * Mirrors Python's `_extract_pod_usage`. Python keeps the leading underscore
45
+ * as a "private" convention and leaves the function unexported. TS exports
46
+ * this (TS `noUnusedLocals` flags unused module-level functions, and the
47
+ * leading-underscore identifier convention doesn't translate cleanly to TS).
48
+ *
49
+ * @internal — call sites are expected to live inside the agent-engine-runner-shared
50
+ * package or downstream framework SDKs; not part of the stable public API.
51
+ */
52
+ export declare function extractPodUsage(usage: Record<string, unknown> | null | undefined, fallbackModel?: string | null): ExtractedUsage;
53
+ export declare class PolicyDeniedException extends Error {
54
+ readonly reason: string;
55
+ /** Guardrail policy identity when the denial came from a guardrail policy. */
56
+ readonly guardrailMeta: GuardrailMeta | null;
57
+ constructor(reason: string, guardrailMeta?: GuardrailMeta | null, options?: ErrorOptions);
58
+ }
59
+ /** Raised when tool execution fails. */
60
+ export declare class ToolExecutionError extends Error {
61
+ readonly error: string;
62
+ constructor(error: string, options?: ErrorOptions);
63
+ }
64
+ export declare class TerminalExecutionError extends ToolExecutionError {
65
+ constructor(error: string, options?: ErrorOptions);
66
+ }
67
+ export declare function raiseForOeRejection(reason: string | null | undefined, guardrailMeta?: GuardrailMeta | null): never;
68
+ /**
69
+ * Raised when a tool call outlives its deadline.
70
+ *
71
+ * Distinct from PolicyDeniedException on purpose. A timeout means the call was
72
+ * permitted and ran — it just ran too long — so reporting it as a denial sends
73
+ * the developer to debug governance instead of their tool.
74
+ */
75
+ export declare class ToolCallTimeoutError extends ToolExecutionError {
76
+ readonly toolName: string;
77
+ readonly timeoutSeconds: number;
78
+ readonly elapsedSeconds: number;
79
+ constructor(toolName: string, timeoutSeconds: number, elapsedSeconds: number, options?: ErrorOptions);
80
+ }
81
+ export declare class ExternalAPICallError extends ToolExecutionError {
82
+ readonly tool_api_error: ToolAPIError;
83
+ constructor(error: string, toolApiError: ToolAPIError, options?: ErrorOptions);
84
+ }
85
+ export declare class LLMInvocationError extends Error {
86
+ readonly error: string;
87
+ /** Invoke-owner attribution. Only `"llm"` means the provider failed. */
88
+ readonly source?: string;
89
+ /**
90
+ * Machine-readable classification the tool pod stamped on the failure
91
+ * (e.g. a provider credential rejection), when it did. Travels to the
92
+ * OE/UI on the ERROR chunk metadata instead of the generic invocation
93
+ * code so consumers can classify without string-matching prose.
94
+ */
95
+ readonly error_code?: string;
96
+ constructor(error: string, options?: ErrorOptions & {
97
+ source?: string;
98
+ error_code?: string;
99
+ });
100
+ }
101
+ export interface RequestOeApprovalArgs {
102
+ oeUrl: string;
103
+ executionId: string;
104
+ toolName: string;
105
+ arguments: Record<string, unknown>;
106
+ step: number;
107
+ kind?: string | null;
108
+ isLocal?: boolean;
109
+ /** Top-level tool argument names to redact from execution logs. */
110
+ redactFields?: readonly string[];
111
+ providerType?: string | null;
112
+ scopes?: readonly string[];
113
+ metadata?: Record<string, unknown>;
114
+ /** Stable LLM tool-call id, forwarded to OE for the execution-log join key. */
115
+ toolCallId?: string;
116
+ /** Caller-provided headers carried only for this active request. */
117
+ customHeaders?: Record<string, string>;
118
+ /**
119
+ * Overall request deadline in milliseconds. Defaults to `getToolReadTimeout()`.
120
+ * The LLM proxy passes a longer value (`LLM_READ_TIMEOUT`) for `invoke_llm`,
121
+ * because OE holds `/tool/execute` open while the LLM call completes — the
122
+ * analog of Python's `httpx.Timeout(get_request_timeout(), read=LLM_READ_TIMEOUT)`.
123
+ */
124
+ timeoutMs?: number;
125
+ }
126
+ /**
127
+ * Request approval from OE before executing a tool/LLM call.
128
+ * Any HTTP or network error becomes PolicyDeniedException — fail-safe.
129
+ */
130
+ export declare function requestOeApproval(args: RequestOeApprovalArgs): Promise<ToolExecuteResponse>;
131
+ /**
132
+ * Repeat the same /tool/execute while OE says the failure is retryable.
133
+ * Reservation-loss returns status=error with retryable=true after releasing
134
+ * the step stamp. Retrying the same step here keeps durable activity from
135
+ * recording FAILED on a call that can still succeed.
136
+ */
137
+ export declare function requestOeApprovalRetryable(args: RequestOeApprovalArgs): Promise<ToolExecuteResponse>;
138
+ export interface ReportOeResultArgs {
139
+ oeUrl: string;
140
+ executionId: string;
141
+ toolName: string;
142
+ step: number;
143
+ toolCallId?: string;
144
+ status: string;
145
+ result?: unknown;
146
+ error?: string | null;
147
+ durationMs: number;
148
+ podName?: string | null;
149
+ promptTokens?: number | null;
150
+ completionTokens?: number | null;
151
+ totalTokens?: number | null;
152
+ model?: string | null;
153
+ kind?: string | null;
154
+ metadata?: Record<string, unknown>;
155
+ /**
156
+ * Validated replica-specific OE owner base URL, already checked against
157
+ * `oeUrl` by the caller. When set, a single owner pre-attempt runs before the
158
+ * service loop and does not consume the service retry budget; the owner is
159
+ * best-effort, so any failure — a transport error OR any non-2xx response —
160
+ * marks the replica unusable and falls through to the trusted `oeUrl` loop.
161
+ * The owner is never retried and an owner response never throws.
162
+ */
163
+ ownerUrl?: string | null;
164
+ /** Called once when the owner pre-attempt fails, before service fallback. */
165
+ onOwnerFailure?: (() => void) | null;
166
+ toolApiError?: ToolAPIError | null;
167
+ }
168
+ /**
169
+ * Report an execution result and require OE to acknowledge settlement.
170
+ *
171
+ * Started as the active span before getCurrentTraceContext() is read below,
172
+ * so the trace_id/span_id put on the wire reflect this span. Without a span
173
+ * here, a slow-to-ack OE (or a retried settlement) is invisible: the
174
+ * surrounding tool-node span just looks slower, with no record of how many
175
+ * attempts happened.
176
+ */
177
+ export declare function reportOeResult(args: ReportOeResultArgs): Promise<void>;
178
+ import { CALL_INTERRUPTED_ARTIFACT_KEY } from "./call_interrupted.js";
179
+ import { type DrainRegistry } from "./server/drain.js";
180
+ export { CALL_INTERRUPTED_ARTIFACT_KEY };
181
+ export declare const INTERRUPTED_CALL_CONTENT = "This call was stopped before completing.";
182
+ /**
183
+ * Process-local operational step_number mint for one AER execution.
184
+ *
185
+ * Shared by SecureToolWrapper and SecureLLMProxy so parallel tools and LLM
186
+ * calls cannot collide under a single AER. Not a multi-OE authority.
187
+ * Node's single-threaded event loop makes a plain counter
188
+ * safe across concurrent async tasks as long as minting stays synchronous
189
+ * before the first await.
190
+ */
191
+ export interface OperationalStepSource {
192
+ next(): number;
193
+ observeAtLeast(n: number): void;
194
+ current(): number;
195
+ }
196
+ export declare class OperationalStepAllocator implements OperationalStepSource {
197
+ private n;
198
+ next(): number;
199
+ observeAtLeast(n: number): void;
200
+ current(): number;
201
+ }
202
+ /**
203
+ * Optional args for {@link SecureToolWrapper.executeTool}, grouped into an
204
+ * object rather than positional parameters so future additions cannot silently
205
+ * shift values with overlapping types into the wrong slot.
206
+ */
207
+ export interface ExecuteToolOptions {
208
+ metadata?: Record<string, unknown> | undefined;
209
+ providerType?: string | null | undefined;
210
+ scopes?: readonly string[] | undefined;
211
+ toolCallId?: string | undefined;
212
+ /**
213
+ * When true, an OE `interrupted` status resolves to the raw `CALL_INTERRUPTED`
214
+ * sentinel instead of `{ interrupted: true }`. Only the LangGraph tool-wrapping
215
+ * path (`createSecureToolFunction`) requests this — it coerces the sentinel
216
+ * into a safe shape immediately, never returning it to the caller.
217
+ */
218
+ rawOnInterrupt?: boolean | undefined;
219
+ /** The tool's `redact_fields` policy, applied to the debug argument dump. */
220
+ redactFields?: readonly string[] | undefined;
221
+ /** Whether OE should return the approved call to this AER. */
222
+ isLocal?: boolean | undefined;
223
+ /** Invoke the registered tool on the current framework stack. */
224
+ localExecutor?: (() => unknown | Promise<unknown>) | undefined;
225
+ /** Identify framework-owned native control-flow errors. */
226
+ isFrameworkControlFlow?: ((error: unknown) => boolean) | undefined;
227
+ /**
228
+ * Declares the tool body honors the per-call stop signal (available to the
229
+ * body via `getCallAbortSignal()`). Opt-in tools answer a per-call Stop
230
+ * with `interrupted` and stop at their next signal checkpoint; tools
231
+ * without it answer `not_cancellable` and run out — Node has no preemptive
232
+ * cancel, so claiming stoppability the body never honors would report
233
+ * Stopped while side effects continue.
234
+ */
235
+ supportsCallInterrupt?: boolean | undefined;
236
+ }
237
+ export declare class SecureToolWrapper {
238
+ readonly oeUrl: string;
239
+ readonly executionId: string;
240
+ readonly customHeaders: Record<string, string>;
241
+ /**
242
+ * Validated replica-specific OE owner base URL, or null. Forwarded
243
+ * to `reportOeResult` for the in-process (local-callback) tool-result path so
244
+ * settlement prefers the owning OE replica.
245
+ */
246
+ readonly oeOwnerUrl: string | null;
247
+ private ownerUrlFailed;
248
+ /** Shared with SecureLLMProxy for this execution (single-AER assumption). */
249
+ readonly operationalSteps: OperationalStepSource;
250
+ durableMemory: DurableMemoryState | null;
251
+ /**
252
+ * Per-execution drain registry, enabling the per-call abort (POST
253
+ * /interrupt/call) for tools this wrapper runs locally; null leaves local
254
+ * calls unaddressable, as before.
255
+ */
256
+ private readonly drainRegistry;
257
+ constructor(oeUrl: string, executionId: string, customHeaders?: Record<string, string>, oeOwnerUrl?: string | null, drainRegistry?: DrainRegistry | null);
258
+ private currentOeOwnerUrl;
259
+ private reportOeOwnerFailure;
260
+ /** Current operational-step watermark for compatibility readers. */
261
+ get stepCounter(): number;
262
+ /** Allocate the next operational step_number for this execution. */
263
+ nextOperationalStep(): number;
264
+ /** Raise the allocator watermark (e.g. from OE latest_step_number). */
265
+ observeOperationalStep(n: number): void;
266
+ close(): Promise<void>;
267
+ /**
268
+ * Execute a tool call through OE.
269
+ *
270
+ * Flow:
271
+ * 1. POST /tool/execute — OE approves or denies
272
+ * 2. OE returns a final outcome or routes the call back in process
273
+ * 3. Wrapper logs the outcome and converts suspend payloads back into framework interrupts
274
+ */
275
+ executeTool(toolName: string, args: Record<string, unknown>, options?: ExecuteToolOptions): Promise<unknown>;
276
+ private executeToolDurably;
277
+ private executeToolActivity;
278
+ private executeToolNative;
279
+ /** Fire the framework HITL interrupt for an OE-confirmed suspend. */
280
+ private handleSuspend;
281
+ }
282
+ export type ToolResponseFormat = "content" | "content_and_artifact";
283
+ /**
284
+ * The subset of the LangChain JS run config a wrapped tool reads. When a tool
285
+ * is invoked with a ToolCall, ToolNode populates `toolCall` (whose `id` is the
286
+ * stable tool-call id) and mirrors the id onto `configurable.tool_call_id`.
287
+ */
288
+ export interface SecureToolRunConfig {
289
+ toolCall?: {
290
+ id?: unknown;
291
+ };
292
+ configurable?: Record<string, unknown>;
293
+ }
294
+ /**
295
+ * Optional args for {@link createSecureToolFunction}, grouped into an object
296
+ * for the same reason as {@link ExecuteToolOptions}.
297
+ */
298
+ export interface CreateSecureToolFunctionOptions {
299
+ metadata?: Record<string, unknown> | undefined;
300
+ providerType?: string | null | undefined;
301
+ scopes?: readonly string[] | undefined;
302
+ /** The wire format the caller's StructuredTool is built with. See {@link coerceContentAndArtifact}. */
303
+ responseFormat?: ToolResponseFormat | undefined;
304
+ /**
305
+ * The tool author's own original format, used only to decide whether a
306
+ * normal result gets shape-matched into a tuple. Defaults to `responseFormat`.
307
+ */
308
+ toolDeclaredFormat?: ToolResponseFormat | undefined;
309
+ /** The tool's `redact_fields` policy, forwarded to the wrapper's debug argument dump. */
310
+ redactFields?: readonly string[] | undefined;
311
+ /** Whether to execute the approved tool on the current AER stack. */
312
+ isLocal?: boolean | undefined;
313
+ /** Identify framework-owned native control-flow errors. */
314
+ isFrameworkControlFlow?: ((error: unknown) => boolean) | undefined;
315
+ /**
316
+ * Declares the tool body honors the per-call stop signal. See
317
+ * {@link ExecuteToolOptions.supportsCallInterrupt}.
318
+ */
319
+ supportsCallInterrupt?: boolean | undefined;
320
+ }
321
+ /**
322
+ * Create a wrapped tool function that routes through SecureToolWrapper.
323
+ *
324
+ * The wrapper is looked up from AsyncLocalStorage context at call time,
325
+ * so the tool can be built before execution context exists.
326
+ *
327
+ * The registered tool must expose an `invoke` method for both approved local
328
+ * execution and the direct-execution debugging path. Direct execution is
329
+ * UNSAFE and only for debugging.
330
+ */
331
+ export declare function createSecureToolFunction(originalTool: unknown, toolName: string, allowDirect?: boolean, options?: CreateSecureToolFunctionOptions): (kwargs?: Record<string, unknown>, config?: SecureToolRunConfig) => Promise<unknown>;
332
+ //# sourceMappingURL=secure_wrapper.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"secure_wrapper.d.ts","sourceRoot":"","sources":["../src/secure_wrapper.ts"],"names":[],"mappings":"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"}