@relkit/langchain 0.0.0-stage → 0.7.11

package/dist/runtime-tool-adapter.js

@@ -0,0 +1,66 @@
+/** Adapts RELKIT callable tools to native SDK tools while preserving validated input, execution context and typed invocation failures. */
+import { invokeRegisteredAgentToolEffect } from "./runtime-tool-invocation.js";
+import { currentInvocationScope, runInInvocationScope, } from "@relkit/invocation";
+import { validate } from "@relkit/schema";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { ApprovalDeniedError } from "@relkit/agents/internal/approval";
+import { agentInvocationFailure } from "./runtime-effect-error.js";
+import { AgentRuntimeError } from "./runtime-errors.js";
+import { signalFailure } from "./signal.js";
+import { createAgentInvocationDispatcherEffect } from "./runtime-tool-dispatcher.js";
+import { emitToolEffect, resolveAgentApproval } from "./runtime-tool-events.js";
+export { createAgentInvocationDispatcher, createAgentInvocationDispatcherEffect, } from "./runtime-tool-dispatcher.js";
+/** Invokes an allowed tool with validated input and public lifecycle events.
+ * @param engine - Function tool engine.
+ * @param tool - Registered tool descriptor.
+ * @param turn - Requested tool call.
+ * @param options - Runtime and invocation integrations.
+ * @param signal - Invocation cancellation signal.
+ * @param invocationId - Current invocation identity.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span identity.
+ * @returns An Effect with the tool result or AgentInvocationFailure.
+ * @example await Effect.runPromise(invokeAgentToolEffect(engine, tool, turn, options, signal, id));
+ */
+export const invokeAgentToolEffect = Effect.fn("Agents.runtime.invokeTool")(function* (engine, tool, turn, options, signal, invocationId, traceId, parentSpanId) {
+    if (signal.aborted)
+        return yield* Effect.fail(agentInvocationFailure(signalFailure(signal)));
+    const parsed = yield* Effect.tryPromise({
+        try: () => Promise.resolve(validate(tool.target.input, turn.input)),
+        catch: agentInvocationFailure,
+    });
+    if (!("value" in parsed)) {
+        return yield* Effect.fail(agentInvocationFailure(new AgentRuntimeError("RELKIT_AGENT_INPUT_VALIDATION", "Tool input validation failed")));
+    }
+    yield* emitToolEffect(options, turn, "started", undefined, signal);
+    yield* emitToolEffect(options, turn, "input-ready", parsed.value, signal);
+    const approvalRequired = tool.approval === "always" || (tool.approval === "on-write" && tool.sideEffect === "write");
+    if (!approvalRequired)
+        yield* emitToolEffect(options, turn, "running", undefined, signal);
+    const progressSink = yield* Effect.try({
+        try: () => options.contentSink?.progressSinkForTool?.({
+            toolCallId: turn.callId,
+            toolId: turn.toolId,
+        }),
+        catch: agentInvocationFailure,
+    });
+    return yield* invokeRegisteredAgentToolEffect(engine, tool, turn, options, signal, invocationId, traceId, parentSpanId, progressSink);
+}, (effect) => observeAgent("runtime.invoke-tool", effect));
+/** Invokes an allowed tool for existing Promise callers.
+ * @param engine - Function tool engine.
+ * @param tool - Registered tool descriptor.
+ * @param turn - Requested tool call.
+ * @param options - Runtime and invocation integrations.
+ * @param signal - Invocation cancellation signal.
+ * @param invocationId - Current invocation identity.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span identity.
+ * @returns A Promise of the tool result.
+ * @throws The original validation, sink, approval, or tool error.
+ * @example await invokeAgentTool(engine, tool, turn, options, signal, id);
+ */
+export function invokeAgentTool(engine, tool, turn, options, signal, invocationId, traceId, parentSpanId) {
+    return Effect.runPromise(invokeAgentToolEffect(engine, tool, turn, options, signal, invocationId, traceId, parentSpanId).pipe(Effect.catchTag("AgentInvocationFailure", (failure) => Effect.fail(failure.cause))), { signal });
+}
+//# sourceMappingURL=runtime-tool-adapter.js.map

package/dist/runtime-tool-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-adapter.js","sourceRoot":"","sources":["../src/runtime-tool-adapter.ts"],"names":[],"mappings":"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"}

package/dist/runtime-tool-dispatcher.d.ts

