@mindstudio-ai/remy 0.1.138 → 0.1.140

package/dist/headless.js

@@ -2352,7 +2352,30 @@ var listDirTool = {
             const capped = children.slice(0, MAX_CHILDREN);
             for (const child of capped) {
               if (child.isDirectory()) {
-                lines.push(`  ${child.name}/`);
+                const [childDisplay, childFinalPath] = await collapsePath(
+                  finalPath,
+                  child.name
+                );
+                lines.push(`  ${childDisplay}/`);
+                try {
+                  const grandchildren = await readAndSort(childFinalPath);
+                  const gcCapped = grandchildren.slice(0, MAX_CHILDREN);
+                  for (const gc of gcCapped) {
+                    if (gc.isDirectory()) {
+                      lines.push(`    ${gc.name}/`);
+                    } else {
+                      lines.push(
+                        await formatFile(childFinalPath, gc.name, "    ")
+                      );
+                    }
+                  }
+                  if (grandchildren.length > MAX_CHILDREN) {
+                    lines.push(
+                      `    ... and ${grandchildren.length - MAX_CHILDREN} more`
+                    );
+                  }
+                } catch {
+                }
               } else {
                 lines.push(await formatFile(finalPath, child.name, "  "));
               }
@@ -2865,8 +2888,10 @@ async function runSubAgent(config) {
     requestId,
     history,
     background,
-    onBackgroundComplete
+    onBackgroundComplete,
+    captureArtifacts
   } = config;
+  const artifacts = {};
   const bgAbort = background ? new AbortController() : null;
   const signal = background ? bgAbort.signal : parentSignal;
   const agentName = subAgentId || "sub-agent";
@@ -3038,7 +3063,12 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
       if (stopReason !== "tool_use" || toolCalls.length === 0) {
         statusWatcher.stop();
         const text = getPartialText(contentBlocks);
-        return { text, messages: thisInvocation() };
+        const hasArtifacts = Object.keys(artifacts).length > 0;
+        return {
+          text,
+          messages: thisInvocation(),
+          ...hasArtifacts ? { artifacts } : {}
+        };
       }
       log5.info("Tools executing", {
         requestId,
@@ -3149,6 +3179,12 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
           if (innerMsgs) {
             block.subAgentMessages = innerMsgs;
           }
+          if (captureArtifacts?.includes(block.name) && !r.isError) {
+            try {
+              artifacts[block.name] = JSON.parse(r.result);
+            } catch {
+            }
+          }
         }
         messages.push({
           role: "user",
@@ -3480,13 +3516,22 @@ var browserAutomationTool = {
           }
           return result2;
         },
-        toolRegistry: context.toolRegistry
+        toolRegistry: context.toolRegistry,
+        captureArtifacts: ["screenshotFullPage"]
       });
       try {
         await sidecarRequest("/reset-browser", {}, { timeout: 5e3 });
       } catch {
       }
       context.subAgentMessages?.set(context.toolCallId, result.messages);
+      const ss = result.artifacts?.screenshotFullPage;
+      if (ss?.url) {
+        return JSON.stringify({
+          text: result.text,
+          screenshotUrl: ss.url,
+          ...ss.styleMap ? { styleMap: ss.styleMap } : {}
+        });
+      }
       return result.text;
     } finally {
       release();
@@ -3534,19 +3579,18 @@ var screenshotTool = {
       if (input.instructions && context) {
         const task = input.path ? `Navigate to "${input.path}", then: ${input.instructions}. After completing these steps, take a full-page screenshot.` : `${input.instructions}. After completing these steps, take a full-page screenshot.`;
         const result = await browserAutomationTool.execute({ task }, context);
-        const urlMatch = result.match(
-          /https:\/\/[^\s"')]+\.(?:png|jpg|jpeg|webp)/i
-        );
-        if (!urlMatch) {
-          return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${result}`;
-        }
-        const url = urlMatch[0];
+        const resultStr = result;
+        let url;
         let styleMap;
         try {
-          const parsed = JSON.parse(result);
-          styleMap = parsed?.styleMap;
+          const parsed = JSON.parse(resultStr);
+          url = parsed.screenshotUrl;
+          styleMap = parsed.styleMap;
         } catch {
         }
+        if (!url) {
+          return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${resultStr}`;
+        }
         const analysisPrompt = buildScreenshotAnalysisPrompt({
           prompt: input.prompt,
           styleMap
@@ -3870,19 +3914,18 @@ async function execute5(input, onLog, context) {
     try {
       const task = input.path ? `Navigate to "${input.path}", then: ${input.instructions}. After completing these steps, take a full-page screenshot.` : `${input.instructions}. After completing these steps, take a full-page screenshot.`;
       const result = await browserAutomationTool.execute({ task }, context);
-      const urlMatch = result.match(
-        /https:\/\/[^\s"')]+\.(?:png|jpg|jpeg|webp)/i
-      );
-      if (!urlMatch) {
-        return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${result}`;
-      }
-      const url = urlMatch[0];
+      const resultStr = result;
+      let url;
       let styleMap;
       try {
-        const parsed = JSON.parse(result);
-        styleMap = parsed?.styleMap;
+        const parsed = JSON.parse(resultStr);
+        url = parsed.screenshotUrl;
+        styleMap = parsed.styleMap;
       } catch {
       }
+      if (!url) {
+        return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${resultStr}`;
+      }
       const analysisPrompt = buildScreenshotAnalysisPrompt({
         prompt: input.prompt,
         styleMap

package/dist/index.js

@@ -2660,7 +2660,30 @@ var init_listDir = __esm({
                 const capped = children.slice(0, MAX_CHILDREN);
                 for (const child of capped) {
                   if (child.isDirectory()) {
-                    lines.push(`  ${child.name}/`);
+                    const [childDisplay, childFinalPath] = await collapsePath(
+                      finalPath,
+                      child.name
+                    );
+                    lines.push(`  ${childDisplay}/`);
+                    try {
+                      const grandchildren = await readAndSort(childFinalPath);
+                      const gcCapped = grandchildren.slice(0, MAX_CHILDREN);
+                      for (const gc of gcCapped) {
+                        if (gc.isDirectory()) {
+                          lines.push(`    ${gc.name}/`);
+                        } else {
+                          lines.push(
+                            await formatFile(childFinalPath, gc.name, "    ")
+                          );
+                        }
+                      }
+                      if (grandchildren.length > MAX_CHILDREN) {
+                        lines.push(
+                          `    ... and ${grandchildren.length - MAX_CHILDREN} more`
+                        );
+                      }
+                    } catch {
+                    }
                   } else {
                     lines.push(await formatFile(finalPath, child.name, "  "));
                   }
@@ -3244,8 +3267,10 @@ async function runSubAgent(config) {
     requestId,
     history,
     background,
-    onBackgroundComplete
+    onBackgroundComplete,
+    captureArtifacts
   } = config;
+  const artifacts = {};
   const bgAbort = background ? new AbortController() : null;
   const signal = background ? bgAbort.signal : parentSignal;
   const agentName = subAgentId || "sub-agent";
@@ -3417,7 +3442,12 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
       if (stopReason !== "tool_use" || toolCalls.length === 0) {
         statusWatcher.stop();
         const text = getPartialText(contentBlocks);
-        return { text, messages: thisInvocation() };
+        const hasArtifacts = Object.keys(artifacts).length > 0;
+        return {
+          text,
+          messages: thisInvocation(),
+          ...hasArtifacts ? { artifacts } : {}
+        };
       }
       log6.info("Tools executing", {
         requestId,
@@ -3528,6 +3558,12 @@ ${partial}` : "[INTERRUPTED] Agent was interrupted before producing output.",
           if (innerMsgs) {
             block.subAgentMessages = innerMsgs;
           }
+          if (captureArtifacts?.includes(block.name) && !r.isError) {
+            try {
+              artifacts[block.name] = JSON.parse(r.result);
+            } catch {
+            }
+          }
         }
         messages.push({
           role: "user",
@@ -3895,13 +3931,22 @@ var init_browserAutomation = __esm({
               }
               return result2;
             },
-            toolRegistry: context.toolRegistry
+            toolRegistry: context.toolRegistry,
+            captureArtifacts: ["screenshotFullPage"]
           });
           try {
             await sidecarRequest("/reset-browser", {}, { timeout: 5e3 });
           } catch {
           }
           context.subAgentMessages?.set(context.toolCallId, result.messages);
+          const ss = result.artifacts?.screenshotFullPage;
+          if (ss?.url) {
+            return JSON.stringify({
+              text: result.text,
+              screenshotUrl: ss.url,
+              ...ss.styleMap ? { styleMap: ss.styleMap } : {}
+            });
+          }
           return result.text;
         } finally {
           release();
@@ -3959,19 +4004,18 @@ var init_screenshot2 = __esm({
           if (input.instructions && context) {
             const task = input.path ? `Navigate to "${input.path}", then: ${input.instructions}. After completing these steps, take a full-page screenshot.` : `${input.instructions}. After completing these steps, take a full-page screenshot.`;
             const result = await browserAutomationTool.execute({ task }, context);
-            const urlMatch = result.match(
-              /https:\/\/[^\s"')]+\.(?:png|jpg|jpeg|webp)/i
-            );
-            if (!urlMatch) {
-              return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${result}`;
-            }
-            const url = urlMatch[0];
+            const resultStr = result;
+            let url;
             let styleMap;
             try {
-              const parsed = JSON.parse(result);
-              styleMap = parsed?.styleMap;
+              const parsed = JSON.parse(resultStr);
+              url = parsed.screenshotUrl;
+              styleMap = parsed.styleMap;
             } catch {
             }
+            if (!url) {
+              return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${resultStr}`;
+            }
             const analysisPrompt = buildScreenshotAnalysisPrompt({
               prompt: input.prompt,
               styleMap
@@ -4311,19 +4355,18 @@ async function execute5(input, onLog, context) {
     try {
       const task = input.path ? `Navigate to "${input.path}", then: ${input.instructions}. After completing these steps, take a full-page screenshot.` : `${input.instructions}. After completing these steps, take a full-page screenshot.`;
       const result = await browserAutomationTool.execute({ task }, context);
-      const urlMatch = result.match(
-        /https:\/\/[^\s"')]+\.(?:png|jpg|jpeg|webp)/i
-      );
-      if (!urlMatch) {
-        return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${result}`;
-      }
-      const url = urlMatch[0];
+      const resultStr = result;
+      let url;
       let styleMap;
       try {
-        const parsed = JSON.parse(result);
-        styleMap = parsed?.styleMap;
+        const parsed = JSON.parse(resultStr);
+        url = parsed.screenshotUrl;
+        styleMap = parsed.styleMap;
       } catch {
       }
+      if (!url) {
+        return `Error: browser navigation completed but no screenshot URL was returned. Agent output: ${resultStr}`;
+      }
       const analysisPrompt = buildScreenshotAnalysisPrompt({
         prompt: input.prompt,
         styleMap

package/dist/prompt/compiled/methods.md

@@ -245,20 +245,54 @@ export function getApprovalState(approvals: Approval[]) {
 
 ## Streaming
 
-Methods can stream token-by-token output (useful for AI-generated content):
+Methods can push real-time updates to the frontend using `stream()`. This is the standard pattern for any method that takes more than a few seconds.
 
 ```typescript
-// Frontend
-const result = await api.generateReport(
-  { month: 'march' },
+import { mindstudio, stream } from '@mindstudio-ai/agent';
+
+export async function enrichProfile(input: { name: string }) {
+  await stream('Researching...');
+
+  const { content } = await mindstudio.generateText(
+    { message: `Find background info on ${input.name}` },
+    { onLog: (event) => stream({ status: event.value }) },
+  );
+
+  await stream({ status: 'generating_image', progress: 0.5 });
+
+  const { imageUrl } = await mindstudio.generateImage(
+    { prompt: `Professional portrait illustration of ${input.name}` },
+    { onLog: (event) => stream({ status: event.value }) },
+  );
+
+  return { bio: content, imageUrl };
+}
+```
+
+Two data types:
+- `stream('text')` sends a text token (like LLM streaming output)
+- `stream({ ... })` sends structured data (progress, status, intermediate results)
+
+Every SDK action accepts an `onLog` callback that emits execution progress. Pipe it through `stream()` so the frontend sees what's happening inside each action in real time. Use `stream()` directly for your own status messages between actions.
+
+When there's no active stream (method not called with `stream: true`, CLI execution, background jobs), `stream()` is a silent no-op. Always safe to include unconditionally.
+
+### Frontend
+
+The frontend calls the method with `stream: true` and receives updates via `onToken`. The `text` value is accumulated (not a delta), so replace your display content each time.
+
+```typescript
+const result = await api.enrichProfile(
+  { name: 'Alice' },
   {
     stream: true,
-    onToken: (text) => setPreview(text),
+    onToken: (text) => setResponseText(text),
   },
 );
+// result is the same final output you'd get without streaming
 ```
 
-The platform handles the SSE transport. The method returns normally — streaming is managed by the SDK and platform, not by your method code.
+Use `onStreamError` for transient error handling. The method's promise still resolves with the final return value once execution completes.
 
 ## Raw Request Context (API Interface)
 

package/dist/prompt/static/coding.md

@@ -30,6 +30,8 @@ For any work involving AI models, external actions (web scraping, email, SMS), o
 
 For multi-step tasks with branching logic (research, enrichment, content pipelines), use `runTask()` instead of manually chaining SDK actions. It runs an autonomous agent loop that composes actions, retries on failure, and returns structured JSON. See the task agents reference for details.
 
+For methods that take more than a few seconds, use `stream()` from `@mindstudio-ai/agent` to push real-time progress to the frontend. Pipe `onLog` from SDK actions through `stream()` so users see what's happening. The frontend calls the method with `stream: true` and gets updates via `onToken`. See the methods reference for the full pattern.
+
 ### Auth
 - Not every app needs auth, and even for apps that do need auth, not every screen needs auth. Think intentionally about places where auth is required. Don't make auth be the first thing a user sees - that's jarring. Only show auth at intuitive and natural moments in the user's journey - be thoughtful about how to implement auth in the UI.
 - Frontend interfaces are always untrusted. Always enforce auth in backend methods. Use frontend auth and role information as a hint to conditionally show/hide UI to make the experience pleasant and seamless for users depending on their state, but remember to always use backend methods for gating data that is conditional on auth.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.138",
+  "version": "0.1.140",
   "description": "MindStudio coding agent",
   "repository": {
     "type": "git",