@mindstudio-ai/agent 0.1.170 → 0.1.172

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -299,7 +299,7 @@ var init_metadata = __esm({
299
299
  "evaluateDecision": {
300
300
  stepType: "evaluateDecision",
301
301
  description: "Ask structured questions about text, JSON, or images and get calibrated answers from a decision model. The model returns a probability, a selected option, or a score. It does not write a reply. Each question is a noul (yes or no, as a probability from 0 to 1), a choice (one option from a set you define, with a probability for each), or a score (a rating against ordered levels). Put every question in the same call. The question id is yours: answers come back under the same ids. The model defaults to Jev (jev-latest).",
302
- usageNotes: "- state is the content to judge: a string, or a JSON object or array (a record, a chat log, application state).\n- questions is a map. The key is an id you choose. It is not shown to the model. The answer comes back under the same id.\n- A noul asks a yes/no question and returns noul, a probability from 0 (no) to 1 (yes). Optional criteria.true and criteria.false say what a yes and a no mean.\n- A choice picks one option. criteria is a map of option id to a short description (or null). At most 255 options. The answer includes the winning choice, a probability for every option, and confidence.\n- A score rates the state on an ordered rubric. criteria is 2 to 10 level descriptions, low to high. The answer's score can land between levels, and includes a probability per level plus confidence.\n- An answer of type refusal means the model declined that question (GPT-6 Luna Decisions can).\n- instructions may be a string, or an object that keeps the question in one field and reference data in the others. Refer to those fields by name in backticks.\n- Send every question you need in one call. The model reads the state once and answers them together.\n- Probabilities from different models are not comparable: tune a threshold against the model, and the version, it will run on.\n- decisionModelOverride.model picks the model:\n - jev-latest (the default) is TypeSafe's current stable release, text only, up to 64k tokens. jev-preview tracks TypeSafe's newest release. Pin a version such as jev-1.13.0 when a threshold was tuned against that version.\n - clef and clef-flash run Cloudflare Clef, which also reads up to 4 PNG, JPEG, or WebP images, each at most 4 MiB and 8 MiB together, and takes at most 64 questions, each id using only letters, digits, underscore, dot, and hyphen, up to 100 characters. clef is the larger model, clef-flash the faster one. @cf/cloudflare/clef and @cf/cloudflare/clef-flash name the same two.\n - mercury-decide runs Inception's Mercury Decide, which reads up to 64k tokens and up to 16 PNG, JPEG, WebP, or GIF images, each at most 10 MiB and 14 MiB together.\n - gpt-6-luna-decisions runs OpenAI's Decisions API (in beta), which reads up to 922k tokens and PNG, JPEG, WebP, or GIF images of up to 20 MB each. It takes up to 200 questions, and a choice needs at least 2 options. gpt-6-luna names it too.\n- images is for a model that reads them. Pass URLs or data URLs. A model that reads none refuses the call.\n- The response model field is the version that answered.\n- Billed per input token. Output tokens are free. Each model has its own rate, and GPT-6 Luna Decisions bills a prompt over 272k tokens at twice its rate.",
302
+ usageNotes: "- state is the content to judge: a string, or a JSON object or array (a record, a chat log, application state).\n- questions is a map. The key is an id you choose. It is not shown to the model. The answer comes back under the same id.\n- A noul asks a yes/no question and returns noul, a probability from 0 (no) to 1 (yes). Optional criteria.true and criteria.false say what a yes and a no mean.\n- A choice picks one option. criteria is a map of option id to a short description (or null). At most 255 options. The answer includes the winning choice, a probability for every option, and confidence.\n- A score rates the state on an ordered rubric. criteria is 2 to 10 level descriptions, low to high. The answer's score can land between levels, and includes a probability per level plus confidence.\n- An answer of type refusal means the model declined that question (GPT-6 Luna Decisions can).\n- instructions may be a string, or an object that keeps the question in one field and reference data in the others. Refer to those fields by name in backticks.\n- Send every question you need in one call. The model reads the state once and answers them together.\n- Probabilities from different models are not comparable: tune a threshold against the model, and the version, it will run on.\n- decisionModelOverride.model picks the model:\n - jev-latest (the default) is TypeSafe's current stable release, text only, up to 64k tokens. jev-preview tracks TypeSafe's newest release. Pin a version such as jev-1.13.0 when a threshold was tuned against that version.\n - clef and clef-flash run Cloudflare Clef, which also reads up to 4 PNG, JPEG, or WebP images, each at most 4 MiB and 8 MiB together, and takes at most 64 questions, each id using only letters, digits, underscore, dot, and hyphen, up to 100 characters. clef is the larger model, clef-flash the faster one. @cf/cloudflare/clef and @cf/cloudflare/clef-flash name the same two.\n - mercury-decide runs Inception's Mercury Decide, which reads up to 64k tokens and up to 16 PNG, JPEG, WebP, or GIF images, each at most 10 MiB and 14 MiB together.\n - drex-max, drex-v2.0 and drex-v1.5 run Nace.AI's Drex, served by DeepInfra, and take at most 16 questions. drex-max reads up to 262k tokens and up to 4 PNG, JPEG, WebP, or GIF images, 9 MiB together. drex-v2.0 and drex-v1.5 read text only, up to 128k tokens. nace-ai/drex-max, nace-ai/drex-v2.0 and nace-ai/drex-v1.5 name the same three.\n - gpt-6-luna-decisions runs OpenAI's Decisions API (in beta), which reads up to 922k tokens and PNG, JPEG, WebP, or GIF images of up to 20 MB each. It takes up to 200 questions, and a choice needs at least 2 options. gpt-6-luna names it too.\n- images is for a model that reads them. Pass URLs or data URLs. A model that reads none refuses the call.\n- The response model field is the version that answered.\n- Billed per input token. Output tokens are free. Each model has its own rate, and GPT-6 Luna Decisions bills a prompt over 272k tokens at twice its rate.",
303
303
  inputSchema: { "type": "object", "properties": { "state": { "anyOf": [{ "type": "string" }, { "type": "object", "properties": {}, "required": [] }, { "type": "array", "items": {} }] }, "questions": { "type": "object", "properties": {}, "required": [], "description": "Questions to ask about the state, keyed by an id you choose." }, "images": { "type": "array", "items": { "type": "string" }, "description": "Images for a model that reads them (Clef, Clef Flash, GPT-6 Luna Decisions). Each entry is a URL or a data URL. A model that reads none refuses the call." }, "decisionModelOverride": { "type": "object", "properties": { "model": { "type": "string", "description": "Decision model: a catalog id, its vendor's name for it (`@cf/cloudflare/clef`, `gpt-6-luna`), or a version it pins (`jev-1.13.0`)" }, "config": { "type": "object", "properties": {}, "required": [], "description": "Additional model-specific configuration" } }, "required": ["model"], "description": "Optional model override. Uses the workspace's default decision model (Jev) if not specified" } }, "required": ["state", "questions"] },
304
304
  outputSchema: { "type": "object", "properties": { "model": { "type": "string", "description": "Versioned model id that answered, such as jev-1.13.0." }, "answers": { "type": "object", "properties": {}, "required": [], "description": "One answer per question, under the same ids." }, "usage": { "type": "object", "properties": { "input_tokens": { "type": "number" }, "output_tokens": { "type": "number" } }, "required": ["input_tokens", "output_tokens"], "description": "Token counts for the call. Input tokens are what the model bills." } }, "required": ["model", "answers", "usage"] }
305
305
  },
@@ -1860,7 +1860,8 @@ function serializeParam(val) {
1860
1860
  }
1861
1861
  function serializeColumnParam(val, columnName, columns) {
1862
1862
  const col = columnsByName(columns).get(columnName);
1863
- if (col?.type === "user" && typeof val === "string") {
1863
+ const isUserColumn = col?.type === "user" || columnName === "last_updated_by";
1864
+ if (isUserColumn && typeof val === "string") {
1864
1865
  return val.startsWith(USER_PREFIX) ? val : `${USER_PREFIX}${val}`;
1865
1866
  }
1866
1867
  return serializeParam(val);
@@ -2055,7 +2056,7 @@ function buildExists(table, where, whereParams, negate) {
2055
2056
  };
2056
2057
  }
2057
2058
  function buildInsert(table, data, columns) {
2058
- const filtered = stripSystemColumns(data);
2059
+ const filtered = stripPlatformColumns(data);
2059
2060
  const keys = Object.keys(filtered);
2060
2061
  const placeholders = keys.map(() => "?").join(", ");
2061
2062
  const params = keys.map((k) => serializeColumnParam(filtered[k], k, columns));
@@ -2065,7 +2066,7 @@ function buildInsert(table, data, columns) {
2065
2066
  };
2066
2067
  }
2067
2068
  function buildUpdate(table, id, data, columns) {
2068
- const filtered = stripSystemColumns(data);
2069
+ const filtered = stripPlatformColumns(data);
2069
2070
  const keys = Object.keys(filtered);
2070
2071
  const assignments = keys.map((k) => `${k} = ?`).join(", ");
2071
2072
  const params = [
@@ -2079,7 +2080,7 @@ function buildUpdate(table, id, data, columns) {
2079
2080
  };
2080
2081
  }
2081
2082
  function buildUpsert(table, data, conflictColumns, columns) {
2082
- const filtered = stripSystemColumns(data);
2083
+ const filtered = stripPlatformColumns(data);
2083
2084
  const keys = Object.keys(filtered);
2084
2085
  const placeholders = keys.map(() => "?").join(", ");
2085
2086
  const params = keys.map((k) => serializeColumnParam(filtered[k], k, columns));
@@ -2095,16 +2096,16 @@ function buildDelete(table, where, whereParams) {
2095
2096
  }
2096
2097
  return { sql, params: whereParams?.length ? whereParams : void 0 };
2097
2098
  }
2098
- function stripSystemColumns(data) {
2099
+ function stripPlatformColumns(data) {
2099
2100
  const result = {};
2100
2101
  for (const [key, value] of Object.entries(data)) {
2101
- if (!SYSTEM_COLUMNS.has(key)) {
2102
+ if (!PLATFORM_COLUMNS.has(key)) {
2102
2103
  result[key] = value;
2103
2104
  }
2104
2105
  }
2105
2106
  return result;
2106
2107
  }
2107
- var USER_PREFIX, byNameCache, SQL_IDENTIFIER_RE, SYSTEM_COLUMNS;
2108
+ var USER_PREFIX, byNameCache, SQL_IDENTIFIER_RE, PLATFORM_COLUMNS;
2108
2109
  var init_sql = __esm({
2109
2110
  "src/db/sql.ts"() {
2110
2111
  "use strict";
@@ -2112,13 +2113,10 @@ var init_sql = __esm({
2112
2113
  USER_PREFIX = "@@user@@";
2113
2114
  byNameCache = /* @__PURE__ */ new WeakMap();
2114
2115
  SQL_IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
2115
- SYSTEM_COLUMNS = /* @__PURE__ */ new Set([
2116
+ PLATFORM_COLUMNS = /* @__PURE__ */ new Set([
2116
2117
  "id",
2117
- "created_at",
2118
2118
  "createdAt",
2119
- "updated_at",
2120
2119
  "updatedAt",
2121
- "last_updated_by",
2122
2120
  "lastUpdatedBy"
2123
2121
  ]);
2124
2122
  }
@@ -3916,6 +3914,9 @@ var init_table = __esm({
3916
3914
  /**
3917
3915
  * Update a row by ID. Only the provided fields are changed.
3918
3916
  * Returns the updated row via `UPDATE ... RETURNING *`.
3917
+ *
3918
+ * The platform advances `updated_at` and stamps `last_updated_by` with the
3919
+ * signed-in user unless the data changes them itself.
3919
3920
  */
3920
3921
  update(id, data) {
3921
3922
  const build = () => {
@@ -4011,6 +4012,8 @@ var init_table = __esm({
4011
4012
  * @param conflictKey - Column name(s) that form the unique constraint.
4012
4013
  * Pass a single string for single-column unique, or an array for compound.
4013
4014
  * @param data - Row data to insert (or update on conflict). Defaults apply.
4015
+ * A `created_at`, `updated_at` or `last_updated_by` it gives is written
4016
+ * either way; whichever it leaves out the platform fills in.
4014
4017
  */
4015
4018
  upsert(conflictKey, data) {
4016
4019
  const conflictColumns = Array.isArray(conflictKey) ? conflictKey : [conflictKey];
@@ -5737,6 +5740,526 @@ var init_events = __esm({
5737
5740
  }
5738
5741
  });
5739
5742
 
5743
+ // src/browser/index.ts
5744
+ import { randomUUID as randomUUID2 } from "crypto";
5745
+ function createBrowser(call, steps) {
5746
+ return {
5747
+ async open(options = {}) {
5748
+ const { session } = await call("open", {
5749
+ ...options.viewport !== void 0 ? { viewport: options.viewport } : {},
5750
+ ...options.idleTimeoutSeconds !== void 0 ? { idleTimeoutSeconds: options.idleTimeoutSeconds } : {}
5751
+ });
5752
+ let ready = session.ready;
5753
+ let failures = 0;
5754
+ while (!ready) {
5755
+ try {
5756
+ ({ ready } = await call("ready", { sessionId: session.id }));
5757
+ failures = 0;
5758
+ } catch (err) {
5759
+ const answered = err instanceof MindStudioError && err.status < 500;
5760
+ if (answered || err.code === "browser_unavailable" || ++failures > 5) {
5761
+ throw err;
5762
+ }
5763
+ await new Promise((r) => setTimeout(r, 2e3));
5764
+ }
5765
+ }
5766
+ const opened = new BrowserSession(session, call, steps);
5767
+ if (options.url) {
5768
+ try {
5769
+ await opened.goto(options.url);
5770
+ } catch (err) {
5771
+ await opened.close().catch(() => {
5772
+ });
5773
+ throw err;
5774
+ }
5775
+ }
5776
+ return opened;
5777
+ },
5778
+ async session(id) {
5779
+ const { session } = await call("session", { sessionId: id });
5780
+ return new BrowserSession(session, call, steps);
5781
+ }
5782
+ };
5783
+ }
5784
+ var RETRYABLE_STATUSES, RETRY_BACKOFFS_MS, MAX_TOOL_STEPS, describeScreenPrompt, toWireTarget, BrowserSession;
5785
+ var init_browser = __esm({
5786
+ "src/browser/index.ts"() {
5787
+ "use strict";
5788
+ init_errors();
5789
+ RETRYABLE_STATUSES = /* @__PURE__ */ new Set([502, 503, 504]);
5790
+ RETRY_BACKOFFS_MS = [1e3, 2e3, 4e3, 8e3, 15e3, 15e3, 15e3];
5791
+ MAX_TOOL_STEPS = 20;
5792
+ describeScreenPrompt = (question) => [
5793
+ "This is a screenshot of a web page, taken by an agent working through the site.",
5794
+ question ? `First answer this question about it: ${question}
5795
+
5796
+ Then describe the page briefly: its layout, its content, and what state it is in.` : "Describe what a person looking at it would see, top to bottom: the layout, the content, what state the page is in (a form partly filled, an error, a dialog open), and anything that looks wrong.",
5797
+ "Be concise and concrete, and quote visible text exactly where it matters. Answer in plain Markdown with no preamble."
5798
+ ].join("\n\n");
5799
+ toWireTarget = (target) => typeof target === "string" ? { ref: target } : target;
5800
+ BrowserSession = class {
5801
+ /** @internal Use `browser.open()`. */
5802
+ constructor(info, call, steps) {
5803
+ this.call = call;
5804
+ this.steps = steps;
5805
+ this.id = info.id;
5806
+ this.viewport = info.viewport;
5807
+ this.expiresAt = info.expiresAt;
5808
+ }
5809
+ call;
5810
+ steps;
5811
+ /** Pass to `browser.session(id)` from a later call to pick this session up again. */
5812
+ id;
5813
+ viewport;
5814
+ /** When the session closes, however busy it is. Milliseconds since epoch. */
5815
+ expiresAt;
5816
+ /** Every action so far, chained: see `run`. */
5817
+ queue = Promise.resolve();
5818
+ /**
5819
+ * One action at a time, in the order they were called. A session has one
5820
+ * page, so actions started together (a `Promise.all`, or a task agent's
5821
+ * tools from one turn, which run concurrently) would otherwise reach it in
5822
+ * whatever order their requests landed: a click on Submit before the field
5823
+ * it submits was typed.
5824
+ */
5825
+ run(action) {
5826
+ const result = this.queue.then(() => this.send(action));
5827
+ this.queue = result.catch(() => {
5828
+ });
5829
+ return result;
5830
+ }
5831
+ /**
5832
+ * One action's request, asked again under the same id when the answer
5833
+ * didn't get back (a dropped connection, an api pod rolling). The platform
5834
+ * runs an id once, so asking again waits on the action already under way
5835
+ * rather than clicking twice.
5836
+ */
5837
+ async send(action) {
5838
+ const commandId = randomUUID2();
5839
+ for (let attempt = 0; ; attempt++) {
5840
+ try {
5841
+ const { value } = await this.call("run", {
5842
+ sessionId: this.id,
5843
+ action,
5844
+ commandId
5845
+ });
5846
+ return value;
5847
+ } catch (err) {
5848
+ const cut = !(err instanceof MindStudioError) || RETRYABLE_STATUSES.has(err.status) && err.code !== "browser_unavailable";
5849
+ if (!cut || attempt >= RETRY_BACKOFFS_MS.length) {
5850
+ throw err;
5851
+ }
5852
+ await new Promise((r) => setTimeout(r, RETRY_BACKOFFS_MS[attempt]));
5853
+ }
5854
+ }
5855
+ }
5856
+ /** Open a URL and wait for it to load. */
5857
+ goto(url) {
5858
+ return this.run({ op: "goto", url });
5859
+ }
5860
+ /** The page as it is now. */
5861
+ snapshot() {
5862
+ return this.run({ op: "snapshot" });
5863
+ }
5864
+ /** Click an element (tap, on a mobile viewport), and wait for what it started to settle. */
5865
+ click(target) {
5866
+ return this.run({ op: "click", target: toWireTarget(target) });
5867
+ }
5868
+ /**
5869
+ * Click into a field and type. `clear` replaces what's there; `submit`
5870
+ * presses Enter after.
5871
+ */
5872
+ type(target, text, options = {}) {
5873
+ return this.run({
5874
+ op: "type",
5875
+ target: toWireTarget(target),
5876
+ text,
5877
+ ...options
5878
+ });
5879
+ }
5880
+ /** Choose an option of a `<select>`, by its text, value or label. */
5881
+ select(target, option) {
5882
+ return this.run({ op: "select", target: toWireTarget(target), option });
5883
+ }
5884
+ /**
5885
+ * Press a key on whatever has focus: `Enter`, `Tab`, `Escape`, `Backspace`,
5886
+ * `Delete`, the arrows, `PageUp`, `PageDown`, `Home`, `End`, `' '`, or any
5887
+ * single character.
5888
+ */
5889
+ press(key) {
5890
+ return this.run({ op: "press", key });
5891
+ }
5892
+ /** Scroll an element into view, or the page by `by` pixels (most of a screen, by default). */
5893
+ scroll(options = {}) {
5894
+ return this.run({
5895
+ op: "scroll",
5896
+ ...options.to !== void 0 ? { target: toWireTarget(options.to) } : {},
5897
+ ...options.by !== void 0 ? { by: options.by } : {}
5898
+ });
5899
+ }
5900
+ /** Wait for text to appear on the page. Throws once `timeoutSeconds` (15 by default) pass without it. */
5901
+ waitFor(text, options = {}) {
5902
+ return this.run({
5903
+ op: "wait",
5904
+ text,
5905
+ ...options.timeoutSeconds !== void 0 ? { timeoutMs: options.timeoutSeconds * 1e3 } : {}
5906
+ });
5907
+ }
5908
+ async screenshot(options = {}) {
5909
+ const { store, key, fullPage, cursor } = options;
5910
+ if (store) {
5911
+ const token = await store.createUploadToken({
5912
+ ...key ? { key } : { filename: "screenshot.png" },
5913
+ contentType: "image/png"
5914
+ });
5915
+ const shot2 = await this.run({
5916
+ op: "screenshot",
5917
+ fullPage: !!fullPage,
5918
+ cursor: !!cursor,
5919
+ upload: { url: token.upload.url, fields: token.upload.fields }
5920
+ });
5921
+ return {
5922
+ ...await store.head(token.key),
5923
+ width: shot2.width,
5924
+ height: shot2.height,
5925
+ deviceScaleFactor: shot2.deviceScaleFactor
5926
+ };
5927
+ }
5928
+ const shot = await this.run({
5929
+ op: "screenshot",
5930
+ fullPage: !!fullPage,
5931
+ cursor: !!cursor
5932
+ });
5933
+ return {
5934
+ data: Buffer.from(shot.data ?? "", "base64"),
5935
+ contentType: "image/png",
5936
+ width: shot.width,
5937
+ height: shot.height,
5938
+ deviceScaleFactor: shot.deviceScaleFactor
5939
+ };
5940
+ }
5941
+ /**
5942
+ * Run a function in the page and get back what it returns (as JSON). The
5943
+ * function is sent as source, so it can't use variables from your code:
5944
+ * pass what it needs as `arg`.
5945
+ *
5946
+ * ```ts
5947
+ * const prices = await session.evaluate(
5948
+ * (selector) => [...document.querySelectorAll(selector)].map((el) => el.textContent),
5949
+ * '.price',
5950
+ * );
5951
+ * ```
5952
+ */
5953
+ evaluate(fn, arg) {
5954
+ return this.run({
5955
+ op: "evaluate",
5956
+ expression: `(${fn.toString()})(${arg === void 0 ? "" : JSON.stringify(arg)})`
5957
+ });
5958
+ }
5959
+ /**
5960
+ * A tool for `mindstudio.runTask()` that drives this session, so a model can
5961
+ * browse. It takes a list of steps (open a URL, read the page, click, type,
5962
+ * choose an option, press a key, scroll, wait for text), runs them in order,
5963
+ * stops at the first that fails, and answers with each step's outcome and
5964
+ * the page after the last one. A model plans "fill the form and submit it"
5965
+ * as one call rather than one turn a field. Only the latest page stays in
5966
+ * the task's transcript (`supersedes`), so a long walk doesn't fill it.
5967
+ *
5968
+ * With `screenshots`, a second tool, `browser_screenshot`, lets the model
5969
+ * see the page: each shot goes into that store and the model reads a
5970
+ * description of it. Those answers all stay in the transcript, since each
5971
+ * names a kept file.
5972
+ */
5973
+ tools(options = {}) {
5974
+ const secrets = options.secrets ?? {};
5975
+ const secretNames = Object.keys(secrets);
5976
+ const screenshots = options.screenshots;
5977
+ const tools = [
5978
+ {
5979
+ name: "browser",
5980
+ description: `Drive the browser. Run one or more steps in order: snapshot (read the page), navigate (open a URL), click, type, select (a dropdown option), press (a key), scroll, and wait (for text to appear). Start with a snapshot to see the page: everything you can act on has a ref ("e12"), good until the next page. Name an element by its ref, or by text, role, label or a CSS selector. Steps stop at the first that fails, and the answer says why. The answer has each step's outcome and the page after the last step: its URL, title and outline. Earlier pages leave the conversation when a newer one arrives, so plan from the latest. Batch the steps you can predict, such as filling a form and submitting it, into one call.` + (secretNames.length > 0 ? ` To type a secret you never see, give type a secret instead of text: ${secretNames.join(", ")}.` : "") + (screenshots ? " To see how the page looks, which the outline can only partly say, use browser_screenshot." : ""),
5981
+ inputSchema: {
5982
+ type: "object",
5983
+ properties: {
5984
+ steps: {
5985
+ type: "array",
5986
+ description: `One to ${MAX_TOOL_STEPS} steps, run in order.`,
5987
+ items: {
5988
+ type: "object",
5989
+ properties: {
5990
+ command: {
5991
+ type: "string",
5992
+ enum: [
5993
+ "snapshot",
5994
+ "navigate",
5995
+ "click",
5996
+ "type",
5997
+ "select",
5998
+ "press",
5999
+ "scroll",
6000
+ "wait"
6001
+ ]
6002
+ },
6003
+ ref: {
6004
+ type: "string",
6005
+ description: "An element, by its ref from the latest page (most reliable)."
6006
+ },
6007
+ text: {
6008
+ type: "string",
6009
+ description: "For click and wait: the element's name or visible text, or the text to wait for. For type: the text to type."
6010
+ },
6011
+ role: {
6012
+ type: "string",
6013
+ description: "With text, only an element of this role (button, link, textbox\u2026)."
6014
+ },
6015
+ label: {
6016
+ type: "string",
6017
+ description: "A form field, by its label."
6018
+ },
6019
+ selector: {
6020
+ type: "string",
6021
+ description: "A CSS selector, the last resort."
6022
+ },
6023
+ url: {
6024
+ type: "string",
6025
+ description: "For navigate: an http or https URL."
6026
+ },
6027
+ ...secretNames.length > 0 ? {
6028
+ secret: {
6029
+ type: "string",
6030
+ enum: secretNames,
6031
+ description: "For type: a secret to type instead of text."
6032
+ }
6033
+ } : {},
6034
+ clear: {
6035
+ type: "boolean",
6036
+ description: "For type: replace what the field holds."
6037
+ },
6038
+ submit: {
6039
+ type: "boolean",
6040
+ description: "For type: press Enter after."
6041
+ },
6042
+ option: {
6043
+ type: "string",
6044
+ description: "For select: the option's text or value."
6045
+ },
6046
+ key: {
6047
+ type: "string",
6048
+ description: "For press: Enter, Tab, Escape, Backspace, Delete, an arrow, PageUp, PageDown, Home, End, or one character."
6049
+ },
6050
+ by: {
6051
+ type: "number",
6052
+ description: "For scroll: pixels down (negative for up). With an element instead, scrolls it into view; with neither, most of a screen."
6053
+ },
6054
+ timeoutSeconds: {
6055
+ type: "number",
6056
+ description: "For wait: how long to wait (15 by default)."
6057
+ }
6058
+ },
6059
+ required: ["command"]
6060
+ }
6061
+ }
6062
+ },
6063
+ required: ["steps"]
6064
+ },
6065
+ supersedes: "browser-page",
6066
+ execute: async (input) => this.runSteps(input.steps, secrets)
6067
+ }
6068
+ ];
6069
+ if (screenshots) {
6070
+ tools.push({
6071
+ name: "browser_screenshot",
6072
+ description: "See the page as a person would. Takes a screenshot of the browser, keeps it, and answers with a description of what it shows, and the answer to your question if you ask one. Use it when the page's outline can't tell you what you need: how the page looks, a chart or an image, whether something is visibly wrong. The answer's key names the kept screenshot.",
6073
+ inputSchema: {
6074
+ type: "object",
6075
+ properties: {
6076
+ question: {
6077
+ type: "string",
6078
+ description: "What to look for or answer from the page. Leave it out for a description of the whole page."
6079
+ },
6080
+ fullPage: {
6081
+ type: "boolean",
6082
+ description: "The whole page, top to bottom, not just what is on screen."
6083
+ },
6084
+ cursor: {
6085
+ type: "boolean",
6086
+ description: "Keep the cursor in the shot, where the last action landed."
6087
+ }
6088
+ }
6089
+ },
6090
+ execute: async (input) => this.describeScreen(screenshots, input)
6091
+ });
6092
+ }
6093
+ return tools;
6094
+ }
6095
+ /**
6096
+ * The screenshot tool: the shot into the store, then a vision model's
6097
+ * description of it. A description that fails still answers with the kept
6098
+ * shot's key, so the model can name it.
6099
+ */
6100
+ async describeScreen(store, input) {
6101
+ const question = typeof input.question === "string" && input.question.trim() ? input.question.trim() : void 0;
6102
+ const shot = await this.screenshot({
6103
+ store,
6104
+ fullPage: input.fullPage === true,
6105
+ cursor: input.cursor === true
6106
+ });
6107
+ try {
6108
+ const { analysis } = await this.steps("analyzeImage", {
6109
+ imageUrl: shot.url,
6110
+ prompt: describeScreenPrompt(question)
6111
+ });
6112
+ return { key: shot.key, description: analysis };
6113
+ } catch (err) {
6114
+ return {
6115
+ key: shot.key,
6116
+ error: `The screenshot was kept, but describing it failed: ${err instanceof Error ? err.message : "unknown error"}`
6117
+ };
6118
+ }
6119
+ }
6120
+ /** The tool's steps, in order, stopping at the first that fails. */
6121
+ async runSteps(raw, secrets) {
6122
+ const steps = Array.isArray(raw) ? raw : [];
6123
+ if (steps.length === 0 || steps.length > MAX_TOOL_STEPS) {
6124
+ throw new MindStudioError(
6125
+ `Give between 1 and ${MAX_TOOL_STEPS} steps.`,
6126
+ "invalid_steps",
6127
+ 400
6128
+ );
6129
+ }
6130
+ const outcomes = [];
6131
+ let last;
6132
+ let failure;
6133
+ for (const step of steps) {
6134
+ const command = typeof step.command === "string" ? step.command : "";
6135
+ try {
6136
+ const answer = await this.runStep(command, step, secrets);
6137
+ last = answer;
6138
+ outcomes.push({
6139
+ command,
6140
+ ok: true,
6141
+ ..."matched" in answer ? { matched: answer.matched } : {}
6142
+ });
6143
+ } catch (err) {
6144
+ failure = err instanceof Error ? err : new Error(String(err));
6145
+ outcomes.push({ command, ok: false, error: failure.message });
6146
+ break;
6147
+ }
6148
+ }
6149
+ if (failure) {
6150
+ const stepError = failure;
6151
+ last = await this.snapshot().catch(() => {
6152
+ throw stepError;
6153
+ });
6154
+ }
6155
+ return {
6156
+ steps: outcomes,
6157
+ ...outcomes.length < steps.length ? { notRun: steps.length - outcomes.length } : {},
6158
+ page: {
6159
+ url: last.url,
6160
+ title: last.title,
6161
+ snapshot: last.snapshot,
6162
+ ...last.dialogs ? { dialogs: last.dialogs } : {}
6163
+ }
6164
+ };
6165
+ }
6166
+ runStep(command, step, secrets) {
6167
+ const str = (v) => typeof v === "string" ? v : void 0;
6168
+ const target = () => {
6169
+ if (str(step.ref)) {
6170
+ return str(step.ref);
6171
+ }
6172
+ const described = {
6173
+ ...command !== "type" && str(step.text) ? { text: str(step.text) } : {},
6174
+ ...str(step.role) ? { role: str(step.role) } : {},
6175
+ ...str(step.label) ? { label: str(step.label) } : {},
6176
+ ...str(step.selector) ? { selector: str(step.selector) } : {}
6177
+ };
6178
+ if (Object.keys(described).length === 0) {
6179
+ throw new MindStudioError(
6180
+ `${command} needs an element: a ref, text, role, label or selector.`,
6181
+ "invalid_steps",
6182
+ 400
6183
+ );
6184
+ }
6185
+ return described;
6186
+ };
6187
+ switch (command) {
6188
+ case "snapshot":
6189
+ return this.snapshot();
6190
+ case "navigate":
6191
+ return this.goto(str(step.url) ?? "");
6192
+ case "click":
6193
+ return this.click(target());
6194
+ case "type": {
6195
+ const secret = str(step.secret);
6196
+ if (secret !== void 0 && !(secret in secrets)) {
6197
+ throw new MindStudioError(
6198
+ `No secret named "${secret}".`,
6199
+ "unknown_secret",
6200
+ 400
6201
+ );
6202
+ }
6203
+ return this.type(
6204
+ target(),
6205
+ secret !== void 0 ? secrets[secret] : str(step.text) ?? "",
6206
+ {
6207
+ clear: step.clear === true || secret !== void 0,
6208
+ submit: step.submit === true
6209
+ }
6210
+ );
6211
+ }
6212
+ case "select":
6213
+ return this.select(target(), str(step.option) ?? "");
6214
+ case "press":
6215
+ return this.press(str(step.key) ?? "");
6216
+ case "scroll": {
6217
+ const hasTarget = str(step.ref) ?? str(step.label) ?? str(step.selector) ?? str(step.text);
6218
+ return this.scroll({
6219
+ ...hasTarget ? { to: target() } : {},
6220
+ ...typeof step.by === "number" ? { by: step.by } : {}
6221
+ });
6222
+ }
6223
+ case "wait":
6224
+ return this.waitFor(str(step.text) ?? "", {
6225
+ ...typeof step.timeoutSeconds === "number" ? { timeoutSeconds: step.timeoutSeconds } : {}
6226
+ });
6227
+ default:
6228
+ throw new MindStudioError(
6229
+ `Unknown command "${command}".`,
6230
+ "invalid_steps",
6231
+ 400
6232
+ );
6233
+ }
6234
+ }
6235
+ /**
6236
+ * A grant to watch this session live, for your frontend: return it from a
6237
+ * method and hand its `token` to `browser.view()` in
6238
+ * `@mindstudio-ai/interface`. Whoever holds it sees the page until it
6239
+ * expires, so check your own access first, as for `events.grant()`.
6240
+ * `ttlSeconds` is clamped to 60 through 3600 (900 by default); the frontend
6241
+ * asks again through your method when it runs out.
6242
+ *
6243
+ * ```ts
6244
+ * export async function watchRun({ runId }: { runId: string }) {
6245
+ * auth.requireRole('admin');
6246
+ * const run = await Runs.get(runId);
6247
+ * const session = await browser.session(run.browserSessionId);
6248
+ * return session.grantView();
6249
+ * }
6250
+ * ```
6251
+ */
6252
+ grantView(options = {}) {
6253
+ return this.call("view", { sessionId: this.id, ...options });
6254
+ }
6255
+ /** Close the session and its browser. */
6256
+ async close() {
6257
+ await this.call("close", { sessionId: this.id });
6258
+ }
6259
+ };
6260
+ }
6261
+ });
6262
+
5740
6263
  // src/task/index.ts
5741
6264
  function resolveStepType(name) {
5742
6265
  const meta = stepMetadata[name];
@@ -5944,7 +6467,7 @@ var init_schema = __esm({
5944
6467
  });
5945
6468
 
5946
6469
  // src/task/local.ts
5947
- import { randomUUID as randomUUID2 } from "crypto";
6470
+ import { randomUUID as randomUUID3 } from "crypto";
5948
6471
  function isPlainObject(value) {
5949
6472
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
5950
6473
  return false;
@@ -6163,9 +6686,14 @@ ${structuredOutputExample}
6163
6686
  const toolKinds = /* @__PURE__ */ new Map();
6164
6687
  const toolDefaults = /* @__PURE__ */ new Map();
6165
6688
  const functionTools = /* @__PURE__ */ new Map();
6689
+ const supersedeKeys = /* @__PURE__ */ new Map();
6690
+ const latestByKey = /* @__PURE__ */ new Map();
6166
6691
  for (const t of options.tools) {
6167
6692
  if (typeof t === "object" && "execute" in t) {
6168
6693
  functionTools.set(t.name, t.execute);
6694
+ if (t.supersedes) {
6695
+ supersedeKeys.set(t.name, t.supersedes);
6696
+ }
6169
6697
  }
6170
6698
  }
6171
6699
  for (const t of wireTools) {
@@ -6188,7 +6716,7 @@ ${structuredOutputExample}
6188
6716
  MAX_TURNS_LIMIT
6189
6717
  );
6190
6718
  const maxToolOutputChars = options.maxToolOutputChars ?? MAX_TOOL_OUTPUT_CHARS;
6191
- const traceId = randomUUID2();
6719
+ const traceId = randomUUID3();
6192
6720
  const messages = [
6193
6721
  { role: "user", content: JSON.stringify(options.input) }
6194
6722
  ];
@@ -6367,6 +6895,17 @@ ${structuredOutputExample}
6367
6895
  toolCallId: toolCall.id,
6368
6896
  ...isError && { isToolError: true }
6369
6897
  });
6898
+ const key = supersedeKeys.get(toolCall.name);
6899
+ if (key !== void 0 && !isError) {
6900
+ const earlier = latestByKey.get(key);
6901
+ if (earlier !== void 0) {
6902
+ messages[earlier] = {
6903
+ ...messages[earlier],
6904
+ content: SUPERSEDED_RESULT
6905
+ };
6906
+ }
6907
+ latestByKey.set(key, messages.length - 1);
6908
+ }
6370
6909
  onEvent?.({
6371
6910
  type: "tool_call_result",
6372
6911
  id: toolCall.id,
@@ -6484,7 +7023,7 @@ ${formatValidationErrors(errors)}`
6484
7023
  )
6485
7024
  );
6486
7025
  }
6487
- var DEFAULT_MAX_TURNS, MAX_TURNS_LIMIT, MAX_SCHEMA_REPAIR_ATTEMPTS, MAX_TOOL_OUTPUT_CHARS, MAX_TURN_ATTEMPTS, INITIAL_BACKOFF_MS, STALL_TIMEOUT_MS, UNSAFE_KEYS, TurnError;
7026
+ var DEFAULT_MAX_TURNS, MAX_TURNS_LIMIT, MAX_SCHEMA_REPAIR_ATTEMPTS, MAX_TOOL_OUTPUT_CHARS, SUPERSEDED_RESULT, MAX_TURN_ATTEMPTS, INITIAL_BACKOFF_MS, STALL_TIMEOUT_MS, UNSAFE_KEYS, TurnError;
6488
7027
  var init_local = __esm({
6489
7028
  async "src/task/local.ts"() {
6490
7029
  "use strict";
@@ -6495,6 +7034,9 @@ var init_local = __esm({
6495
7034
  MAX_TURNS_LIMIT = 100;
6496
7035
  MAX_SCHEMA_REPAIR_ATTEMPTS = 3;
6497
7036
  MAX_TOOL_OUTPUT_CHARS = 5e4;
7037
+ SUPERSEDED_RESULT = JSON.stringify({
7038
+ superseded: "An earlier result, replaced by a newer one from the same tool further on. Work from the latest."
7039
+ });
6498
7040
  MAX_TURN_ATTEMPTS = 5;
6499
7041
  INITIAL_BACKOFF_MS = 1e3;
6500
7042
  STALL_TIMEOUT_MS = 3e5;
@@ -7062,6 +7604,7 @@ var init_client = __esm({
7062
7604
  init_analytics();
7063
7605
  init_email();
7064
7606
  init_events();
7607
+ init_browser();
7065
7608
  await init_local();
7066
7609
  init_steps();
7067
7610
  init_metadata();
@@ -7118,6 +7661,7 @@ var init_client = __esm({
7118
7661
  _analytics;
7119
7662
  _email;
7120
7663
  _events;
7664
+ _browser;
7121
7665
  /** @internal Auth type — 'internal' for CALLBACK_TOKEN (managed mode), 'apiKey' otherwise. */
7122
7666
  _authType;
7123
7667
  /** @internal Usage source sent on step executions (from MINDSTUDIO_REQUEST_SOURCE).
@@ -8184,6 +8728,17 @@ var init_client = __esm({
8184
8728
  get events() {
8185
8729
  return this._events ??= createEvents(this._eventsRequest.bind(this));
8186
8730
  }
8731
+ /**
8732
+ * The `browser` namespace — a real Chrome your app drives. `open()` starts
8733
+ * a session; every action answers with the page afterward. See
8734
+ * {@link Browser}.
8735
+ */
8736
+ get browser() {
8737
+ return this._browser ??= createBrowser(
8738
+ this._browserRequest.bind(this),
8739
+ (stepType, step) => this.executeStep(stepType, step)
8740
+ );
8741
+ }
8187
8742
  /**
8188
8743
  * Outbound email: sending, the per-recipient delivery log, blast stats, and
8189
8744
  * this app's unsubscribe list.
@@ -8381,6 +8936,17 @@ var init_client = __esm({
8381
8936
  fallbackCode: "events_error"
8382
8937
  });
8383
8938
  }
8939
+ /**
8940
+ * @internal Transport for the `browser` namespace —
8941
+ * POST /_internal/v2/browser/<op> with the raw hook token. No 429 retry:
8942
+ * an action repeated is a second click.
8943
+ */
8944
+ async _browserRequest(op, body) {
8945
+ return this._brokeredRequest("browser", op, body, {
8946
+ fallbackMessage: "Browser call failed",
8947
+ fallbackCode: "browser_error"
8948
+ });
8949
+ }
8384
8950
  async _analyticsRequest(op, body) {
8385
8951
  const call = () => this._brokeredRequest("analytics", op, body, {
8386
8952
  fallbackMessage: "Analytics read failed",
@@ -9469,7 +10035,7 @@ async function startMcpServer(options) {
9469
10035
  capabilities: { tools: {} },
9470
10036
  serverInfo: {
9471
10037
  name: "mindstudio-agent",
9472
- version: "0.1.170"
10038
+ version: "0.1.172"
9473
10039
  },
9474
10040
  instructions: 'Welcome to MindStudio \u2014 a platform with 200+ AI models, 850+ third-party integrations, and pre-built agents.\n\nGetting started:\n1. Call `ask` with any question about the SDK \u2014 it knows every action, model, and connector and returns working code with real model IDs and config options. Examples: ask("generate an image with FLUX"), ask("what models support vision?"), ask("how do I send a Slack message?").\n2. Call `changeName` to set your display name \u2014 use your name or whatever your user calls you. This is how you\'ll appear in MindStudio request logs.\n3. If you have a profile picture, pass its public image URL to `changeProfilePicture`.\n4. For manual browsing, call `listActions` to discover all available actions.\n\nThen use the tools to generate text, images, video, audio, search the web, work with data sources, run agents, and more.\n\nImportant:\n- AI-powered actions (text generation, image generation, video, audio, etc.) cost money. Before running these, call `estimateActionCost` and confirm with the user before proceeding \u2014 unless they\'ve explicitly told you to go ahead.\n- Not all agents from `listAgents` are configured for API use. Do not try to run an agent just because it appears in the list \u2014 it will likely fail. Only run agents the user specifically asks you to run.'
9475
10041
  });
@@ -10411,7 +10977,7 @@ function isNewerVersion(current, latest) {
10411
10977
  return false;
10412
10978
  }
10413
10979
  async function checkForUpdate() {
10414
- const currentVersion = "0.1.170";
10980
+ const currentVersion = "0.1.172";
10415
10981
  if (!currentVersion || process.env.MINDSTUDIO_NO_UPDATE_CHECK) {
10416
10982
  return null;
10417
10983
  }
@@ -10446,7 +11012,7 @@ async function checkForUpdate() {
10446
11012
  }
10447
11013
  }
10448
11014
  function printUpdateNotice(latestVersion) {
10449
- const currentVersion = "0.1.170";
11015
+ const currentVersion = "0.1.172";
10450
11016
  process.stderr.write(
10451
11017
  `
10452
11018
  ${ansi2.cyanBright("Update available")} ${ansi2.gray(currentVersion + " \u2192")} ${ansi2.cyanBold(latestVersion)}
@@ -10459,7 +11025,7 @@ function isStandaloneBinary() {
10459
11025
  return !argv1.includes("node_modules");
10460
11026
  }
10461
11027
  async function cmdUpdate() {
10462
- const currentVersion = "0.1.170";
11028
+ const currentVersion = "0.1.172";
10463
11029
  process.stderr.write(
10464
11030
  ` ${ansi2.gray("Current version:")} ${currentVersion}
10465
11031
  `
@@ -10580,7 +11146,7 @@ async function cmdLogin(options) {
10580
11146
  process.stderr.write("\n");
10581
11147
  printLogo();
10582
11148
  process.stderr.write("\n");
10583
- const ver = "0.1.170";
11149
+ const ver = "0.1.172";
10584
11150
  process.stderr.write(
10585
11151
  ` ${ansi2.bold("MindStudio Agent")} ${ver ? " " + ansi2.gray("v" + ver) : ""}
10586
11152
  `
@@ -10892,7 +11458,7 @@ async function main() {
10892
11458
  const updatePromise = command !== "mcp" && command !== "login" && command !== "update" ? checkForUpdate() : Promise.resolve(null);
10893
11459
  try {
10894
11460
  if (command === "version" || command === "-v") {
10895
- process.stdout.write("0.1.170\n");
11461
+ process.stdout.write("0.1.172\n");
10896
11462
  return;
10897
11463
  }
10898
11464
  if (command === "login") {