@@ -0,0 +1,32 @@
+/** Dispatches native tool calls to the selected RELKIT tool target and carries approval and execution failures back to the native loop. */
+import { type InvocationDispatchRequest, type InvocationDispatcher } from "@relkit/invocation";
+import type { ToolEngine } from "@relkit/tools";
+import { Effect } from "effect";
+import type { RuntimeToolOptions } from "./runtime-tool-events.types.js";
+/** Creates a nested function dispatcher with stable agent parent context.
+ * @param engine - Function tool engine.
+ * @param options - Runtime invocation options.
+ * @param invocationId - Current agent invocation identity.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns An Effect with a frozen dispatcher and no expected failure.
+ * @example Effect.runSync(createAgentInvocationDispatcherEffect(engine, options, id, trace, span, signal));
+ */
+export declare const createAgentInvocationDispatcherEffect: (engine: ToolEngine, options: RuntimeToolOptions, invocationId: string, traceId: string | undefined, parentSpanId: string | undefined, signal: AbortSignal) => Effect.Effect<Readonly<{
+    dispatch: <Input, Output, Context extends {
+        readonly signal: AbortSignal;
+    }>(request: InvocationDispatchRequest<Input, Output, Context>) => Promise<Output>;
+}>, never, never>;
+/** Creates a nested function dispatcher for existing synchronous callers.
+ * @param engine - Function tool engine.
+ * @param options - Runtime invocation options.
+ * @param invocationId - Current agent invocation identity.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns A frozen dispatcher.
+ * @example createAgentInvocationDispatcher(engine, options, id, trace, span, signal);
+ */
+export declare function createAgentInvocationDispatcher(engine: ToolEngine, options: RuntimeToolOptions, invocationId: string, traceId: string | undefined, parentSpanId: string | undefined, signal: AbortSignal): InvocationDispatcher;
+//# sourceMappingURL=runtime-tool-dispatcher.d.ts.map

package/dist/runtime-tool-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-dispatcher.d.ts","sourceRoot":"","sources":["../src/runtime-tool-dispatcher.ts"],"names":[],"mappings":"AAAA,2IAA2I;AAE3I,OAAO,EAGL,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,UAAU,EAAwB,MAAM,eAAe,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAEzE;;;;;;;;;GASG;AACH,eAAO,MAAM,qCAAqC;eAsB/B,KAAK,EAAE,MAAM,EAAE,OAAO,SAAS;QAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;KAAE,WAC/D,yBAAyB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,KAyBtB,OAAO,CAAC,MAAM,CAAC;iBAK5D,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,+BAA+B,CAC7C,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE,kBAAkB,EAC3B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,MAAM,EAAE,WAAW,GAClB,oBAAoB,CAWtB"}

package/dist/runtime-tool-dispatcher.js

@@ -0,0 +1,67 @@
+/** Dispatches native tool calls to the selected RELKIT tool target and carries approval and execution failures back to the native loop. */
+import { currentExecutionContext, resolveDescriptorIdentity, } from "@relkit/invocation";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+/** Creates a nested function dispatcher with stable agent parent context.
+ * @param engine - Function tool engine.
+ * @param options - Runtime invocation options.
+ * @param invocationId - Current agent invocation identity.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns An Effect with a frozen dispatcher and no expected failure.
+ * @example Effect.runSync(createAgentInvocationDispatcherEffect(engine, options, id, trace, span, signal));
+ */
+export const createAgentInvocationDispatcherEffect = Effect.fn("Agents.runtime.createToolDispatcher")((engine, options, invocationId, traceId, parentSpanId, signal) => Effect.sync(() => {
+    const active = currentExecutionContext();
+    const parent = {
+        id: invocationId,
+        traceId: active?.span.traceId ?? traceId ?? invocationId,
+        signal,
+        ...(active?.span.spanId === undefined && parentSpanId === undefined
+            ? {}
+            : { spanId: active?.span.spanId ?? parentSpanId }),
+    };
+    return Object.freeze({
+        dispatch: (request) => {
+            const target = request.target;
+            const invocation = {
+                functionId: resolveDescriptorIdentity(target).id,
+                input: request.input,
+                source: "tool",
+                inputSchema: target.input,
+                outputSchema: target.output,
+                ...(target.errors === undefined
+                    ? {}
+                    : { errors: target.errors }),
+                ...(request.options?.timeoutMs === undefined
+                    ? {}
+                    : { timeoutMs: request.options.timeoutMs }),
+                signal: request.options?.signal ?? signal,
+                ...(options.hooks === undefined ? {} : { hooks: options.hooks }),
+                ...(request.options?.toolHooks === undefined
+                    ? {}
+                    : { toolHooks: request.options.toolHooks }),
+                ...(request.options?.progressSink === undefined
+                    ? {}
+                    : { progressSink: request.options.progressSink }),
+                parent,
+            };
+            return engine.invoke(invocation);
+        },
+    });
+}), (effect) => observeAgent("runtime.create-tool-dispatcher", effect));
+/** Creates a nested function dispatcher for existing synchronous callers.
+ * @param engine - Function tool engine.
+ * @param options - Runtime invocation options.
+ * @param invocationId - Current agent invocation identity.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns A frozen dispatcher.
+ * @example createAgentInvocationDispatcher(engine, options, id, trace, span, signal);
+ */
+export function createAgentInvocationDispatcher(engine, options, invocationId, traceId, parentSpanId, signal) {
+    return Effect.runSync(createAgentInvocationDispatcherEffect(engine, options, invocationId, traceId, parentSpanId, signal));
+}
+//# sourceMappingURL=runtime-tool-dispatcher.js.map

