feat(managed-agent): Claude Platform Managed Agents workflow blocks

Ship two workflow blocks that let a workflow author invoke a Claude
Platform Managed Agent (cloud or self-hosted) as a first-class node,
plus the workspace-scoped connection layer that stores the linked
Anthropic API key.

Blocks
- **Claude Managed Agents** (`managed_agent_cloud`) — cloud
  environments. Session-create payload carries `agent`,
  `environment_id`, `vault_ids`, `resources` (memory + files) and
  free-form `metadata` tags.
- **Claude Managed Agents (self-hosted)** (`managed_agent_self_hosted`)
  — self-hosted environments. Session `metadata` is forwarded as
  env vars to the deployer's self-hosted agent sandbox; the memory
  fields are gated behind
  `NEXT_PUBLIC_MANAGED_AGENT_SELF_HOSTED_MEMORY_ENABLED` because
  Claude self-hosted environments do not currently support the
  memory-store resource attach on the session API. Default seed
  rows for the Session-parameters table come from
  `NEXT_PUBLIC_MANAGED_AGENT_SELF_HOSTED_DEFAULTS` (JSON object);
  the seeded keys stay out of source so this block is deployment-
  neutral in the public tree.

Connections
- New `managed_agent_connection` table (workspace-scoped, encrypted
  API key). All CRUD paths go through
  `getUserEntityPermissions(userId, 'workspace', workspaceId)`;
  `admin`/`write` to create, rotate, or delete; any workspace
  member can list/browse. Plaintext keys never cross the client
  boundary — list responses return only a masked preview.
- Settings surface under `settings/components/managed-agents/` lets
  admins add / rotate / remove connections with an inline
  Anthropic-API verify (`GET /v1/agents`).
- 8 server routes proxy the Claude Platform read endpoints (agents,
  environments, memory stores, vaults, environment detail) so the
  block picker resolves options against the linked workspace.

Tool + session client
- `tools/managed_agent/run_session.ts` (client-safe skeleton) +
  `run_session.server.ts` (server-only impl, self-registered on
  boot via `globalThis` so the client bundle never pulls
  `postgres` / `fs` / encryption). Reconnect + `events.list`
  catch-up loop matches the docs' two-step session lifecycle.
- `lib/managed-agents/session-client.ts` — the reusable HTTP
  client that shapes the cloud vs. self-hosted request bodies.
- `tools/managed_agent/normalizers.ts` — pure input normalizers
  that coerce the workflow block's runtime shapes (table rows,
  JSON strings, flat objects, comma-lists) into typed values.

Node UX
- Optional `BlockConfig.nodeWidth` (default 250, MA blocks use 400)
  threaded through `calculateWorkflowBlockDimensions` for both the
  workflow-block hook and autolayout so long Anthropic IDs are not
  ellipsis-truncated in the collapsed row.
- Friendly-name hydration on the collapsed row resolves connection
  / agent / environment / vault / memory-store IDs to human labels
  via the React Query hooks. New `blockType` prop on `SubBlockRow`
  gates the lookup.
- New optional `defaultRows` prop on the `Table` subblock so any
  block can seed a fresh table with initial rows.

