fix(managed-agent): address review findings on session lifecycle ops

- List Events kept the OLDEST slice when capped, dropping the agent's most
  recent reply. Paging is exhaustive again and the cap now keeps the newest
  N after ordering, with a `truncated` flag so callers know it is a tail.
- listPaginated returned whole pages past maxItems; it now trims to the
  exact cap.
- A whitespace-only title passed the update guard and would have cleared an
  existing session title. Blank is now treated as not provided.
- Interrupt had no request timeout and could hang; bounded at 15s while
  still honoring the workflow signal.
- Custom-tool gates were surfaced by Get Session but could not be answered,
  since they need user.custom_tool_result rather than a confirmation. Adds a
  Respond To Custom Tool operation and a `kind` on each pending gate so a
  workflow routes to the right one.
- Docs rendered a raw ${DEFAULT_EVENT_LIMIT} placeholder for the default.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/managed_agent.mdx

@@ -125,7 +125,7 @@ Read a Managed Agent session: status, stop reason, token usage, metadata, and an
 | `status` | string | Session status — 'idle', 'running', 'rescheduling', or 'terminated'. |
 | `stopReason` | string | Why the session last stopped, e.g. 'end_turn' or 'requires_action'. |
 | `requiresAction` | boolean | True when the session is waiting on a tool confirmation or custom tool result. |
-| `pendingTools` | json | Tool calls awaiting approval — \[\{id, eventType, name, input\}\]. Pass each id to Respond To Tool Confirmation. |
+| `pendingTools` | json | Blocking tool calls — \[\{id, eventType, kind, name, input\}\]. Route by kind: 'confirmation' ids go to Respond To Tool Confirmation, 'custom_tool_result' ids go to Respond To Custom Tool. |
 | `metadata` | json | Session metadata. |
 | `title` | string | Session title. |
 | `inputTokens` | number | Cumulative input tokens. |
@@ -140,7 +140,7 @@ Read a Managed Agent session's event history and the agent's reply text.
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `eventTypes` | array | No | Optional event-type filter, e.g. \['agent.message'\]. Omit to return every event. |
-| `limit` | number | No | Maximum events to return \(default $\{DEFAULT_EVENT_LIMIT\}\). |
+| `limit` | number | No | Maximum events to return, keeping the most recent \(default 500\). |
 
 #### Output
 
@@ -150,6 +150,7 @@ Read a Managed Agent session's event history and the agent's reply text.
 | `events` | json | Session events, oldest first. |
 | `count` | number | Number of events returned. |
 | `assistantText` | string | Concatenated text of every persisted agent.message, in order. |
+| `truncated` | boolean | True when the limit was hit and older events were dropped. |
 
 ### `managed_agent_update_session`
 
@@ -195,7 +196,7 @@ Allow or deny the tool calls a Managed Agent session is waiting on before it can
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
-| `toolUseIds` | array | Yes | Blocking tool-use EVENT ids, from Get Session pendingTools\[\].id \(not toolu_ ids\). |
+| `toolUseIds` | array | Yes | Blocking tool-use EVENT ids, from Get Session pendingTools\[\].id where kind is 'confirmation' \(not toolu_ ids\). |
 | `decision` | string | Yes | 'allow' to let the tools run, or 'deny' to reject them. |
 | `denyMessage` | string | No | Reason surfaced to the agent. Only sent when the decision is deny. |
 
@@ -207,6 +208,25 @@ Allow or deny the tool calls a Managed Agent session is waiting on before it can
 | `decision` | string | The decision applied — 'allow' or 'deny'. |
 | `confirmedToolUseIds` | json | The tool-use event ids that were answered. |
 
+### `managed_agent_respond_custom_tool`
+
+Return the result of a custom tool a Managed Agent session is waiting on so it can continue.
+
+#### Input
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `customToolUseIds` | array | Yes | Custom tool-use EVENT ids, from Get Session pendingTools\[\].id where kind is 'custom_tool_result'. |
+| `result` | string | Yes | The tool's output, returned to the agent as text. |
+| `isError` | boolean | No | Mark the result as a failure so the agent can adjust its approach. |
+
+#### Output
+
+| Parameter | Type | Description |
+| --------- | ---- | ----------- |
+| `sessionId` | string | The session that was answered. |
+| `answeredToolUseIds` | json | The custom tool-use event ids that were answered. |
+
 ### `managed_agent_archive_session`
 
 Archive a Managed Agent session, preserving its history. Not reversible.

apps/sim/blocks/blocks/managed_agent.test.ts

