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

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 |
+| `profileId` | string | Browser Context Profile the run attached, null when none did |
+| `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 |
+|   ↳ `profileId` | string | Browser Context Profile the run attached, null when none did |
+|   ↳ `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. 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',
@@ -495,6 +504,9 @@ Return ONLY the comma-separated URL list - no explanations, no extra text.`,
         const maxSteps = String(params.maxSteps ?? '').trim()
         if (maxSteps) result.maxSteps = Number(maxSteps)
 
+        const maxDurationSeconds = String(params.maxDurationSeconds ?? '').trim()
+        if (maxDurationSeconds) result.maxDurationSeconds = Number(maxDurationSeconds)
+
         const limit = String(params.limit ?? '').trim()
         if (limit) result.limit = Number(limit)
 
@@ -520,6 +532,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' },
@@ -596,6 +612,19 @@ 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:
@@ -718,7 +747,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. 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,
+    },
   },
 }

apps/sim/tools/tinyfish/list_profiles.ts

@@ -44,6 +44,16 @@ describe('buildAutomationBody', () => {
     expect(body.agent_config).toEqual({ mode: 'strict', max_steps: 50 })
   })
 
+  it('sends a wall-clock cap alongside the step cap', () => {
+    const body = buildAutomationBody({
+      url: 'https://example.com',
+      goal: 'Find pricing',
+      maxSteps: 50,
+      maxDurationSeconds: 300,
+    })
+    expect(body.agent_config).toEqual({ max_steps: 50, max_duration_seconds: 300 })
+  })
+
   it('omits agent_config entirely when neither field is set', () => {
     const body = buildAutomationBody({ url: 'https://example.com', goal: 'Find pricing' })
     expect(body).not.toHaveProperty('agent_config')
@@ -227,6 +237,7 @@ describe('tinyfish_run', () => {
       result: { price: 799 },
       schemaValidation: { valid: true, rePromptAttempts: 0, errors: [] },
       error: null,
+      profileHint: null,
     })
   })
 
@@ -653,6 +664,64 @@ describe('tinyfish_list_vault_items', () => {
   })
 })
 
+describe('tinyfish profile diagnostics', () => {
+  it('surfaces the profile nudge on a failed synchronous run', async () => {
+    const result = await runTool.transformResponse!(
+      jsonResponse({
+        run_id: 'run_1',
+        status: 'FAILED',
+        num_of_steps: 4,
+        error: { message: 'Blocked', category: 'AGENT_FAILURE' },
+        profile_hint: {
+          message: 'Set up a Browser Context Profile to sign in first',
+          setup_url: '/profiles/prof_abc123/setup?domain=example.com',
+          reason: 'auth_wall',
+        },
+      })
+    )
+
+    expect(result.success).toBe(false)
+    expect(result.output.profileHint).toEqual({
+      message: 'Set up a Browser Context Profile to sign in first',
+      setupUrl: '/profiles/prof_abc123/setup?domain=example.com',
+      reason: 'auth_wall',
+    })
+  })
+
+  it('reports no hint rather than a half-filled one when a field is missing', async () => {
+    const result = await runTool.transformResponse!(
+      jsonResponse({
+        run_id: 'run_1',
+        status: 'FAILED',
+        profile_hint: { message: 'Try a profile', reason: 'bot_challenge' },
+      })
+    )
+    expect(result.output.profileHint).toBeNull()
+  })
+
+  it('reports which profile a run actually attached', async () => {
+    const result = await getRunTool.transformResponse!(
+      jsonResponse({
+        run_id: 'run_1',
+        status: 'COMPLETED',
+        profile_attached: true,
+        profile_id: 'prof_abc123',
+      })
+    )
+    expect(result.output.profileAttached).toBe(true)
+    expect(result.output.profileId).toBe('prof_abc123')
+  })
+
+  it('leaves the profile fields null on a run that attached none', async () => {
+    const result = await getRunTool.transformResponse!(
+      jsonResponse({ run_id: 'run_1', status: 'COMPLETED' })
+    )
+    expect(result.output.profileAttached).toBeNull()
+    expect(result.output.profileId).toBeNull()
+    expect(result.output.profileHint).toBeNull()
+  })
+})
+
 describe('tinyfish profile visibility', () => {
   it('keeps the profile fields out of the schema the agent model writes', () => {
     for (const tool of [runTool, runAsyncTool]) {
@@ -672,8 +741,10 @@ describe('tinyfish_list_profiles', () => {
             name: 'Salesforce Production',
             proxy_country_code: 'US',
             fingerprint_seed: '12345678',
+            domain_count: 3,
             created_at: '2026-06-04T18:00:00.000Z',
-            set_as_default: true,
+            updated_at: '2026-06-05T09:30:00.000Z',
+            is_default: true,
           },
         ],
       })
@@ -684,7 +755,9 @@ describe('tinyfish_list_profiles', () => {
       name: 'Salesforce Production',
       proxyCountryCode: 'US',
       fingerprintSeed: '12345678',
+      domainCount: 3,
       createdAt: '2026-06-04T18:00:00.000Z',
+      updatedAt: '2026-06-05T09:30:00.000Z',
       isDefault: true,
     })
   })