@dogpile/sdk 0.1.0

package/src/runtime/sequential.ts

@@ -0,0 +1,357 @@
+import type {
+  AgentSpec,
+  ConfiguredModelProvider,
+  CostSummary,
+  DogpileOptions,
+  ModelRequest,
+  ModelResponse,
+  ReplayTraceProtocolDecision,
+  ReplayTraceProviderCall,
+  RuntimeTool,
+  RunEvent,
+  RunResult,
+  JsonObject,
+  JsonValue,
+  SequentialProtocolConfig,
+  TerminationCondition,
+  TerminationStopRecord,
+  Tier,
+  TranscriptEntry
+} from "../types.js";
+import {
+  addCost,
+  createReplayTraceBudget,
+  createReplayTraceBudgetStateChanges,
+  createReplayTraceFinalOutput,
+  createReplayTraceProtocolDecision,
+  createReplayTraceRunInputs,
+  createReplayTraceSeed,
+  createRunAccounting,
+  createRunEventLog,
+  createRunMetadata,
+  createRunUsage,
+  createTranscriptLink,
+  emptyCost,
+  nextProviderCallId
+} from "./defaults.js";
+import { throwIfAborted } from "./cancellation.js";
+import { isParticipatingDecision, parseAgentDecision } from "./decisions.js";
+import { generateModelTurn } from "./model.js";
+import { evaluateTerminationStop } from "./termination.js";
+import { createRuntimeToolExecutor, executeModelResponseToolRequests, runtimeToolAvailability } from "./tools.js";
+
+interface SequentialRunOptions {
+  readonly intent: string;
+  readonly protocol: SequentialProtocolConfig;
+  readonly tier: Tier;
+  readonly model: ConfiguredModelProvider;
+  readonly agents: readonly AgentSpec[];
+  readonly tools: readonly RuntimeTool<JsonObject, JsonValue>[];
+  readonly temperature: number;
+  readonly budget?: DogpileOptions["budget"];
+  readonly seed?: string | number;
+  readonly signal?: AbortSignal;
+  readonly terminate?: TerminationCondition;
+  readonly emit?: (event: RunEvent) => void;
+}
+
+export async function runSequential(options: SequentialRunOptions): Promise<RunResult> {
+  const runId = createRunId();
+  const events: RunEvent[] = [];
+  const transcript: TranscriptEntry[] = [];
+  const protocolDecisions: ReplayTraceProtocolDecision[] = [];
+  const providerCalls: ReplayTraceProviderCall[] = [];
+  let totalCost = emptyCost();
+  const maxTurns = options.protocol.maxTurns ?? options.agents.length;
+  const activeAgents = options.agents.slice(0, maxTurns);
+  const startedAtMs = nowMs();
+  let stopped = false;
+  let termination: TerminationStopRecord | undefined;
+
+  const emit = (event: RunEvent): void => {
+    events.push(event);
+    options.emit?.(event);
+  };
+
+  const recordProtocolDecision = (
+    event: RunEvent,
+    decisionOptions?: Parameters<typeof createReplayTraceProtocolDecision>[3]
+  ): void => {
+    protocolDecisions.push(
+      createReplayTraceProtocolDecision("sequential", event, events.length - 1, decisionOptions)
+    );
+  };
+
+  const toolExecutor = createRuntimeToolExecutor({
+    runId,
+    protocol: "sequential",
+    tier: options.tier,
+    tools: options.tools,
+    emit(event): void {
+      emit(event);
+      recordProtocolDecision(event);
+    },
+    getTrace: () => ({ events, transcript }),
+    ...(options.signal !== undefined ? { abortSignal: options.signal } : {})
+  });
+  const toolAvailability = runtimeToolAvailability(toolExecutor.tools);
+
+  throwIfAborted(options.signal, options.model.id);
+
+  for (const agent of activeAgents) {
+    const event: RunEvent = {
+      type: "role-assignment",
+      runId,
+      at: new Date().toISOString(),
+      agentId: agent.id,
+      role: agent.role
+    };
+    emit(event);
+    recordProtocolDecision(event);
+  }
+
+  for (const [index, agent] of activeAgents.entries()) {
+    if (stopIfNeeded()) {
+      break;
+    }
+
+    const turn = index + 1;
+    const input = buildSequentialInput(options.intent, transcript);
+    const request: ModelRequest = {
+      temperature: options.temperature,
+      ...(options.signal !== undefined ? { signal: options.signal } : {}),
+      metadata: {
+        runId,
+        protocol: "sequential",
+        agentId: agent.id,
+        role: agent.role,
+        tier: options.tier,
+        turn,
+        ...toolAvailability
+      },
+      messages: [
+        {
+          role: "system",
+          content: buildSystemPrompt(agent)
+        },
+        {
+          role: "user",
+          content: input
+        }
+      ]
+    };
+    const response = await generateModelTurn({
+      model: options.model,
+      request,
+      runId,
+      agent,
+      input,
+      emit,
+      callId: nextProviderCallId(runId, providerCalls),
+      onProviderCall(call): void {
+        providerCalls.push(call);
+      }
+    });
+    const turnCost = responseCost(response);
+    totalCost = addCost(totalCost, turnCost);
+    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);
+
+    transcript.push({
+      agentId: agent.id,
+      role: agent.role,
+      input,
+      output: response.text,
+      ...(decision !== undefined ? { decision } : {}),
+      ...(toolCalls.length > 0 ? { toolCalls } : {})
+    });
+
+    const event: RunEvent = {
+      type: "agent-turn",
+      runId,
+      at: new Date().toISOString(),
+      agentId: agent.id,
+      role: agent.role,
+      input,
+      output: response.text,
+      ...(decision !== undefined ? { decision } : {}),
+      cost: totalCost
+    };
+    emit(event);
+    recordProtocolDecision(event, {
+      turn,
+      transcriptEntryCount: transcript.length
+    });
+
+    if (stopIfNeeded()) {
+      break;
+    }
+  }
+
+  const output = [...transcript].reverse().find((entry) => isParticipatingDecision(entry.decision))?.output ?? "";
+  throwIfAborted(options.signal, options.model.id);
+  const final: RunEvent = {
+    type: "final",
+    runId,
+    at: new Date().toISOString(),
+    output,
+    cost: totalCost,
+    transcript: createTranscriptLink(transcript),
+    ...(termination !== undefined ? { termination } : {})
+  };
+  emit(final);
+  recordProtocolDecision(final, {
+    transcriptEntryCount: transcript.length
+  });
+  const finalEvent = events.at(-1);
+
+  return {
+    output,
+    eventLog: createRunEventLog(runId, "sequential", events),
+    trace: {
+      schemaVersion: "1.0",
+      runId,
+      protocol: "sequential",
+      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 ?? events[0] ?? {
+        type: "final",
+        runId,
+        at: "",
+        output,
+        cost: totalCost,
+        transcript: createTranscriptLink(transcript)
+      }),
+      events,
+      transcript
+    },
+    transcript,
+    usage: createRunUsage(totalCost),
+    metadata: createRunMetadata({
+      runId,
+      protocol: "sequential",
+      tier: options.tier,
+      modelProviderId: options.model.id,
+      agentsUsed: activeAgents,
+      events
+    }),
+    accounting: createRunAccounting({
+      tier: options.tier,
+      ...(options.budget ? { budget: options.budget } : {}),
+      ...(options.terminate ? { termination: options.terminate } : {}),
+      cost: totalCost,
+      events
+    }),
+    cost: totalCost
+  };
+
+  function stopIfNeeded(): boolean {
+    throwIfAborted(options.signal, options.model.id);
+
+    if (stopped || !options.terminate) {
+      return stopped;
+    }
+
+    const stopRecord = evaluateTerminationStop(options.terminate, {
+      runId,
+      protocol: "sequential",
+      tier: options.tier,
+      cost: totalCost,
+      events,
+      transcript,
+      iteration: transcript.length,
+      elapsedMs: elapsedMs(startedAtMs)
+    });
+
+    if (!stopRecord) {
+      return false;
+    }
+
+    stopped = true;
+    termination = stopRecord;
+    if (stopRecord.reason === "budget") {
+      emitBudgetStop(stopRecord);
+    }
+    return true;
+  }
+
+  function emitBudgetStop(record: TerminationStopRecord): void {
+    const event: RunEvent = {
+      type: "budget-stop",
+      runId,
+      at: new Date().toISOString(),
+      reason: record.budgetReason ?? "cost",
+      cost: totalCost,
+      iteration: transcript.length,
+      elapsedMs: elapsedMs(startedAtMs),
+      detail: record.detail ?? {}
+    };
+    emit(event);
+    recordProtocolDecision(event, {
+      transcriptEntryCount: transcript.length
+    });
+  }
+}
+
+function buildSystemPrompt(agent: AgentSpec): string {
+  const instruction = agent.instructions ? `\nInstructions: ${agent.instructions}` : "";
+  return `You are ${agent.id}, acting as ${agent.role} in a Sequential multi-agent protocol.${instruction}`;
+}
+
+function buildSequentialInput(intent: string, transcript: readonly TranscriptEntry[]): string {
+  if (transcript.length === 0) {
+    return `Mission: ${intent}\nProvide your contribution.`;
+  }
+
+  const prior = transcript
+    .map((entry) => `${entry.role} (${entry.agentId}): ${entry.output}`)
+    .join("\n\n");
+  return `Mission: ${intent}\n\nPrior contributions:\n${prior}\n\nContinue the sequence with a useful next contribution.`;
+}
+
+function responseCost(response: ModelResponse): CostSummary {
+  return {
+    usd: response.costUsd ?? 0,
+    inputTokens: response.usage?.inputTokens ?? 0,
+    outputTokens: response.usage?.outputTokens ?? 0,
+    totalTokens: response.usage?.totalTokens ?? 0
+  };
+}
+
+function createRunId(): string {
+  const random = globalThis.crypto?.randomUUID?.();
+  return random ?? `run-${Date.now().toString(36)}`;
+}
+
+function nowMs(): number {
+  return globalThis.performance?.now() ?? Date.now();
+}
+
+function elapsedMs(startedAtMs: number): number {
+  return Math.max(0, nowMs() - startedAtMs);
+}