package/dist/runtime-tool-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-dispatcher.js","sourceRoot":"","sources":["../src/runtime-tool-dispatcher.ts"],"names":[],"mappings":"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"}

package/dist/runtime-tool-events.d.ts

@@ -0,0 +1,49 @@
+/** Publishes tool lifecycle observations for native calls with stable call identity, preserving failure and completion ordering. */
+import type { ToolApprovalRequest } from "@relkit/tools";
+import { Effect } from "effect";
+import type { RuntimeToolOptions } from "./runtime-tool-events.types.js";
+import type { AgentToolCall } from "./runtime-tools.types.js";
+import type { ToolPartState } from "@relkit/agents/internal/state.types";
+/** Emits a public tool transition with linked Effect cancellation.
+ * @param options - Runtime content sink.
+ * @param turn - Tool and call identities.
+ * @param state - Transition state.
+ * @param value - Optional public value.
+ * @param signal - Invocation cancellation signal.
+ * @returns An Effect with void or AgentInvocationFailure.
+ * @example await Effect.runPromise(emitToolEffect(options, turn, "running", undefined, signal));
+ */
+export declare const emitToolEffect: (options: RuntimeToolOptions, turn: Pick<AgentToolCall, "callId" | "toolId">, state: ToolPartState, value: unknown, signal: AbortSignal) => Effect.Effect<undefined, import("./runtime-effect-error.js").AgentInvocationFailure, never>;
+/** Emits a tool transition for existing Promise callers.
+ * @param options - Runtime content sink.
+ * @param turn - Tool and call identities.
+ * @param state - Transition state.
+ * @param value - Optional public value.
+ * @param signal - Invocation cancellation signal.
+ * @returns A Promise that resolves after the sink completes.
+ * @throws The original sink or cancellation error.
+ * @example await emitTool(options, turn, "running", undefined, signal);
+ */
+export declare function emitTool(options: RuntimeToolOptions, turn: Pick<AgentToolCall, "callId" | "toolId">, state: ToolPartState, value: unknown, signal: AbortSignal): Promise<void>;
+/** Resolves tool approval and emits its lifecycle transitions.
+ * @param options - Runtime approval handler and sink.
+ * @param request - Tool approval request.
+ * @param toolCallId - Tool call identity.
+ * @param invocationId - Invocation identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns An Effect with true or AgentInvocationFailure.
+ * @example await Effect.runPromise(resolveAgentApprovalEffect(options, request, callId, id, signal));
+ */
+export declare const resolveAgentApprovalEffect: (options: RuntimeToolOptions, request: import("@relkit/functions").FunctionToolApprovalRequest, toolCallId: string, invocationId: string, signal: AbortSignal) => Effect.Effect<true, import("./runtime-effect-error.js").AgentInvocationFailure, never>;
+/** Resolves approval for existing Promise callers.
+ * @param options - Runtime approval handler and sink.
+ * @param request - Tool approval request.
+ * @param toolCallId - Tool call identity.
+ * @param invocationId - Invocation identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns A Promise of true for an approved call.
+ * @throws The original approval, sink, or cancellation error.
+ * @example await resolveAgentApproval(options, request, callId, id, signal);
+ */
+export declare function resolveAgentApproval(options: RuntimeToolOptions, request: ToolApprovalRequest, toolCallId: string, invocationId: string, signal: AbortSignal): Promise<true>;
+//# sourceMappingURL=runtime-tool-events.d.ts.map

package/dist/runtime-tool-events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-events.d.ts","sourceRoot":"","sources":["../src/runtime-tool-events.ts"],"names":[],"mappings":"AAAA,oIAAoI;AAIpI,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACzD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAUhC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AAEzE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,yOA6B1B,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,kBAAkB,EAC3B,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,QAAQ,GAAG,QAAQ,CAAC,EAC9C,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAOf;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,0PAyDtC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,IAAI,CAAC,CAOf"}

package/dist/runtime-tool-events.js

