@dogpile/sdk 0.4.0 → 0.6.0

package/src/runtime/shared.ts

@@ -16,6 +16,7 @@ import type {
   TerminationCondition,
   TerminationStopRecord,
   Tier,
+  Trace,
   TranscriptEntry
 } from "../types.js";
 import { createRunId, elapsedMs, nowMs, providerCallIdFor } from "./ids.js";
@@ -34,6 +35,7 @@ import {
   createTranscriptLink,
   emptyCost
 } from "./defaults.js";
+import { computeHealth, DEFAULT_HEALTH_THRESHOLDS } from "./health.js";
 import { throwIfAborted } from "./cancellation.js";
 import { parseAgentDecision } from "./decisions.js";
 import { generateModelTurn } from "./model.js";
@@ -54,9 +56,12 @@ interface SharedRunOptions {
   readonly signal?: AbortSignal;
   readonly terminate?: TerminationCondition;
   readonly wrapUpHint?: DogpileOptions["wrapUpHint"];
+  readonly maxConcurrentAgentTurns?: number;
   readonly emit?: (event: RunEvent) => void;
 }
 
+const DEFAULT_MAX_CONCURRENT_AGENT_TURNS = 4;
+
 export async function runShared(options: SharedRunOptions): Promise<RunResult> {
   const runId = createRunId();
   const events: RunEvent[] = [];
@@ -122,77 +127,88 @@ export async function runShared(options: SharedRunOptions): Promise<RunResult> {
 
   if (!stopIfNeeded()) {
     const providerCallSlots: ReplayTraceProviderCall[] = [];
-    const turnResults = await Promise.all(
-      activeAgents.map(async (agent, index) => {
-        const turn = index + 1;
-        const input = buildSharedInput(options.intent, sharedState, turn);
-        const request: ModelRequest = {
-          temperature: options.temperature,
-          ...(options.signal !== undefined ? { signal: options.signal } : {}),
-          metadata: {
-            runId,
-            protocol: "shared",
-            agentId: agent.id,
-            role: agent.role,
-            tier: options.tier,
-            turn,
-            ...toolAvailability
-          },
-          messages: wrapUpHint.inject(
-            [
-              {
-                role: "system",
-                content: buildSystemPrompt(agent)
+    const fanout = createFanoutAbortController(options.signal);
+    const turnResults = await (async () => {
+      try {
+        return await mapWithConcurrency(
+          activeAgents,
+          options.maxConcurrentAgentTurns ?? DEFAULT_MAX_CONCURRENT_AGENT_TURNS,
+          fanout,
+          async (agent, index) => {
+            throwIfAborted(fanout.signal, options.model.id);
+            const turn = index + 1;
+            const input = buildSharedInput(options.intent, sharedState, turn);
+            const request: ModelRequest = {
+              temperature: options.temperature,
+              signal: fanout.signal,
+              metadata: {
+                runId,
+                protocol: "shared",
+                agentId: agent.id,
+                role: agent.role,
+                tier: options.tier,
+                turn,
+                ...toolAvailability
               },
-              {
-                role: "user",
-                content: input
-              }
-            ],
-            {
+              messages: wrapUpHint.inject(
+                [
+                  {
+                    role: "system",
+                    content: buildSystemPrompt(agent)
+                  },
+                  {
+                    role: "user",
+                    content: input
+                  }
+                ],
+                {
+                  runId,
+                  protocol: "shared",
+                  cost: totalCost,
+                  events,
+                  transcript,
+                  iteration: transcript.length,
+                  elapsedMs: elapsedMs(startedAtMs)
+                }
+              )
+            };
+            const response = await generateModelTurn({
+              model: options.model,
+              request,
               runId,
-              protocol: "shared",
-              cost: totalCost,
-              events,
-              transcript,
-              iteration: transcript.length,
-              elapsedMs: elapsedMs(startedAtMs)
-            }
-          )
-        };
-        const response = await generateModelTurn({
-          model: options.model,
-          request,
-          runId,
-          agent,
-          input,
-          emit,
-          callId: providerCallIdFor(runId, providerCalls.length + index + 1),
-          onProviderCall(call): void {
-            providerCallSlots[index] = call;
+              agent,
+              input,
+              emit,
+              callId: providerCallIdFor(runId, providerCalls.length + index + 1),
+              onProviderCall(call): void {
+                providerCallSlots[index] = call;
+              }
+            });
+            const decision = parseAgentDecision(response.text);
+            const toolCalls = await executeModelResponseToolRequests({
+              response,
+              executor: toolExecutor,
+              agentId: agent.id,
+              role: agent.role,
+              turn
+            });
+            throwIfAborted(fanout.signal, options.model.id);
+
+            return {
+              agent,
+              turn,
+              input,
+              response,
+              decision,
+              toolCalls,
+              turnCost: responseCost(response)
+            };
           }
-        });
-        const decision = parseAgentDecision(response.text);
-        const toolCalls = await executeModelResponseToolRequests({
-          response,
-          executor: toolExecutor,
-          agentId: agent.id,
-          role: agent.role,
-          turn
-        });
-        throwIfAborted(options.signal, options.model.id);
-
-        return {
-          agent,
-          turn,
-          input,
-          response,
-          decision,
-          toolCalls,
-          turnCost: responseCost(response)
-        };
-      })
-    );
+        );
+      } finally {
+        fanout.cleanup();
+      }
+    })();
     providerCalls.push(...providerCallSlots.filter((call): call is ReplayTraceProviderCall => call !== undefined));
 
     for (const result of turnResults) {
@@ -242,45 +258,46 @@ export async function runShared(options: SharedRunOptions): Promise<RunResult> {
     transcriptEntryCount: transcript.length
   });
   const finalEvent = events.at(-1);
+  const trace: Trace = {
+    schemaVersion: "1.0",
+    runId,
+    protocol: "shared",
+    tier: options.tier,
+    modelProviderId: options.model.id,
+    agentsUsed: activeAgents,
+    inputs: createReplayTraceRunInputs({
+      intent: options.intent,
+      protocol: options.protocol,
+      tier: options.tier,
+      modelProviderId: options.model.id,
+      agents: activeAgents,
+      temperature: options.temperature
+    }),
+    budget: createReplayTraceBudget({
+      tier: options.tier,
+      ...(options.budget ? { caps: options.budget } : {}),
+      ...(options.terminate ? { termination: options.terminate } : {})
+    }),
+    budgetStateChanges: createReplayTraceBudgetStateChanges(events),
+    seed: createReplayTraceSeed(options.seed),
+    protocolDecisions,
+    providerCalls,
+    finalOutput: createReplayTraceFinalOutput(output, finalEvent ?? {
+      type: "final",
+      runId,
+      at: "",
+      output,
+      cost: totalCost,
+      transcript: createTranscriptLink(transcript)
+    }),
+    events,
+    transcript
+  };
 
   return {
     output,
     eventLog: createRunEventLog(runId, "shared", events),
-    trace: {
-      schemaVersion: "1.0",
-      runId,
-      protocol: "shared",
-      tier: options.tier,
-      modelProviderId: options.model.id,
-      agentsUsed: activeAgents,
-      inputs: createReplayTraceRunInputs({
-        intent: options.intent,
-        protocol: options.protocol,
-        tier: options.tier,
-        modelProviderId: options.model.id,
-        agents: activeAgents,
-        temperature: options.temperature
-      }),
-      budget: createReplayTraceBudget({
-        tier: options.tier,
-        ...(options.budget ? { caps: options.budget } : {}),
-        ...(options.terminate ? { termination: options.terminate } : {})
-      }),
-      budgetStateChanges: createReplayTraceBudgetStateChanges(events),
-      seed: createReplayTraceSeed(options.seed),
-      protocolDecisions,
-      providerCalls,
-      finalOutput: createReplayTraceFinalOutput(output, finalEvent ?? {
-        type: "final",
-        runId,
-        at: "",
-        output,
-        cost: totalCost,
-        transcript: createTranscriptLink(transcript)
-      }),
-      events,
-      transcript
-    },
+    trace,
     transcript,
     usage: createRunUsage(totalCost),
     metadata: createRunMetadata({
@@ -298,7 +315,8 @@ export async function runShared(options: SharedRunOptions): Promise<RunResult> {
       cost: totalCost,
       events
     }),
-    cost: totalCost
+    cost: totalCost,
+    health: computeHealth(trace, DEFAULT_HEALTH_THRESHOLDS)
   };
 
   function stopIfNeeded(): boolean {
@@ -376,3 +394,72 @@ function responseCost(response: ModelResponse): CostSummary {
   };
 }
 
+interface FanoutAbortController {
+  readonly signal: AbortSignal;
+  abort(reason: unknown): void;
+  cleanup(): void;
+}
+
+function createFanoutAbortController(parentSignal: AbortSignal | undefined): FanoutAbortController {
+  const controller = new AbortController();
+  let removeParentListener = (): void => {};
+
+  if (parentSignal?.aborted) {
+    controller.abort(parentSignal.reason);
+  } else if (parentSignal !== undefined) {
+    const abortFromParent = (): void => {
+      controller.abort(parentSignal.reason);
+    };
+    parentSignal.addEventListener("abort", abortFromParent, { once: true });
+    removeParentListener = (): void => {
+      parentSignal.removeEventListener("abort", abortFromParent);
+    };
+  }
+
+  return {
+    signal: controller.signal,
+    abort(reason: unknown): void {
+      if (!controller.signal.aborted) {
+        controller.abort(reason);
+      }
+    },
+    cleanup(): void {
+      removeParentListener();
+    }
+  };
+}
+
+async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  maxConcurrent: number,
+  fanout: FanoutAbortController,
+  mapper: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const results: R[] = new Array(items.length);
+  let nextIndex = 0;
+  let firstError: unknown;
+  const workerCount = Math.min(maxConcurrent, items.length);
+
+  await Promise.all(Array.from({ length: workerCount }, async () => {
+    while (nextIndex < items.length && firstError === undefined) {
+      const index = nextIndex;
+      nextIndex += 1;
+      try {
+        results[index] = await mapper(items[index]!, index);
+      } catch (error) {
+        firstError ??= error;
+        fanout.abort(error);
+      }
+    }
+  }));
+
+  if (firstError !== undefined) {
+    throw firstError;
+  }
+
+  return results;
+}

package/src/runtime/tools/built-in.ts

@@ -60,6 +60,8 @@ export interface WebSearchToolAdapterOptions {
   readonly fetch?: WebSearchFetch;
   readonly headers?: HeadersInit;
   readonly defaultMaxResults?: number;
+  readonly allowHosts?: readonly string[];
+  readonly allowPrivateNetwork?: boolean;
   readonly identity?: BuiltInDogpileToolIdentityOptions;
   readonly permissions?: readonly RuntimeToolPermission[];
   readonly buildRequest?: WebSearchFetchRequestBuilder;
@@ -271,11 +273,15 @@ export function createWebSearchToolAdapter(
   options: WebSearchToolAdapterOptions
 ): RuntimeToolAdapterContract<WebSearchToolInput, WebSearchToolOutput> {
   const identity = mergeIdentity(webSearchIdentity, options.identity);
+  const endpointUrl = new URL(String(options.endpoint));
+  const allowedHosts = normalizeAllowedHosts(options.allowHosts ?? [endpointUrl.hostname]);
+  const allowPrivateNetwork = options.allowPrivateNetwork ?? false;
+  const permissions = options.permissions ?? webSearchPermissionsFor(allowedHosts, allowPrivateNetwork);
 
   return normalizeBuiltInDogpileTool({
     name: "webSearch",
     ...(options.identity ? { identity: options.identity } : {}),
-    ...(options.permissions ? { permissions: options.permissions } : {}),
+    permissions,
     async execute(input, context): Promise<RuntimeToolResult<WebSearchToolOutput>> {
       const fetchImplementation = options.fetch ?? globalThis.fetch;
 
@@ -295,6 +301,15 @@ export function createWebSearchToolAdapter(
       const request = options.buildRequest
         ? options.buildRequest(input, context)
         : defaultWebSearchRequest(options, input, context);
+      const policyError = validateWebSearchRequestPolicy(request.url, allowedHosts, allowPrivateNetwork);
+      if (policyError !== undefined) {
+        return {
+          type: "error",
+          toolCallId: context.toolCallId,
+          tool: identity,
+          error: policyError
+        };
+      }
       const response = await fetchImplementation(request.url, {
         ...request.init,
         ...(context.abortSignal ? { signal: context.abortSignal } : {})
@@ -616,10 +631,19 @@ async function executeSandboxWithPolicy(
     } satisfies RuntimeToolAdapterError;
   }
 
-  const execution = Promise.resolve().then(() => execute(input, context));
+  const policy = createToolPolicyAbortController(context.abortSignal);
+  const executionContext: RuntimeToolExecutionContext = {
+    ...context,
+    abortSignal: policy.signal
+  };
+  const execution = Promise.resolve().then(() => execute(input, executionContext));
 
   if (timeoutMs === undefined && context.abortSignal === undefined) {
-    return await execution;
+    try {
+      return await execution;
+    } finally {
+      policy.cleanup();
+    }
   }
 
   return await new Promise<CodeExecToolOutput>((resolve, reject) => {
@@ -627,31 +651,33 @@ async function executeSandboxWithPolicy(
 
     const cleanup = (): void => {
       if (timeoutId !== undefined) clearTimeout(timeoutId);
-      context.abortSignal?.removeEventListener("abort", abortHandler);
+      policy.signal.removeEventListener("abort", abortHandler);
+      policy.cleanup();
     };
 
     const abortHandler = (): void => {
       cleanup();
-      reject({
-        code: "aborted",
-        message: "Code execution was aborted.",
-        retryable: true
-      } satisfies RuntimeToolAdapterError);
+      const reason = policy.signal.reason;
+      reject(isRuntimeToolAdapterError(reason)
+        ? reason
+        : {
+            code: "aborted",
+            message: "Code execution was aborted.",
+            retryable: true
+          } satisfies RuntimeToolAdapterError);
     };
 
-    if (context.abortSignal) {
-      context.abortSignal.addEventListener("abort", abortHandler, { once: true });
-    }
+    policy.signal.addEventListener("abort", abortHandler, { once: true });
 
     if (timeoutMs !== undefined) {
       timeoutId = setTimeout(() => {
-        cleanup();
-        reject({
+        const error = {
           code: "timeout",
           message: `Code execution exceeded timeout of ${timeoutMs}ms.`,
           retryable: true,
           detail: { timeoutMs }
-        } satisfies RuntimeToolAdapterError);
+        } satisfies RuntimeToolAdapterError;
+        policy.abort(error);
       }, timeoutMs);
     }
 
@@ -662,6 +688,133 @@ async function executeSandboxWithPolicy(
   });
 }
 
+function webSearchPermissionsFor(
+  allowedHosts: ReadonlySet<string>,
+  allowPrivateNetwork: boolean
+): readonly RuntimeToolPermission[] {
+  return [
+    {
+      kind: "network",
+      allowHosts: Array.from(allowedHosts).sort(),
+      allowPrivateNetwork
+    }
+  ];
+}
+
+function validateWebSearchRequestPolicy(
+  requestUrl: string | URL,
+  allowedHosts: ReadonlySet<string>,
+  allowPrivateNetwork: boolean
+): RuntimeToolAdapterError | undefined {
+  const url = new URL(String(requestUrl));
+  const host = normalizeHost(url.hostname);
+
+  if (!allowedHosts.has(host)) {
+    return {
+      code: "permission-denied",
+      message: `webSearch request host ${url.hostname} is not allowed.`,
+      retryable: false,
+      detail: {
+        reason: "host-not-allowed",
+        host: url.hostname,
+        allowedHosts: Array.from(allowedHosts).sort()
+      }
+    };
+  }
+
+  if (!allowPrivateNetwork && classifyNetworkHost(host) === "private") {
+    return {
+      code: "permission-denied",
+      message: `webSearch request host ${url.hostname} is private-network and is not allowed.`,
+      retryable: false,
+      detail: {
+        reason: "private-network-not-allowed",
+        host: url.hostname
+      }
+    };
+  }
+
+  return undefined;
+}
+
+function normalizeAllowedHosts(hosts: readonly string[]): ReadonlySet<string> {
+  return new Set(hosts.map(normalizeHost));
+}
+
+function normalizeHost(host: string): string {
+  return host.toLowerCase().replace(/^\[|\]$/g, "");
+}
+
+function classifyNetworkHost(host: string): "private" | "public" {
+  const mappedIpv4 = ipv4MappedToDottedQuad(host);
+  if (mappedIpv4 !== undefined) {
+    return classifyNetworkHost(mappedIpv4);
+  }
+  if (host === "localhost") return "private";
+  if (host.endsWith(".local")) return "private";
+  if (/^127(?:\.\d{1,3}){3}$/.test(host)) return "private";
+  if (/^10(?:\.\d{1,3}){3}$/.test(host)) return "private";
+  if (/^172\.(?:1[6-9]|2\d|3[01])(?:\.\d{1,3}){2}$/.test(host)) return "private";
+  if (/^192\.168(?:\.\d{1,3}){2}$/.test(host)) return "private";
+  if (/^169\.254(?:\.\d{1,3}){2}$/.test(host)) return "private";
+  if (host === "::1") return "private";
+  if (/^f[cd][0-9a-f]{2}:/.test(host)) return "private";
+  if (/^fe[89ab][0-9a-f]?:/.test(host)) return "private";
+  return "public";
+}
+
+function ipv4MappedToDottedQuad(host: string): string | undefined {
+  const match = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
+  if (match === null) {
+    return undefined;
+  }
+  const high = Number.parseInt(match[1] ?? "", 16);
+  const low = Number.parseInt(match[2] ?? "", 16);
+  if (!Number.isFinite(high) || !Number.isFinite(low)) {
+    return undefined;
+  }
+  return `${high >> 8}.${high & 255}.${low >> 8}.${low & 255}`;
+}
+
+interface ToolPolicyAbortController {
+  readonly signal: AbortSignal;
+  abort(reason: unknown): void;
+  cleanup(): void;
+}
+
+function createToolPolicyAbortController(parentSignal: AbortSignal | undefined): ToolPolicyAbortController {
+  const controller = new AbortController();
+  let removeParentListener = (): void => {};
+
+  if (parentSignal?.aborted) {
+    controller.abort(parentSignal.reason);
+  } else if (parentSignal !== undefined) {
+    const abortFromParent = (): void => {
+      controller.abort(parentSignal.reason ?? {
+        code: "aborted",
+        message: "Code execution was aborted.",
+        retryable: true
+      } satisfies RuntimeToolAdapterError);
+    };
+    parentSignal.addEventListener("abort", abortFromParent, { once: true });
+    removeParentListener = (): void => {
+      parentSignal.removeEventListener("abort", abortFromParent);
+    };
+  }
+
+  return {
+    signal: controller.signal,
+    abort(reason: unknown): void {
+      if (!controller.signal.aborted) {
+        controller.abort(reason);
+      }
+    },
+    cleanup(): void {
+      removeParentListener();
+    }
+  };
+}
+
 function normalizeWebSearchResult(value: unknown): WebSearchToolResult {
   if (!isJsonObject(value)) {
     throw {

package/src/runtime/tools.ts

@@ -16,6 +16,8 @@ import type {
 import { validateRuntimeToolRegistrations } from "./validation.js";
 import { normalizeRuntimeToolAdapterError } from "./tools/built-in.js";
 
+const DEFAULT_MAX_CONCURRENT_TOOL_CALLS = 4;
+
 // Re-export the public surface from the split modules so the
 // `@dogpile/sdk/runtime/tools` subpath stays stable.
 export {
@@ -98,12 +100,18 @@ export interface RuntimeToolExecutorOptions {
 export function createRuntimeToolExecutor(options: RuntimeToolExecutorOptions): RuntimeToolExecutor {
   validateRuntimeToolRegistrations(options.tools);
   const tools = Array.from(options.tools);
+  const toolsById = new Map<string, RuntimeTool<JsonObject, JsonValue>>();
+  for (const tool of tools) {
+    if (!toolsById.has(tool.identity.id)) {
+      toolsById.set(tool.identity.id, tool);
+    }
+  }
   let callCount = 0;
 
   return {
     tools,
     async execute(request: RuntimeToolExecutionRequest): Promise<RuntimeToolResult> {
-      const tool = tools.find((candidate) => candidate.identity.id === request.toolId);
+      const tool = toolsById.get(request.toolId);
       const identity = tool?.identity ?? {
         id: request.toolId,
         name: request.toolId
@@ -182,9 +190,9 @@ export async function executeModelResponseToolRequests(options: {
   readonly turn: number;
   readonly metadata?: JsonObject;
 }): Promise<readonly TranscriptToolCall[]> {
-  const toolCalls: TranscriptToolCall[] = [];
+  const requests = options.response.toolRequests ?? [];
 
-  for (const request of options.response.toolRequests ?? []) {
+  return mapWithConcurrency(requests, DEFAULT_MAX_CONCURRENT_TOOL_CALLS, async (request) => {
     const result = await options.executor.execute({
       ...request,
       agentId: request.agentId ?? options.agentId,
@@ -192,15 +200,14 @@ export async function executeModelResponseToolRequests(options: {
       turn: request.turn ?? options.turn,
       metadata: mergeToolMetadata(options.metadata, request.metadata)
     });
-    toolCalls.push({
+
+    return {
       toolCallId: result.toolCallId,
       tool: result.tool,
       input: request.input,
       result
-    });
-  }
-
-  return toolCalls;
+    };
+  });
 }
 
 function runtimeToolIdentityManifest(identity: RuntimeToolIdentity): JsonObject {
@@ -321,3 +328,27 @@ function mergeToolMetadata(base: JsonObject | undefined, request: JsonObject | u
 function defaultToolCallId(runId: string, callIndex: number): string {
   return `${runId}:tool-${callIndex + 1}`;
 }
+
+async function mapWithConcurrency<T, R>(
+  items: readonly T[],
+  maxConcurrent: number,
+  mapper: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const results: R[] = new Array(items.length);
+  let nextIndex = 0;
+  const workerCount = Math.min(maxConcurrent, items.length);
+
+  await Promise.all(Array.from({ length: workerCount }, async () => {
+    while (nextIndex < items.length) {
+      const index = nextIndex;
+      nextIndex += 1;
+      results[index] = await mapper(items[index]!, index);
+    }
+  }));
+
+  return results;
+}