@standardagents/builder 0.19.2 → 0.20.0

package/dist/built-in-routes.js

@@ -47,9 +47,10 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // 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;
@@ -3630,9 +3631,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
@@ -3823,6 +3823,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;
@@ -3921,6 +3922,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"
@@ -3975,10 +3990,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();
@@ -4000,11 +4017,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, {
@@ -4028,7 +4047,8 @@ ${errorLines.join("\n")}`);
             stub,
             initialMessageContent,
             receivesMessages,
-            initialMessageAttachments
+            initialMessageAttachments,
+            initialArguments
           );
           await this.upsertChildRegistry(state, {
             reference: childThreadId,
@@ -4039,6 +4059,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
@@ -4048,7 +4069,7 @@ ${errorLines.join("\n")}`);
               childThreadId,
               agentName,
               initialMessages,
-              {}
+              initialArguments
             );
             const copiedAttachments = await this.copyAttachmentsBetweenThreads(
               stub,
@@ -4081,7 +4102,7 @@ ${errorLines.join("\n")}`);
                 childThreadId,
                 agentName,
                 initialMessages,
-                {}
+                initialArguments
               );
               const copiedAttachments = await this.copyAttachmentsBetweenThreads(
                 stub,
@@ -4212,21 +4233,38 @@ ${errorLines.join("\n")}`);
         const message = typeof args.message === "string" ? args.message : "";
         const attachments = args.attachments;
         const name15 = typeof args.name === "string" ? args.name.trim() : "";
+        const rawArguments = args.arguments;
+        const initialArguments = this.isPlainRecord(rawArguments) ? rawArguments : {};
         if (!agent) {
           return {
             agent: "",
             message,
             attachments,
             name: name15,
+            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: name15,
+            initialArguments,
+            arguments: initialArguments,
+            error: `${SUBAGENT_CREATE_TOOL} arguments must be an object when provided.`
+          };
+        }
         if (!message.trim()) {
           return {
             agent,
             message,
             attachments,
             name: name15,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} requires message.`
           };
         }
@@ -4236,6 +4274,8 @@ ${errorLines.join("\n")}`);
             message,
             attachments,
             name: name15,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} requires attachments (use [] when none).`
           };
         }
@@ -4245,6 +4285,8 @@ ${errorLines.join("\n")}`);
             message,
             attachments,
             name: name15,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} name must be a string when provided.`
           };
         }
@@ -4254,10 +4296,141 @@ ${errorLines.join("\n")}`);
             message,
             attachments,
             name: name15,
+            initialArguments,
+            arguments: initialArguments,
             error: `${SUBAGENT_CREATE_TOOL} requires name.`
           };
         }
-        return { agent, message, attachments, name: name15 };
+        return {
+          agent,
+          message,
+          attachments,
+          name: name15,
+          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((path9) => path9.length > 0)
+            )
+          );
+          const detail = issues.map((issue) => {
+            const path9 = Array.isArray(issue.path) ? issue.path.map(String).join(".") : "";
+            const message = typeof issue.message === "string" ? issue.message : "invalid value";
+            return path9 ? `${path9}: ${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") {
@@ -4337,7 +4510,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,
@@ -4347,6 +4520,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({
@@ -4355,7 +4536,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({
@@ -4365,7 +4546,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;
       }
@@ -5764,6 +5945,7 @@ var init_FlowEngine = __esm({
           },
           queue: stateInput.queue || [],
           stream,
+          arguments: stateInput.arguments || {},
           context: stateInput.context || {},
           retryCount: stateInput.retryCount || 0,
           retryReason: stateInput.retryReason,
@@ -5800,8 +5982,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
        */
@@ -6898,6 +7116,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;
@@ -6972,7 +7200,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(
@@ -7130,10 +7358,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",
@@ -7585,13 +7816,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;
@@ -7613,18 +7852,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((name15) => !required.includes(name15));
+        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",
@@ -7634,6 +7941,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: {
@@ -7658,8 +7966,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"]
             }
           }
@@ -11185,6 +11495,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 {
@@ -11232,6 +11543,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.