refactor(agent): simplify spawn wiring

Author: dcramer

packages/junior/migrations/0008_agent_invocations.sql

@@ -3,14 +3,11 @@ CREATE TABLE "junior_agent_bindings" (
 	"name" text NOT NULL,
 	"child_conversation_id" text NOT NULL,
 	"reasoning_level" text,
-	"created_at" timestamp with time zone NOT NULL,
-	"updated_at" timestamp with time zone NOT NULL,
 	CONSTRAINT "junior_agent_bindings_parent_conversation_id_name_pk" PRIMARY KEY("parent_conversation_id","name")
 );
 --> statement-breakpoint
 CREATE TABLE "junior_agent_invocations" (
 	"invocation_id" text PRIMARY KEY NOT NULL,
-	"idempotency_key" text NOT NULL,
 	"parent_conversation_id" text NOT NULL,
 	"child_conversation_id" text NOT NULL,
 	"agent_name" text,
@@ -35,6 +32,5 @@ ALTER TABLE "junior_agent_bindings" ADD CONSTRAINT "junior_agent_bindings_child_
 ALTER TABLE "junior_agent_invocations" ADD CONSTRAINT "junior_agent_invocations_parent_conversation_id_junior_conversations_conversation_id_fk" FOREIGN KEY ("parent_conversation_id") REFERENCES "public"."junior_conversations"("conversation_id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
 ALTER TABLE "junior_agent_invocations" ADD CONSTRAINT "junior_agent_invocations_child_conversation_id_junior_conversations_conversation_id_fk" FOREIGN KEY ("child_conversation_id") REFERENCES "public"."junior_conversations"("conversation_id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
 CREATE UNIQUE INDEX "junior_agent_bindings_child_idx" ON "junior_agent_bindings" USING btree ("child_conversation_id");--> statement-breakpoint
-CREATE UNIQUE INDEX "junior_agent_invocations_idempotency_idx" ON "junior_agent_invocations" USING btree ("parent_conversation_id","idempotency_key");--> statement-breakpoint
 CREATE INDEX "junior_agent_invocations_child_idx" ON "junior_agent_invocations" USING btree ("child_conversation_id");--> statement-breakpoint
 CREATE INDEX "junior_agent_invocations_mailbox_idx" ON "junior_agent_invocations" USING btree ("mailbox_status","created_at");

packages/junior/migrations/meta/0008_snapshot.json

@@ -1,5 +1,5 @@
 {
-  "id": "90f9bca0-661a-4e74-a368-5a4b574b6f96",
+  "id": "eeef7202-0cb2-4b49-bbc8-1d52e10eff0f",
   "prevId": "b85697dd-3399-4757-93bf-3bdad67612ea",
   "version": "7",
   "dialect": "postgresql",
@@ -31,18 +31,6 @@
           "type": "text",
           "primaryKey": false,
           "notNull": false
-        },
-        "created_at": {
-          "name": "created_at",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": true
-        },
-        "updated_at": {
-          "name": "updated_at",
-          "type": "timestamp with time zone",
-          "primaryKey": false,
-          "notNull": true
         }
       },
       "indexes": {
@@ -103,12 +91,6 @@
           "primaryKey": true,
           "notNull": true
         },
-        "idempotency_key": {
-          "name": "idempotency_key",
-          "type": "text",
-          "primaryKey": false,
-          "notNull": true
-        },
         "parent_conversation_id": {
           "name": "parent_conversation_id",
           "type": "text",
@@ -213,27 +195,6 @@
         }
       },
       "indexes": {
-        "junior_agent_invocations_idempotency_idx": {
-          "name": "junior_agent_invocations_idempotency_idx",
-          "columns": [
-            {
-              "expression": "parent_conversation_id",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            },
-            {
-              "expression": "idempotency_key",
-              "isExpression": false,
-              "asc": true,
-              "nulls": "last"
-            }
-          ],
-          "isUnique": true,
-          "concurrently": false,
-          "method": "btree",
-          "with": {}
-        },
         "junior_agent_invocations_child_idx": {
           "name": "junior_agent_invocations_child_idx",
           "columns": [

packages/junior/migrations/meta/_journal.json

@@ -61,7 +61,7 @@
     {
       "idx": 8,
       "version": "7",
-      "when": 1785117467102,
+      "when": 1785171129009,
       "tag": "0008_agent_invocations",
       "breakpoints": true
     }

packages/junior/src/app.ts

@@ -62,10 +62,7 @@ import {
   type VercelConversationWorkCallbackOptions,
 } from "@/chat/task-execution/vercel-callback";
 import { getVercelConversationWorkQueue } from "@/chat/task-execution/vercel-queue";
-import {
-  bindAgentSpawnControl,
-  createAgentInvocationCreator,
-} from "@/chat/agent-invocations/spawn";
+import { bindSpawnAgent } from "@/chat/agent-invocations/spawn";
 import {
   createVercelPluginTaskCallback,
   registerVercelPluginTaskDevConsumer,
@@ -626,12 +623,9 @@ export async function createApp(options?: JuniorAppOptions): Promise<Hono> {
   const waitUntil = options?.waitUntil ?? (await defaultWaitUntil());
   const tracePropagation = { domains: sandboxEgressTracePropagationDomains };
   const conversationWorkQueue = getVercelConversationWorkQueue();
-  const agentInvocationCreator = createAgentInvocationCreator({
-    queue: conversationWorkQueue,
-  });
   const agentRunner = createAgentRunner(executeAgentRun, {
     bindSpawnAgent: (request) =>
-      bindAgentSpawnControl(request, agentInvocationCreator),
+      bindSpawnAgent(request, { queue: conversationWorkQueue }),
     tracePropagation,
   });
   const runtimeServiceOverrides = {

packages/junior/src/chat/agent-invocations/spawn.ts

@@ -2,67 +2,40 @@ import type { StateAdapter } from "chat";
 import type { ConversationStore } from "@/chat/conversations/store";
 import type {
   AgentRunRequest,
-  AgentSpawnControl,
-  AgentSpawnInput,
-  AgentSpawnResult,
+  SpawnAgent,
+  SpawnAgentInput,
 } from "@/chat/agent/request";
 import {
   actorFromRouting,
   toolInvocationDestination,
 } from "@/chat/agent/request";
 import type { ConversationWorkQueue } from "@/chat/task-execution/queue";
-import type { CreateAgentInvocationInput } from "./types";
 import { createAndEnqueueAgentInvocation } from "./work";
 
-export interface AgentInvocationCreator {
-  create(input: CreateAgentInvocationInput): Promise<AgentSpawnResult>;
-}
-
-interface AgentInvocationCreatorOptions {
+type SpawnOptions = {
   conversationStore?: ConversationStore;
   queue: ConversationWorkQueue | (() => ConversationWorkQueue);
   state?: StateAdapter;
-}
-
-/** Create the narrow durable invocation capability used by agent runners. */
-export function createAgentInvocationCreator(
-  options: AgentInvocationCreatorOptions,
-): AgentInvocationCreator {
-  return {
-    async create(input) {
-      const queue =
-        typeof options.queue === "function" ? options.queue() : options.queue;
-      const created = await createAndEnqueueAgentInvocation(input, {
-        ...options,
-        queue,
-      });
-      return {
-        agentName: created.invocation.agentName,
-        childConversationId: created.invocation.childConversationId,
-        invocationId: created.invocation.invocationId,
-        replayed: created.status === "existing",
-        status: created.invocation.status,
-      };
-    },
-  };
-}
+};
 
 /** Bind one run's runtime-owned authority to the model-safe spawn capability. */
-export function bindAgentSpawnControl(
+export function bindSpawnAgent(
   request: AgentRunRequest,
-  creator: AgentInvocationCreator,
-): AgentSpawnControl | undefined {
+  options: SpawnOptions,
+): SpawnAgent | undefined {
   const actor = actorFromRouting(request.routing);
   if (!actor) {
     return undefined;
   }
-  return {
-    async execute(
-      input: AgentSpawnInput,
-      options: { signal?: AbortSignal; toolCallId: string },
-    ) {
-      options.signal?.throwIfAborted();
-      return await creator.create({
+  return async (
+    input: SpawnAgentInput,
+    call: { signal?: AbortSignal; toolCallId: string },
+  ) => {
+    call.signal?.throwIfAborted();
+    const queue =
+      typeof options.queue === "function" ? options.queue() : options.queue;
+    const invocation = await createAndEnqueueAgentInvocation(
+      {
         actor,
         ...(input.name ? { agentName: input.name } : {}),
         ...(request.routing.credentialContext
@@ -74,14 +47,16 @@ export function bindAgentSpawnControl(
               destinationVisibility: request.routing.destinationVisibility,
             }
           : {}),
-        idempotencyKey: `${request.turnId}:${options.toolCallId}`,
+        idempotencyKey: `${request.turnId}:${call.toolCallId}`,
         input: input.task,
         parentConversationId: request.conversationId,
         ...(input.reasoningLevel
           ? { reasoningLevel: input.reasoningLevel }
           : {}),
         source: request.routing.source,
-      });
-    },
+      },
+      { ...options, queue },
+    );
+    return { invocationId: invocation.invocationId };
   };
 }

packages/junior/src/chat/agent-invocations/store.ts

@@ -42,7 +42,7 @@ export function getAgentInvocationId(
 }
 
 /** Return the stable child identity for one invocation without a named binding. */
-export function getEphemeralAgentConversationId(invocationId: string): string {
+export function getUnnamedAgentConversationId(invocationId: string): string {
   return stableId("agent", invocationId);
 }
 
@@ -69,11 +69,9 @@ function bindingFromRow(
 ): AgentBinding {
   return agentBindingSchema.parse({
     childConversationId: row.childConversationId,
-    createdAtMs: row.createdAt.getTime(),
     name: row.name,
     parentConversationId: row.parentConversationId,
     ...(row.reasoningLevel ? { reasoningLevel: row.reasoningLevel } : {}),
-    updatedAtMs: row.updatedAt.getTime(),
   });
 }
 
@@ -93,7 +91,6 @@ function invocationFromRow(
       ? { destinationVisibility: row.destinationVisibility }
       : {}),
     ...(row.errorMessage !== null ? { errorMessage: row.errorMessage } : {}),
-    idempotencyKey: row.idempotencyKey,
     input: row.input,
     invocationId: row.invocationId,
     mailboxStatus: row.mailboxStatus,
@@ -114,7 +111,6 @@ function sameCreateInput(
 ): boolean {
   return (
     invocation.parentConversationId === input.parentConversationId &&
-    invocation.idempotencyKey === input.idempotencyKey &&
     invocation.agentName === input.agentName &&
     invocation.input === input.input &&
     invocation.reasoningLevel === input.reasoningLevel &&
@@ -129,7 +125,7 @@ function sameCreateInput(
 }
 
 /** Read one named child binding in its parent-agent scope. */
-export async function getAgentBinding(args: {
+async function getAgentBinding(args: {
   name: string;
   parentConversationId: string;
 }): Promise<AgentBinding | undefined> {
@@ -205,20 +201,20 @@ async function getNonTerminalAgentInvocationForConversation(
 
 /**
  * Create or replay one invocation, reusing named child conversations and
- * keeping ephemeral child identities scoped to the invocation.
+ * keeping unnamed child identities scoped to the invocation.
  */
 export async function createAgentInvocation(
   rawInput: CreateAgentInvocationInput,
   nowMs = Date.now(),
-): Promise<{ invocation: AgentInvocation; status: "created" | "existing" }> {
+): Promise<AgentInvocation> {
   const input = createAgentInvocationSchema.parse(rawInput);
   const invocationId = getAgentInvocationId(
     input.parentConversationId,
     input.idempotencyKey,
   );
   const childConversationId = input.agentName
     ? getNamedAgentConversationId(input.parentConversationId, input.agentName)
-    : getEphemeralAgentConversationId(invocationId);
+    : getUnnamedAgentConversationId(invocationId);
   const lockName = `${CREATE_LOCK_PREFIX}:${
     input.agentName ? childConversationId : invocationId
   }`;
@@ -248,7 +244,7 @@ export async function createAgentInvocation(
           `Agent invocation idempotency key was reused with different input for ${invocationId}`,
         );
       }
-      return { invocation: existing, status: "existing" };
+      return existing;
     }
 
     await getConversationStore().createChild({
@@ -264,11 +260,9 @@ export async function createAgentInvocation(
         .insert(juniorAgentBindings)
         .values({
           childConversationId,
-          createdAt: new Date(nowMs),
           name: input.agentName,
           parentConversationId: input.parentConversationId,
           reasoningLevel: effectiveInput.reasoningLevel ?? null,
-          updatedAt: new Date(nowMs),
         })
         .onConflictDoNothing();
       const binding = await getAgentBinding({
@@ -297,7 +291,6 @@ export async function createAgentInvocation(
       .insert(juniorAgentInvocations)
       .values({
         invocationId,
-        idempotencyKey: input.idempotencyKey,
         parentConversationId: input.parentConversationId,
         childConversationId,
         agentName: input.agentName ?? null,
@@ -319,7 +312,7 @@ export async function createAgentInvocation(
     if (!invocation || !sameCreateInput(invocation, effectiveInput)) {
       throw new Error(`Agent invocation creation raced for ${invocationId}`);
     }
-    return { invocation, status: "created" };
+    return invocation;
   });
 }
 

packages/junior/src/chat/agent-invocations/types.ts

@@ -18,20 +18,16 @@ const exactStringSchema = z
 
 export const agentNameSchema = exactStringSchema.max(64);
 
-export const agentInvocationStatusSchema = z.enum(AGENT_INVOCATION_STATUSES);
-
-export const agentInvocationMailboxStatusSchema = z.enum(
+const agentInvocationMailboxStatusSchema = z.enum(
   AGENT_INVOCATION_MAILBOX_STATUSES,
 );
 
 export const agentBindingSchema = z
   .object({
     childConversationId: exactStringSchema,
-    createdAtMs: z.number().finite(),
     name: agentNameSchema,
     parentConversationId: exactStringSchema,
     reasoningLevel: z.enum(TURN_REASONING_LEVELS).optional(),
-    updatedAtMs: z.number().finite(),
   })
   .strict();
 
@@ -44,7 +40,6 @@ const agentInvocationBaseSchema = z
     credentialContext: credentialContextSchema.optional(),
     destination: destinationSchema,
     destinationVisibility: z.enum(["public", "private"]).optional(),
-    idempotencyKey: exactStringSchema,
     input: exactStringSchema,
     invocationId: exactStringSchema,
     mailboxStatus: agentInvocationMailboxStatusSchema,
@@ -88,12 +83,7 @@ export const createAgentInvocationSchema = z
 
 export type AgentBinding = z.output<typeof agentBindingSchema>;
 export type AgentInvocation = z.output<typeof agentInvocationSchema>;
-export type AgentInvocationStatus = z.output<
-  typeof agentInvocationStatusSchema
->;
-export type AgentInvocationMailboxStatus = z.output<
-  typeof agentInvocationMailboxStatusSchema
->;
+export type AgentInvocationStatus = (typeof AGENT_INVOCATION_STATUSES)[number];
 export type CreateAgentInvocationInput = z.input<
   typeof createAgentInvocationSchema
 >;