@@ -0,0 +1,106 @@
+/** Publishes tool lifecycle observations for native calls with stable call identity, preserving failure and completion ordering. */
+import { resolveApprovalDecisionEffect } from "./runtime-approval-decision.js";
+import { frameworkTrace } from "@relkit/invocation";
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+import { approveApprovalEffect, assertApprovalGrantedEffect, createApprovalEffect, denyApprovalEffect, } from "@relkit/agents/internal/approval";
+import { agentInvocationFailure } from "./runtime-effect-error.js";
+import { signalFailure } from "./signal.js";
+/** Emits a public tool transition with linked Effect cancellation.
+ * @param options - Runtime content sink.
+ * @param turn - Tool and call identities.
+ * @param state - Transition state.
+ * @param value - Optional public value.
+ * @param signal - Invocation cancellation signal.
+ * @returns An Effect with void or AgentInvocationFailure.
+ * @example await Effect.runPromise(emitToolEffect(options, turn, "running", undefined, signal));
+ */
+export const emitToolEffect = Effect.fn("Agents.runtime.emitTool")((options, turn, state, value, signal) => Effect.gen(function* () {
+    const emit = options.contentSink?.emitTool;
+    if (emit === undefined)
+        return;
+    if (signal.aborted)
+        return yield* Effect.fail(agentInvocationFailure(signalFailure(signal)));
+    yield* Effect.tryPromise({
+        try: (effectSignal) => Promise.resolve(emit({
+            toolCallId: turn.callId,
+            toolId: turn.toolId,
+            state,
+            ...(value === undefined ? {} : { value }),
+        }, AbortSignal.any([signal, effectSignal]))),
+        catch: agentInvocationFailure,
+    });
+}), (effect) => observeAgent("runtime.emit-tool", effect));
+/** Emits a tool transition for existing Promise callers.
+ * @param options - Runtime content sink.
+ * @param turn - Tool and call identities.
+ * @param state - Transition state.
+ * @param value - Optional public value.
+ * @param signal - Invocation cancellation signal.
+ * @returns A Promise that resolves after the sink completes.
+ * @throws The original sink or cancellation error.
+ * @example await emitTool(options, turn, "running", undefined, signal);
+ */
+export function emitTool(options, turn, state, value, signal) {
+    return Effect.runPromise(emitToolEffect(options, turn, state, value, signal).pipe(Effect.catchTag("AgentInvocationFailure", (failure) => Effect.fail(failure.cause))), { signal });
+}
+/** Resolves tool approval and emits its lifecycle transitions.
+ * @param options - Runtime approval handler and sink.
+ * @param request - Tool approval request.
+ * @param toolCallId - Tool call identity.
+ * @param invocationId - Invocation identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns An Effect with true or AgentInvocationFailure.
+ * @example await Effect.runPromise(resolveAgentApprovalEffect(options, request, callId, id, signal));
+ */
+export const resolveAgentApprovalEffect = Effect.fn("Agents.runtime.resolveApproval")(function* (options, request, toolCallId, invocationId, signal) {
+    if (signal.aborted)
+        return yield* Effect.fail(agentInvocationFailure(signalFailure(signal)));
+    const approval = yield* createApprovalEffect({
+        invocationId,
+        toolCallId,
+        toolId: request.toolId,
+        sideEffect: request.sideEffect,
+        policy: request.policy,
+    }).pipe(Effect.mapError((failure) => agentInvocationFailure(failure.cause)));
+    if (approval.state !== "pending")
+        return true;
+    const turn = { callId: toolCallId, toolId: request.toolId };
+    yield* emitToolEffect(options, turn, "approval-required", undefined, signal);
+    yield* Effect.sync(() => frameworkTrace.event("agent.tool.approval.requested", {
+        "relkit.tool.id": request.toolId,
+        "relkit.tool.call.id": toolCallId,
+    }));
+    const handler = options.approval;
+    if (handler === undefined) {
+        yield* assertApprovalGrantedEffect(approval).pipe(Effect.mapError((failure) => agentInvocationFailure(failure.cause)));
+        return true;
+    }
+    const response = yield* Effect.tryPromise({
+        try: () => Promise.resolve(handler(approval)),
+        catch: agentInvocationFailure,
+    });
+    const decision = yield* resolveApprovalDecisionEffect(approval, response);
+    yield* Effect.sync(() => frameworkTrace.event("agent.tool.approval.resolved", {
+        "relkit.tool.id": request.toolId,
+        "relkit.tool.call.id": toolCallId,
+        "relkit.tool.approval": decision.state,
+    }));
+    yield* emitToolEffect(options, turn, decision.state === "approved" ? "running" : "denied", undefined, signal);
+    yield* assertApprovalGrantedEffect(decision).pipe(Effect.mapError((failure) => agentInvocationFailure(failure.cause)));
+    return true;
+}, (effect) => observeAgent("runtime.resolve-approval", effect));
+/** Resolves approval for existing Promise callers.
+ * @param options - Runtime approval handler and sink.
+ * @param request - Tool approval request.
+ * @param toolCallId - Tool call identity.
+ * @param invocationId - Invocation identity.
+ * @param signal - Invocation cancellation signal.
+ * @returns A Promise of true for an approved call.
+ * @throws The original approval, sink, or cancellation error.
+ * @example await resolveAgentApproval(options, request, callId, id, signal);
+ */
+export function resolveAgentApproval(options, request, toolCallId, invocationId, signal) {
+    return Effect.runPromise(resolveAgentApprovalEffect(options, request, toolCallId, invocationId, signal).pipe(Effect.catchTag("AgentInvocationFailure", (failure) => Effect.fail(failure.cause))), { signal });
+}
+//# sourceMappingURL=runtime-tool-events.js.map

