feat(tinyfish): surface run profile diagnostics and a wall-clock cap (#7489)

* feat(tinyfish): surface run profile diagnostics and a wall-clock cap

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ej1gsFPVzN5xZZ3QzvK8bD

* fix(tinyfish): reject a malformed numeric cap instead of dropping it

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ej1gsFPVzN5xZZ3QzvK8bD

* docs(tinyfish): document the null case on the profile metadata fields

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ej1gsFPVzN5xZZ3QzvK8bD

* docs(tinyfish): describe a null profileId as unknown, not as proof

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ej1gsFPVzN5xZZ3QzvK8bD

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: waleedlatif1

apps/docs/content/docs/integrations/tinyfish.mdx

@@ -78,6 +78,7 @@ Run a TinyFish web agent against a website and wait for it to finish, returning
 | `browserProfile` | string | No | Browser engine: "lite" \(standard\) or "stealth" \(anti-detection\). Not a Browser Context Profile — use useProfile for saved logins |
 | `agentMode` | string | No | Agent behavior: "default" or "strict" \(fail fast\) |
 | `maxSteps` | number | No | Maximum tool-call steps before the agent stops \(1-500, default 150\) |
+| `maxDurationSeconds` | number | No | Maximum wall-clock seconds before the agent stops. Unlimited by default, so a run stalled on a slow page is only bounded by the step cap |
 | `outputSchema` | json | No | JSON Schema draft-07 contract the run result must satisfy |
 | `proxyEnabled` | boolean | No | Route the run through TinyFish’s Tetra proxy |
 | `proxyCountryCode` | string | No | Proxy country: US, GB, CA, DE, FR, JP, or AU |
@@ -112,6 +113,10 @@ Run a TinyFish web agent against a website and wait for it to finish, returning
 |   ↳ `retryAfter` | number | Suggested retry delay in seconds, null when not retryable |
 |   ↳ `helpUrl` | string | Troubleshooting documentation URL |
 |   ↳ `helpMessage` | string | Human-readable guidance |
+| `profileHint` | object | Present when TinyFish believes a Browser Context Profile would fix this failed run, such as one that stopped at a login wall |
+|   ↳ `message` | string | Why a Browser Context Profile would help this run |
+|   ↳ `setupUrl` | string | Path on the TinyFish dashboard that sets up a profile for the blocked domain |
+|   ↳ `reason` | string | auth_wall \(the run hit a login\) or bot_challenge \(the site blocked automation\) |
 
 ### TinyFish Start Agent Run
 
@@ -126,6 +131,7 @@ Queue a TinyFish web agent run and return its run ID immediately, without waitin
 | `browserProfile` | string | No | Browser engine: "lite" \(standard\) or "stealth" \(anti-detection\). Not a Browser Context Profile — use useProfile for saved logins |
 | `agentMode` | string | No | Agent behavior: "default" or "strict" \(fail fast\) |
 | `maxSteps` | number | No | Maximum tool-call steps before the agent stops \(1-500, default 150\) |
+| `maxDurationSeconds` | number | No | Maximum wall-clock seconds before the agent stops. Unlimited by default, so a run stalled on a slow page is only bounded by the step cap |
 | `outputSchema` | json | No | JSON Schema draft-07 contract the run result must satisfy |
 | `proxyEnabled` | boolean | No | Route the run through TinyFish’s Tetra proxy |
 | `proxyCountryCode` | string | No | Proxy country: US, GB, CA, DE, FR, JP, or AU |
@@ -184,6 +190,12 @@ Get the status, extracted result, and step history of a TinyFish automation run
 | `browserConfig` | object | Proxy settings the run executed with |
 |   ↳ `proxyEnabled` | boolean | Whether a proxy was used |
 |   ↳ `proxyCountryCode` | string | Proxy country code |
+| `profileAttached` | boolean | Whether the run actually started from a Browser Context Profile, null when the API omits it — treat null as unknown rather than as false |
+| `profileId` | string | Browser Context Profile the run attached. Null covers both no profile and a payload that omitted the field, so read profileAttached alongside it rather than reading null as proof |
+| `profileHint` | object | Present when TinyFish believes a Browser Context Profile would fix this failed run |
+|   ↳ `message` | string | Why a Browser Context Profile would help this run |
+|   ↳ `setupUrl` | string | Path on the TinyFish dashboard that sets up a profile for the blocked domain |
+|   ↳ `reason` | string | auth_wall \(the run hit a login\) or bot_challenge \(the site blocked automation\) |
 | `videoUrl` | string | Presigned recording URL, expires 15 minutes after it is issued |
 | `steps` | array | Steps the agent took during the run |
 |   ↳ `id` | string | Step identifier |
@@ -261,6 +273,12 @@ List TinyFish automation runs, optionally filtered by status, goal text, or crea
 |   ↳ `browserConfig` | object | Proxy settings the run executed with |
 |     ↳ `proxyEnabled` | boolean | Whether a proxy was used |
 |     ↳ `proxyCountryCode` | string | Proxy country code |
+|   ↳ `profileAttached` | boolean | Whether the run actually started from a Browser Context Profile, null when the API omits it — treat null as unknown rather than as false |
+|   ↳ `profileId` | string | Browser Context Profile the run attached. Null covers both no profile and a payload that omitted the field, so read profileAttached alongside it rather than reading null as proof |
+|   ↳ `profileHint` | object | Present when TinyFish believes a Browser Context Profile would fix this failed run |
+|     ↳ `message` | string | Why a Browser Context Profile would help this run |
+|     ↳ `setupUrl` | string | Path on the TinyFish dashboard that sets up a profile for the blocked domain |
+|     ↳ `reason` | string | auth_wall \(the run hit a login\) or bot_challenge \(the site blocked automation\) |
 | `total` | number | Total runs matching the filters |
 | `nextCursor` | string | Cursor for the next page, null when there are no more results |
 | `hasMore` | boolean | Whether more results follow this page |
@@ -371,7 +389,9 @@ List the Browser Context Profiles saved on the TinyFish account, with the ids an
 |   ↳ `name` | string | Profile name, such as "Salesforce Production" |
 |   ↳ `proxyCountryCode` | string | Country the profile proxies through, null when it has no proxy |
 |   ↳ `fingerprintSeed` | string | Seed for the browser fingerprint the profile replays, null when the API omits it |
+|   ↳ `domainCount` | number | How many domains the profile holds saved state for, null when the API omits it. Zero means it was created but never logged into |
 |   ↳ `createdAt` | string | ISO 8601 timestamp when the profile was created, null when the API omits it |
-|   ↳ `isDefault` | boolean | Whether runs with no Browser Profile ID use this one, null when the API does not report it |
+|   ↳ `updatedAt` | string | ISO 8601 timestamp when the profile was last saved, null when the API omits it |
+|   ↳ `isDefault` | boolean | Whether runs with no Browser Profile ID use this one, null when the API omits it |
 
 

apps/sim/blocks/blocks/tinyfish.ts

@@ -181,6 +181,15 @@ Return ONLY the JSON Schema - no explanations, no extra text.`,
       condition: { field: 'operation', value: AUTOMATION_OPERATIONS },
       mode: 'advanced',
     },
+    {
+      id: 'maxDurationSeconds',
+      title: 'Max Duration (seconds)',
+      type: 'short-input',
+      placeholder: '300',
+      description: 'Wall-clock limit before the agent stops. Unlimited when empty',
+      condition: { field: 'operation', value: AUTOMATION_OPERATIONS },
+      mode: 'advanced',
+    },
     {
       id: 'proxyEnabled',
       title: 'Use Proxy',
@@ -492,11 +501,30 @@ Return ONLY the comma-separated URL list - no explanations, no extra text.`,
       params: (params) => {
         const result: Record<string, unknown> = {}
 
+        /**
+         * A numeric text input that does not parse is rejected rather than
+         * dropped. Omitting it silently hands the run TinyFish's default — no
+         * wall-clock limit at all for Max Duration — while the block still
+         * shows the value the user typed.
+         */
+        const toFiniteNumber = (value: string, field: string): number => {
+          const parsed = Number(value)
+          if (!Number.isFinite(parsed)) {
+            throw new Error(`Invalid numeric value for ${field}: ${value}`)
+          }
+          return parsed
+        }
+
         const maxSteps = String(params.maxSteps ?? '').trim()
-        if (maxSteps) result.maxSteps = Number(maxSteps)
+        if (maxSteps) result.maxSteps = toFiniteNumber(maxSteps, 'Max Steps')
+
+        const maxDurationSeconds = String(params.maxDurationSeconds ?? '').trim()
+        if (maxDurationSeconds) {
+          result.maxDurationSeconds = toFiniteNumber(maxDurationSeconds, 'Max Duration (seconds)')
+        }
 
         const limit = String(params.limit ?? '').trim()
-        if (limit) result.limit = Number(limit)
+        if (limit) result.limit = toFiniteNumber(limit, 'Limit')
 
         /**
          * The list filter has its own sub-block id so it does not collide with
@@ -520,6 +548,10 @@ Return ONLY the comma-separated URL list - no explanations, no extra text.`,
     browserProfile: { type: 'string', description: 'Browser engine: lite or stealth' },
     agentMode: { type: 'string', description: 'Agent behavior: default or strict' },
     maxSteps: { type: 'number', description: 'Maximum agent steps' },
+    maxDurationSeconds: {
+      type: 'number',
+      description: 'Maximum wall-clock seconds before the agent stops',
+    },
     proxyEnabled: { type: 'boolean', description: 'Route the run through the Tetra proxy' },
     proxyCountryCode: { type: 'string', description: 'Proxy country code' },
     useVault: { type: 'boolean', description: 'Allow vault credentials during the run' },
@@ -578,7 +610,7 @@ Return ONLY the comma-separated URL list - no explanations, no extra text.`,
     runs: {
       type: 'json',
       description:
-        'Runs matching the list filters [{runId, status, goal, createdAt, startedAt, finishedAt, numOfSteps, result, schemaValidation, error, streamingUrl, browserConfig}]',
+        'Runs matching the list filters [{runId, status, goal, createdAt, startedAt, finishedAt, numOfSteps, result, schemaValidation, error, streamingUrl, browserConfig, profileAttached, profileId, profileHint}]',
     },
     total: { type: 'number', description: 'Total runs matching the list filters' },
     nextCursor: { type: 'string', description: 'Cursor for the next page of runs' },
@@ -596,10 +628,23 @@ Return ONLY the comma-separated URL list - no explanations, no extra text.`,
       description:
         'Vault credentials available to a run [{itemId, connectionId, label, vaultName, domains, fieldMetadata, hasTotp}]',
     },
+    profileId: {
+      type: 'string',
+      description: 'Browser Context Profile the run attached, null when none did',
+    },
+    profileAttached: {
+      type: 'boolean',
+      description: 'Whether the run actually started from a Browser Context Profile',
+    },
+    profileHint: {
+      type: 'json',
+      description:
+        'Set when TinyFish believes a Browser Context Profile would fix a failed run {message, setupUrl, reason} — reason is auth_wall or bot_challenge',
+    },
     profiles: {
       type: 'json',
       description:
-        'Browser Context Profiles a run can start from [{profileId, name, proxyCountryCode, fingerprintSeed, createdAt, isDefault}]. Every field but profileId and name can be null when the API omits it',
+        'Browser Context Profiles a run can start from [{profileId, name, proxyCountryCode, fingerprintSeed, domainCount, createdAt, updatedAt, isDefault}]. Every field but profileId and name can be null when the API omits it',
     },
   },
 }
@@ -718,7 +763,7 @@ export const TinyFishBlockMeta = {
       description:
         'Read a failed TinyFish run and decide whether to retry, reword the goal, or escalate. Use when an automation returns FAILED or a workflow keeps burning steps without a result.',
       content:
-        '# Diagnose A Failed Run\n\nA failed automation comes back as a normal 200 response with the failure inside the run, so read `status` before trusting `result`.\n\n## Steps\n1. Read `error.category`. `AGENT_FAILURE` means the goal or the page is the problem — reword the goal or start the run closer to the target. `SYSTEM_FAILURE` is TinyFish-side; wait `error.retryAfter` seconds and retry the same input. `BILLING_FAILURE` means the TinyFish wallet is empty and no retry will help. `UNKNOWN` should be treated as retryable once.\n2. Compare `numOfSteps` against the Max Steps you set. Hitting the cap means the agent was still working, so raise the cap or narrow the goal.\n3. If an Output Schema was set, read `schemaValidation.errors` — a run can reach the right page and still fail on one mistyped field, and `rePromptAttempts` shows how hard TinyFish already tried to repair it.\n4. For an async run, call Get Run and read the `steps` list to find the last action before the failure. `videoUrl` gives a recording, but the link expires 15 minutes after it is issued.\n\n## Output\nState the category, the concrete cause, and the single next action. Quote `error.message` rather than paraphrasing it, and do not retry a `BILLING_FAILURE` or an `AGENT_FAILURE` without changing the input first.',
+        '# Diagnose A Failed Run\n\nA failed automation comes back as a normal 200 response with the failure inside the run, so read `status` before trusting `result`.\n\n## Steps\n1. Read `error.category`. `AGENT_FAILURE` means the goal or the page is the problem — reword the goal or start the run closer to the target. `SYSTEM_FAILURE` is TinyFish-side; wait `error.retryAfter` seconds and retry the same input. `BILLING_FAILURE` means the TinyFish wallet is empty and no retry will help. `UNKNOWN` should be treated as retryable once.\n2. Read `profileHint` whenever it is set — TinyFish attaches it only when a Browser Context Profile would likely fix the run, so it outranks the category above. `reason` is `auth_wall` (the agent hit a login) or `bot_challenge` (the site blocked automation); the fix is to set up a profile for that domain and rerun with Use Browser Profile on, not to reword the goal.\n3. Compare `numOfSteps` against the Max Steps you set. Hitting the cap means the agent was still working, so raise the cap or narrow the goal. If the run instead stopped early on a slow page, set Max Duration.\n4. If an Output Schema was set, read `schemaValidation.errors` — a run can reach the right page and still fail on one mistyped field, and `rePromptAttempts` shows how hard TinyFish already tried to repair it.\n5. For an async run, call Get Run and read the `steps` list to find the last action before the failure. `videoUrl` gives a recording, but the link expires 15 minutes after it is issued.\n\n## Output\nState the category, the concrete cause, and the single next action. Quote `error.message` rather than paraphrasing it, and do not retry a `BILLING_FAILURE` or an `AGENT_FAILURE` without changing the input first.',
     },
     {
       name: 'queue-and-track-long-runs',

apps/sim/tools/generated/tool-metadata.ts

@@ -14,10 +14,10 @@ import type { ToolConfig } from '@/tools/types'
 /**
  * Reads the profile array out of the list payload.
  *
- * TinyFish publishes no example response for `GET /v1/profiles`, so all three
- * shapes a list endpoint plausibly returns are accepted rather than betting on
- * one: a bare array, and the `profiles` and `data` envelopes its other list
- * endpoints use.
+ * The OpenAPI spec documents a `{ profiles: [...] }` envelope, which is what
+ * this reads first. The bare array and the `data` envelope its other list
+ * endpoints use stay accepted because the prose docs show no example at all and
+ * tolerating them costs nothing.
  */
 function extractProfiles(data: TinyFishRawProfiles | TinyFishRawProfile[]): TinyFishRawProfile[] {
   if (Array.isArray(data)) return data
@@ -72,8 +72,10 @@ export const listProfilesTool: ToolConfig<
           name: profile?.name ?? '',
           proxyCountryCode: profile?.proxy_country_code ?? null,
           fingerprintSeed: profile?.fingerprint_seed ?? null,
+          domainCount: profile?.domain_count ?? null,
           createdAt: profile?.created_at ?? null,
-          isDefault: profile?.set_as_default ?? profile?.is_default ?? null,
+          updatedAt: profile?.updated_at ?? null,
+          isDefault: profile?.is_default ?? null,
         })),
       },
     }