@@ -85,6 +85,7 @@ describe('Managed Agent block — operation routing', () => {
     ['update_session', 'managed_agent_update_session'],
     ['interrupt_session', 'managed_agent_interrupt_session'],
     ['respond_tool_confirmation', 'managed_agent_respond_tool_confirmation'],
+    ['respond_custom_tool', 'managed_agent_respond_custom_tool'],
     ['archive_session', 'managed_agent_archive_session'],
     ['delete_session', 'managed_agent_delete_session'],
   ])('maps %s to %s', (operation, toolId) => {
@@ -112,6 +113,7 @@ describe('Managed Agent block — per-operation field visibility', () => {
       'update_session',
       'interrupt_session',
       'respond_tool_confirmation',
+      'respond_custom_tool',
       'archive_session',
       'delete_session',
     ]) {
@@ -153,6 +155,17 @@ describe('Managed Agent block — per-operation field visibility', () => {
     expect(isVisible('denyMessage', { operation: 'send_message', decision: 'deny' })).toBe(false)
   })
 
+  it('separates confirmation fields from custom-tool-result fields', () => {
+    // A confirmation cannot unblock a custom tool, so the two operations must
+    // not share inputs — otherwise a workflow can silently answer the wrong way.
+    expect(isVisible('toolUseIds', { operation: 'respond_tool_confirmation' })).toBe(true)
+    expect(isVisible('toolUseIds', { operation: 'respond_custom_tool' })).toBe(false)
+    expect(isVisible('customToolUseIds', { operation: 'respond_custom_tool' })).toBe(true)
+    expect(isVisible('customToolUseIds', { operation: 'respond_tool_confirmation' })).toBe(false)
+    expect(isVisible('result', { operation: 'respond_custom_tool' })).toBe(true)
+    expect(isVisible('decision', { operation: 'respond_custom_tool' })).toBe(false)
+  })
+
   it('shows metadata for update session but not the agent config fields', () => {
     expect(isVisible('sessionParameters', { operation: 'update_session' })).toBe(true)
     expect(isVisible('title', { operation: 'update_session' })).toBe(true)

apps/sim/blocks/blocks/managed_agent.ts

@@ -2938,6 +2938,10 @@
           "name": "Respond to tool confirmation",
           "description": "Allow or deny the tool calls a Managed Agent session is waiting on before it can continue."
         },
+        {
+          "name": "Respond to custom tool",
+          "description": "Return the result of a custom tool a Managed Agent session is waiting on so it can continue."
+        },
         {
           "name": "Archive session",
           "description": "Archive a Managed Agent session, preserving its history. Not reversible."
@@ -2947,7 +2951,7 @@
           "description": "Permanently delete a Managed Agent session, its events, and its sandbox. Not reversible."
         }
       ],
-      "operationCount": 10,
+      "operationCount": 11,
       "triggers": [],
       "triggerCount": 0,
       "authType": "api-key",

apps/sim/lib/integrations/integrations.json

@@ -9,6 +9,7 @@ import {
   listSessionEvents,
   parseSessionSnapshot,
   resolvePendingToolGates,
+  sendCustomToolResults,
   sendToolConfirmations,
   updateSession,
 } from '@/lib/managed-agents/session-client'
@@ -402,10 +403,17 @@ describe('resolvePendingToolGates', () => {
     })
 
     expect(gates).toEqual([
-      { id: 'sevt_1', eventType: 'agent.tool_use', name: 'bash', input: { command: 'ls' } },
+      {
+        id: 'sevt_1',
+        eventType: 'agent.tool_use',
+        kind: 'confirmation',
+        name: 'bash',
+        input: { command: 'ls' },
+      },
       {
         id: 'sevt_2',
         eventType: 'agent.mcp_tool_use',
+        kind: 'confirmation',
         name: 'create_issue',
         input: { title: 'x' },
       },
@@ -442,6 +450,36 @@ describe('resolvePendingToolGates', () => {
     expect(gates).toEqual([{ id: 'sevt_1' }, { id: 'sevt_2' }])
   })
 
+  it('labels a custom-tool gate as needing a custom tool result, not a confirmation', async () => {
+    // A confirmation cannot unblock a custom tool — the agent is waiting on the
+    // tool's actual output — so the kind must route callers to the right op.
+    global.fetch = vi.fn(async () =>
+      Response.json({
+        data: [{ id: 'sevt_9', type: 'agent.custom_tool_use', name: 'lookup_order' }],
+        next_page: null,
+      })
+    ) as unknown as typeof fetch
+
+    const gates = await resolvePendingToolGates({
+      apiKey: 'sk-ant-fake',
+      sessionId: 'sesn_1',
+      eventIds: ['sevt_9'],
+    })
+    expect(gates[0]?.kind).toBe('custom_tool_result')
+  })
+
+  it('omits kind when the event could not be resolved', async () => {
+    global.fetch = vi.fn(async () => {
+      throw new Error('network down')
+    }) as unknown as typeof fetch
+    const gates = await resolvePendingToolGates({
+      apiKey: 'sk-ant-fake',
+      sessionId: 'sesn_1',
+      eventIds: ['sevt_1'],
+    })
+    expect(gates[0]).toEqual({ id: 'sevt_1' })
+  })
+
   it('short-circuits with no ids', async () => {
     const spy = vi.fn() as unknown as typeof fetch
     global.fetch = spy
@@ -458,28 +496,51 @@ describe('listSessionEvents — bounded reads', () => {
     global.fetch = originalFetch
   })
 
-  const pagedFetch = () =>
-    vi.fn(async () =>
-      Response.json({
+  /** Emits `pages` pages of 100 chronologically-increasing events. */
+  const pagedFetch = (pages: number) => {
+    let page = 0
+    return vi.fn(async () => {
+      const offset = page * 100
+      page += 1
+      return Response.json({
         data: Array.from({ length: 100 }, (_, i) => ({
-          id: `e${i}`,
+          id: `e${offset + i}`,
           type: 'agent.message',
-          processed_at: '2026-01-01T00:00:00Z',
+          processed_at: new Date(Date.UTC(2026, 0, 1) + (offset + i) * 1000).toISOString(),
         })),
-        next_page: 'cursor',
+        next_page: page < pages ? `cursor-${page}` : null,
       })
-    ) as unknown as typeof fetch
+    }) as unknown as typeof fetch
+  }
 
-  it('stops paging once maxItems is reached', async () => {
-    const spy = pagedFetch()
-    global.fetch = spy
+  it('returns exactly maxItems, never a whole extra page', async () => {
+    global.fetch = pagedFetch(3)
     const events = await listSessionEvents({
       apiKey: 'sk-ant-fake',
       sessionId: 'sesn_1',
       maxItems: 250,
     })
-    // 3 pages of 100 covers 250; a 4th would exceed the cap.
-    expect((spy as unknown as ReturnType<typeof vi.fn>).mock.calls).toHaveLength(3)
+    expect(events).toHaveLength(250)
+  })
+
+  it('keeps the NEWEST events when capping, not the oldest', async () => {
+    // Ascending history: e0 (oldest) .. e249 (newest). A cap of 10 must return
+    // the last ten — capping the fetch instead would return e0..e9 and silently
+    // drop the agent's most recent reply, which is what callers read this for.
+    global.fetch = pagedFetch(3)
+    const events = await listSessionEvents({
+      apiKey: 'sk-ant-fake',
+      sessionId: 'sesn_1',
+      maxItems: 10,
+    })
+    expect(events).toHaveLength(10)
+    expect(events[0]?.id).toBe('e290')
+    expect(events.at(-1)?.id).toBe('e299')
+  })
+
+  it('returns the whole history when uncapped', async () => {
+    global.fetch = pagedFetch(3)
+    const events = await listSessionEvents({ apiKey: 'sk-ant-fake', sessionId: 'sesn_1' })
     expect(events).toHaveLength(300)
   })
 
@@ -497,3 +558,54 @@ describe('listSessionEvents — bounded reads', () => {
     expect(new URL(url).searchParams.getAll('types[]')).toEqual(['agent.message', 'agent.tool_use'])
   })
 })
+
+describe('sendCustomToolResults', () => {
+  const originalFetch = global.fetch
+  afterEach(() => {
+    global.fetch = originalFetch
+  })
+
+  it('sends a user.custom_tool_result per pending call', async () => {
+    const spy = vi.fn(async () => Response.json({})) as unknown as typeof fetch
+    global.fetch = spy
+    await sendCustomToolResults({
+      apiKey: 'sk-ant-fake',
+      sessionId: 'sesn_1',
+      results: [{ customToolUseId: 'sevt_9', content: 'order #42 shipped', isError: false }],
+    })
+    const [, init] = (spy as unknown as ReturnType<typeof vi.fn>).mock.calls[0] as [
+      string,
+      RequestInit,
+    ]
+    expect(JSON.parse(init.body as string)).toEqual({
+      events: [
+        {
+          type: 'user.custom_tool_result',
+          custom_tool_use_id: 'sevt_9',
+          content: [{ type: 'text', text: 'order #42 shipped' }],
+          is_error: false,
+        },
+      ],
+    })
+  })
+
+  it('defaults is_error to false and honors an explicit failure', async () => {
+    const spy = vi.fn(async () => Response.json({})) as unknown as typeof fetch
+    global.fetch = spy
+    await sendCustomToolResults({
+      apiKey: 'sk-ant-fake',
+      sessionId: 'sesn_1',
+      results: [
+        { customToolUseId: 'a', content: 'ok' },
+        { customToolUseId: 'b', content: 'lookup failed', isError: true },
+      ],
+    })
+    const [, init] = (spy as unknown as ReturnType<typeof vi.fn>).mock.calls[0] as [
+      string,
+      RequestInit,
+    ]
+    const events = JSON.parse(init.body as string).events
+    expect(events[0].is_error).toBe(false)
+    expect(events[1].is_error).toBe(true)
+  })
+})