package/src/runtime/shared.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, it } from "vitest";
+import { createDeterministicSharedTestMission } from "../internal.js";
+import { Dogpile, run, runtimeToolManifest } from "../index.js";
+import type {
+  ConfiguredModelProvider,
+  JsonObject,
+  ModelRequest,
+  ModelResponse,
+  RunEvent,
+  RuntimeTool
+} from "../index.js";
+
+describe("shared protocol", () => {
+  it("executes end-to-end through the branded high-level SDK call", async () => {
+    const result = await Dogpile.pile(createDeterministicSharedTestMission());
+
+    expect(result.output).toBe(
+      [
+        "state-initializer:agent-1 => state-initializer:agent-1 initialized the shared state.",
+        "state-reviewer:agent-2 => state-reviewer:agent-2 initialized the shared state.",
+        "state-synthesizer:agent-3 => state-synthesizer:agent-3 initialized the shared state."
+      ].join("\n")
+    );
+    expect(result.trace.protocol).toBe("shared");
+    expect(result.trace.modelProviderId).toBe("deterministic-shared-model");
+    expect(result.trace.events.map((event) => event.type)).toEqual([
+      "role-assignment",
+      "role-assignment",
+      "role-assignment",
+      "agent-turn",
+      "agent-turn",
+      "agent-turn",
+      "final"
+    ]);
+    expect(result.transcript).toHaveLength(3);
+    expect(result.trace.transcript).toEqual(result.transcript);
+    expect(JSON.parse(JSON.stringify(result.trace))).toEqual(result.trace);
+    expect(result.cost.totalTokens).toBeGreaterThan(0);
+  });
+
+  it("runs a deterministic shared-state test mission against the configured model provider", async () => {
+    const requests: ModelRequest[] = [];
+    const model: ConfiguredModelProvider = {
+      id: "configured-shared-model",
+      async generate(request: ModelRequest): Promise<ModelResponse> {
+        requests.push(request);
+        const agentId = String(request.metadata.agentId);
+        const role = String(request.metadata.role);
+        const turn = Number(request.metadata.turn);
+
+        return {
+          text: `${role}:${agentId} wrote shared turn ${turn}.`,
+          usage: {
+            inputTokens: 9,
+            outputTokens: 5,
+            totalTokens: 14
+          },
+          costUsd: 0.001
+        };
+      }
+    };
+
+    const result = await run(createDeterministicSharedTestMission(model));
+
+    expect(requests).toHaveLength(3);
+    expect(result.trace.protocol).toBe("shared");
+    expect(result.trace.modelProviderId).toBe("configured-shared-model");
+    expect(result.trace.events.map((event) => event.type)).toEqual([
+      "role-assignment",
+      "role-assignment",
+      "role-assignment",
+      "agent-turn",
+      "agent-turn",
+      "agent-turn",
+      "final"
+    ]);
+
+    for (const [index, request] of requests.entries()) {
+      const turn = index + 1;
+      const userMessage = request.messages.find((message) => message.role === "user");
+      const systemMessage = request.messages.find((message) => message.role === "system");
+
+      expect(request.metadata).toMatchObject({
+        protocol: "shared",
+        tier: "fast",
+        turn
+      });
+      expect(userMessage?.content).toContain("Decide whether the shared protocol can support portable replay.");
+      expect(userMessage?.content).toContain(`Shared turn ${turn}`);
+      expect(userMessage?.content).toContain("Shared state:");
+      expect(systemMessage?.content).toContain("Shared multi-agent protocol");
+    }
+
+    expect(requests[0]?.messages.find((message) => message.role === "user")?.content).toContain("(empty)");
+    expect(requests[1]?.messages.find((message) => message.role === "user")?.content).toContain("(empty)");
+    expect(requests[2]?.messages.find((message) => message.role === "user")?.content).toContain("(empty)");
+    expect(requests[1]?.messages.find((message) => message.role === "user")?.content).not.toContain(
+      "state-initializer:agent-1 =>"
+    );
+    expect(result.output).toBe(
+      [
+        "state-initializer:agent-1 => state-initializer:agent-1 wrote shared turn 1.",
+        "state-reviewer:agent-2 => state-reviewer:agent-2 wrote shared turn 2.",
+        "state-synthesizer:agent-3 => state-synthesizer:agent-3 wrote shared turn 3."
+      ].join("\n")
+    );
+    expect(result.transcript).toHaveLength(3);
+    expect(result.trace.transcript).toEqual(result.transcript);
+    expect(JSON.parse(JSON.stringify(result.trace))).toEqual(result.trace);
+    expect(result.cost.totalTokens).toBe(42);
+  });
+
+  it("streams shared coordination events through the high-level SDK handle", async () => {
+    const handle = Dogpile.stream(createDeterministicSharedTestMission());
+
+    const streamedEvents: RunEvent[] = [];
+    for await (const event of handle) {
+      if (event.type !== "error") {
+        streamedEvents.push(event as RunEvent);
+      }
+    }
+    const result = await handle.result;
+
+    const expectedOutput = [
+      "state-initializer:agent-1 => state-initializer:agent-1 initialized the shared state.",
+      "state-reviewer:agent-2 => state-reviewer:agent-2 initialized the shared state.",
+      "state-synthesizer:agent-3 => state-synthesizer:agent-3 initialized the shared state."
+    ].join("\n");
+
+    expect(result.output).toBe(expectedOutput);
+    expect(streamedEvents.map((event) => event.type)).toEqual([
+      "role-assignment",
+      "role-assignment",
+      "role-assignment",
+      "agent-turn",
+      "agent-turn",
+      "agent-turn",
+      "final"
+    ]);
+    expect(result.trace.events).toEqual(streamedEvents);
+    expect(result.transcript).toEqual([
+      {
+        agentId: "agent-1",
+        role: "state-initializer",
+        input:
+          "Mission: Decide whether the shared protocol can support portable replay.\nShared turn 1: read the shared state and return an improved shared-state update.\n\nShared state:\n(empty)",
+        output: "state-initializer:agent-1 initialized the shared state."
+      },
+      {
+        agentId: "agent-2",
+        role: "state-reviewer",
+        input:
+          "Mission: Decide whether the shared protocol can support portable replay.\nShared turn 2: read the shared state and return an improved shared-state update.\n\nShared state:\n(empty)",
+        output: "state-reviewer:agent-2 initialized the shared state."
+      },
+      {
+        agentId: "agent-3",
+        role: "state-synthesizer",
+        input:
+          "Mission: Decide whether the shared protocol can support portable replay.\nShared turn 3: read the shared state and return an improved shared-state update.\n\nShared state:\n(empty)",
+        output: "state-synthesizer:agent-3 initialized the shared state."
+      }
+    ]);
+    expect(result.trace.transcript).toEqual(result.transcript);
+  });
+
+  it("gives every shared agent the same organizational memory snapshot", async () => {
+    const requests: ModelRequest[] = [];
+    const model: ConfiguredModelProvider = {
+      id: "shared-memory-snapshot-model",
+      async generate(request) {
+        requests.push(request);
+        return { text: `output-${String(request.metadata.agentId)}` };
+      }
+    };
+
+    await run({
+      intent: "Coordinate from historical organization memory.",
+      protocol: {
+        kind: "shared",
+        maxTurns: 2,
+        organizationalMemory: "Prior task memory: uploader and verifier roles were useful."
+      },
+      tier: "fast",
+      model,
+      agents: [
+        { id: "agent-a", role: "autonomous-agent" },
+        { id: "agent-b", role: "autonomous-agent" }
+      ]
+    });
+
+    expect(requests).toHaveLength(2);
+    const userPrompts = requests.map((request) => request.messages.find((message) => message.role === "user")?.content);
+    expect(userPrompts).toEqual([
+      "Mission: Coordinate from historical organization memory.\nShared turn 1: read the shared state and return an improved shared-state update.\n\nShared state:\nPrior task memory: uploader and verifier roles were useful.",
+      "Mission: Coordinate from historical organization memory.\nShared turn 2: read the shared state and return an improved shared-state update.\n\nShared state:\nPrior task memory: uploader and verifier roles were useful."
+    ]);
+    expect(userPrompts[1]).not.toContain("output-agent-a");
+  });
+
+  it("threads runtime tool availability through every shared model turn", async () => {
+    interface LookupInput extends JsonObject {
+      readonly query: string;
+    }
+
+    interface LookupOutput extends JsonObject {
+      readonly answer: string;
+    }
+
+    const requests: ModelRequest[] = [];
+    const lookupTool: RuntimeTool<LookupInput, LookupOutput> = {
+      identity: {
+        id: "fixture.lookup",
+        name: "lookup",
+        description: "Lookup contextual facts for the active mission."
+      },
+      inputSchema: {
+        kind: "json-schema",
+        schema: {
+          type: "object",
+          properties: {
+            query: { type: "string" }
+          },
+          required: ["query"],
+          additionalProperties: false
+        }
+      },
+      execute(input, context) {
+        return {
+          type: "success",
+          toolCallId: context.toolCallId,
+          tool: this.identity,
+          output: {
+            answer: `found:${input.query}`
+          }
+        };
+      }
+    };
+    const model: ConfiguredModelProvider = {
+      id: "shared-tool-availability-model",
+      async generate(request) {
+        requests.push(request);
+        return { text: `turn-${requests.length}` };
+      }
+    };
+
+    await run({
+      intent: "Use available tools while updating shared state.",
+      protocol: { kind: "shared", maxTurns: 2 },
+      tier: "fast",
+      model,
+      agents: [
+        { id: "initializer-seat", role: "initializer" },
+        { id: "reviewer-seat", role: "reviewer" }
+      ],
+      tools: [lookupTool]
+    });
+
+    expect(requests).toHaveLength(2);
+    expect(requests.map((request) => request.metadata.tools)).toEqual([
+      runtimeToolManifest([lookupTool]),
+      runtimeToolManifest([lookupTool])
+    ]);
+  });
+});