@mindstudio-ai/agent 0.1.100 → 0.1.102

package/llms.txt

@@ -19,7 +19,7 @@ For specific use cases:
 - **Pre-built agents**: Call `listAgents()` to see what's available → `runAgent({ appId })` to execute one. **Important:** Not all agents are configured for API use. Do not try to run an agent just because it appears in the list — only run agents the user specifically asks you to run.
 - **Model selection**: Call `listModelsSummary()` or `listModelsSummaryByType("llm_chat")` to browse models, then pass the model ID as `modelOverride.model` to actions like `generateText`. Use the summary endpoints (not `listModels`) to keep token usage low.
 - **Cost estimation**: AI-powered actions (text generation, image generation, video, audio, etc.) cost money. Call `estimateStepCost(stepType, stepInput)` before running these and confirm with the user before proceeding — unless they've explicitly given permission to go ahead. Non-AI actions (data lookups, OAuth connectors, etc.) are generally free.
-- **Task agents**: For multi-step tasks that need autonomous tool use (research, content creation, data enrichment), use `runTask()`. Provide a prompt, input, tools, an output contract, and a tool-use model id. The SDK runs a tool-use loop — calling the model, executing tools, feeding results back — until structured output is produced. Tools are SDK action names and/or your own app methods, written as `{ appMethod: "saveVendor", description: "when to use it" }`. App methods run as the user who invoked the method that started the task, with their roles, so the agent can read and write app state on their behalf. Prefer `outputSchema` for the output contract: plain JSON Schema (`type`/`properties`/`required`/`enum`/`items`; nullable via type arrays like `["string","null"]` — no `oneOf`/`$ref`/`nullable`). Output is validated every turn with automatic repair, `result.output` is fully typed from the schema (no generic argument, no `parsedSuccessfully` check), and the call throws `MindStudioError` code `task_output_schema_mismatch` if the agent cannot produce conforming output. Example: `runTask({ prompt: "Research this restaurant and save it", input: { name: "Tartine" }, tools: ["searchGoogle", "fetchUrl", { appMethod: "saveRestaurant", description: "Persist the researched restaurant." }], outputSchema: { type: "object", properties: { name: { type: "string" }, url: { type: ["string", "null"] } }, required: ["name"] }, model: yourModelId })`. The legacy `structuredOutputExample` option (an example object the model imitates) still works but is unvalidated — check `result.parsedSuccessfully` before using its output. Pass a current tool-use model id (call `listModels` or ask). Don't hardcode one.
+- **Task agents**: For multi-step tasks that need autonomous tool use (research, content creation, data enrichment), use `runTask()`. Provide a prompt, input, tools, an output contract, and a tool-use model id. The SDK runs a tool-use loop — calling the model, executing tools, feeding results back — until structured output is produced. Tools are SDK action names and/or your own app methods, written as `{ appMethod: "save-vendor", description: "when to use it" }`. App methods run as the user who invoked the method that started the task, with their roles, so the agent can read and write app state on their behalf. Prefer `outputSchema` for the output contract: plain JSON Schema (`type`/`properties`/`required`/`enum`/`items`; nullable via type arrays like `["string","null"]` — no `oneOf`/`$ref`/`nullable`). Output is validated every turn with automatic repair, `result.output` is fully typed from the schema (no generic argument, no `parsedSuccessfully` check), and the call throws `MindStudioError` code `task_output_schema_mismatch` if the agent cannot produce conforming output. Example: `runTask({ prompt: "Research this restaurant and save it", input: { name: "Tartine" }, tools: ["searchGoogle", "fetchUrl", { appMethod: "saveRestaurant", description: "Persist the researched restaurant." }], outputSchema: { type: "object", properties: { name: { type: "string" }, url: { type: ["string", "null"] } }, required: ["name"] }, model: yourModelId })`. The legacy `structuredOutputExample` option (an example object the model imitates) still works but is unvalidated — check `result.parsedSuccessfully` before using its output. Pass a current tool-use model id (call `listModels` or ask). Don't hardcode one.
 
 ## Install
 
@@ -729,31 +729,35 @@ Scrape public profile data from a LinkedIn profile page.
 #### scrapeUrl
 Extract text, HTML, or structured content from one or more web pages.
 - Accepts a single URL or multiple URLs (as a JSON array, comma-separated, or newline-separated).
-- Output format controls the result shape: "text" returns markdown, "html" returns raw HTML, "json" returns structured scraper data.
+- Output format controls the result shape: "text" returns markdown, "html" returns raw HTML, "json" returns structured scraper data, "summary" returns a model-written summary and requires the "firecrawl" service.
 - Can optionally capture a screenshot of each page.
-- Input: `{ url: string, service?: "default" | "firecrawl", autoEnhance?: boolean, outputFormat?: "text" | "json" | "html", pageOptions?: { onlyMainContent: boolean, screenshot: boolean, waitFor: number, replaceAllPathsWithAbsolutePaths: boolean, headers: object, removeTags: string[], mobile: boolean } }`
-- Output: `{ content: string | string[] | { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string } } | { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string } }[], screenshot?: string | string[] }`
+- Handles bot protection automatically; no proxy or rendering configuration is needed.
+- Input: `{ url: string, service?: "default" | "firecrawl", autoEnhance?: boolean, outputFormat?: "text" | "json" | "html" | "summary", pageOptions?: { onlyMainContent: boolean, screenshot: boolean, waitFor: number, replaceAllPathsWithAbsolutePaths: boolean, headers: object, removeTags: string[], mobile: boolean } }`
+- Output: `{ content: string | string[] | { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string }, costUnits?: number } | { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string }, costUnits?: number }[], screenshot?: string | string[] }`
 
 #### scrapeXPost
 Scrape data from a single X (Twitter) post by URL.
 - Returns structured post data (text, html, optional json/screenshot/metadata).
 - Optionally saves the text content to a variable.
 - Input: `{ url: string }`
