@xyne/workflow-sdk 2.2.0 → 2.3.0

package/dist/agents/agent-step.d.ts

@@ -23,20 +23,54 @@ export declare const AgentStepConfigSchema: z.ZodObject<{
     requireApproval: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     maxTurns: z.ZodDefault<z.ZodNumber>;
     toolTimeout: z.ZodDefault<z.ZodNumber>;
+    attachments: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        mimeType: z.ZodString;
+        data: z.ZodString;
+        size: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }, {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }>, "many">, z.ZodString]>>;
+    outputType: z.ZodDefault<z.ZodEnum<["string", "json"]>>;
+    outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     systemPrompt: string;
     userMessage: string;
     maxTurns: number;
     toolTimeout: number;
+    outputType: "string" | "json";
+    attachments?: string | {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }[] | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
     tools?: string[] | undefined;
     requireApproval?: string[] | undefined;
 }, {
     systemPrompt: string;
     userMessage: string;
+    attachments?: string | {
+        name: string;
+        mimeType: string;
+        data: string;
+        size?: number | undefined;
+    }[] | undefined;
+    outputSchema?: Record<string, unknown> | undefined;
     tools?: string[] | undefined;
     requireApproval?: string[] | undefined;
     maxTurns?: number | undefined;
     toolTimeout?: number | undefined;
+    outputType?: "string" | "json" | undefined;
 }>;
 export type AgentStepConfig = z.infer<typeof AgentStepConfigSchema>;
 export declare class AgentStep extends BaseActionStep<typeof AgentStepConfigSchema, AgentResult> {
@@ -52,23 +86,57 @@ export declare class AgentStep extends BaseActionStep<typeof AgentStepConfigSche
         requireApproval: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         maxTurns: z.ZodDefault<z.ZodNumber>;
         toolTimeout: z.ZodDefault<z.ZodNumber>;
+        attachments: z.ZodOptional<z.ZodUnion<[z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            mimeType: z.ZodString;
+            data: z.ZodString;
+            size: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }, {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }>, "many">, z.ZodString]>>;
+        outputType: z.ZodDefault<z.ZodEnum<["string", "json"]>>;
+        outputSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         systemPrompt: string;
         userMessage: string;
         maxTurns: number;
         toolTimeout: number;