Test coverage
Aligned with the repo's existing patterns (`@vitest-environment
node`, `vi.hoisted` + `vi.mock` + static imports, `@sim/testing`
helpers). 86 tests across 5 files:

- `tools/managed_agent/normalizers.test.ts` (27) — every shape the
  block subblocks hand off + bad-input paths.
- `lib/managed-agents/session-client.test.ts` (17) — cloud vs.
  self-hosted branch: memory routing (resource vs. metadata),
  file resources cloud-only, `vault_ids` only when non-empty,
  user metadata does not overwrite memory keys, envType-omitted
  default.
- `lib/managed-agents/connections.test.ts` (17) — CRUD via
  captured DB-chain args: encryption on write (plaintext never
  lands in row), masking on read, workspace-scoped `WHERE` on
  every op, `verify` gate blocks persistence, error truncation
  to 500 chars.
- `app/api/managed-agent-connections/route.test.ts` (15) —
  permission gates on GET/POST/DELETE: 401 unauthenticated,
  400 missing params, 403 read-tier callers on create/delete,
  404 for missing rows, plaintext never in POST response, both
  `write` and `admin` accepted.
- `blocks/blocks/managed_agent_self_hosted.test.ts` (10) —
  env-driven `readSessionMetadataDefaults` and
  `isSelfHostedMemoryEnabled` (truthy/falsy/whitespace forms).

Documentation
- New env vars documented in `apps/sim/.env.example`:
  `MANAGED_AGENT_DEBUG_PAYLOAD`,
  `NEXT_PUBLIC_MANAGED_AGENT_SELF_HOSTED_DEFAULTS`,
  `NEXT_PUBLIC_MANAGED_AGENT_SELF_HOSTED_MEMORY_ENABLED`.

Author: Ricardo DeMatos

apps/sim/.env.example

@@ -64,6 +64,8 @@ API_ENCRYPTION_KEY=your_api_encryption_key # Use `openssl rand -hex 32` to gener
 # LITELLM_API_KEY=                       # Optional bearer token if your LiteLLM proxy requires auth
 # FIREWORKS_API_KEY=                     # Optional Fireworks AI API key for model listing
 # NEXT_PUBLIC_BEDROCK_DEFAULT_CREDENTIALS=true  # Set when using AWS default credential chain (IAM roles, ECS task roles, IRSA). Hides credential fields in Agent block UI.
+# NEXT_PUBLIC_MANAGED_AGENT_SELF_HOSTED_DEFAULTS='{"SOURCE_TYPE":"git","SOURCE_REF":"main"}'  # JSON object of default session-metadata rows seeded into fresh Claude Managed Agents (self-hosted) blocks. Deployment-specific; keys map to whatever env vars your self-hosted agent sandbox reads. Absent = empty table.
+# NEXT_PUBLIC_MANAGED_AGENT_SELF_HOSTED_MEMORY_ENABLED=true  # Reveal Memory Store + Memory Access fields on the Claude Managed Agents (self-hosted) block. Off by default: Claude self-hosted environments do not currently support the memory-store resource attach on the session API. Enable only if your self-hosted agent sandbox implements memory attach on its side.
 # AZURE_OPENAI_ENDPOINT=                        # Azure OpenAI endpoint (hides field in UI when set alongside NEXT_PUBLIC_AZURE_CONFIGURED)
 # AZURE_OPENAI_API_KEY=                         # Azure OpenAI API key
 # AZURE_OPENAI_API_VERSION=                     # Azure OpenAI API version

apps/sim/app/api/managed-agent-connections/[id]/agents/route.ts

@@ -0,0 +1,89 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import {
+  type ManagedAgentAgent,
+  managedAgentProxyParamsSchema,
+  managedAgentProxyQuerySchema,
+} from '@/lib/api/contracts'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
+import {
+  type AnthropicListPage,
+  ManagedAgentProxyError,
+  proxyManagedAgentsGet,
+} from '@/lib/managed-agents/proxy'
+import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+
+const logger = createLogger('ManagedAgentAgentsAPI')
+
+interface AnthropicAgent {
+  id: string
+  name?: string
+  description?: string
+  latest_version?: number | string
+  version?: number | string
+}
+
+interface RouteContext {
+  params: Promise<{ id: string }>
+}
+
+export const GET = withRouteHandler(async (request: NextRequest, context: RouteContext) => {
+  const requestId = generateRequestId()
+  try {
+    const authResult = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success || !authResult.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const userId = authResult.userId
+
+    const rawParams = await context.params
+    const paramsValidation = managedAgentProxyParamsSchema.safeParse(rawParams)
+    const queryValidation = managedAgentProxyQuerySchema.safeParse(
+      Object.fromEntries(request.nextUrl.searchParams.entries())
+    )
+    if (!paramsValidation.success || !queryValidation.success) {
+      return NextResponse.json({ error: 'Invalid request data' }, { status: 400 })
+    }
+    const { id } = paramsValidation.data
+    const { workspaceId } = queryValidation.data
+
+    const userPermission = await getUserEntityPermissions(userId, 'workspace', workspaceId)
+    if (!userPermission) {
+      return NextResponse.json({ error: 'Access denied' }, { status: 403 })
+    }
+
+    const apiKey = await getDecryptedApiKey({ id, workspaceId })
+    if (!apiKey) {
+      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
+    }
+
+    try {
+      const body = await proxyManagedAgentsGet<AnthropicListPage<AnthropicAgent>>(
+        apiKey,
+        '/v1/agents?limit=100'
+      )
+      const data: ManagedAgentAgent[] = (body.data ?? []).map((row) => ({
+        id: row.id,
+        name: row.name ?? null,
+        description: row.description ?? null,
+        version: row.latest_version ?? row.version ?? null,
+      }))
+      return NextResponse.json({ data })
+    } catch (error) {
+      if (error instanceof ManagedAgentProxyError) {
+        return NextResponse.json({ error: error.message }, { status: 502 })
+      }
+      throw error
+    }
+  } catch (error) {
+    logger.error(`[${requestId}] Failed to list agents`, error)
+    return NextResponse.json(
+      { error: getErrorMessage(error, 'Failed to list agents') },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/managed-agent-connections/[id]/environments/[envId]/route.ts

@@ -0,0 +1,102 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import {
+  type ManagedAgentEnvironment,
+  managedAgentEnvironmentDetailParamsSchema,
+  managedAgentProxyQuerySchema,
+} from '@/lib/api/contracts'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
+import {
+  ManagedAgentProxyError,
+  proxyManagedAgentsGet,
+} from '@/lib/managed-agents/proxy'
+import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+
+const logger = createLogger('ManagedAgentEnvironmentAPI')
+
+interface AnthropicEnvironment {
+  id: string
+  name?: string
+  description?: string
+  scope?: 'organization' | 'account' | null
+  config?: { type?: 'cloud' | 'self_hosted' }
+}
+
+interface RouteContext {
+  params: Promise<{ id: string; envId: string }>
+}
+
+/**
+ * GET /api/managed-agent-connections/[id]/environments/[envId] — used by
+ * the workflow-block tool at run time to resolve `envType` before
+ * building the session-create payload.
+ */
+export const GET = withRouteHandler(async (request: NextRequest, context: RouteContext) => {
+  const requestId = generateRequestId()
+  try {
+    const authResult = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success || !authResult.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const userId = authResult.userId
+
+    const rawParams = await context.params
+    const paramsValidation = managedAgentEnvironmentDetailParamsSchema.safeParse(rawParams)
+    const queryValidation = managedAgentProxyQuerySchema.safeParse(
+      Object.fromEntries(request.nextUrl.searchParams.entries())
+    )
+    if (!paramsValidation.success || !queryValidation.success) {
+      return NextResponse.json({ error: 'Invalid request data' }, { status: 400 })
+    }
+    const { id, envId } = paramsValidation.data
+    const { workspaceId } = queryValidation.data
+
+    const userPermission = await getUserEntityPermissions(userId, 'workspace', workspaceId)
+    if (!userPermission) {
+      return NextResponse.json({ error: 'Access denied' }, { status: 403 })
+    }
+
+    const apiKey = await getDecryptedApiKey({ id, workspaceId })
+    if (!apiKey) {
+      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
+    }
+
+    try {
+      const body = await proxyManagedAgentsGet<AnthropicEnvironment>(
+        apiKey,
+        `/v1/environments/${encodeURIComponent(envId)}`
+      )
+      const envType = body.config?.type
+      if (envType !== 'cloud' && envType !== 'self_hosted') {
+        return NextResponse.json(
+          { error: 'Environment returned an unrecognised config.type' },
+          { status: 502 }
+        )
+      }
+      const data: ManagedAgentEnvironment = {
+        id: body.id,
+        name: body.name ?? null,
+        description: body.description ?? null,
+        envType,
+        scope: body.scope ?? null,
+      }
+      return NextResponse.json({ data })
+    } catch (error) {
+      if (error instanceof ManagedAgentProxyError) {
+        const status = error.status === 404 ? 404 : 502
+        return NextResponse.json({ error: error.message }, { status })
+      }
+      throw error
+    }
+  } catch (error) {
+    logger.error(`[${requestId}] Failed to fetch environment`, error)
+    return NextResponse.json(
+      { error: getErrorMessage(error, 'Failed to fetch environment') },
+      { status: 500 }
+    )
+  }
+})

apps/sim/app/api/managed-agent-connections/[id]/environments/route.ts

@@ -0,0 +1,96 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import {
+  type ManagedAgentEnvironment,
+  managedAgentProxyParamsSchema,
+  managedAgentProxyQuerySchema,
+} from '@/lib/api/contracts'
+import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { getDecryptedApiKey } from '@/lib/managed-agents/connections'
+import {
+  type AnthropicListPage,
+  ManagedAgentProxyError,
+  proxyManagedAgentsGet,
+} from '@/lib/managed-agents/proxy'
+import { getUserEntityPermissions } from '@/lib/workspaces/permissions/utils'
+
+const logger = createLogger('ManagedAgentEnvironmentsAPI')
+
+interface AnthropicEnvironment {
+  id: string
+  name?: string
+  description?: string
+  scope?: 'organization' | 'account' | null
+  config?: { type?: 'cloud' | 'self_hosted' }
+}
+
+interface RouteContext {
+  params: Promise<{ id: string }>
+}
+
+export const GET = withRouteHandler(async (request: NextRequest, context: RouteContext) => {
+  const requestId = generateRequestId()
+  try {
+    const authResult = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
+    if (!authResult.success || !authResult.userId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+    const userId = authResult.userId
+
+    const rawParams = await context.params
+    const paramsValidation = managedAgentProxyParamsSchema.safeParse(rawParams)
+    const queryValidation = managedAgentProxyQuerySchema.safeParse(
+      Object.fromEntries(request.nextUrl.searchParams.entries())
+    )
+    if (!paramsValidation.success || !queryValidation.success) {
+      return NextResponse.json({ error: 'Invalid request data' }, { status: 400 })
+    }
+    const { id } = paramsValidation.data
+    const { workspaceId } = queryValidation.data
+
+    const userPermission = await getUserEntityPermissions(userId, 'workspace', workspaceId)
+    if (!userPermission) {
+      return NextResponse.json({ error: 'Access denied' }, { status: 403 })
+    }
+
+    const apiKey = await getDecryptedApiKey({ id, workspaceId })
+    if (!apiKey) {
+      return NextResponse.json({ error: 'Connection not found' }, { status: 404 })
+    }
+
+    try {
+      const body = await proxyManagedAgentsGet<AnthropicListPage<AnthropicEnvironment>>(
+        apiKey,
+        '/v1/environments?limit=100'
+      )
+      const data: ManagedAgentEnvironment[] = (body.data ?? [])
+        .map((row) => {
+          const envType = row.config?.type
+          if (envType !== 'cloud' && envType !== 'self_hosted') return null
+          return {
+            id: row.id,
+            name: row.name ?? null,
+            description: row.description ?? null,
+            envType,
+            scope: row.scope ?? null,
+          }
+        })
+        .filter((row): row is ManagedAgentEnvironment => row !== null)
+      return NextResponse.json({ data })
+    } catch (error) {
+      if (error instanceof ManagedAgentProxyError) {
+        return NextResponse.json({ error: error.message }, { status: 502 })
+      }
+      throw error
+    }
+  } catch (error) {
+    logger.error(`[${requestId}] Failed to list environments`, error)
+    return NextResponse.json(
+      { error: getErrorMessage(error, 'Failed to list environments') },
+      { status: 500 }
+    )
+  }
+})