@@ -104,17 +106,31 @@ export const listProfilesTool: ToolConfig<
             optional: true,
             nullable: true,
           },
+          domainCount: {
+            type: 'number',
+            description:
+              'How many domains the profile holds saved state for, null when the API omits it. Zero means it was created but never logged into',
+            optional: true,
+            nullable: true,
+          },
           createdAt: {
             type: 'string',
             description:
               'ISO 8601 timestamp when the profile was created, null when the API omits it',
             optional: true,
             nullable: true,
           },
+          updatedAt: {
+            type: 'string',
+            description:
+              'ISO 8601 timestamp when the profile was last saved, null when the API omits it',
+            optional: true,
+            nullable: true,
+          },
           isDefault: {
             type: 'boolean',
             description:
-              'Whether runs with no Browser Profile ID use this one, null when the API does not report it',
+              'Whether runs with no Browser Profile ID use this one, null when the API omits it',
             optional: true,
             nullable: true,
           },

apps/sim/tools/generated/tool-outputs.ts

@@ -1,5 +1,6 @@
 import { tinyfishAgentHosting } from '@/tools/tinyfish/hosting'
 import {
+  PROFILE_HINT_OUTPUT_PROPERTIES,
   RUN_ERROR_OUTPUT_PROPERTIES,
   SCHEMA_VALIDATION_OUTPUT_PROPERTIES,
   type TinyFishRawRun,
@@ -9,6 +10,7 @@ import {
 import {
   AUTOMATION_TOOL_PARAMS,
   buildAutomationBody,
+  mapProfileHint,
   mapRunError,
   mapSchemaValidation,
   selectAutomationModelInput,
@@ -62,6 +64,7 @@ export const runTool: ToolConfig<TinyFishRunParams, TinyFishRunResponse> = {
         result: data.result ?? null,
         schemaValidation: mapSchemaValidation(data.schema_validation),
         error: mapRunError(data.error),
+        profileHint: mapProfileHint(data.profile_hint),
       },
       error: data.error?.message ?? undefined,
     }
@@ -99,5 +102,13 @@ export const runTool: ToolConfig<TinyFishRunParams, TinyFishRunResponse> = {
       optional: true,
       properties: RUN_ERROR_OUTPUT_PROPERTIES,
     },
+    profileHint: {
+      type: 'object',
+      description:
+        'Present when TinyFish believes a Browser Context Profile would fix this failed run, such as one that stopped at a login wall',
+      optional: true,
+      nullable: true,
+      properties: PROFILE_HINT_OUTPUT_PROPERTIES,
+    },
   },
 }