@standardagents/builder 0.19.3 → 0.20.0

package/dist/index.js

@@ -35,9 +35,10 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/agents/types.ts
-var MAX_STEPS, MAX_RETRIES_PER_MODEL, TIMESTAMP_MULTIPLIER, STREAM_COOLDOWN, BACKOFF_BASE;
+var SUBAGENT_INITIAL_ARGUMENTS_THREAD_PROPERTY, MAX_STEPS, MAX_RETRIES_PER_MODEL, TIMESTAMP_MULTIPLIER, STREAM_COOLDOWN, BACKOFF_BASE;
 var init_types = __esm({
   "src/agents/types.ts"() {
+    SUBAGENT_INITIAL_ARGUMENTS_THREAD_PROPERTY = "__agentbuilder_subagent_initial_arguments";
     MAX_STEPS = 250;
     MAX_RETRIES_PER_MODEL = 2;
     TIMESTAMP_MULTIPLIER = 1e3;
@@ -3622,9 +3623,8 @@ var init_ToolExecutor = __esm({
             // Pass through parent thread instance and metadata
             // Propagate namespace context to sub-flows for packed agent isolation
             namespaceContext: state.namespaceContext,
+            arguments: args,
             context: {
-              ...args,
-              // Pass tool arguments for template interpolation
               // Pass parent tool config for response options
               __parentToolConfig: toolConfig,
               __parentToolName: call.function.name
@@ -3815,6 +3815,7 @@ ${errorLines.join("\n")}`);
           const targetAgentForCreate = createArgs?.agent;
           const builtinCreateMessage = createArgs?.message;
           const builtinCreateAttachmentValue = createArgs?.attachments;
+          const builtinCreateInitialArguments = createArgs?.initialArguments ?? {};
           const registryAgentName = targetAgentForCreate || call.function.name;
           const packageId = getPackageId(state);
           let agentDef = null;
@@ -3913,6 +3914,20 @@ ${errorLines.join("\n")}`);
             args,
             initAttachmentsProperty
           );
+          const initialArguments = builtinSubagentAction === "create" ? builtinCreateInitialArguments : args;
+          const argumentValidationError = await this.validateSubagentArguments(
+            state,
+            agentDef,
+            initialArguments,
+            {
+              agentName,
+              receivesMessages,
+              packageId
+            }
+          );
+          if (argumentValidationError) {
+            return argumentValidationError;
+          }
           const existingChildren = await this.getChildrenRegistry(state);
           const activeInstances = existingChildren.filter(
             (entry) => entry.name === registryAgentName && entry.status !== "terminated"
@@ -3967,10 +3982,12 @@ ${errorLines.join("\n")}`);
                   width: attachment.width,
                   height: attachment.height
                 })),
+                initial_arguments: initialArguments,
                 initial_agent_name: initialAgentName,
                 agent_title: agentDef.title || registryAgentName,
                 agent_description: agentDef.toolDescription || `Autonomous subagent ${agentDef.title || registryAgentName}`,
-                spawn_group_id: state.pendingMessageId ?? null
+                spawn_group_id: state.pendingMessageId ?? null,
+                arguments: initialArguments
               }
             });
             const requestId = pending && typeof pending.request_id === "string" ? pending.request_id : crypto.randomUUID();
@@ -3992,11 +4009,13 @@ ${errorLines.join("\n")}`);
             agent_name: agentName,
             parent: state.threadId,
             env: providedScopedEnv ?? void 0,
+            properties: this.buildSubagentThreadProperties(initialArguments) ?? void 0,
             tags: initialAgentName ? [this.buildThreadNameTag(initialAgentName)] : void 0
           });
           const childThreadId = childThread.id;
           const durableId = state.env.AGENT_BUILDER_THREAD.idFromName(childThreadId);
           const stub = state.env.AGENT_BUILDER_THREAD.get(durableId);
+          await this.persistSubagentArguments(stub, childThreadId, initialArguments);
           try {
             const { FlowEngine: FlowEngine2 } = await Promise.resolve().then(() => (init_FlowEngine(), FlowEngine_exports));
             const childState = ThreadStateImpl.fromThreadInstance(stub, {
@@ -4020,7 +4039,8 @@ ${errorLines.join("\n")}`);
             stub,
             initialMessageContent,
             receivesMessages,
-            initialMessageAttachments
+            initialMessageAttachments,
+            initialArguments
           );
           await this.upsertChildRegistry(state, {
             reference: childThreadId,
@@ -4031,6 +4051,7 @@ ${errorLines.join("\n")}`);
             blocking,
             ...resumable ? { parentCommunication } : {},
             status: "running",
+            ...this.hasInitialArguments(initialArguments) ? { initialArguments } : {},
             ...initialAgentName ? { threadName: initialAgentName } : {},
             ...state.pendingMessageId ? { spawnGroupId: state.pendingMessageId } : {},
             createdAt: Date.now() * 1e3
@@ -4040,7 +4061,7 @@ ${errorLines.join("\n")}`);
               childThreadId,
               agentName,
               initialMessages,
-              {}
+              initialArguments
             );
             const copiedAttachments = await this.copyAttachmentsBetweenThreads(
               stub,
@@ -4073,7 +4094,7 @@ ${errorLines.join("\n")}`);
                 childThreadId,
                 agentName,
                 initialMessages,
-                {}
+                initialArguments
               );
               const copiedAttachments = await this.copyAttachmentsBetweenThreads(
                 stub,
@@ -4204,21 +4225,38 @@ ${errorLines.join("\n")}`);
         const message = typeof args.message === "string" ? args.message : "";
         const attachments = args.attachments;
         const name = typeof args.name === "string" ? args.name.trim() : "";
+        const rawArguments = args.arguments;
+        const initialArguments = this.isPlainRecord(rawArguments) ? rawArguments : {};
         if (!agent) {
           return {
             agent: "",
             message,
             attachments,
             name,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} requires agent.`
           };
         }
+        if (rawArguments !== void 0 && (typeof rawArguments !== "object" || rawArguments === null || Array.isArray(rawArguments))) {
+          return {
+            agent,
+            message,
+            attachments,
+            name,
+            initialArguments,
+            arguments: initialArguments,
+            error: `${SUBAGENT_CREATE_TOOL} arguments must be an object when provided.`
+          };
+        }
         if (!message.trim()) {
           return {
             agent,
             message,
             attachments,
             name,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} requires message.`
           };
         }
@@ -4228,6 +4266,8 @@ ${errorLines.join("\n")}`);
             message,
             attachments,
             name,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} requires attachments (use [] when none).`
           };
         }
@@ -4237,6 +4277,8 @@ ${errorLines.join("\n")}`);
             message,
             attachments,
             name,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} name must be a string when provided.`
           };
         }
@@ -4246,10 +4288,141 @@ ${errorLines.join("\n")}`);
             message,
             attachments,
             name,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} requires name.`
           };
         }
-        return { agent, message, attachments, name };
+        return {
+          agent,
+          message,
+          attachments,
+          name,
+          initialArguments,
+          arguments: initialArguments
+        };
+      }
+      static hasInitialArguments(args) {
+        return Object.keys(args).length > 0;
+      }
+      static isPlainRecord(value) {
+        return !!value && typeof value === "object" && !Array.isArray(value);
+      }
+      static buildSubagentThreadProperties(initialArguments) {
+        if (!this.hasInitialArguments(initialArguments)) {
+          return null;
+        }
+        return {
+          [SUBAGENT_INITIAL_ARGUMENTS_THREAD_PROPERTY]: initialArguments
+        };
+      }
+      static qualifyPromptNameForAgent(promptName, agentName, packageId) {
+        if (!promptName) {
+          return null;
+        }
+        if (promptName.includes("/")) {
+          return promptName;
+        }
+        const agentPackageId = agentName.includes("/") ? agentName.split("/")[0] : packageId;
+        return agentPackageId ? `${agentPackageId}/${promptName}` : promptName;
+      }
+      static async validateSubagentInitialArguments(state, agentName, agentDef, receivesMessages, initialArguments, packageId) {
+        return this.validateSubagentArguments(state, agentDef, initialArguments, {
+          agentName,
+          receivesMessages,
+          packageId
+        });
+      }
+      /**
+       * Validate initial subagent arguments against the prompt schema on the child
+       * side that receives parent messages.
+       */
+      static async validateSubagentArguments(state, agentDef, args, options = {}) {
+        const receivesMessages = options.receivesMessages ?? "side_a";
+        const promptName = receivesMessages === "side_b" ? agentDef.sideB?.prompt : agentDef.sideA?.prompt;
+        const qualifiedPromptName = this.qualifyPromptNameForAgent(
+          promptName,
+          options.agentName ?? agentDef?.name ?? "",
+          options.packageId
+        );
+        if (!qualifiedPromptName) {
+          return null;
+        }
+        try {
+          const promptDef = await state.thread.instance.loadPrompt(qualifiedPromptName);
+          const schema = promptDef?.requiredSchema;
+          if (!schema || typeof schema.safeParse !== "function") {
+            return null;
+          }
+          const parsed = schema.safeParse(args);
+          if (parsed.success) {
+            return null;
+          }
+          const issues = Array.isArray(
+            parsed.error?.issues
+          ) ? parsed.error.issues : [];
+          const missing = Array.from(
+            new Set(
+              issues.map(
+                (issue) => Array.isArray(issue.path) ? issue.path.map(String).join(".") : String(issue.path ?? "")
+              ).filter((path20) => path20.length > 0)
+            )
+          );
+          const detail = issues.map((issue) => {
+            const path20 = Array.isArray(issue.path) ? issue.path.map(String).join(".") : "";
+            const message = typeof issue.message === "string" ? issue.message : "invalid value";
+            return path20 ? `${path20}: ${message}` : message;
+          }).join("; ") || parsed.error.message || "invalid arguments";
+          const agentLabel = agentDef.title || agentDef.name || options.agentName || qualifiedPromptName;
+          return {
+            status: "error",
+            error: `${SUBAGENT_CREATE_TOOL} arguments for "${agentLabel}" failed validation: ${detail}.`,
+            error_code: "subagent_arguments_required",
+            error_data: {
+              agent: agentLabel,
+              required: missing
+            }
+          };
+        } catch {
+          return null;
+        }
+      }
+      static buildSubagentInitialArgumentsMessage(initialArguments, createdAt) {
+        if (!this.hasInitialArguments(initialArguments)) {
+          return null;
+        }
+        return {
+          id: crypto.randomUUID(),
+          role: "system",
+          content: [
+            "Persistent initial arguments for this subagent thread.",
+            "These values were supplied by the parent when the child was created and remain in effect for side_a and side_b.",
+            "They are available as ThreadState.arguments and prompt variables by their top-level keys.",
+            "",
+            this.formatInitialArguments(initialArguments)
+          ].join("\n"),
+          silent: true,
+          metadata: {
+            subagentInitialArguments: true
+          },
+          created_at: createdAt
+        };
+      }
+      static formatInitialArguments(initialArguments) {
+        return JSON.stringify(initialArguments, null, 2);
+      }
+      static async persistSubagentArguments(stub, childThreadId, args) {
+        if (!args || Object.keys(args).length === 0) {
+          return;
+        }
+        if (typeof stub.setSubagentArguments !== "function") {
+          return;
+        }
+        try {
+          await stub.setSubagentArguments(childThreadId, args);
+        } catch (error) {
+          console.error("[ToolExecutor] Failed to persist subagent arguments:", error);
+        }
       }
       static getSubpromptToolConfig(config) {
         if (!config || typeof config !== "object") {
@@ -4329,7 +4502,7 @@ ${errorLines.join("\n")}`);
           await childThread.terminateThread(reference);
         }
       }
