fix(managed-agent): floor event cap and make metadata clearing explicit

- A `maxItems` between 0 and 1 slipped past the zero guard and became
  `slice(-0)` — the whole history — because slice truncates its index toward
  zero. The cap is now floored at the library boundary, so no caller can hit
  it whatever they pass.
- Update Session documented full metadata replacement but could not express
  a clear: an empty map normalizes to "absent". Inferring the clear from
  emptiness would be worse, since an untouched table is also empty and would
  wipe metadata on every title-only update. Adds an explicit `clearMetadata`
  instead, and corrects the parameter's documentation.

Author: waleedlatif1

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

@@ -161,7 +161,8 @@ Update a Managed Agent session's title or metadata.
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `title` | string | No | New session title. |
-| `sessionParameters` | object | No | Replacement metadata map \(replaces all stored metadata, not merged\). |
+| `sessionParameters` | object | No | Replacement metadata map \(replaces all stored metadata, not merged\). Leaving it empty leaves the stored metadata unchanged — use clearMetadata to remove it. |
+| `clearMetadata` | boolean | No | Removes all of the session's stored metadata. Overrides any map supplied above. |
 
 #### Output
 

apps/sim/blocks/blocks/managed_agent.ts

@@ -651,6 +651,32 @@ describe('listSessionEvents — bounded reads', () => {
     expect(negative.events).toHaveLength(0)
   })
 