package/dist/runtime-tool-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-events.js","sourceRoot":"","sources":["../src/runtime-tool-events.ts"],"names":[],"mappings":"AAAA,oIAAoI;AAEpI,OAAO,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AACvE,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,MAAM,CAAC,EAAE,CAAC,yBAAyB,CAAC,CAChE,CACE,OAA2B,EAC3B,IAA8C,EAC9C,KAAoB,EACpB,KAAc,EACd,MAAmB,EACnB,EAAE,CACF,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,EAAE,QAAQ,CAAC;IAC3C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7F,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;QACvB,GAAG,EAAE,CAAC,YAAY,EAAE,EAAE,CACpB,OAAO,CAAC,OAAO,CACb,IAAI,CACF;YACE,UAAU,EAAE,IAAI,CAAC,MAAM;YACvB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,KAAK;YACL,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;SAC1C,EACD,WAAW,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CACxC,CACF;QACH,KAAK,EAAE,sBAAsB;KAC9B,CAAC,CAAC;AACL,CAAC,CAAC,EACJ,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,mBAAmB,EAAE,MAAM,CAAC,CACtD,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,QAAQ,CACtB,OAA2B,EAC3B,IAA8C,EAC9C,KAAoB,EACpB,KAAc,EACd,MAAmB;IAEnB,OAAO,MAAM,CAAC,UAAU,CACtB,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,IAAI,CACtD,MAAM,CAAC,QAAQ,CAAC,wBAAwB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CACnF,EACD,EAAE,MAAM,EAAE,CACX,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC,EAAE,CAAC,gCAAgC,CAAC,CACnF,QAAQ,CAAC,EACP,OAA2B,EAC3B,OAA4B,EAC5B,UAAkB,EAClB,YAAoB,EACpB,MAAmB;IAEnB,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC7F,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,oBAAoB,CAAC;QAC3C,YAAY;QACZ,UAAU;QACV,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,sBAAsB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7E,IAAI,QAAQ,CAAC,KAAK,KAAK,SAAS;QAAE,OAAO,IAAa,CAAC;IACvD,MAAM,IAAI,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;IAC5D,KAAK,CAAC,CAAC,cAAc,CAAC,OAAO,EAAE,IAAI,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IAC7E,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CACtB,cAAc,CAAC,KAAK,CAAC,+BAA+B,EAAE;QACpD,gBAAgB,EAAE,OAAO,CAAC,MAAM;QAChC,qBAAqB,EAAE,UAAU;KAClC,CAAC,CACH,CAAC;IACF,MAAM,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC;IACjC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,KAAK,CAAC,CAAC,2BAA2B,CAAC,QAAQ,CAAC,CAAC,IAAI,CAC/C,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,sBAAsB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CACpE,CAAC;QACF,OAAO,IAAa,CAAC;IACvB,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC;QACxC,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7C,KAAK,EAAE,sBAAsB;KAC9B,CAAC,CAAC;IACH,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,6BAA6B,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC1E,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,CACtB,cAAc,CAAC,KAAK,CAAC,8BAA8B,EAAE;QACnD,gBAAgB,EAAE,OAAO,CAAC,MAAM;QAChC,qBAAqB,EAAE,UAAU;QACjC,sBAAsB,EAAE,QAAQ,CAAC,KAAK;KACvC,CAAC,CACH,CAAC;IACF,KAAK,CAAC,CAAC,cAAc,CACnB,OAAO,EACP,IAAI,EACJ,QAAQ,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EACpD,SAAS,EACT,MAAM,CACP,CAAC;IACF,KAAK,CAAC,CAAC,2BAA2B,CAAC,QAAQ,CAAC,CAAC,IAAI,CAC/C,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,sBAAsB,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CACpE,CAAC;IACF,OAAO,IAAa,CAAC;AACvB,CAAC,EACD,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,0BAA0B,EAAE,MAAM,CAAC,CAC7D,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAA2B,EAC3B,OAA4B,EAC5B,UAAkB,EAClB,YAAoB,EACpB,MAAmB;IAEnB,OAAO,MAAM,CAAC,UAAU,CACtB,0BAA0B,CAAC,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC,IAAI,CACjF,MAAM,CAAC,QAAQ,CAAC,wBAAwB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CACnF,EACD,EAAE,MAAM,EAAE,CACX,CAAC;AACJ,CAAC"}

package/dist/runtime-tool-events.types.d.ts