-      static async buildChildInvocationMessages(state, childThread, content, receivesMessages, parentAttachments) {
+      static async buildChildInvocationMessages(state, childThread, content, receivesMessages, parentAttachments, initialArguments) {
         const copiedAttachments = await this.copyAttachmentsBetweenThreads(
           state.thread.instance,
           childThread,
@@ -4339,6 +4512,14 @@ ${errorLines.join("\n")}`);
         const targetRole = receivesMessages === "side_a" ? "user" : "assistant";
         const baseTimestamp = Date.now() * 1e3;
         const messages = [];
+        const initialArgumentsMessage = this.buildSubagentInitialArgumentsMessage(
+          initialArguments,
+          baseTimestamp
+        );
+        if (initialArgumentsMessage) {
+          messages.push(initialArgumentsMessage);
+        }
+        const timestampOffset = messages.length;
         for (let i = 0; i < copiedAttachments.length; i++) {
           const attachment = copiedAttachments[i];
           messages.push({
@@ -4347,7 +4528,7 @@ ${errorLines.join("\n")}`);
             content: `Initial asset attachment path: ${attachment.path}`,
             attachments: JSON.stringify([attachment]),
             silent: true,
-            created_at: baseTimestamp + i
+            created_at: baseTimestamp + timestampOffset + i
           });
         }
         messages.push({
@@ -4357,7 +4538,7 @@ ${errorLines.join("\n")}`);
           // Keep binary refs on the silent path messages only to avoid rendering
           // duplicate attachments on the visible init message.
           attachments: void 0,
-          created_at: baseTimestamp + copiedAttachments.length
+          created_at: baseTimestamp + timestampOffset + copiedAttachments.length
         });
         return messages;
       }
@@ -5849,6 +6030,7 @@ var init_FlowEngine = __esm({
           },
           queue: stateInput.queue || [],
           stream,
+          arguments: stateInput.arguments || {},
           context: stateInput.context || {},
           retryCount: stateInput.retryCount || 0,
           retryReason: stateInput.retryReason,
@@ -5885,8 +6067,44 @@ var init_FlowEngine = __esm({
         } else {
           state.rootState = state;
         }
+        try {
+          const persistedArgs = await this.loadSubagentArguments(state);
+          if (persistedArgs && Object.keys(persistedArgs).length > 0) {
+            state.context = { ...persistedArgs, ...state.context || {} };
+          }
+        } catch (error) {
+          console.error(
+            "[FlowEngine] Failed to hydrate persisted subagent arguments:",
+            error
+          );
+        }
         return state;
       }
+      static getPromptInterpolationContext(state) {
+        return {
+          ...state.context || {},
+          ...state.arguments || {}
+        };
+      }
+      /**
+       * Read persisted subagent invocation arguments from execution_state.
+       * Returns an empty object for top-level threads or when none were stored.
+       */
+      static async loadSubagentArguments(state) {
+        try {
+          const cursor = await state.storage.sql.exec(
+            `SELECT value FROM execution_state WHERE key = 'subagent_arguments' LIMIT 1`
+          );
+          const raw = cursor.toArray()[0]?.value;
+          if (!raw) {
+            return {};
+          }
+          const parsed = JSON.parse(raw);
+          return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+        } catch {
+          return {};
+        }
+      }
       /**
        * Execute a single step
        */
@@ -6983,6 +7201,16 @@ var init_FlowEngine = __esm({
         const normalized = value.replace(/\s+/g, " ").trim();
         return normalized.length > 0 ? normalized : null;
       }
+      static getRegistryInitialArguments(entry) {
+        const value = entry.initialArguments;
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          return null;
+        }
+        return Object.keys(value).length > 0 ? value : null;
+      }
+      static formatInitialArgumentsForPrompt(initialArguments) {
+        return JSON.stringify(initialArguments, null, 2);
+      }
       static extractSubagentIdFromMetadata(metadata) {
         if (!metadata) {
           return null;
@@ -7057,7 +7285,7 @@ var init_FlowEngine = __esm({
         const includePastTools = state.prompt.include_past_tools ?? true;
         const promptContent = await this.interpolatePrompt(
           state.prompt.prompt,
-          state.context || {},
+          this.getPromptInterpolationContext(state),
           state
         );
         const systemPromptText = await this.runAfterSystemMessageHook(
@@ -7215,10 +7443,13 @@ ${msg.content}` : `${imageDescriptions}${nonImageList}`;
           const lines = subagentRegistry.map((entry) => {
             const threadName = this.getRegistryThreadName(entry) ?? fallbackNameMap.get(entry.reference) ?? null;
             const displayName = threadName ? `${entry.name} (${threadName})` : entry.name;
+            const initialArguments = this.getRegistryInitialArguments(entry);
+            const argumentsLine = initialArguments ? `
+  Initial arguments: ${this.formatInitialArgumentsForPrompt(initialArguments)}` : "";
             return `- Reference: ${entry.reference}
   Name: ${displayName}
   Description: ${entry.description}
-  Status: ${entry.status}`;
+  Status: ${entry.status}${argumentsLine}`;
           });
           messages.push({
             role: "system",
@@ -7670,13 +7901,21 @@ ${lines.join("\n\n")}`
           const subagentConfig = this.isSubagentToolConfig(configEntry) ? configEntry : void 0;
           const blocking = subagentConfig?.blocking ?? true;
           const resumable = !!subagentConfig?.resumable && typeof subagentConfig.resumable === "object";
+          const receivesMessages = subagentConfig?.resumable && typeof subagentConfig.resumable === "object" ? subagentConfig.resumable.receives_messages : "side_a";
+          const argumentSchema = await this.resolveSubagentArgumentSchema(
+            state,
+            agentDef,
+            receivesMessages,
+            packageId
+          );
           descriptors.push({
             name: toolName,
             title: agentDef.title || toolName,
             description: agentDef.toolDescription || `Run ${agentDef.title || toolName} subagent`,
             blocking,
             resumable,
-            maxInstances: subagentConfig?.resumable && typeof subagentConfig.resumable === "object" ? subagentConfig.resumable.maxInstances : void 0
+            maxInstances: subagentConfig?.resumable && typeof subagentConfig.resumable === "object" ? subagentConfig.resumable.maxInstances : void 0,
+            argumentSchema
           });
         }
         return descriptors;
@@ -7698,18 +7937,86 @@ ${lines.join("\n\n")}`
           return null;
         }
       }
+      static qualifyPromptNameForPackage(promptName, packageId) {
+        if (!promptName) {
+          return null;
+        }
+        if (promptName.includes("/") || !packageId) {
+          return promptName;
+        }
+        return `${packageId}/${promptName}`;
+      }
+      static async resolveSubagentArgumentSchema(state, agentDef, receivesMessages, packageId) {
+        const promptName = receivesMessages === "side_b" ? agentDef.sideB?.prompt : agentDef.sideA?.prompt;
+        const qualifiedPromptName = this.qualifyPromptNameForPackage(promptName, packageId);
+        if (!qualifiedPromptName) {
+          return void 0;
+        }
+        try {
+          const promptDef = await state.thread.instance.loadPrompt(qualifiedPromptName);
+          if (!promptDef?.requiredSchema) {
+            return void 0;
+          }
+          const schema = this.zodToJsonSchema(promptDef.requiredSchema);
+          return schema && typeof schema === "object" && !Array.isArray(schema) ? schema : void 0;
+        } catch {
+          return void 0;
+        }
+      }
       static isSubagentToolConfig(configEntry) {
         if (typeof configEntry !== "object" || configEntry === null) {
           return false;
         }
         return "blocking" in configEntry || "resumable" in configEntry || "immediate" in configEntry || "optional" in configEntry || "initUserMessageProperty" in configEntry || "initAttachmentsProperty" in configEntry || "initAgentNameProperty" in configEntry;
       }
+      static normalizeSubagentArgumentSchema(schema) {
+        const normalized = schema && typeof schema === "object" && !Array.isArray(schema) ? { ...schema } : {};
+        normalized.type = "object";
+        if (!normalized.properties || typeof normalized.properties !== "object") {
+          normalized.properties = {};
+        }
+        if (!("additionalProperties" in normalized)) {
+          normalized.additionalProperties = false;
+        }
+        return normalized;
+      }
+      static describeSubagentArguments(schema) {
+        const normalized = this.normalizeSubagentArgumentSchema(schema);
+        const properties = normalized.properties && typeof normalized.properties === "object" && !Array.isArray(normalized.properties) ? Object.keys(normalized.properties) : [];
+        const required = Array.isArray(normalized.required) ? normalized.required.filter((item) => typeof item === "string") : [];
+        const optional = properties.filter((name) => !required.includes(name));
+        const parts = [];
+        if (required.length > 0) {
+          parts.push(`required arguments: ${required.join(", ")}`);
+        }
+        if (optional.length > 0) {
+          parts.push(`optional arguments: ${optional.join(", ")}`);
+        }
+        return parts.length > 0 ? parts.join("; ") : "no extra initial arguments";
+      }
+      static buildSubagentArgumentsSchema(promptSubagents) {
+        const variants = promptSubagents.map((entry) => ({
+          ...this.normalizeSubagentArgumentSchema(entry.argumentSchema),
+          title: `${entry.name} initial arguments`,
+          description: `Initial arguments for ${entry.name}. These values persist for the child thread lifetime.`
+        }));
+        if (variants.length === 1) {
+          return variants[0];
+        }
+        return {
+          type: "object",
+          description: "Agent-specific initial arguments for the selected subagent. Use the schema matching the selected agent.",
+          additionalProperties: false,
+          anyOf: variants
+        };
+      }
       static buildSubagentCreateTool(promptSubagents) {
         const agentNames = promptSubagents.map((entry) => entry.name);
         const descriptionLines = promptSubagents.map((entry) => {
           const mode = `${entry.blocking ? "blocking" : "non-blocking"}, ${entry.resumable ? "resumable" : "non-resumable"}`;
           const maxInstances = typeof entry.maxInstances === "number" && entry.maxInstances > 0 ? `, max instances: ${entry.maxInstances}` : "";
-          return `- ${entry.name}: ${entry.description} (mode: ${mode}${maxInstances})`;
+          const argumentSummary = this.describeSubagentArguments(entry.argumentSchema);
+          return `- ${entry.name}: ${entry.description} (mode: ${mode}${maxInstances}; ${argumentSummary})`;
         });
         return {
           type: "function",
@@ -7719,6 +8026,7 @@ ${lines.join("\n\n")}`
               "Create and run a configured resumable dual_ai subagent.",
               "Available resumable subagents:",
               ...descriptionLines,
+              "Provide any required invocation arguments via `arguments`; they persist for the life of the subagent thread.",
               "Use subagent_message for follow-up communication with resumable instances."
             ].join("\n"),
             parameters: {
@@ -7743,8 +8051,10 @@ ${lines.join("\n\n")}`
                 name: {
                   type: "string",
                   description: "Required human-readable instance name for the spawned subagent thread. Use a concise stable label that identifies this child instance."
-                }
+                },
+                arguments: this.buildSubagentArgumentsSchema(promptSubagents)
               },
+              additionalProperties: false,
               required: ["agent", "message", "attachments", "name"]
             }
           }
@@ -11547,6 +11857,7 @@ function runCodeViaThreadRpc(threadInstance, threadId, source, options) {
 var ThreadStateImpl, ExecutionStateImpl;
 var init_ThreadStateImpl = __esm({
   "src/agents/ThreadStateImpl.ts"() {
+    init_types();
     init_utilities();
     init_code_execution();
     ThreadStateImpl = class _ThreadStateImpl {
@@ -11594,6 +11905,19 @@ var init_ThreadStateImpl = __esm({
       get terminated() {
         return this._terminatedCache;
       }
+      get arguments() {
+        if (this._flowState) {
+          return this._flowState.arguments ?? this.getMetadataArguments();
+        }
+        return this.getMetadataArguments();
+      }
+      getMetadataArguments() {
+        const value = this._metadata.properties?.[SUBAGENT_INITIAL_ARGUMENTS_THREAD_PROPERTY];
+        if (!value || typeof value !== "object" || Array.isArray(value)) {
+          return {};
+        }
+        return value;
+      }
       /**
        * Get the agent configuration from the underlying FlowState.
        * This is for backward compatibility with hooks that access state.agentConfig.
@@ -23258,6 +23582,39 @@ var DurableThread = class extends DurableObject {
       await this.setChildrenRegistry(next);
     }
   }
+  /**
+   * Persist the invocation arguments supplied when this subagent thread was
+   * created. These are hydrated into prompt-interpolation context on every
+   * activation of either side, so they survive for the life of the thread.
+   */
+  async setSubagentArguments(_threadId, args) {
+    await this.ensureMigrated();
+    const payload = args && typeof args === "object" && !Array.isArray(args) ? args : {};
+    await this.ctx.storage.sql.exec(
+      `INSERT OR REPLACE INTO execution_state (key, value) VALUES ('subagent_arguments', ?)`,
+      JSON.stringify(payload)
+    );
+  }
+  /**
+   * Read the persisted invocation arguments for this subagent thread.
+   * Returns an empty object when none were stored.
+   */
+  async getSubagentArguments(_threadId) {
+    await this.ensureMigrated();
+    const cursor = await this.ctx.storage.sql.exec(
+      `SELECT value FROM execution_state WHERE key = 'subagent_arguments' LIMIT 1`
+    );
+    const raw = cursor.toArray()[0]?.value;
+    if (!raw) {
+      return {};
+    }
+    try {
+      const parsed = JSON.parse(raw);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    } catch {
+      return {};
+    }
+  }
   asOptionalString(value) {
     if (typeof value !== "string") {
       return null;
@@ -25805,6 +26162,23 @@ ${resultContent}${attachmentSummary}`;
       console.error("[DurableThread] Alarm handler failed:", error);
     }
   }
+  normalizePlainRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return null;
+    }
+    return value;
+  }
+  buildExecutionArguments(data, properties) {
+    const dataRecord = this.normalizePlainRecord(data) ?? {};
+    const persistedInitialArguments = this.normalizePlainRecord(
+      properties?.[SUBAGENT_INITIAL_ARGUMENTS_THREAD_PROPERTY]
+    );
+    const initialArguments = persistedInitialArguments ?? dataRecord;
+    if (!initialArguments || Object.keys(initialArguments).length === 0) {
+      return {};
+    }
+    return initialArguments;
+  }
   /**
    * Internal method: Execute a flow (called by alarm queue)
    * This is the actual execution logic, separate from the public execute() RPC method
@@ -25934,6 +26308,7 @@ ${resultContent}${attachmentSummary}`;
         emitMessageChunk: (messageId, chunk, depth) => this.broadcastMessageChunk(messageId, chunk, depth),
         emitTelemetry: (event) => this.broadcastTelemetry(event),
         emitEvent: (type, data2) => this.broadcastEvent(type, data2),
+        arguments: this.buildExecutionArguments(data, thread.properties),
         rootMessageId,
         abortController: this.currentAbortController
       }, awaitCompletion);
@@ -27203,6 +27578,7 @@ async function decryptEnvs(encrypted, encryptionKey) {
 }
 
 // src/durable-objects/DurableAgentBuilder.ts
+init_types();
 var ENV_TYPES_PROPERTY = "__agentbuilder_env_types";
 var DurableAgentBuilder = class extends DurableObject {
   migratedToVersion = null;
@@ -27228,6 +27604,45 @@ var DurableAgentBuilder = class extends DurableObject {
     }
     return Object.keys(result).length > 0 ? result : null;
   }
+  normalizePlainObject(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input)) {
+      return void 0;
+    }
+    const result = { ...input };
+    return Object.keys(result).length > 0 ? result : void 0;
+  }
+  hasInitialArguments(args) {
+    return Object.keys(args).length > 0;
+  }
+  buildSubagentThreadProperties(initialArguments) {
+    if (!this.hasInitialArguments(initialArguments)) {
+      return void 0;
+    }
+    return {
+      [SUBAGENT_INITIAL_ARGUMENTS_THREAD_PROPERTY]: initialArguments
+    };
+  }
+  buildSubagentInitialArgumentsMessage(initialArguments, createdAt) {
+    if (!this.hasInitialArguments(initialArguments)) {
+      return null;
+    }
+    return {
+      id: crypto.randomUUID(),
+      role: "system",
+      content: [
+        "Persistent initial arguments for this subagent thread.",
+        "These values were supplied by the parent when the child was created and remain in effect for side_a and side_b.",
+        "They are available as ThreadState.arguments and prompt variables by their top-level keys.",
+        "",
+        JSON.stringify(initialArguments, null, 2)
+      ].join("\n"),
+      silent: true,
+      metadata: {
+        subagentInitialArguments: true
+      },
+      created_at: createdAt
+    };
+  }
   normalizeEnvTypeRecord(input, env) {
     if (!input || typeof input !== "object" || !env) {
       return null;
@@ -28293,10 +28708,12 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
       initial_message_attachments: this.normalizePendingAttachments(
         params.payload.initial_message_attachments
       ),
+      initial_arguments: this.normalizePlainObject(params.payload.initial_arguments),
       initial_agent_name: typeof params.payload.initial_agent_name === "string" ? params.payload.initial_agent_name : null,
       agent_title: typeof params.payload.agent_title === "string" ? params.payload.agent_title : null,
       agent_description: typeof params.payload.agent_description === "string" ? params.payload.agent_description : null,
-      spawn_group_id: typeof params.payload.spawn_group_id === "string" ? params.payload.spawn_group_id : null
+      spawn_group_id: typeof params.payload.spawn_group_id === "string" ? params.payload.spawn_group_id : null,
+      arguments: params.payload.arguments && typeof params.payload.arguments === "object" && !Array.isArray(params.payload.arguments) ? params.payload.arguments : {}
     };
     await this.ctx.storage.sql.exec(
       `INSERT INTO pending_subagent_env_requests (
@@ -28358,7 +28775,8 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
       initial_agent_name: typeof payloadObject.initial_agent_name === "string" ? payloadObject.initial_agent_name : null,
       agent_title: typeof payloadObject.agent_title === "string" ? payloadObject.agent_title : null,
       agent_description: typeof payloadObject.agent_description === "string" ? payloadObject.agent_description : null,
-      spawn_group_id: typeof payloadObject.spawn_group_id === "string" ? payloadObject.spawn_group_id : null
+      spawn_group_id: typeof payloadObject.spawn_group_id === "string" ? payloadObject.spawn_group_id : null,
+      arguments: payloadObject.arguments && typeof payloadObject.arguments === "object" && !Array.isArray(payloadObject.arguments) ? payloadObject.arguments : {}
     };
     let requiredRaw = [];
     let missingRaw = [];
@@ -28411,16 +28829,26 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
       );
     }
     const initialAgentName = typeof pending.payload.initial_agent_name === "string" ? pending.payload.initial_agent_name.replace(/\s+/g, " ").trim() : "";
+    const initialArguments = this.normalizePlainObject(pending.payload.initial_arguments) ?? {};
     const childThread = await this.createThread({
       agent_name: pending.agent_name,
       parent: params.parent_thread_id,
       env: providedEnv,
+      properties: this.buildSubagentThreadProperties(initialArguments),
       tags: initialAgentName ? [this.buildThreadNameTag(initialAgentName)] : void 0
     });
     const parentId = this.env.AGENT_BUILDER_THREAD.idFromName(params.parent_thread_id);
     const childId = this.env.AGENT_BUILDER_THREAD.idFromName(childThread.id);
     const parentThread = this.env.AGENT_BUILDER_THREAD.get(parentId);
     const childThreadStub = this.env.AGENT_BUILDER_THREAD.get(childId);
+    const pendingArguments = pending.payload.arguments;
+    if (pendingArguments && typeof pendingArguments === "object" && !Array.isArray(pendingArguments) && Object.keys(pendingArguments).length > 0 && typeof childThreadStub.setSubagentArguments === "function") {
+      try {
+        await childThreadStub.setSubagentArguments(childThread.id, pendingArguments);
+      } catch (error) {
+        console.error("[DurableAgentBuilder] Failed to persist subagent arguments:", error);
+      }
+    }
     const canCopyInitialAttachments = typeof parentThread.readFile === "function" && typeof parentThread.statFile === "function" && typeof childThreadStub.writeFile === "function";
     const initialAttachments = canCopyInitialAttachments ? await this.copyPendingAttachmentsBetweenThreads(
       {
@@ -28435,6 +28863,14 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
     const targetRole = pending.payload.receives_messages === "side_b" ? "assistant" : "user";
     const baseTimestamp = Date.now() * 1e3;
     const initialMessages = [];
+    const initialArgumentsMessage = this.buildSubagentInitialArgumentsMessage(
+      initialArguments,
+      baseTimestamp
+    );
+    if (initialArgumentsMessage) {
+      initialMessages.push(initialArgumentsMessage);
+    }
+    const timestampOffset = initialMessages.length;
     for (let i = 0; i < initialAttachments.length; i++) {
       const attachment = initialAttachments[i];
       initialMessages.push({
@@ -28443,7 +28879,7 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
         content: `Initial asset attachment path: ${attachment.path}`,
         attachments: JSON.stringify([attachment]),
         silent: true,
-        created_at: baseTimestamp + i
+        created_at: baseTimestamp + timestampOffset + i
       });
     }
     initialMessages.push({
@@ -28451,7 +28887,7 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
       role: targetRole,
       content: pending.payload.initial_message_content,
       attachments: void 0,
-      created_at: baseTimestamp + initialAttachments.length
+      created_at: baseTimestamp + timestampOffset + initialAttachments.length
     });
     if (typeof parentThread.upsertChildRegistry === "function") {
       await parentThread.upsertChildRegistry(params.parent_thread_id, {
@@ -28462,6 +28898,7 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
         resumable: pending.payload.resumable,
         blocking: pending.payload.blocking,
         status: "running",
+        ...this.hasInitialArguments(initialArguments) ? { initialArguments } : {},
         ...initialAgentName ? { threadName: initialAgentName } : {},
         ...pending.payload.spawn_group_id ? { spawnGroupId: pending.payload.spawn_group_id } : {},
         createdAt: Date.now() * 1e3
@@ -28476,7 +28913,7 @@ ${result ?? error ?? "No result content."}${attachmentSummary}`;
           childThread.id,
           pending.agent_name,
           initialMessages,
-          {}
+          initialArguments
         );
         const resultAttachments = Array.isArray(childResult.attachments) && childResult.attachments.length > 0 && typeof childThreadStub.readFile === "function" && typeof childThreadStub.statFile === "function" && typeof parentThread.writeFile === "function" ? await this.copyPendingAttachmentsBetweenThreads(
           {