+        outputType: "string" | "json";
+        attachments?: string | {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }[] | undefined;
+        outputSchema?: Record<string, unknown> | undefined;
         tools?: string[] | undefined;
         requireApproval?: string[] | undefined;
     }, {
         systemPrompt: string;
         userMessage: string;
+        attachments?: string | {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }[] | undefined;
+        outputSchema?: Record<string, unknown> | undefined;
         tools?: string[] | undefined;
         requireApproval?: string[] | undefined;
         maxTurns?: number | undefined;
         toolTimeout?: number | undefined;
+        outputType?: "string" | "json" | undefined;
     }>;
     readonly outputSchema: z.ZodObject<{
-        response: z.ZodString;
+        response: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
         toolCalls: z.ZodArray<z.ZodObject<{
             name: z.ZodString;
             args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -96,8 +164,30 @@ export declare class AgentStep extends BaseActionStep<typeof AgentStepConfigSche
             inputTokens: number;
             outputTokens: number;
         }>;
+        attachments: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            mimeType: z.ZodString;
+            data: z.ZodString;
+            size: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }, {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }>, "many">;
     }, "strip", z.ZodTypeAny, {
-        response: string;
+        attachments: {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }[];
+        response: string | Record<string, unknown>;
         toolCalls: {
             name: string;
             args: Record<string, unknown>;
@@ -110,7 +200,13 @@ export declare class AgentStep extends BaseActionStep<typeof AgentStepConfigSche
             outputTokens: number;
         };
     }, {
-        response: string;
+        attachments: {
+            name: string;
+            mimeType: string;
+            data: string;
+            size?: number | undefined;
+        }[];
+        response: string | Record<string, unknown>;
         toolCalls: {
             name: string;
             args: Record<string, unknown>;
@@ -126,6 +222,7 @@ export declare class AgentStep extends BaseActionStep<typeof AgentStepConfigSche
     readonly category: StepCategory;
     constructor(runtime: BaseAgentRuntime, toolRegistry: AgentToolRegistry);
     decorateConfigSchema(jsonSchema: Record<string, unknown>): Record<string, unknown>;
+    resolveOutputJsonSchema(config: Record<string, unknown>): Record<string, unknown>;
     execute(config: AgentStepConfig, ctx: StepExecutionContext): Promise<AgentResult>;
     /**
      * Continue a prior conversation. Called from `execute()` when
@@ -148,5 +245,20 @@ export declare class AgentStep extends BaseActionStep<typeof AgentStepConfigSche
     private buildHooks;
     private consumeEvents;
     private buildResult;
+    /**
+     * Open the per-execution tool runtime: an artifact sink (backed by storage)
+     * and — when a SandboxAdapter is configured and the `run_code` tool is
+     * enabled — one sandbox session with the step's input attachments mounted at
+     * `/mnt/files`. Returns the extras to merge into each tool's context, the
+     * collected-artifacts array, and a `dispose()` that tears the sandbox down.
+     */
+    /** Append the uploaded-files note to the system prompt when files were mounted. */
+    private withAttachmentsNote;
+    private openToolRuntime;
+    /**
+     * Attach collected artifacts and shape `response` per `outputType`
+     * (parse JSON when requested). Applied to every successful agent result.
+     */
+    private finalizeResult;
 }
 //# sourceMappingURL=agent-step.d.ts.map

package/dist/agents/agent-step.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-step.d.ts","sourceRoot":"","sources":["../../src/agents/agent-step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAQ5D,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,YAAY,CAAC;AAIpB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;EAOhC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAiDpE,qBAAa,SAAU,SAAQ,cAAc,CAC3C,OAAO,qBAAqB,EAC5B,WAAW,CACZ;IASG,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAT/B,SAAkB,IAAI,EAAE,QAAQ,CAAe;IAC/C,SAAkB,IAAI,eAAe;IACrC,SAAkB,WAAW,qCAAqC;IAClE,SAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;OAAyB;IACvD,SAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAqB;IACnD,SAAkB,QAAQ,EAAE,YAAY,CAAQ;gBAG7B,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,iBAAiB;IAKzC,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAyB5E,OAAO,CACpB,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,WAAW,CAAC;IA2CvB;;;;;;;OAOG;YACW,oBAAoB;IAkDnB,QAAQ,CACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,WAAW,CAAC;IAiDvB,OAAO,CAAC,YAAY;IA8BpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,UAAU;YAmBJ,aAAa;IAoI3B,OAAO,CAAC,WAAW;CAkBpB"}
+{"version":3,"file":"agent-step.d.ts","sourceRoot":"","sources":["../../src/agents/agent-step.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAa5D,OAAO,KAAK,EACV,WAAW,EAKZ,MAAM,YAAY,CAAC;AAIpB,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAehC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AA2EpE,qBAAa,SAAU,SAAQ,cAAc,CAC3C,OAAO,qBAAqB,EAC5B,WAAW,CACZ;IASG,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAT/B,SAAkB,IAAI,EAAE,QAAQ,CAAe;IAC/C,SAAkB,IAAI,eAAe;IACrC,SAAkB,WAAW,qCAAqC;IAClE,SAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAyB;IACvD,SAAkB,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAAqB;IACnD,SAAkB,QAAQ,EAAE,YAAY,CAAQ;gBAG7B,OAAO,EAAE,gBAAgB,EACzB,YAAY,EAAE,iBAAiB;IAKzC,oBAAoB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IA8BlF,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAmB3E,OAAO,CACpB,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,WAAW,CAAC;IA0CvB;;;;;;;OAOG;YACW,oBAAoB;IA0DnB,QAAQ,CACrB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,WAAW,CAAC;IAwDvB,OAAO,CAAC,YAAY;IAgCpB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAWvB,OAAO,CAAC,iBAAiB;IAazB,OAAO,CAAC,UAAU;YAgBJ,aAAa;IA8H3B,OAAO,CAAC,WAAW;IAsBnB;;;;;;OAMG;IACH,mFAAmF;IACnF,OAAO,CAAC,mBAAmB;YAQb,eAAe;IAqE7B;;;OAGG;IACH,OAAO,CAAC,cAAc;CAWvB"}

package/dist/agents/agent-step.js

@@ -10,6 +10,9 @@
  */
 import { z } from 'zod';
 import { BaseActionStep } from '../steps/base-step.js';
+import { variableRef } from '../types/workflow-config.js';
+import { AttachmentSchema, ATTACHMENT_ARRAY_JSON_SCHEMA, markAttachmentFields } from '../common/attachment.js';
+import { bindSandboxSession } from '../sandbox/types.js';
 import { runInterceptorChain, } from './interceptor.js';
 import { ApprovalGateInterceptor } from './interceptors/approval-gate.js';
 import { ToolLoggingInterceptor } from './interceptors/tool-logger.js';
@@ -21,10 +24,16 @@ export const AgentStepConfigSchema = z.object({
     requireApproval: z.array(z.string()).optional().describe('Tool names that require human approval before execution'),
     maxTurns: z.number().int().min(1).default(10).describe('Maximum number of agent reasoning turns'),
     toolTimeout: z.number().int().positive().default(30_000).describe('Timeout per tool call in milliseconds'),
+    attachments: variableRef(z.array(AttachmentSchema)
+        .describe('Input documents mounted into the sandbox at /mnt/files. Bind to a ref, e.g. {{trigger.attachments}}')).optional(),
+    outputType: z.enum(['string', 'json']).default('string')
+        .describe('Shape of the agent response: free text, or a JSON object matching outputSchema'),
+    outputSchema: z.record(z.unknown()).optional()
+        .describe('When outputType is "json", the JSON Schema the response object should match'),
 });
 // ─── Result Schema ───
 const AgentResultSchema = z.object({
-    response: z.string(),
+    response: z.union([z.string(), z.record(z.unknown())]),
     toolCalls: z.array(z.object({
         name: z.string(),
         args: z.record(z.unknown()),
@@ -36,6 +45,7 @@ const AgentResultSchema = z.object({
         inputTokens: z.number(),
         outputTokens: z.number(),
     }),
+    attachments: z.array(AttachmentSchema),
 });
 // ─── Utility ───
 function withTimeout(promise, timeoutMs) {
@@ -50,13 +60,34 @@ function withTimeout(promise, timeoutMs) {
         }),
     ]);
 }
-/** Extract text content from an AssistantMessage. */
+/** Extract text content from an AssistantMessage.
+ *
+ * Tolerant of the shapes different providers/runtimes return for `content`:
+ * an array of content blocks (pi-ai), a plain string (OpenAI/LiteLLM-style),
+ * or null/undefined (tool-call-only turns). */
 function extractResponseText(message) {
-    return message.content
-        .filter((c) => c.type === 'text')
+    const content = message.content;
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .filter((c) => !!c && typeof c === 'object' && c.type === 'text'
+        && typeof c.text === 'string')
         .map((c) => c.text)
         .join('');
 }
+/**
+ * Tell the agent which uploaded files are available, so it knows to read them
+ * via `run_code` (otherwise it has no idea attachments exist). Appended to the
+ * system prompt when input attachments were mounted into the sandbox.
+ */
+function attachmentsSystemNote(files) {
+    const list = files.map((f) => `/mnt/files/${f}`).join(', ');
+    return (`\n\nThe user attached ${files.length} file(s), available in the sandbox at: ${list}. `
+        + `Use the run_code tool to read them (e.g. open the file under /mnt/files) before responding. `
+        + `Write any files you generate to /mnt/output.`);
+}
 // ─── AgentStep ───
 export class AgentStep extends BaseActionStep {
     runtime;
@@ -73,12 +104,16 @@ export class AgentStep extends BaseActionStep {
         this.toolRegistry = toolRegistry;
     }
     decorateConfigSchema(jsonSchema) {
-        const toolNames = this.toolRegistry.getNames();
-        if (toolNames.length === 0)
-            return jsonSchema;
         const props = jsonSchema['properties'];
         if (!props)
             return jsonSchema;
+        if (props['outputSchema']) {
+            props['outputSchema'] = { ...props['outputSchema'], format: 'json-schema' };
+        }
+        markAttachmentFields(jsonSchema, ['attachments']);
+        const toolNames = this.toolRegistry.getNames();
+        if (toolNames.length === 0)
+            return jsonSchema;
         // Inject enum into tools array items so the generic renderer shows multi-select
         if (props['tools']?.['items']) {
             props['tools'] = {
@@ -95,6 +130,22 @@ export class AgentStep extends BaseActionStep {
         }
         return jsonSchema;
     }
+    resolveOutputJsonSchema(config) {
+        const outputType = config['outputType'] === 'json' ? 'json' : 'string';
+        const userSchema = config['outputSchema'];
+        const response = outputType === 'json'
+            ? (userSchema && Object.keys(userSchema).length > 0 ? userSchema : { type: 'object' })
+            : { type: 'string' };
+        return {
+            type: 'object',
+            properties: {
+                response,
+                attachments: ATTACHMENT_ARRAY_JSON_SCHEMA,
+                toolCalls: { type: 'array' },
+                usage: { type: 'object' },
+            },
+        };
+    }
     async execute(config, ctx) {
         // Conversation continuity: when a prior run left messages (review-gate
         // retry or rerunFromStep), continue the conversation with the new
@@ -107,24 +158,26 @@ export class AgentStep extends BaseActionStep {
         const workflowTools = config.tools
             ? this.toolRegistry.resolve(config.tools)
             : [];
-        // 2. Convert WorkflowTools → pi-mono AgentTools
-        const piTools = this.convertTools(workflowTools, config.toolTimeout, ctx);
-        // 3. Clamp maxTurns if runtime doesn't support multi-turn
-        const effectiveMaxTurns = this.runtime.capabilities.multiTurn
-            ? config.maxTurns
-            : 1;
-        // 4. Build interceptor chain
-        const interceptors = this.buildInterceptors(config, ctx);
-        // 5. Map interceptors → AgentHooks
-        const hooks = this.buildHooks(interceptors, ctx);
-        // 6. Execute runtime
-        const events = this.runtime.execute(config, {
-            tools: this.runtime.capabilities.toolUse ? piTools : [],
-            hooks: this.runtime.capabilities.hooks ? hooks : {},
-            signal: ctx.runtime.metadata['signal'] ?? new AbortController().signal,
-        }, ctx);
-        // 7. Consume event stream
-        return this.consumeEvents(events, ctx, effectiveMaxTurns);
+        const bag = await this.openToolRuntime(config, ctx);
+        try {
+            const runConfig = this.withAttachmentsNote(config, bag.mountedFiles);
+            const piTools = this.convertTools(workflowTools, config.toolTimeout, ctx, bag.extras);
+            const effectiveMaxTurns = this.runtime.capabilities.multiTurn
+                ? config.maxTurns
+                : 1;
+            const interceptors = this.buildInterceptors(config, ctx);
+            const hooks = this.buildHooks(interceptors, ctx);
+            const events = this.runtime.execute(runConfig, {
+                tools: this.runtime.capabilities.toolUse ? piTools : [],
+                hooks: this.runtime.capabilities.hooks ? hooks : {},
+                signal: ctx.runtime.metadata['signal'] ?? new AbortController().signal,
+            }, ctx);
+            const result = await this.consumeEvents(events, ctx, effectiveMaxTurns);
+            return this.finalizeResult(result, config, bag.collected);
+        }
+        finally {
+            await bag.dispose();
+        }
     }
     /**
      * Continue a prior conversation. Called from `execute()` when
@@ -139,42 +192,50 @@ export class AgentStep extends BaseActionStep {
         const workflowTools = config.tools
             ? this.toolRegistry.resolve(config.tools)
             : [];
-        const piTools = this.convertTools(workflowTools, config.toolTimeout, ctx);
-        const interceptors = this.buildInterceptors(config, ctx);
-        const hooks = this.buildHooks(interceptors, ctx);
         const effectiveMaxTurns = this.runtime.capabilities.multiTurn
             ? config.maxTurns
             : 1;
         const completedToolCalls = priorState.completedToolCalls ?? [];
         const usage = priorState.usage ?? { inputTokens: 0, outputTokens: 0 };
         const currentTurn = priorState.currentTurn ?? 0;
-        const input = {
-            tools: this.runtime.capabilities.toolUse ? piTools : [],
-            hooks: this.runtime.capabilities.hooks ? hooks : {},
-            signal: ctx.runtime.metadata['signal'] ?? new AbortController().signal,
-            resume: {
-                messages: priorMessages,
-                payload: { action: 'approve', feedback: config.userMessage },
-                pauseState: {
-                    type: 'awaiting_feedback',
-                    reason: 'Continuing prior conversation',
-                    prompt: config.userMessage,
-                    state: {
-                        messages: priorMessages,
-                        currentTurn,
-                        completedToolCalls,
-                        usage,
+        const bag = await this.openToolRuntime(config, ctx);
+        try {
+            const runConfig = this.withAttachmentsNote(config, bag.mountedFiles);
+            const piTools = this.convertTools(workflowTools, config.toolTimeout, ctx, bag.extras);
+            const interceptors = this.buildInterceptors(config, ctx);
+            const hooks = this.buildHooks(interceptors, ctx);
+            const input = {
+                tools: this.runtime.capabilities.toolUse ? piTools : [],
+                hooks: this.runtime.capabilities.hooks ? hooks : {},
+                signal: ctx.runtime.metadata['signal'] ?? new AbortController().signal,
+                resume: {
+                    messages: priorMessages,
+                    payload: { action: 'approve', feedback: config.userMessage },
+                    pauseState: {
+                        type: 'awaiting_feedback',
+                        reason: 'Continuing prior conversation',
+                        prompt: config.userMessage,
+                        state: {
+                            messages: priorMessages,
+                            currentTurn,
+                            completedToolCalls,
+                            usage,
+                        },
                     },
                 },
-            },
-        };
-        const events = this.runtime.execute(config, input, ctx);
-        return this.consumeEvents(events, ctx, effectiveMaxTurns, {
-            messages: priorMessages,
-            currentTurn,
-            completedToolCalls,
-            usage,
-        });
+            };
+            const events = this.runtime.execute(runConfig, input, ctx);
+            const result = await this.consumeEvents(events, ctx, effectiveMaxTurns, {
+                messages: priorMessages,
+                currentTurn,
+                completedToolCalls,
+                usage,
+            });
+            return this.finalizeResult(result, config, bag.collected);
+        }
+        finally {
+            await bag.dispose();
+        }
     }
     async onResume(rowData, config, ctx) {
         const pauseState = rowData;
@@ -188,36 +249,45 @@ export class AgentStep extends BaseActionStep {
                 toolCalls: pauseState.completedToolCalls,
                 turnCount: pauseState.currentTurn,
                 usage: pauseState.usage,
+                attachments: [],
             };
         }
         // Resolve tools again (MCP tools may have changed)
         const workflowTools = config.tools
             ? this.toolRegistry.resolve(config.tools)
             : [];
-        const piTools = this.convertTools(workflowTools, config.toolTimeout, ctx);
-        const interceptors = this.buildInterceptors(config, ctx);
-        const hooks = this.buildHooks(interceptors, ctx);
         const effectiveMaxTurns = this.runtime.capabilities.multiTurn
             ? config.maxTurns
             : 1;
-        const input = {
-            tools: this.runtime.capabilities.toolUse ? piTools : [],
-            hooks: this.runtime.capabilities.hooks ? hooks : {},
-            signal: ctx.runtime.metadata['signal'] ?? new AbortController().signal,
-        };
-        if (pauseRequest) {
-            input.resume = {
-                messages: pauseState.messages,
-                payload: resumePayload ?? { action: 'approve' },
-                pauseState: pauseRequest,
+        const bag = await this.openToolRuntime(config, ctx);
+        try {
+            const runConfig = this.withAttachmentsNote(config, bag.mountedFiles);
+            const piTools = this.convertTools(workflowTools, config.toolTimeout, ctx, bag.extras);
+            const interceptors = this.buildInterceptors(config, ctx);
+            const hooks = this.buildHooks(interceptors, ctx);
+            const input = {
+                tools: this.runtime.capabilities.toolUse ? piTools : [],
+                hooks: this.runtime.capabilities.hooks ? hooks : {},
+                signal: ctx.runtime.metadata['signal'] ?? new AbortController().signal,
             };
+            if (pauseRequest) {
+                input.resume = {
+                    messages: pauseState.messages,
+                    payload: resumePayload ?? { action: 'approve' },
+                    pauseState: pauseRequest,
+                };
+            }
+            const events = this.runtime.execute(runConfig, input, ctx);
+            // Consume events, carrying over state from before pause
+            const result = await this.consumeEvents(events, ctx, effectiveMaxTurns, pauseState);
+            return this.finalizeResult(result, config, bag.collected);
+        }
+        finally {
+            await bag.dispose();
         }
-        const events = this.runtime.execute(config, input, ctx);
-        // Consume events, carrying over state from before pause
-        return this.consumeEvents(events, ctx, effectiveMaxTurns, pauseState);
     }
     // ─── Private: Tool conversion ───
-    convertTools(tools, timeoutMs, ctx) {
+    convertTools(tools, timeoutMs, ctx, extras) {
         return tools.map((tool) => ({
             name: tool.name,
             label: tool.name,
@@ -227,6 +297,7 @@ export class AgentStep extends BaseActionStep {
                 const result = await withTimeout(tool.execute(params, {
                     signal: signal ?? new AbortController().signal,
                     log: ctx.log,
+                    ...extras,
                 }), timeoutMs);
                 return {
                     content: [{ type: 'text', text: JSON.stringify(result) }],
@@ -258,17 +329,14 @@ export class AgentStep extends BaseActionStep {
         }
         return interceptors;
     }
-    buildHooks(interceptors, ctx) {
+    buildHooks(interceptors, _ctx) {
         return {
             async beforeToolCall(tool, args) {
                 return runInterceptorChain(interceptors, tool, args);
             },
-            async afterToolCall(tool, args, result) {
-                ctx.emit({
-                    type: 'tool_call',
-                    data: { tool, args, result, phase: 'end' },
-                });
-            },
+            // Note: the tool_call end event is emitted from consumeEvents
+            // (tool_execution_end) with the toolCallId, so we don't emit it here too
+            // (that produced duplicate timeline entries).
         };
     }
     // ─── Private: Event consumption ───
@@ -293,15 +361,9 @@ export class AgentStep extends BaseActionStep {
                 case 'message_start':
                     ctx.emit({ type: 'thinking', data: { phase: 'start' } });
                     break;
-                case 'message_update': {
-                    const updateMsg = event.message;
-                    const partialText = extractResponseText(updateMsg);
-                    ctx.emit({
-                        type: 'progress',
-                        data: { content: partialText },
-                    });
+                case 'message_update':
+                    // Partial streaming deltas — intentionally NOT emitted.
                     break;
-                }
                 case 'message_end': {
                     const endMsg = event.message;
                     state.messages.push(endMsg);
@@ -387,8 +449,85 @@ export class AgentStep extends BaseActionStep {
             toolCalls: state.completedToolCalls,
             turnCount: state.currentTurn,
             usage: state.usage,
+            attachments: [],
         };
     }
+    // ─── Private: Sandbox session + artifact sink (per execution) ───
+    /**
+     * Open the per-execution tool runtime: an artifact sink (backed by storage)
+     * and — when a SandboxAdapter is configured and the `run_code` tool is
+     * enabled — one sandbox session with the step's input attachments mounted at
+     * `/mnt/files`. Returns the extras to merge into each tool's context, the
+     * collected-artifacts array, and a `dispose()` that tears the sandbox down.
+     */
+    /** Append the uploaded-files note to the system prompt when files were mounted. */
+    withAttachmentsNote(config, mountedFiles) {
+        if (mountedFiles.length === 0)
+            return config;
+        return { ...config, systemPrompt: config.systemPrompt + attachmentsSystemNote(mountedFiles) };
+    }
+    async openToolRuntime(config, ctx) {
+        const collected = [];
+        const mountedFiles = [];
+        const scope = ctx.runtime.metadata;
+        const storage = ctx.storage;
+        const addArtifact = storage
+            ? async (file) => {
+                const att = await storage.store(scope, file);
+                collected.push(att);
+                return att;
+            }
+            : undefined;
+        const usesRunCode = config.tools?.includes('run_code') ?? false;
+        let handle;
+        let session;
+        if (ctx.sandbox && usesRunCode) {
+            handle = await ctx.sandbox.create({ scope });
+            session = bindSandboxSession(ctx.sandbox, handle);
+            // Mount the step's resolved input documents at /mnt/files. The field is a
+            // `variableRef` union (Attachment[] | ref-string); by execute() the
+            // resolver has replaced any ref with the concrete array, so a non-array
+            // here means "nothing bound".
+            const inputs = Array.isArray(config.attachments) ? config.attachments : [];
+            if (inputs.length > 0 && storage) {
+                const files = await Promise.all(inputs.map(async (a) => ({
+                    path: `/mnt/files/${a.name}`,
+                    bytes: await storage.read(a),
+                })));
+                await session.writeFiles(files);
+                mountedFiles.push(...inputs.map((a) => a.name));
+            }
+        }
+        // Only the two narrow capabilities are exposed to tools; storage/scope/
+        // attachments stay internal to this step (used above to mount inputs and to
+        // back addArtifact).
+        const extras = {
+            ...(session ? { sandbox: session } : {}),
+            ...(addArtifact ? { addArtifact } : {}),
+        };
+        const dispose = async () => {
+            if (ctx.sandbox && handle) {
+                try {
+                    await ctx.sandbox.destroy(handle);
+                }
+                catch (err) {
+                    ctx.log.warn(`Failed to destroy sandbox: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        };
+        return { extras, collected, mountedFiles, dispose };
+    }
+    /**
+     * Attach collected artifacts and shape `response` per `outputType`
+     * (parse JSON when requested). Applied to every successful agent result.
+     */
+    finalizeResult(result, config, collected) {
+        let response = result.response;
+        if (config.outputType === 'json' && typeof response === 'string') {
+            response = parseJsonResponse(response);
+        }
+        return { ...result, response, attachments: collected };
+    }
 }
 /**
  * Pull prior conversation messages out of an opaque `priorState` blob.
@@ -402,4 +541,27 @@ function extractPriorMessages(priorState) {
         return null;
     return candidate;
 }
+/**
+ * Parse a JSON-mode agent response into an object. Strips Markdown code fences
+ * the model may wrap around the JSON. Falls back to `{ text }` if the response
+ * isn't valid JSON or isn't an object, so the output always matches the
+ * declared object shape.
+ */
+function parseJsonResponse(raw) {
+    const trimmed = raw.trim();
+    const unfenced = trimmed
+        .replace(/^```(?:json)?\s*/i, '')
+        .replace(/\s*```$/, '')
+        .trim();
+    try {
+        const parsed = JSON.parse(unfenced);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return { value: parsed };
+    }
+    catch {
+        return { text: raw };
+    }
+}
 //# sourceMappingURL=agent-step.js.map