@@ -0,0 +1,8 @@
+/** Publishes tool lifecycle observations for native calls with stable call identity, preserving failure and completion ordering. This companion preserves the native input and output types without starting runtime work. */
+import type { AgentInvocationOptions, AgentRuntimeOptions } from "./runtime.types.js";
+/** Runtime integrations needed to emit tool events and resolve approval.
+ * The invocation options supply the approval callback and content sink.
+ * @example const options: RuntimeToolOptions = { ...runtime, input };
+ */
+export type RuntimeToolOptions = AgentRuntimeOptions & AgentInvocationOptions;
+//# sourceMappingURL=runtime-tool-events.types.d.ts.map

package/dist/runtime-tool-events.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-events.types.d.ts","sourceRoot":"","sources":["../src/runtime-tool-events.types.ts"],"names":[],"mappings":"AAAA,8NAA8N;AAE9N,OAAO,KAAK,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAEtF;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,sBAAsB,CAAC"}

package/dist/runtime-tool-events.types.js

@@ -0,0 +1,3 @@
+/** Publishes tool lifecycle observations for native calls with stable call identity, preserving failure and completion ordering. This companion preserves the native input and output types without starting runtime work. */
+export {};
+//# sourceMappingURL=runtime-tool-events.types.js.map

package/dist/runtime-tool-events.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-events.types.js","sourceRoot":"","sources":["../src/runtime-tool-events.types.ts"],"names":[],"mappings":"AAAA,8NAA8N"}

package/dist/runtime-tool-invocation.d.ts

@@ -0,0 +1,19 @@
+import type { ToolDescriptor, ToolEngine } from "@relkit/tools";
+import { Effect } from "effect";
+import { type AgentInvocationFailure } from "./runtime-effect-error.js";
+import type { RuntimeToolOptions } from "./runtime-tool-events.types.js";
+import type { AgentToolCall } from "./runtime-tools.types.js";
+/** Dispatches a checked tool inside its existing call scope.
+ * @param engine - Common function engine.
+ * @param tool - Validated descriptor.
+ * @param turn - Tool-call identity.
+ * @param options - Runtime callbacks and approval policy.
+ * @param signal - Linked caller cancellation.
+ * @param invocationId - Current invocation.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span.
+ * @param progressSink - Tool-scoped progress destination.
+ * @returns Validated result or the original invocation failure.
+ */
+export declare const invokeRegisteredAgentToolEffect: (engine: ToolEngine, tool: ToolDescriptor<string>, turn: AgentToolCall, options: RuntimeToolOptions, signal: AbortSignal, invocationId: string, traceId: string | undefined, parentSpanId: string | undefined, progressSink: import("@relkit/invocation").ProgressSink | undefined) => Effect.Effect<unknown, AgentInvocationFailure, never>;
+//# sourceMappingURL=runtime-tool-invocation.d.ts.map

package/dist/runtime-tool-invocation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-invocation.d.ts","sourceRoot":"","sources":["../src/runtime-tool-invocation.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAwB,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAEhC,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAGhG,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAE9D;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,+BAA+B,8UA6D3C,CAAC"}

package/dist/runtime-tool-invocation.js