+  it.each([0.5, 0.99, 0, -0.5, -5])(
+    'never returns the whole history for the sub-integer cap %p',
+    async (maxItems) => {
+      // `slice` truncates its index toward zero, so any cap under 1 becomes
+      // `slice(-0)` — the entire array — unless it is floored first.
+      global.fetch = pagedFetch(1)
+      const res = await listSessionEventsPage({
+        apiKey: 'sk-ant-fake',
+        sessionId: 'sesn_1',
+        maxItems,
+      })
+      expect(res.events).toHaveLength(0)
+      expect(res.total).toBe(100)
+    }
+  )
+
+  it('floors a fractional cap above 1 rather than widening it', async () => {
+    global.fetch = pagedFetch(1)
+    const res = await listSessionEventsPage({
+      apiKey: 'sk-ant-fake',
+      sessionId: 'sesn_1',
+      maxItems: 10.9,
+    })
+    expect(res.events).toHaveLength(10)
+  })
+
   it('returns the whole history when uncapped', async () => {
     global.fetch = pagedFetch(3)
     const events = await listSessionEvents({ apiKey: 'sk-ant-fake', sessionId: 'sesn_1' })

apps/sim/lib/managed-agents/session-client.test.ts

@@ -617,15 +617,19 @@ export async function listSessionEventsPage(
     (a, b) => parseProcessedAt(a.processed_at) - parseProcessedAt(b.processed_at)
   )
   const total = ordered.length
-  const maxItems = input.maxItems
-  if (maxItems === undefined || Number.isNaN(maxItems) || total <= maxItems) {
+  if (input.maxItems === undefined || Number.isNaN(input.maxItems)) {
     return { events: ordered, total }
   }
+  // Floor first: `slice` truncates its index toward zero, so a cap between 0
+  // and 1 would become `slice(-0)` — i.e. `slice(0)` — and hand back the ENTIRE
+  // history for what the caller asked to be the tightest possible bound. Doing
+  // it here means no caller can hit that, whatever it passes.
+  const maxItems = Math.floor(input.maxItems)
+  if (maxItems <= 0) return { events: [], total }
+  if (total <= maxItems) return { events: ordered, total }
   // Slice AFTER ordering so the cap is "the newest N", independent of the order
-  // the API returned pages in. A zero or negative cap short-circuits because
-  // `slice(-0)` is `slice(0)` — it would hand back the ENTIRE history for what
-  // the caller asked to be the tightest possible bound.
-  return { events: maxItems <= 0 ? [] : ordered.slice(-maxItems), total }
+  // the API returned pages in.
+  return { events: ordered.slice(-maxItems), total }
 }
 
 /** Epoch millis for a `processed_at`, or +Infinity when absent/queued/unparseable (sorts last). */

apps/sim/lib/managed-agents/session-client.ts

@@ -120,6 +120,8 @@ export interface ManagedAgentListEventsResponse extends ToolResponse {
 export interface ManagedAgentUpdateSessionParams extends ManagedAgentSessionOpParams {
   title?: string
   sessionParameters?: unknown
+  /** Explicitly removes all stored metadata; an empty map cannot express this. */
+  clearMetadata?: boolean | string
 }
 
 export interface ManagedAgentUpdateSessionResponse extends ToolResponse {

apps/sim/tools/managed_agent/types.ts

@@ -0,0 +1,63 @@
+/**
+ * @vitest-environment node
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { managedAgentUpdateSessionTool } from '@/tools/managed_agent/update_session'
+
+const originalFetch = global.fetch
+afterEach(() => {
+  global.fetch = originalFetch
+})
+
+const capture = () => {
+  const spy = vi.fn(async () => Response.json({ status: 'idle' })) as unknown as typeof fetch
+  global.fetch = spy
+  return spy as unknown as ReturnType<typeof vi.fn>
+}
+
+const run = (params: Record<string, unknown>) =>
+  managedAgentUpdateSessionTool.directExecution!(
+    { credential: 'c', accessToken: 'sk-ant-fake', sessionId: 'sesn_1', ...params } as never,
+    undefined
+  )
+
+const bodyOf = (spy: ReturnType<typeof vi.fn>) =>
+  JSON.parse((spy.mock.calls[0] as [string, RequestInit])[1].body as string)
+
+describe('managed_agent_update_session — metadata clearing', () => {
+  it('does not touch metadata on a title-only update', async () => {
+    const spy = capture()
+    await run({ title: 'renamed' })
+    expect(bodyOf(spy)).toEqual({ title: 'renamed' })
+  })
+
+  it.each([[[]], [{}], [undefined]])(
+    'leaves stored metadata alone for the empty value %p rather than wiping it',
+    async (sessionParameters) => {
+      // An untouched metadata table is also empty, so emptiness cannot mean
+      // "clear" — inferring it would wipe metadata on every title-only update.
+      const spy = capture()
+      await run({ title: 'renamed', sessionParameters })
+      expect(bodyOf(spy).metadata).toBeUndefined()
+    }
+  )
+
+  it('clears metadata only when explicitly asked', async () => {
+    const spy = capture()
+    await run({ clearMetadata: true })
+    expect(bodyOf(spy)).toEqual({ metadata: {} })
+  })
+
+  it('lets an explicit clear win over a supplied map', async () => {
+    const spy = capture()
+    await run({ clearMetadata: true, sessionParameters: { a: 'b' } })
+    expect(bodyOf(spy).metadata).toEqual({})
+  })
+
+  it('still refuses a no-op update', async () => {
+    capture()
+    const res = (await run({})) as { success: boolean; error?: string }
+    expect(res.success).toBe(false)
+    expect(res.error).toMatch(/Clear metadata/)
+  })
+})

apps/sim/tools/managed_agent/update_session.test.ts

@@ -1,6 +1,6 @@
 import { getErrorMessage } from '@sim/utils/errors'
 import { updateSession } from '@/lib/managed-agents/session-client'
-import { normalizeSessionParameters } from '@/tools/managed_agent/normalizers'
+import { isTruthyAck, normalizeSessionParameters } from '@/tools/managed_agent/normalizers'
 import {
   ACCESS_TOKEN_PARAM,
   CREDENTIAL_PARAM,
@@ -23,7 +23,9 @@ import type { ToolConfig } from '@/tools/types'
  * that ordering gap.
  *
  * Metadata is a FULL REPLACEMENT of the stored map, matching the API. To add
- * one key, read the session first and send the merged map.
+ * one key, read the session first and send the merged map. Removing metadata
+ * entirely takes an explicit `clearMetadata`, because an empty map is
+ * indistinguishable from a field the author never filled in.
  */
 export const managedAgentUpdateSessionTool: ToolConfig<
   ManagedAgentUpdateSessionParams,
@@ -48,7 +50,15 @@ export const managedAgentUpdateSessionTool: ToolConfig<
       type: 'object',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Replacement metadata map (replaces all stored metadata, not merged).',
+      description:
+        'Replacement metadata map (replaces all stored metadata, not merged). Leaving it empty leaves the stored metadata unchanged — use clearMetadata to remove it.',
+    },
+    clearMetadata: {
+      type: 'boolean',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        "Removes all of the session's stored metadata. Overrides any map supplied above.",
     },
   },
 
@@ -65,12 +75,18 @@ export const managedAgentUpdateSessionTool: ToolConfig<
     // both slip past the guard below and silently clear an existing title.
     const trimmedTitle = params.title?.trim()
     const title = trimmedTitle ? trimmedTitle : undefined
-    const metadata = normalizeSessionParameters(params.sessionParameters)
+
+    // Clearing metadata needs its own explicit signal. An empty metadata table
+    // cannot mean "clear": a table the author never touched is also empty, so
+    // inferring intent from emptiness would wipe a session's metadata on every
+    // title-only update. `{}` is only sent when the author asks for it.
+    const clearMetadata = isTruthyAck(params.clearMetadata)
+    const metadata = clearMetadata ? {} : normalizeSessionParameters(params.sessionParameters)
     if (title === undefined && metadata === undefined) {
       return {
         success: false,
         output: { sessionId: target.sessionId, updated: false },
-        error: 'Provide a title or metadata to update.',
+        error: 'Provide a title or metadata to update, or check "Clear metadata".',
       }
     }