-- Output: `{ post: { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string } } }`
+- Output: `{ post: { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string }, costUnits?: number } }`
 
 #### scrapeXProfile
 Scrape public profile data from an X (Twitter) account by URL.
 - Returns structured profile data.
 - Optionally saves the result to a variable.
 - Input: `{ url: string }`
-- Output: `{ profile: { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string } } }`
+- Output: `{ profile: { text: string, html: string, json?: object, screenshotUrl?: string, metadata?: { title: string, description: string, url: string, image: string }, error?: { code: string, message: string }, costUnits?: number } }`
 
 #### screenshotUrl
 Capture a screenshot of a web page as a PNG image.
 - Takes a viewport or full-page screenshot of the given URL.
 - Returns a CDN-hosted PNG image URL.
-- Viewport mode captures only the visible area; fullPage captures the entire scrollable page.
-- You can customize viewport width/height, add a delay, or wait for a CSS selector before capturing.
+- Viewport mode captures only the visible area; fullPage captures the entire scrollable page, scrolling it first so lazy-loaded content is included.
+- Works on sites behind bot protection (Cloudflare and similar).
+- Cookie-consent banners and similar overlays are suppressed automatically.
+- `width` and `height` are the exact output pixel dimensions.
+- You can add a delay or wait for a CSS selector before capturing. A selector that never appears fails the step rather than capturing early.
 - Input: `{ url: string, mode?: "viewport" | "fullPage", width?: number, height?: number, delay?: number, waitFor?: string }`
 - Output: `{ screenshotUrl: string }`
 
@@ -1806,7 +1810,7 @@ const { url } = await mindstudio.uploadFile(readFileSync('photo.png'), { extensi
 Output: `{ url: string }` — The permanent public CDN URL.
 
 #### `files` — per-app file storage (private by default)
-Typed per-app file storage: user uploads, generated documents, images, marketing assets. Think of a store as a CDN-backed bucket the app talks to — NOT app-defined state like a `db` table. The API is *shaped* like the `db` namespace (define a store at module scope, then read/write), but its contents aren't modeled by code, and one store is shared across dev and prod (a file uploaded in the dev editor is already live in prod at the same URL). Creates are safe by default because keys default to unique (UUID, or a content-addressed hash); the operations to treat with care are `delete(key)` and overwriting a fixed key. Files are served on the app's own domain: private stores (the default) are signed / session-authorized; public stores are world-readable, CDN-served, and images resize via query params (e.g. `?w=400&h=300&fit=cover`). Prefer this over the deprecated `uploadFile()` for app storage.
+Typed per-app file storage: user uploads, generated documents, images, marketing assets. Think of a store as a CDN-backed bucket the app talks to — NOT app-defined state like a `db` table. The API is *shaped* like the `db` namespace (define a store at module scope, then read/write), but its contents aren't modeled by code, and one store is shared across dev and prod (a file uploaded in the dev editor is already live in prod at the same URL). Creates are safe by default because keys default to unique (UUID, or a content-addressed hash); the operations to treat with care are `delete(key)` and overwriting a fixed key. Public objects are CDN-cached per their `Cache-Control`, set at put time via `cacheControl`: auto-minted keys default to immutable (cache-forever — the key is never reused), and named keys default to `public, max-age=300`, so overwriting one propagates publicly within ~5 minutes; pass `cacheControl` to tune (e.g. `'public, max-age=60'` for near-live config, `'no-store'` to revalidate every read). Files are served on the app's own domain: private stores (the default) are signed / session-authorized; public stores are world-readable, CDN-served, and images resize via query params (e.g. `?w=400&h=300&fit=cover`). Prefer this over the deprecated `uploadFile()` for app storage.
 
 ```typescript
 import { files } from '@mindstudio-ai/agent';
@@ -1822,7 +1826,7 @@ await file.shareUrl(); // absolute signed URL that works with NO session (email/
 ```
 
 Store methods:
-- `put(content, { key?, contentType?, filename?, contentAddressed? })` → `StoredFile`. `content` is `Buffer | Uint8Array | string`. Omit `key` for a random UUID; `contentAddressed: true` derives an immutable `<sha256>.<ext>` key.
+- `put(content, { key?, contentType?, filename?, contentAddressed?, cacheControl? })` → `StoredFile`. `content` is `Buffer | Uint8Array | string`. Omit `key` for a random UUID; `contentAddressed: true` derives an immutable `<sha256>.<ext>` key. `cacheControl` sets the CDN caching of a public object (defaults: auto-minted keys immutable, named keys `public, max-age=300`).
 - `get(key)` → `Buffer` · `head(key)` → `StoredFile` · `exists(key)` → `boolean`
 - `list({ prefix?, cursor?, limit? })` → `{ files: StoredFile[]; cursor? }`
 - `delete(key)` → `void`
@@ -1835,7 +1839,7 @@ Store methods:
 User uploads (client-direct — bytes go straight to storage, never through the app backend): a backend method mints a token, the frontend submits it with `@mindstudio-ai/interface`.
 ```typescript
 // backend method
-const token = await Uploads.createUploadToken({ contentType, maxSize: 25 * 1024 * 1024 });
+const token = await Uploads.createUploadToken({ contentType, maxSize: 25 * 1024 * 1024 }); // also accepts cacheControl
 return token;
 // frontend (@mindstudio-ai/interface)
 import { platform } from '@mindstudio-ai/interface';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/agent",
-  "version": "0.1.100",
+  "version": "0.1.102",
   "description": "TypeScript SDK for MindStudio direct step execution",
   "type": "module",
   "main": "./dist/index.js",