@@ -0,0 +1,74 @@
+/**
+ * Executes a validated tool in the original invocation scope and emits terminal
+ * lifecycle records without changing approval or progress routing.
+ */
+import { currentInvocationScope, runInInvocationScope, } from "@relkit/invocation";
+import { Effect } from "effect";
+import { ApprovalDeniedError } from "@relkit/agents/internal/approval";
+import { agentInvocationFailure } from "./runtime-effect-error.js";
+import { createAgentInvocationDispatcherEffect } from "./runtime-tool-dispatcher.js";
+import { emitToolEffect, resolveAgentApproval } from "./runtime-tool-events.js";
+/** Dispatches a checked tool inside its existing call scope.
+ * @param engine - Common function engine.
+ * @param tool - Validated descriptor.
+ * @param turn - Tool-call identity.
+ * @param options - Runtime callbacks and approval policy.
+ * @param signal - Linked caller cancellation.
+ * @param invocationId - Current invocation.
+ * @param traceId - Optional trace identity.
+ * @param parentSpanId - Optional parent span.
+ * @param progressSink - Tool-scoped progress destination.
+ * @returns Validated result or the original invocation failure.
+ */
+export const invokeRegisteredAgentToolEffect = Effect.fn("Agents.runtime.dispatchTool")(function* (engine, tool, turn, options, signal, invocationId, traceId, parentSpanId, progressSink) {
+    const current = yield* Effect.sync(() => currentInvocationScope());
+    const baseDispatcher = current?.dispatcher ??
+        (yield* createAgentInvocationDispatcherEffect(engine, options, invocationId, traceId, parentSpanId, signal));
+    const dispatcher = progressSink === undefined ? baseDispatcher : withProgressSink(baseDispatcher, progressSink);
+    const result = yield* Effect.tryPromise({
+        try: (effectSignal) => {
+            const combined = AbortSignal.any([signal, effectSignal]);
+            return Promise.resolve(runInInvocationScope(current === undefined
+                ? {
+                    dispatcher,
+                    parent: {
+                        id: invocationId,
+                        traceId: traceId ?? invocationId,
+                        signal: combined,
+                        ...(parentSpanId === undefined ? {} : { spanId: parentSpanId }),
+                    },
+                }
+                : { ...current, dispatcher }, () => tool.invoke(turn.input, {
+                signal: combined,
+                approval: (request) => resolveAgentApproval(options, request, turn.callId, invocationId, combined),
+            })));
+        },
+        catch: agentInvocationFailure,
+    });
+    yield* emitToolEffect(options, turn, "succeeded", result, signal);
+    return result;
+}, (effect, _engine, _tool, turn, options, signal) => effect.pipe(Effect.catchTag("AgentInvocationFailure", (failure) => emitToolFailure(options, turn, signal, failure))));
+/** Reports terminal state before propagating the unchanged failure.
+ * @param options - Content sink.
+ * @param turn - Tool-call identity.
+ * @param signal - Invocation signal.
+ * @param failure - Original tagged failure.
+ * @returns The original failure after best-effort terminal reporting.
+ */
+function emitToolFailure(options, turn, signal, failure) {
+    return Effect.gen(function* () {
+        const state = failure.cause instanceof ApprovalDeniedError ? "denied" : "failed";
+        yield* emitToolEffect(options, turn, state, undefined, signal).pipe(Effect.catchTag("AgentInvocationFailure", () => Effect.void));
+        return yield* Effect.fail(failure);
+    });
+}
+function withProgressSink(dispatcher, progressSink) {
+    const scoped = {
+        dispatch: (request) => dispatcher.dispatch({
+            ...request,
+            options: { ...request.options, progressSink },
+        }),
+    };
+    return Object.freeze(scoped);
+}
+//# sourceMappingURL=runtime-tool-invocation.js.map

package/dist/runtime-tool-invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-invocation.js","sourceRoot":"","sources":["../src/runtime-tool-invocation.ts"],"names":[],"mappings":"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"}

package/dist/runtime-tool-lookup.d.ts

@@ -0,0 +1,56 @@
+/** Resolves authored RELKIT tool references against the invocation tool registry before native tool construction. */
+import type { ToolDescriptor, ToolSource } from "@relkit/tools";
+import { Effect } from "effect";
+/** Produces a bounded model-facing name for one tool ID.
+ * @param id - RELKIT tool ID.
+ * @param index - Tool position.
+ * @returns An Effect with a stable native name.
+ * @example Effect.runSync(modelToolNameEffect("math.add", 0));
+ */
+export declare const modelToolNameEffect: (id: string, index: number) => Effect.Effect<string, never, never>;
+/** Produces a native tool name for existing synchronous callers.
+ * @param id - RELKIT tool ID.
+ * @param index - Tool position.
+ * @returns Stable native tool name.
+ * @example modelToolName("math.add", 0);
+ */
+export declare function modelToolName(id: string, index: number): string;
+/** Finds a native tool by direct or model-facing name.
+ * @param source - Registered tool source.
+ * @param refs - Declared agent tool references.
+ * @param name - Native tool name.
+ * @returns An Effect with a tool descriptor or undefined.
+ * @example Effect.runSync(findModelToolEffect(tools, refs, "math_add_0"));
+ */
+export declare const findModelToolEffect: (source: ToolSource, refs: readonly {
+    readonly ref: {
+        readonly id: string;
+    };
+}[], name: string) => Effect.Effect<ToolDescriptor<string> | undefined, never, never>;
+/** Finds a native tool for existing synchronous callers.
+ * @param source - Registered tool source.
+ * @param refs - Declared agent tool references.
+ * @param name - Native tool name.
+ * @returns A tool descriptor or undefined.
+ * @example findModelTool(tools, refs, "math_add_0");
+ */
+export declare function findModelTool(source: ToolSource, refs: readonly {
+    readonly ref: {
+        readonly id: string;
+    };
+}[], name: string): ToolDescriptor<string> | undefined;
+/** Finds a registered tool by map key or descriptor ID.
+ * @param source - Registered tool source.
+ * @param id - RELKIT tool ID.
+ * @returns An Effect with a descriptor or undefined.
+ * @example Effect.runSync(findToolEffect(tools, "math.add"));
+ */
+export declare const findToolEffect: (source: ToolSource, id: string) => Effect.Effect<ToolDescriptor<string> | undefined, never, never>;
+/** Finds a tool for existing synchronous callers.
+ * @param source - Registered tool source.
+ * @param id - RELKIT tool ID.
+ * @returns A tool descriptor or undefined.
+ * @example findTool(tools, "math.add");
+ */
+export declare function findTool(source: ToolSource, id: string): ToolDescriptor<string> | undefined;
+//# sourceMappingURL=runtime-tool-lookup.d.ts.map

