@dogpile/sdk 0.5.0 → 0.6.0

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;
+}

package/src/runtime/validation.ts

@@ -73,6 +73,7 @@ export function validateDogpileOptions(options: DogpileOptions): void {
   validateOptionalAbortSignal(options.signal, "signal");
   validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
   validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+  validateOptionalPositiveInteger(options.maxConcurrentAgentTurns, "maxConcurrentAgentTurns");
   validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
   validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }
@@ -91,6 +92,7 @@ export function validateRunCallOptions(options: unknown, path = "options"): void
   const record = requireRecord(options, path);
   validateOptionalNonNegativeInteger(record.maxDepth, `${path}.maxDepth`);
   validateOptionalPositiveInteger(record.maxConcurrentChildren, `${path}.maxConcurrentChildren`);
+  validateOptionalPositiveInteger(record.maxConcurrentAgentTurns, `${path}.maxConcurrentAgentTurns`);
   validateOptionalOnChildFailure(record.onChildFailure, `${path}.onChildFailure`);
 }
 
@@ -113,6 +115,7 @@ export function validateEngineOptions(options: EngineOptions): void {
   validateOptionalAbortSignal(options.signal, "signal");
   validateOptionalNonNegativeInteger(options.maxDepth, "maxDepth");
   validateOptionalPositiveInteger(options.maxConcurrentChildren, "maxConcurrentChildren");
+  validateOptionalPositiveInteger(options.maxConcurrentAgentTurns, "maxConcurrentAgentTurns");
   validateOptionalPositiveFiniteNumber(options.defaultSubRunTimeoutMs, "defaultSubRunTimeoutMs");
   validateOptionalOnChildFailure(options.onChildFailure, "onChildFailure");
 }

package/src/types/events.ts

@@ -140,7 +140,7 @@ export interface ModelResponseEvent {
  * - `input`: prompt text visible to that agent for this turn.
  * - `chunkIndex`: zero-based chunk index within this model turn.
  * - `text`: text delta from the provider.
- * - `output`: accumulated output for this turn after applying the chunk.
+ * - `outputLength`: accumulated output character length after applying the chunk.
  */
 export interface ModelOutputChunkEvent {
   /** Discriminant for event rendering and exhaustive switches. */
@@ -161,8 +161,8 @@ export interface ModelOutputChunkEvent {
   readonly chunkIndex: number;
   /** Text delta produced by the model provider. */
   readonly text: string;
-  /** Accumulated output for this turn after applying this chunk. */
-  readonly output: string;
+  /** Accumulated output character length after applying this chunk. */
+  readonly outputLength: number;
 }
 
 /**

package/src/types/replay.ts

@@ -163,8 +163,10 @@ export interface ReplayTraceProtocolDecision {
   readonly contributionCount?: number;
   /** Prompt/input associated with turn decisions. */
   readonly input?: string;
-  /** Output associated with turn or final decisions. */
+  /** Output associated with turn/final decisions, or a streaming text delta. */
   readonly output?: string;
+  /** Accumulated output character length for streaming output observations. */
+  readonly outputLength?: number;
   /** Cumulative cost visible at this decision point. */
   readonly cost?: CostSummary;
   /** Normalized budget stop reason for budget-stop decisions. */

package/src/types.ts

@@ -1929,6 +1929,14 @@ export interface DogpileOptions extends BudgetCostTierOptions {
    * ceiling; the effective value is `min(engine, run ?? Infinity, decision ?? Infinity)`.
    */
   readonly maxConcurrentChildren?: number;
+  /**
+   * Maximum agent model turns that may execute in parallel for shared,
+   * broadcast, and coordinator worker fan-out.
+   *
+   * Defaults to 4. Per-run values can only lower the engine ceiling.
+   * This is independent from delegated child-run concurrency.
+   */
+  readonly maxConcurrentAgentTurns?: number;
   /**
    * Fallback timeout (milliseconds) applied to delegated sub-runs when neither
    * the parent's `budget.timeoutMs` nor the decision-level
@@ -2058,6 +2066,14 @@ export interface EngineOptions {
    * call sites via {@link RunCallOptions.maxConcurrentChildren}.
    */
   readonly maxConcurrentChildren?: number;
+  /**
+   * Maximum agent model turns that may execute in parallel for shared,
+   * broadcast, and coordinator worker fan-out.
+   *
+   * Defaults to 4. Per-run lowering happens at `engine.run` / `engine.stream`
+   * call sites via {@link RunCallOptions.maxConcurrentAgentTurns}.
+   */
+  readonly maxConcurrentAgentTurns?: number;
   /**
    * Fallback timeout (milliseconds) applied to delegated sub-runs when neither
    * the parent's `budget.timeoutMs` nor the decision-level
@@ -2097,6 +2113,10 @@ export interface RunCallOptions {
    * ceiling.
    */
   readonly maxConcurrentChildren?: number;
+  /**
+   * Per-run agent-turn fan-out ceiling. Cannot raise the engine's ceiling.
+   */
+  readonly maxConcurrentAgentTurns?: number;
   /** Per-run child-failure behavior. Overrides the engine default. */
   readonly onChildFailure?: OnChildFailureMode;
 }