package/dist/runtime-tool-lookup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-lookup.d.ts","sourceRoot":"","sources":["../src/runtime-tool-lookup.ts"],"names":[],"mappings":"AAAA,qHAAqH;AAErH,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAGhC;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,oEAO/B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;kBACsB;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE;qFAQ5E,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,SAAS;IAAE,QAAQ,CAAC,GAAG,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAAE,EAC1D,IAAI,EAAE,MAAM,GACX,cAAc,CAAC,MAAM,CAAC,GAAG,SAAS,CAEpC;AAED;;;;;GAKG;AACH,eAAO,MAAM,cAAc,qGAG1B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,CAAC,MAAM,CAAC,GAAG,SAAS,CAE3F"}

package/dist/runtime-tool-lookup.js

@@ -0,0 +1,71 @@
+/** Resolves authored RELKIT tool references against the invocation tool registry before native tool construction. */
+import { Effect } from "effect";
+import { observeAgent } from "@relkit/agents/internal/agent-telemetry";
+/** Produces a bounded model-facing name for one tool ID.
+ * @param id - RELKIT tool ID.
+ * @param index - Tool position.
+ * @returns An Effect with a stable native name.
+ * @example Effect.runSync(modelToolNameEffect("math.add", 0));
+ */
+export const modelToolNameEffect = Effect.fn("Agents.runtime.modelToolName")((id, index) => Effect.sync(() => {
+    const suffix = `_${index}`;
+    return `${id.replaceAll(".", "_").slice(0, 64 - suffix.length)}${suffix}`;
+}), (effect) => observeAgent("runtime.model-tool-name", effect));
+/** Produces a native tool name for existing synchronous callers.
+ * @param id - RELKIT tool ID.
+ * @param index - Tool position.
+ * @returns Stable native tool name.
+ * @example modelToolName("math.add", 0);
+ */
+export function modelToolName(id, index) {
+    return Effect.runSync(modelToolNameEffect(id, index));
+}
+/** Finds a native tool by direct or model-facing name.
+ * @param source - Registered tool source.
+ * @param refs - Declared agent tool references.
+ * @param name - Native tool name.
+ * @returns An Effect with a tool descriptor or undefined.
+ * @example Effect.runSync(findModelToolEffect(tools, refs, "math_add_0"));
+ */
+export const findModelToolEffect = Effect.fn("Agents.runtime.findModelTool")((source, refs, name) => Effect.sync(() => {
+    const direct = findToolCore(source, name);
+    if (direct !== undefined)
+        return direct;
+    const ref = refs.find((entry, index) => modelToolName(entry.ref.id, index) === name);
+    return ref === undefined ? undefined : findToolCore(source, ref.ref.id);
+}), (effect) => observeAgent("runtime.find-model-tool", effect));
+/** Finds a native tool for existing synchronous callers.
+ * @param source - Registered tool source.
+ * @param refs - Declared agent tool references.
+ * @param name - Native tool name.
+ * @returns A tool descriptor or undefined.
+ * @example findModelTool(tools, refs, "math_add_0");
+ */
+export function findModelTool(source, refs, name) {
+    return Effect.runSync(findModelToolEffect(source, refs, name));
+}
+/** Finds a registered tool by map key or descriptor ID.
+ * @param source - Registered tool source.
+ * @param id - RELKIT tool ID.
+ * @returns An Effect with a descriptor or undefined.
+ * @example Effect.runSync(findToolEffect(tools, "math.add"));
+ */
+export const findToolEffect = Effect.fn("Agents.runtime.findTool")((source, id) => Effect.sync(() => findToolCore(source, id)), (effect) => observeAgent("runtime.find-tool", effect));
+/** Finds a tool for existing synchronous callers.
+ * @param source - Registered tool source.
+ * @param id - RELKIT tool ID.
+ * @returns A tool descriptor or undefined.
+ * @example findTool(tools, "math.add");
+ */
+export function findTool(source, id) {
+    return Effect.runSync(findToolEffect(source, id));
+}
+function findToolCore(source, id) {
+    if (Array.isArray(source))
+        return source.find((tool) => tool.id === id);
+    if (source instanceof Map)
+        return source.get(id) ?? [...source.values()].find((tool) => tool.id === id);
+    const record = source;
+    return record[id] ?? Object.values(record).find((tool) => tool.id === id);
+}
+//# sourceMappingURL=runtime-tool-lookup.js.map

package/dist/runtime-tool-lookup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-tool-lookup.js","sourceRoot":"","sources":["../src/runtime-tool-lookup.ts"],"names":[],"mappings":"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"}