From 4dfc35326a2691df98fa97f5a8276ae04d9bd75c Mon Sep 17 00:00:00 2001
From: Juniper Bevensee <juniperbevensee@users.noreply.github.com>
Date: Sat, 18 Jul 2026 11:18:26 +1000
Subject: [PATCH 1/3] spike(letta): Letta server-as-container + REST agent
 layer + read-only view (Path 1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Proof (spike, do not merge) that HSM can run a Letta *server* as a managed
container via the existing runtime-neutral DockerService, and CRUD/message
individual Letta agents over REST as a separate "agents-as-API-resources"
layer distinct from the container model.

- docker/letta-compose.yml: letta/letta server, :8283, embedded Postgres
  volume (commented shared-pgvector alt). Managed by DockerService unchanged.
- lib/services/letta.ts: minimal fetch REST client — listAgents, getAgent,
  createAgent, sendMessage, getMemoryBlocks. Base URL from LETTA_BASE_URL,
  defaults http://localhost:8283. Loosely typed (spike).
- app/api/letta/*: same-origin proxy routes (list / send message / blocks).
- app/(dashboard)/letta: read-only agents view + single send-message action.
- Sidebar: "Letta" nav entry.

Out of scope: airlock, wizard integration, runtime-adapter refactor, no
lib/types.ts changes on main. Typecheck + lint pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/(dashboard)/letta/page.tsx              | 199 ++++++++++++++++++++
 app/api/letta/agents/[id]/blocks/route.ts   |  19 ++
 app/api/letta/agents/[id]/messages/route.ts |  24 +++
 app/api/letta/agents/route.ts               |  16 ++
 components/shell/sidebar.tsx                |   6 +-
 docker/letta-compose.yml                    |  75 ++++++++
 lib/services/index.ts                       |   4 +
 lib/services/letta.ts                       | 175 +++++++++++++++++
 8 files changed, 516 insertions(+), 2 deletions(-)
 create mode 100644 app/(dashboard)/letta/page.tsx
 create mode 100644 app/api/letta/agents/[id]/blocks/route.ts
 create mode 100644 app/api/letta/agents/[id]/messages/route.ts
 create mode 100644 app/api/letta/agents/route.ts
 create mode 100644 docker/letta-compose.yml
 create mode 100644 lib/services/letta.ts

diff --git a/app/(dashboard)/letta/page.tsx b/app/(dashboard)/letta/page.tsx
new file mode 100644
index 0000000..eaf55e0
--- /dev/null
+++ b/app/(dashboard)/letta/page.tsx
@@ -0,0 +1,199 @@
+'use client'
+
+/**
+ * SPIKE (Path 1) — read-only "Letta agents" view. See spec §4 steps 2–3.
+ *
+ * Proves the "agents-as-API-resources" shape distinct from HSM's container
+ * model: it lists agents from one Letta *server* (GET /v1/agents), lets you send
+ * one message (the single action), and peek at an agent's core-memory blocks.
+ * No create/delete UI, no per-agent lifecycle buttons — those don't exist for
+ * Letta agents (they're rows in Postgres, not containers).
+ */
+
+import { useState } from 'react'
+import { useApi } from '@/lib/hooks/use-api'
+import { Button } from '@/components/ui/button'
+import type { LettaAgent, LettaBlock, LettaMessage } from '@/lib/services/letta'
+import { toast } from 'sonner'
+
+/** Best-effort stringify of a Letta message's `content` (spike-loose typing). */
+function renderContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .map((c) => (typeof c === 'string' ? c : (c as { text?: string })?.text ?? JSON.stringify(c)))
+      .join('')
+  }
+  return content == null ? '' : JSON.stringify(content)
+}
+
+function AgentRow({ agent }: { agent: LettaAgent }) {
+  const [open, setOpen] = useState(false)
+  const [text, setText] = useState('')
+  const [sending, setSending] = useState(false)
+  const [reply, setReply] = useState<LettaMessage[] | null>(null)
+  const [blocks, setBlocks] = useState<LettaBlock[] | null>(null)
+  const [blocksLoading, setBlocksLoading] = useState(false)
+
+  async function send() {
+    if (!text.trim()) return
+    setSending(true)
+    setReply(null)
+    try {
+      const res = await fetch(`/api/letta/agents/${agent.id}/messages`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text: text.trim() }),
+      })
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.error ?? 'Send failed')
+      setReply(json.messages ?? [])
+      setText('')
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Send failed')
+    } finally {
+      setSending(false)
+    }
+  }
+
+  async function loadBlocks() {
+    setBlocksLoading(true)
+    try {
+      const res = await fetch(`/api/letta/agents/${agent.id}/blocks`)
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.error ?? 'Failed to read memory')
+      setBlocks(json)
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Failed to read memory')
+    } finally {
+      setBlocksLoading(false)
+    }
+  }
+
+  return (
+    <>
+      <tr className="border-b border-[var(--border)] last:border-0 hover:bg-muted/30 transition-colors">
+        <td className="px-4 py-3">
+          <span className="font-medium">{agent.name ?? agent.id}</span>
+        </td>
+        <td className="px-4 py-3 text-muted-foreground font-mono text-xs">{agent.id}</td>
+        <td className="px-4 py-3 text-muted-foreground">{agent.model ?? '—'}</td>
+        <td className="px-4 py-3 text-right">
+          <Button variant="ghost" size="xs" onClick={() => setOpen((o) => !o)}>
+            {open ? 'Close' : 'Message'}
+          </Button>
+        </td>
+      </tr>
+      {open && (
+        <tr className="border-b border-[var(--border)] last:border-0 bg-muted/20">
+          <td colSpan={4} className="px-4 py-4 space-y-3">
+            {/* Single action: send a message */}
+            <div className="flex items-start gap-2">
+              <textarea
+                value={text}
+                onChange={(e) => setText(e.target.value)}
+                placeholder={`Message ${agent.name ?? agent.id}…`}
+                rows={2}
+                className="flex-1 rounded-md border border-[var(--border)] bg-[var(--surface)] px-3 py-2 text-sm resize-y"
+              />
+              <Button size="sm" onClick={send} disabled={sending || !text.trim()}>
+                {sending ? 'Sending…' : 'Send'}
+              </Button>
+            </div>
+
+            {reply && (
+              <div className="space-y-1.5 text-sm">
+                {reply.map((m, i) => (
+                  <div key={m.id ?? i} className="rounded-md border border-[var(--border)] px-3 py-2">
+                    <span className="text-xs text-muted-foreground uppercase tracking-wide">
+                      {m.message_type ?? m.role ?? 'message'}
+                    </span>
+                    <div className="mt-1 whitespace-pre-wrap">{renderContent(m.content)}</div>
+                  </div>
+                ))}
+              </div>
+            )}
+
+            {/* Read-only peek at core-memory blocks */}
+            <div>
+              <Button variant="ghost" size="xs" onClick={loadBlocks} disabled={blocksLoading}>
+                {blocksLoading ? 'Loading memory…' : blocks ? 'Reload memory blocks' : 'View memory blocks'}
+              </Button>
+              {blocks && (
+                <div className="mt-2 space-y-1.5">
+                  {blocks.length === 0 && (
+                    <p className="text-xs text-muted-foreground">No memory blocks.</p>
+                  )}
+                  {blocks.map((b, i) => (
+                    <div key={b.id ?? b.label ?? i} className="rounded-md border border-[var(--border)] px-3 py-2 text-sm">
+                      <span className="font-mono text-xs text-accent-foreground">{b.label}</span>
+                      <div className="mt-1 whitespace-pre-wrap text-muted-foreground">{b.value}</div>
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          </td>
+        </tr>
+      )}
+    </>
+  )
+}
+
+export default function LettaPage() {
+  const { data: agents, loading, error, refetch } = useApi<LettaAgent[]>('/api/letta/agents', 10000)
+
+  return (
+    <div>
+      <div className="flex items-center justify-between mb-2">
+        <h2 className="text-2xl font-semibold">Letta agents</h2>
+        <Button variant="outline" size="sm" onClick={refetch}>
+          Refresh
+        </Button>
+      </div>
+      <p className="text-xs text-muted-foreground mb-6">
+        SPIKE (Path 1) · agents on one Letta server (REST :8283), not containers.
+      </p>
+
+      {loading && <p className="text-muted-foreground">Loading…</p>}
+
+      {!loading && error && (
+        <div className="rounded-xl border border-[var(--border)] bg-[var(--surface)] p-8 text-center space-y-2">
+          <p className="text-sm text-destructive">Couldn&apos;t reach the Letta server.</p>
+          <p className="text-xs text-muted-foreground">{error}</p>
+          <p className="text-xs text-muted-foreground">
+            Start it: <code>docker compose -f docker/letta-compose.yml -p letta up -d</code>
+          </p>
+        </div>
+      )}
+
+      {!loading && !error && agents && agents.length === 0 && (
+        <div className="rounded-xl border border-[var(--border)] bg-[var(--surface)] p-8 text-center">
+          <p className="text-sm text-muted-foreground">
+            No agents yet. Create one via the Letta REST API (POST /v1/agents) or the ADE.
+          </p>
+        </div>
+      )}
+
+      {!loading && !error && agents && agents.length > 0 && (
+        <div className="rounded-xl border border-[var(--border)] bg-[var(--surface)] overflow-hidden">
+          <table className="w-full text-sm">
+            <thead>
+              <tr className="border-b border-[var(--border)] text-xs text-muted-foreground uppercase tracking-wide">
+                <th className="text-left px-4 py-3">Name</th>
+                <th className="text-left px-4 py-3">ID</th>
+                <th className="text-left px-4 py-3">Model</th>
+                <th className="text-right px-4 py-3">Action</th>
+              </tr>
+            </thead>
+            <tbody>
+              {agents.map((a) => (
+                <AgentRow key={a.id} agent={a} />
+              ))}
+            </tbody>
+          </table>
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/app/api/letta/agents/[id]/blocks/route.ts b/app/api/letta/agents/[id]/blocks/route.ts
new file mode 100644
index 0000000..e129073
--- /dev/null
+++ b/app/api/letta/agents/[id]/blocks/route.ts
@@ -0,0 +1,19 @@
+// SPIKE (Path 1): read one agent's core-memory blocks — the granularity the
+// "Librarian in an Airlock" use-case hangs on. Read-only.
+import { NextResponse } from 'next/server'
+import { services } from '@/lib/services'
+
+export async function GET(
+  _request: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id } = await params
+  try {
+    return NextResponse.json(await services.letta.getMemoryBlocks(id))
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Failed to read memory blocks' },
+      { status: 502 },
+    )
+  }
+}
diff --git a/app/api/letta/agents/[id]/messages/route.ts b/app/api/letta/agents/[id]/messages/route.ts
new file mode 100644
index 0000000..9a15423
--- /dev/null
+++ b/app/api/letta/agents/[id]/messages/route.ts
@@ -0,0 +1,24 @@
+// SPIKE (Path 1): send a message to one Letta agent. The single "action" of the
+// otherwise read-only view.
+import { NextResponse } from 'next/server'
+import { services } from '@/lib/services'
+
+export async function POST(
+  request: Request,
+  { params }: { params: Promise<{ id: string }> },
+) {
+  const { id } = await params
+  try {
+    const body = await request.json().catch(() => ({}))
+    const text = typeof body?.text === 'string' ? body.text.trim() : ''
+    if (!text) {
+      return NextResponse.json({ error: 'Message text is required' }, { status: 400 })
+    }
+    return NextResponse.json(await services.letta.sendMessage(id, text))
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Failed to send message' },
+      { status: 502 },
+    )
+  }
+}
diff --git a/app/api/letta/agents/route.ts b/app/api/letta/agents/route.ts
new file mode 100644
index 0000000..108334b
--- /dev/null
+++ b/app/api/letta/agents/route.ts
@@ -0,0 +1,16 @@
+// SPIKE (Path 1): proxy the Letta server's agent list through HSM so the
+// read-only view can fetch it same-origin (the Letta base URL is server-side
+// config, not something the browser should reach directly).
+import { NextResponse } from 'next/server'
+import { services } from '@/lib/services'
+
+export async function GET() {
+  try {
+    return NextResponse.json(await services.letta.listAgents())
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Failed to list Letta agents' },
+      { status: 502 },
+    )
+  }
+}
diff --git a/components/shell/sidebar.tsx b/components/shell/sidebar.tsx
index 0e59f19..ddaf5e0 100644
--- a/components/shell/sidebar.tsx
+++ b/components/shell/sidebar.tsx
@@ -4,18 +4,20 @@ import Link from 'next/link'
 import { usePathname } from 'next/navigation'
 import {
   LayoutDashboard, Bot, MessageSquare, Wrench, KeyRound,
-  Brain, Users, ScrollText, Settings, Plug,
+  Brain, Users, ScrollText, Settings, Plug, Boxes,
 } from 'lucide-react'
 import type { LucideIcon } from 'lucide-react'
 
 const icons: Record<string, LucideIcon> = {
   LayoutDashboard, Bot, MessageSquare, Wrench, KeyRound,
-  Brain, Users, ScrollText, Settings, Plug,
+  Brain, Users, ScrollText, Settings, Plug, Boxes,
 }
 
 const NAV_ITEMS = [
   { label: 'Dashboard', href: '/', icon: 'LayoutDashboard' },
   { label: 'Harnesses', href: '/harnesses', icon: 'Bot' },
+  // SPIKE (Path 1): read-only Letta agents view (agents-as-API-resources).
+  { label: 'Letta', href: '/letta', icon: 'Boxes' },
   // { label: 'Surfaces', href: '/surfaces', icon: 'Plug' },
   { label: 'Tools', href: '/tools', icon: 'Wrench' },
   { label: 'Keys', href: '/keys', icon: 'KeyRound' },
diff --git a/docker/letta-compose.yml b/docker/letta-compose.yml
new file mode 100644
index 0000000..d8b65db
--- /dev/null
+++ b/docker/letta-compose.yml
@@ -0,0 +1,75 @@
+# =============================================================================
+# SPIKE ARTIFACT — Letta runtime (Path 1). Do NOT wire into the deploy wizard.
+# Branch: dev/juniperbevensee/swarm-map-letta-runtime  ·  see spec §4 steps 1–3.
+#
+# The whole point of this file: prove that HSM's EXISTING, runtime-neutral
+# DockerService (lib/services/docker.ts) can start/stop/logs a Letta *server*
+# container with ZERO new Docker code. A Letta "agent" is a row in Postgres,
+# not a container — those are managed over REST by lib/services/letta.ts, a
+# separate abstraction ("agents-as-API-resources").
+#
+# One `letta/letta` server (~500MB) hosts N agents against one Postgres. This is
+# Path 1 from finding 2026-07-06-swarm-map-managing-letta-agents.md. Path 2
+# (one server per agent, ~800MB each) is a non-starter on the RAM-constrained
+# hardware and is explicitly rejected.
+#
+# Run it by hand, the same way DockerService would drive it:
+#   ANTHROPIC_API_KEY=sk-ant-... docker compose -f docker/letta-compose.yml -p letta up -d
+#   docker compose -f docker/letta-compose.yml -p letta logs -f letta
+#   docker compose -f docker/letta-compose.yml -p letta stop letta
+# then point the REST client at http://localhost:8283 (LETTA_BASE_URL).
+#
+# Docs caveat (docs.letta.com/guides/selfhosting, verified 2026-07-18): Letta
+# flag the self-host Docker image as "no longer an actively maintained/supported
+# product surface" and nudge toward Letta Cloud / local mode. Fine for a spike;
+# a production host decision is out of scope here.
+# =============================================================================
+
+services:
+  letta:
+    # Pin to :latest for the spike — Letta's self-host docs give no stable
+    # semver tag to pin against. A real deploy should pin a digest.
+    image: letta/letta:latest
+    container_name: letta
+    restart: unless-stopped
+    ports:
+      # REST API (and the ADE web UI) — matches the :8283 the client defaults to.
+      - published: 8283
+        target: 8283
+    environment:
+      # Provider keys are SERVER-WIDE in self-hosted Letta (not per-agent) — a
+      # key difference from Hermes, where creds are per-container env. Passed
+      # through from the host env; unset ones are simply absent.
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-}
+      # --- Shared external Postgres (production shape) ------------------------
+      # For a shared/inspectable fleet, point Letta at a pgvector Postgres via
+      # LETTA_PG_URI and the volume below becomes unnecessary. Left commented so
+      # the spike runs with zero extra services (embedded PG, see volume). The
+      # target DB MUST have the pgvector extension.
+      # - LETTA_PG_URI=postgresql://letta:letta@letta-db:5432/letta
+    volumes:
+      # Persist the embedded Postgres so agents/memory survive restarts. This is
+      # the "its Postgres volume" from the spike plan — embedded PG is what the
+      # official `docker run` example uses.
+      - letta-pgdata:/var/lib/postgresql/data
+
+  # --- OPTIONAL shared pgvector Postgres (production shape) -------------------
+  # Uncomment together with LETTA_PG_URI above to run a dedicated, inspectable
+  # Postgres instead of the embedded one. Auditability of agent memory + message
+  # history (rows in Postgres) is the entire trust proposition of the north-star
+  # "Librarian in an Airlock" use-case — a shared PG is where that lives.
+  # letta-db:
+  #   image: ankane/pgvector:latest
+  #   container_name: letta-db
+  #   restart: unless-stopped
+  #   environment:
+  #     - POSTGRES_USER=letta
+  #     - POSTGRES_PASSWORD=letta
+  #     - POSTGRES_DB=letta
+  #   volumes:
+  #     - letta-dbdata:/var/lib/postgresql/data
+
+volumes:
+  letta-pgdata:
+  # letta-dbdata:
diff --git a/lib/services/index.ts b/lib/services/index.ts
index 5c3222b..337d3d5 100644
--- a/lib/services/index.ts
+++ b/lib/services/index.ts
@@ -8,6 +8,7 @@ import { MemoryService } from './memory'
 import { ConfigService } from './config'
 import { SignalPinService } from './signal-pin'
 import { SurfaceAdminService } from './surface-admins'
+import { LettaService } from './letta'
 import path from 'path'
 import os from 'os'
 
@@ -40,4 +41,7 @@ export const services = {
   memory: new MemoryService(storage),
   signalPin: new SignalPinService(keysService, process.env.SIGNAL_API_URL || 'http://localhost:8080'),
   surfaceAdmins: new SurfaceAdminService(storage, audit),
+  // SPIKE (Path 1): agents-as-API-resources layer, distinct from the container
+  // model. Base URL from LETTA_BASE_URL, defaults to the compose-published :8283.
+  letta: new LettaService(),
 }
diff --git a/lib/services/letta.ts b/lib/services/letta.ts
new file mode 100644
index 0000000..596be26
--- /dev/null
+++ b/lib/services/letta.ts
@@ -0,0 +1,175 @@
+/**
+ * SPIKE ARTIFACT — Letta runtime (Path 1). See spec §2 / §4 and finding
+ * 2026-07-06-swarm-map-managing-letta-agents.md.
+ *
+ * The "agents-as-API-resources" layer, deliberately DISTINCT from the container
+ * model. HSM manages the Letta *server* as a container via DockerService
+ * (docker/letta-compose.yml); this talks to that server's REST API on :8283 to
+ * CRUD/message individual agents — which have no container of their own (they're
+ * rows in Postgres). None of HSM's per-agent container verbs (start/stop/
+ * restart) apply here; create/message/read-memory over REST is the whole model.
+ *
+ * Intentionally thin and loosely typed — this is a spike to feel the shape, not
+ * a hardened SDK. Response types are `Record`/`unknown`-ish on purpose; a real
+ * build would generate types from Letta's OpenAPI spec.
+ *
+ * Endpoints verified against docs.letta.com (2026-07-18):
+ *   GET    /v1/agents                     list agents
+ *   POST   /v1/agents                     create agent
+ *   GET    /v1/agents/{id}                get one agent
+ *   POST   /v1/agents/{id}/messages       send a message (returns the turn)
+ *   GET    /v1/agents/{id}/blocks         list core-memory blocks
+ * (The blocks path is the CURRENT shape; older docs showed
+ *  /v1/agents/{id}/core-memory/blocks. This uses the current one.)
+ */
+
+/** A Letta memory block — the native "expose this slice, hide that" granularity. */
+export interface LettaBlock {
+  id?: string
+  label: string
+  value: string
+  limit?: number
+  description?: string
+  [k: string]: unknown
+}
+
+/** A Letta agent (rows in Postgres). Loosely typed — spike. */
+export interface LettaAgent {
+  id: string
+  name: string
+  created_at?: string
+  last_updated_at?: string
+  model?: string
+  memory_blocks?: LettaBlock[]
+  [k: string]: unknown
+}
+
+/** One message in a turn's response. Letta returns typed messages, not one blob. */
+export interface LettaMessage {
+  id?: string
+  message_type?: string // user_message | assistant_message | reasoning_message | tool_call_message | ...
+  content?: unknown
+  role?: string
+  date?: string
+  [k: string]: unknown
+}
+
+/** Response envelope for POST .../messages. */
+export interface LettaMessageResponse {
+  messages: LettaMessage[]
+  usage?: Record<string, unknown>
+  stop_reason?: string
+  [k: string]: unknown
+}
+
+/** Minimal create payload. Letta defaults most of this; blocks are the interesting part. */
+export interface CreateAgentConfig {
+  name: string
+  /** e.g. "anthropic/claude-3-5-sonnet-20241022" — a provider-independent handle. */
+  model?: string
+  /** Optional embedding handle, e.g. "openai/text-embedding-3-small". */
+  embedding?: string
+  /** Core-memory blocks the agent boots with (e.g. a curated `shareable` block). */
+  memory_blocks?: LettaBlock[]
+  system?: string
+  [k: string]: unknown
+}
+
+/**
+ * Base URL of the Letta server. Defaults to the compose-published :8283.
+ * Server-wide config (provider keys, tool sandbox) lives on the server itself,
+ * not here — this client only speaks agent-resource REST.
+ */
+const DEFAULT_BASE_URL = 'http://localhost:8283'
+
+export class LettaService {
+  private readonly baseUrl: string
+
+  constructor(baseUrl?: string) {
+    this.baseUrl =
+      (baseUrl ?? process.env.LETTA_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '')
+  }
+
+  /** Whether a base URL is configured. (There's no cheap sync reachability check.) */
+  isConfigured(): boolean {
+    return this.baseUrl.length > 0
+  }
+
+  private async request<T>(
+    path: string,
+    init?: RequestInit,
+  ): Promise<T> {
+    let res: Response
+    try {
+      res = await fetch(`${this.baseUrl}${path}`, {
+        ...init,
+        headers: {
+          'Content-Type': 'application/json',
+          ...(init?.headers ?? {}),
+        },
+        // Server-side calls only; no caching of live agent state.
+        cache: 'no-store',
+      })
+    } catch (err) {
+      // Connection refused etc. — the server container probably isn't up.
+      throw new Error(
+        `Letta server unreachable at ${this.baseUrl} — is the letta container running? (${err instanceof Error ? err.message : String(err)})`,
+      )
+    }
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '')
+      throw new Error(`Letta ${init?.method ?? 'GET'} ${path} failed: ${res.status} ${res.statusText}${body ? ` — ${body.slice(0, 300)}` : ''}`)
+    }
+
+    // DELETE and some endpoints may return empty bodies.
+    const text = await res.text()
+    return (text ? JSON.parse(text) : undefined) as T
+  }
+
+  /** GET /v1/agents — list all agents on the server. */
+  async listAgents(): Promise<LettaAgent[]> {
+    return this.request<LettaAgent[]>('/v1/agents')
+  }
+
+  /** GET /v1/agents/{id} — one agent's full state. */
+  async getAgent(id: string): Promise<LettaAgent> {
+    return this.request<LettaAgent>(`/v1/agents/${encodeURIComponent(id)}`)
+  }
+
+  /** POST /v1/agents — create an agent (memory-first: pass memory_blocks). */
+  async createAgent(cfg: CreateAgentConfig): Promise<LettaAgent> {
+    return this.request<LettaAgent>('/v1/agents', {
+      method: 'POST',
+      body: JSON.stringify(cfg),
+    })
+  }
+
+  /**
+   * POST /v1/agents/{id}/messages — send one user message, get the full turn
+   * back (reasoning + assistant + any tool messages).
+   *
+   * NOTE (serialization): Letta processes an agent's messages sequentially. A
+   * real control plane must serialize per-agent sends; this spike does not.
+   */
+  async sendMessage(id: string, text: string): Promise<LettaMessageResponse> {
+    return this.request<LettaMessageResponse>(
+      `/v1/agents/${encodeURIComponent(id)}/messages`,
+      {
+        method: 'POST',
+        body: JSON.stringify({
+          messages: [{ role: 'user', content: text }],
+        }),
+      },
+    )
+  }
+
+  /**
+   * GET /v1/agents/{id}/blocks — the agent's core-memory blocks. This is the
+   * granularity the "Librarian in an Airlock" use-case hangs on (one curated
+   * `shareable` block, the rest private).
+   */
+  async getMemoryBlocks(id: string): Promise<LettaBlock[]> {
+    return this.request<LettaBlock[]>(`/v1/agents/${encodeURIComponent(id)}/blocks`)
+  }
+}

From 2e8e3213dab87ee0f63189efad228536d0efcd2e Mon Sep 17 00:00:00 2001
From: Juniper Bevensee <juniperbevensee@users.noreply.github.com>
Date: Sat, 18 Jul 2026 12:05:26 +1000
Subject: [PATCH 2/3] =?UTF-8?q?feat(letta):=20fork=20slice=201=20=E2=80=94?=
 =?UTF-8?q?=20runtime=20seam=20+=20agents-as-Harness=20(read-only)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First slice of the Letta wizard/base-package fork (design
2026-07-18-letta-wizard-fork-design.md, §5 recommended first slice). Stacks
on the Letta REST spike (#163, branch swarm-map-letta-runtime). Entirely
additive; no live Letta server required to compile.

Phase 0 (discriminator + server-as-Harness):
- lib/types.ts: extend Harness.runtime union with 'letta' + 'letta-server'
  (the one additive types.ts change the spike deliberately avoided).
- lib/services/runtime-adapter.ts: ContainerRuntimeAdapter interface — the
  container-runtime seam (design §1b), discovery surface only.
- lib/services/harness.ts: hermesAdapter + pickContainerAdapter registry;
  discover() now dispatches the discovery gate / runtime / dataDir / persona /
  models through the adapter instead of the inline hermes-/seraph- string gate.
  Behavior-preserving extraction — hermesAdapter delegates to the same
  module-local guessDataDir/readSoul/readModelConfig, overlay-only containers
  keep hermes semantics via `effAdapter = adapter ?? hermesAdapter`.
- lib/services/letta-agent-provider.ts: AgentResourceProvider (Letta) — maps
  LettaAgent -> Harness (design §1c), plus the Letta server as a
  container-backed 'letta-server' Harness. Read-only (list/get) in this slice.
- lib/services/index.ts: wire the provider as services.lettaAgents.

Phase 1 read-only half (UI degradation):
- app/api/letta/harnesses: fleet-list endpoint (server + agents as Harness[]).
- app/api/harnesses/[id]: GET branches to the Letta provider for h_letta_* ids.
- components/harness/letta-agent-detail.tsx: dedicated read-only Letta detail
  view — model handle instead of CPU/mem, memory-block viewer, message viewer
  in place of the container Logs tab, no lifecycle buttons (design §4a).
- harnesses/[id]/page.tsx: runtime-branching wrapper early-returns to the Letta
  view; existing Hermes page renamed HermesHarnessDetail, otherwise untouched.
- harnesses/page.tsx: merge Letta harnesses into the fleet list; Letta rows
  degrade to Open only (no restart/stop/duplicate/remove), no cost/inv stats.

Deferred to later phases (clear TODOs in-code): adapter extraction of
generateCompose/scaffold/image-ref (Phase 2, touches Hermes deploy — untouched
here), wizard runtime toggle + deploy branch (Phase 3), live-server validation
of create/message/block shapes (Phase 4), Librarian package + airlock (Phase 5).

Verify: tsc --noEmit clean; eslint clean on all new files (pre-existing
warnings/1 error remain in untouched ModelCascadeEditor code); 6/6 existing
harness.test.ts pass (behavior preservation).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 app/(dashboard)/harnesses/[id]/page.tsx   |  19 ++
 app/(dashboard)/harnesses/page.tsx        |  61 ++++--
 app/api/harnesses/[id]/route.ts           |  10 +
 app/api/letta/harnesses/route.ts          |  17 ++
 components/harness/letta-agent-detail.tsx | 216 ++++++++++++++++++++++
 lib/services/harness.ts                   |  48 ++++-
 lib/services/index.ts                     |  10 +-
 lib/services/letta-agent-provider.ts      | 156 ++++++++++++++++
 lib/services/runtime-adapter.ts           |  46 +++++
 lib/types.ts                              |   7 +-
 10 files changed, 564 insertions(+), 26 deletions(-)
 create mode 100644 app/api/letta/harnesses/route.ts
 create mode 100644 components/harness/letta-agent-detail.tsx
 create mode 100644 lib/services/letta-agent-provider.ts
 create mode 100644 lib/services/runtime-adapter.ts

diff --git a/app/(dashboard)/harnesses/[id]/page.tsx b/app/(dashboard)/harnesses/[id]/page.tsx
index 22db863..1212e32 100644
--- a/app/(dashboard)/harnesses/[id]/page.tsx
+++ b/app/(dashboard)/harnesses/[id]/page.tsx
@@ -26,6 +26,7 @@ import { MessageSquare, Globe, Bot, Hash, Pencil, ChevronDown, ChevronRight, Shi
 import { TagInput } from '@/components/ui/tag-input'
 import { Switch } from '@/components/ui/switch'
 import { TIER_LABELS } from '@/lib/constants'
+import { LettaAgentDetail } from '@/components/harness/letta-agent-detail'
 
 type PairingUser = {
   userId: string
@@ -122,7 +123,25 @@ type UsageData = {
   recentSessions: UsageSession[]
 }
 
+// Runtime-branching wrapper (design §4a). Letta harnesses have no container, so
+// their detail view is a dedicated read-only component rather than a thicket of
+// `runtime === 'letta'` branches through the container-shaped Hermes page below.
+// Fetching harness here (before branching) keeps rules-of-hooks intact — each
+// child owns its own hooks.
 export default function HarnessDetailPage({ params }: { params: Promise<{ id: string }> }) {
+  const { id } = use(params)
+  const { data: harness, loading } = useApi<Harness>(`/api/harnesses/${id}`)
+
+  if (loading && !harness) {
+    return <p className="text-muted-foreground">Loading...</p>
+  }
+  if (harness && (harness.runtime === 'letta' || harness.runtime === 'letta-server')) {
+    return <LettaAgentDetail harness={harness} />
+  }
+  return <HermesHarnessDetail params={params} />
+}
+
+function HermesHarnessDetail({ params }: { params: Promise<{ id: string }> }) {
   const { id } = use(params)
   const router = useRouter()
 
diff --git a/app/(dashboard)/harnesses/page.tsx b/app/(dashboard)/harnesses/page.tsx
index 2c75dfd..4f492fb 100644
--- a/app/(dashboard)/harnesses/page.tsx
+++ b/app/(dashboard)/harnesses/page.tsx
@@ -11,9 +11,20 @@ import { toast } from 'sonner'
 
 export default function HarnessesPage() {
   const router = useRouter()
-  const { data: harnesses, loading, refetch } = useApi<Harness[]>('/api/harnesses', 5000)
+  const { data: containerHarnesses, loading, refetch } = useApi<Harness[]>('/api/harnesses', 5000)
+  // Letta agents come from a separate async REST path (design §1c) — merge them
+  // into the fleet list. Failure is soft: no Letta server → just no Letta rows.
+  const { data: lettaHarnesses } = useApi<Harness[]>('/api/letta/harnesses', 10000)
 
-  const running = harnesses?.filter((h) => h.status === 'running') ?? []
+  const harnesses =
+    containerHarnesses || lettaHarnesses
+      ? [...(containerHarnesses ?? []), ...(Array.isArray(lettaHarnesses) ? lettaHarnesses : [])]
+      : undefined
+
+  // Only container harnesses can be bulk-restarted (Letta agents aren't containers).
+  const running = containerHarnesses?.filter((h) => h.status === 'running') ?? []
+
+  const isLetta = (h: Harness) => h.runtime === 'letta' || h.runtime === 'letta-server'
 
   async function restartAll() {
     try {
@@ -178,24 +189,40 @@ export default function HarnessesPage() {
                   <td className="px-4 py-3">
                     <TierBadge tier={h.tier} />
                   </td>
-                  <td className="px-4 py-3 text-muted-foreground">{h.platform} / {h.channel}</td>
+                  <td className="px-4 py-3 text-muted-foreground">
+                    {isLetta(h) ? (
+                      <span className="rounded-full bg-muted px-2 py-0.5 text-xs uppercase tracking-wide">{h.runtime}</span>
+                    ) : (
+                      <>{h.platform} / {h.channel}</>
+                    )}
+                  </td>
                   <td className="px-4 py-3 text-muted-foreground">{h.models?.[0] ?? '—'}</td>
-                  <td className="px-4 py-3 text-right">${(h.costToday ?? 0).toFixed(2)}</td>
-                  <td className="px-4 py-3 text-right">{h.invocations ?? 0}</td>
+                  {/* Letta agents have no per-agent container stats (design §4b) */}
+                  <td className="px-4 py-3 text-right">{isLetta(h) ? '—' : `$${(h.costToday ?? 0).toFixed(2)}`}</td>
+                  <td className="px-4 py-3 text-right">{isLetta(h) ? '—' : (h.invocations ?? 0)}</td>
                   <td className="px-4 py-3 text-right">
                     <div className="flex items-center justify-end gap-2">
-                      <Button variant="ghost" size="xs" onClick={() => restartOne(h.id)} disabled={h.status === 'restarting'}>
-                        {h.status === 'restarting' ? 'Rebuilding...' : 'Restart'}
-                      </Button>
-                      <Button variant="ghost" size="xs" onClick={() => stopOne(h.id)}>
-                        Stop
-                      </Button>
-                      <Button variant="ghost" size="xs" onClick={() => duplicateOne(h.id, h.name)} title="Duplicate">
-                        ⧉
-                      </Button>
-                      <Button variant="ghost" size="xs" onClick={() => removeOne(h.id, h.name)} title="Remove" className="text-destructive hover:text-destructive">
-                        ✕
-                      </Button>
+                      {isLetta(h) ? (
+                        // No container lifecycle for a Postgres row — just open it.
+                        <Link href={`/harnesses/${h.id}`}>
+                          <Button variant="ghost" size="xs">Open</Button>
+                        </Link>
+                      ) : (
+                        <>
+                          <Button variant="ghost" size="xs" onClick={() => restartOne(h.id)} disabled={h.status === 'restarting'}>
+                            {h.status === 'restarting' ? 'Rebuilding...' : 'Restart'}
+                          </Button>
+                          <Button variant="ghost" size="xs" onClick={() => stopOne(h.id)}>
+                            Stop
+                          </Button>
+                          <Button variant="ghost" size="xs" onClick={() => duplicateOne(h.id, h.name)} title="Duplicate">
+                            ⧉
+                          </Button>
+                          <Button variant="ghost" size="xs" onClick={() => removeOne(h.id, h.name)} title="Remove" className="text-destructive hover:text-destructive">
+                            ✕
+                          </Button>
+                        </>
+                      )}
                     </div>
                   </td>
                 </tr>
diff --git a/app/api/harnesses/[id]/route.ts b/app/api/harnesses/[id]/route.ts
index 28dbbd8..ce38b48 100644
--- a/app/api/harnesses/[id]/route.ts
+++ b/app/api/harnesses/[id]/route.ts
@@ -1,11 +1,21 @@
 import { NextResponse } from 'next/server'
 import { services } from '@/lib/services'
+import { isLettaHarnessId } from '@/lib/services/letta-agent-provider'
 
 export async function GET(
   _request: Request,
   { params }: { params: Promise<{ id: string }> }
 ) {
   const { id } = await params
+  // Letta agents/server aren't containers — resolve them over REST (design §1c),
+  // not through the sync container discovery in HarnessService.get().
+  if (isLettaHarnessId(id)) {
+    const harness = await services.lettaAgents.get(id)
+    if (!harness) {
+      return NextResponse.json({ error: 'Not found' }, { status: 404 })
+    }
+    return NextResponse.json(harness)
+  }
   const harness = services.harness.get(id)
   if (!harness) {
     return NextResponse.json({ error: 'Not found' }, { status: 404 })
diff --git a/app/api/letta/harnesses/route.ts b/app/api/letta/harnesses/route.ts
new file mode 100644
index 0000000..ed66323
--- /dev/null
+++ b/app/api/letta/harnesses/route.ts
@@ -0,0 +1,17 @@
+// Slice 1: Letta agents (+ the Letta server) mapped to Harness objects, so the
+// fleet list can render them alongside container harnesses. Read-only. See
+// design §1c / §4b. Distinct from /api/harnesses (sync container discovery) —
+// this path is async REST against the Letta server.
+import { NextResponse } from 'next/server'
+import { services } from '@/lib/services'
+
+export async function GET() {
+  try {
+    return NextResponse.json(await services.lettaAgents.list())
+  } catch (err) {
+    return NextResponse.json(
+      { error: err instanceof Error ? err.message : 'Failed to list Letta harnesses', harnesses: [] },
+      { status: 502 },
+    )
+  }
+}
diff --git a/components/harness/letta-agent-detail.tsx b/components/harness/letta-agent-detail.tsx
new file mode 100644
index 0000000..54f8e5b
--- /dev/null
+++ b/components/harness/letta-agent-detail.tsx
@@ -0,0 +1,216 @@
+'use client'
+
+/**
+ * Read-only detail view for a Letta harness (agent or server). Slice 1 of the
+ * Letta fork (design §4a): the container-shaped Hermes detail page has no
+ * meaning for a Postgres-row agent, so we render a dedicated degraded view
+ * instead of threading `runtime === 'letta'` branches through the 1800-line
+ * Hermes page.
+ *
+ * What degrades to what (design §4a):
+ *   Lifecycle buttons  → Send message (Reset/Delete deferred to a later phase)
+ *   Overview CPU/mem    → model handle + agent identity
+ *   Logs tab            → message / turn viewer (send + rendered reply)
+ *   Memory rows         → core-memory block viewer (the airlock's key surface)
+ *
+ * Everything here is read-only except "send a message" (which the spike route
+ * already supports). Create/update/reset need a live Letta server (Phase 4).
+ */
+
+import { useState } from 'react'
+import Link from 'next/link'
+import { Button } from '@/components/ui/button'
+import { StatusDot } from '@/components/shared/status-dot'
+import { useApi } from '@/lib/hooks/use-api'
+import type { Harness } from '@/lib/types'
+import type { LettaBlock, LettaMessage } from '@/lib/services/letta'
+import { toast } from 'sonner'
+
+/** Best-effort stringify of a Letta message's `content` (spike-loose typing). */
+function renderContent(content: unknown): string {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    return content
+      .map((c) => (typeof c === 'string' ? c : (c as { text?: string })?.text ?? JSON.stringify(c)))
+      .join('')
+  }
+  return content == null ? '' : JSON.stringify(content)
+}
+
+function Row({ label, value }: { label: string; value: React.ReactNode }) {
+  return (
+    <div className="flex items-center justify-between py-2 border-b border-[var(--border)] last:border-0">
+      <span className="text-sm text-muted-foreground">{label}</span>
+      <span className="text-sm font-medium">{value}</span>
+    </div>
+  )
+}
+
+/** Strip the `h_letta_` prefix to recover the raw Letta agent id for the spike routes. */
+function agentIdFromHarnessId(id: string): string {
+  return id.startsWith('h_letta_') ? id.slice('h_letta_'.length) : id
+}
+
+export function LettaAgentDetail({ harness }: { harness: Harness }) {
+  const isServer = harness.runtime === 'letta-server'
+  const agentId = agentIdFromHarnessId(harness.id)
+
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center gap-3">
+        <Link href="/harnesses" className="text-sm text-muted-foreground hover:underline">
+          ← Harnesses
+        </Link>
+      </div>
+
+      <div className="flex items-center gap-3">
+        <StatusDot status={harness.status ?? 'stopped'} />
+        <h2 className="text-2xl font-semibold">{harness.name}</h2>
+        <span className="rounded-full bg-muted px-2 py-0.5 text-xs text-muted-foreground uppercase tracking-wide">
+          {harness.runtime}
+        </span>
+      </div>
+
+      <p className="text-xs text-muted-foreground">
+        {isServer
+          ? 'Letta server (a real container). Hosts N agents as Postgres rows — start/stop/logs via Docker are available on the server, agents are managed over REST.'
+          : 'Letta agent — a row in the Letta server’s Postgres, not a container. No CPU/memory, no lifecycle buttons; managed over REST.'}
+      </p>
+
+      {/* Overview: model handle + identity, not CPU/mem (design §4a) */}
+      <section className="rounded-xl border border-[var(--border)] bg-[var(--surface)] p-4">
+        <h3 className="text-sm font-semibold mb-2">Overview</h3>
+        <Row label="Runtime" value={harness.runtime} />
+        <Row label="Status" value={harness.status === 'running' ? 'reachable' : harness.status} />
+        {!isServer && <Row label="Model handle" value={harness.models?.[0] ?? '—'} />}
+        {!isServer && <Row label="Agent ID" value={<span className="font-mono text-xs">{agentId}</span>} />}
+        {isServer && <Row label="Service" value={<span className="font-mono text-xs">{harness.serviceName}</span>} />}
+        {isServer && <Row label="Endpoint" value={<span className="font-mono text-xs">{harness.channel || ':8283'}</span>} />}
+      </section>
+
+      {isServer ? (
+        <ServerAgentsList />
+      ) : (
+        <>
+          <MemoryBlocks agentId={agentId} />
+          <MessageViewer agentId={agentId} name={harness.name} />
+        </>
+      )}
+    </div>
+  )
+}
+
+function ServerAgentsList() {
+  // Server-hosted agents, for the server view's child list (design §4c tree).
+  const { data: fleet } = useApi<Harness[]>('/api/letta/harnesses')
+  const children = (fleet ?? []).filter((h) => h.runtime === 'letta')
+  return (
+    <section className="rounded-xl border border-[var(--border)] bg-[var(--surface)] p-4">
+      <h3 className="text-sm font-semibold mb-2">Hosted agents ({children.length})</h3>
+      {children.length === 0 ? (
+        <p className="text-sm text-muted-foreground">No agents on this server yet.</p>
+      ) : (
+        <ul className="space-y-1">
+          {children.map((c) => (
+            <li key={c.id}>
+              <Link href={`/harnesses/${c.id}`} className="flex items-center gap-2 text-sm hover:underline">
+                <StatusDot status={c.status ?? 'stopped'} />
+                <span className="font-medium">{c.name}</span>
+                <span className="text-xs text-muted-foreground">{c.models?.[0] ?? '—'}</span>
+              </Link>
+            </li>
+          ))}
+        </ul>
+      )}
+    </section>
+  )
+}
+
+/** Core-memory block viewer — the single most important Letta-native surface (design §4a). */
+function MemoryBlocks({ agentId }: { agentId: string }) {
+  const { data: blocks, loading, error } = useApi<LettaBlock[]>(`/api/letta/agents/${agentId}/blocks`)
+  return (
+    <section className="rounded-xl border border-[var(--border)] bg-[var(--surface)] p-4">
+      <h3 className="text-sm font-semibold mb-2">Memory blocks</h3>
+      <p className="text-xs text-muted-foreground mb-3">
+        Read-only in slice 1. Editing (the airlock&apos;s <code>shareable</code> block) lands with the live server.
+      </p>
+      {loading && <p className="text-sm text-muted-foreground">Loading…</p>}
+      {error && <p className="text-sm text-destructive">Couldn&apos;t read memory: {error}</p>}
+      {blocks && blocks.length === 0 && <p className="text-sm text-muted-foreground">No memory blocks.</p>}
+      {blocks && blocks.length > 0 && (
+        <div className="space-y-2">
+          {blocks.map((b, i) => (
+            <div key={b.id ?? b.label ?? i} className="rounded-md border border-[var(--border)] px-3 py-2 text-sm">
+              <div className="flex items-center gap-2">
+                <span className="font-mono text-xs text-accent-foreground">{b.label}</span>
+                {typeof b.limit === 'number' && (
+                  <span className="text-xs text-muted-foreground">limit {b.limit}</span>
+                )}
+              </div>
+              <div className="mt-1 whitespace-pre-wrap text-muted-foreground">{b.value}</div>
+            </div>
+          ))}
+        </div>
+      )}
+    </section>
+  )
+}
+
+/** Message / turn viewer — replaces the container Logs tab (design §4a). */
+function MessageViewer({ agentId, name }: { agentId: string; name: string }) {
+  const [text, setText] = useState('')
+  const [sending, setSending] = useState(false)
+  const [reply, setReply] = useState<LettaMessage[] | null>(null)
+
+  async function send() {
+    if (!text.trim()) return
+    setSending(true)
+    setReply(null)
+    try {
+      const res = await fetch(`/api/letta/agents/${agentId}/messages`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text: text.trim() }),
+      })
+      const json = await res.json()
+      if (!res.ok) throw new Error(json?.error ?? 'Send failed')
+      setReply(json.messages ?? [])
+      setText('')
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : 'Send failed')
+    } finally {
+      setSending(false)
+    }
+  }
+
+  return (
+    <section className="rounded-xl border border-[var(--border)] bg-[var(--surface)] p-4">
+      <h3 className="text-sm font-semibold mb-2">Messages</h3>
+      <div className="flex items-start gap-2">
+        <textarea
+          value={text}
+          onChange={(e) => setText(e.target.value)}
+          placeholder={`Message ${name}…`}
+          rows={2}
+          className="flex-1 rounded-md border border-[var(--border)] bg-[var(--surface)] px-3 py-2 text-sm resize-y"
+        />
+        <Button size="sm" onClick={send} disabled={sending || !text.trim()}>
+          {sending ? 'Sending…' : 'Send'}
+        </Button>
+      </div>
+      {reply && (
+        <div className="mt-3 space-y-1.5 text-sm">
+          {reply.map((m, i) => (
+            <div key={m.id ?? i} className="rounded-md border border-[var(--border)] px-3 py-2">
+              <span className="text-xs text-muted-foreground uppercase tracking-wide">
+                {m.message_type ?? m.role ?? 'message'}
+              </span>
+              <div className="mt-1 whitespace-pre-wrap">{renderContent(m.content)}</div>
+            </div>
+          ))}
+        </div>
+      )}
+    </section>
+  )
+}
diff --git a/lib/services/harness.ts b/lib/services/harness.ts
index fe692c2..2011e9e 100644
--- a/lib/services/harness.ts
+++ b/lib/services/harness.ts
@@ -17,6 +17,7 @@ import { getUseCaseTemplate, reapplyUseCaseTemplate as reapplyTemplateToDataDir
 import type { ToolsService } from './tools'
 import { generateStandaloneCompose, setComposeImage, readComposeImage, readComposeBuildContext } from './harness-compose'
 import { RegistryService, parseImageRef } from './registry'
+import type { ContainerRuntimeAdapter } from './runtime-adapter'
 
 const DEFAULT_IMAGE_REPO = 'nimblecoai/hermes-agent-mt'
 import { hsmBaseUrl } from './hsm-url'
@@ -681,6 +682,34 @@ export function guessDataDir(serviceName: string, containerName: string): string
   return path.join(home, '.hermes-' + serviceName)
 }
 
+// --- Container-runtime seam (design §1b) ------------------------------------
+// The Hermes adapter is a behavior-preserving wrapper around the module
+// functions discover() already calls inline. Extracting them behind
+// ContainerRuntimeAdapter lets discover() dispatch on runtime instead of
+// hardcoding the `hermes-`/`seraph-` prefix. readSoul/guessDataDir/
+// readModelConfig are module-local, so this delegates with ZERO behavior change.
+export const hermesAdapter: ContainerRuntimeAdapter = {
+  runtime: 'hermes',
+  // Preserves the exact gate from discover(): hermes-* and seraph-* containers.
+  matches: (containerName) =>
+    containerName.startsWith('hermes-') || containerName.startsWith('seraph-'),
+  dataDir: (serviceName, containerName) => guessDataDir(serviceName, containerName),
+  readPersona: (dataDir) => readSoul(dataDir),
+  readModels: (dataDir) => readModelConfig(dataDir),
+}
+
+// Registry of container adapters. Hermes is the only member in slice 1;
+// claude-code-proxy/custom slot in here later (design §1b). Letta is NOT here —
+// it's an AgentResourceProvider (REST), not a container adapter.
+const containerAdapters: ContainerRuntimeAdapter[] = [hermesAdapter]
+
+/** Pick the container adapter that owns this live container, if any. */
+export function pickContainerAdapter(
+  containerName: string,
+): ContainerRuntimeAdapter | undefined {
+  return containerAdapters.find((a) => a.matches(containerName))
+}
+
 // Resolve a harness's data dir from its NAME, honoring the personal special-case
 // (personal lives at ~/.hermes; every other agent at ~/.hermes-<name>). The
 // name-keyed twin of guessDataDir — used by duplicate/remove, which work from
@@ -878,12 +907,17 @@ export class HarnessService {
       const name = containerNameToHarnessName(containerName)
       const id = 'h_' + name.replace(/-/g, '_')
 
-      // Only include containers that look like hermes agents or have an overlay
-      const isHermes = containerName.startsWith('hermes-') || containerName.startsWith('seraph-')
-      if (!isHermes && !overlays[id]) continue
+      // Dispatch on the container-runtime seam (design §1b). A container is
+      // included if a runtime adapter claims it OR it has a stored overlay.
+      // Overlay-only containers keep Hermes semantics (the historical default),
+      // so `effAdapter` falls back to hermesAdapter — behavior-identical to the
+      // old inline `isHermes`/`runtime:'hermes'`/guessDataDir path.
+      const adapter = pickContainerAdapter(containerName)
+      if (!adapter && !overlays[id]) continue
+      const effAdapter = adapter ?? hermesAdapter
 
-      const dataDir = guessDataDir(live.serviceName, containerName)
-      const persona = readSoul(dataDir)
+      const dataDir = effAdapter.dataDir(live.serviceName, containerName)
+      const persona = effAdapter.readPersona(dataDir)
 
       const stats = allStats[containerName] ?? { cpu: 0, memMiB: 0 }
 
@@ -896,7 +930,7 @@ export class HarnessService {
         // Discoverable fields
         id,
         name,
-        runtime: 'hermes',
+        runtime: effAdapter.runtime,
         status: stateToStatus(live.state),
         health: { errors: 0 },
         persona: persona || overlay.persona || `Hermes agent: ${name}`,
@@ -909,7 +943,7 @@ export class HarnessService {
         tier: overlay.tier ?? 'individual',
         platform: overlay.platform ?? 'hermes',
         channel: overlay.channel ?? (port ? `:${port}` : ''),
-        models: overlay.models?.length ? overlay.models : readModelConfig(dataDir),
+        models: overlay.models?.length ? overlay.models : effAdapter.readModels(dataDir),
         costToday: getCostToday(id),
         invocations: getInvocationsToday(id),
         tools: overlay.tools?.length ? overlay.tools : (this.autoDiscoverTools(name) ?? []),
diff --git a/lib/services/index.ts b/lib/services/index.ts
index 337d3d5..1848c8a 100644
--- a/lib/services/index.ts
+++ b/lib/services/index.ts
@@ -9,6 +9,7 @@ import { ConfigService } from './config'
 import { SignalPinService } from './signal-pin'
 import { SurfaceAdminService } from './surface-admins'
 import { LettaService } from './letta'
+import { LettaAgentProvider } from './letta-agent-provider'
 import path from 'path'
 import os from 'os'
 
@@ -27,6 +28,11 @@ const tools = new ToolsService(storage)
 
 const keysService = new KeysService(storage, audit, DATA_DIR)
 
+// Agents-as-API-resources layer (design §1c). Maps Letta agents → Harness so
+// the fleet list/detail render them uniformly, gated by harness.runtime.
+const lettaService = new LettaService()
+const lettaAgents = new LettaAgentProvider(lettaService)
+
 // Wire ToolsService into HarnessService for auto-discovery of tools
 harness.setToolsService(tools)
 
@@ -43,5 +49,7 @@ export const services = {
   surfaceAdmins: new SurfaceAdminService(storage, audit),
   // SPIKE (Path 1): agents-as-API-resources layer, distinct from the container
   // model. Base URL from LETTA_BASE_URL, defaults to the compose-published :8283.
-  letta: new LettaService(),
+  letta: lettaService,
+  // Provider that maps Letta agents → Harness objects for the fleet UI (slice 1).
+  lettaAgents,
 }
diff --git a/lib/services/letta-agent-provider.ts b/lib/services/letta-agent-provider.ts
new file mode 100644
index 0000000..528956c
--- /dev/null
+++ b/lib/services/letta-agent-provider.ts
@@ -0,0 +1,156 @@
+/**
+ * LettaAgentProvider — the "agents-as-API-resources" layer (design §1c).
+ *
+ * This is NOT a ContainerRuntimeAdapter. A Letta agent has no container, no
+ * compose file, no port, no data dir — it is a row in the Letta server's
+ * Postgres. This provider wraps the spiked LettaService (REST :8283) and maps
+ * each LettaAgent into a `Harness` object so the existing fleet list / detail
+ * UI can render Letta agents uniformly, gated by `harness.runtime`.
+ *
+ * SCOPE (slice 1): read-only. list()/get() only. create/update/remove/message
+ * live on later phases (design §3/§4) — the deploy-route Letta branch and the
+ * live-server validation, which need a running Letta server to confirm payload
+ * shapes. Sending messages is still available through the existing
+ * /api/letta/agents/[id]/messages route the spike shipped.
+ */
+
+import type { Harness } from '@/lib/types'
+import type { LettaService, LettaAgent } from './letta'
+
+/** Stable id for the singleton Letta server harness (the container that hosts agents). */
+export const LETTA_SERVER_HARNESS_ID = 'h_letta_server'
+
+/** Prefix for agent harness ids, chosen to not collide with container `h_<name>` ids. */
+const AGENT_ID_PREFIX = 'h_letta_'
+
+/** The compose file + service that DockerService drives for the Letta server. */
+const LETTA_COMPOSE_FILE = 'docker/letta-compose.yml'
+const LETTA_SERVICE_NAME = 'letta'
+
+/** Is this harness id a Letta-runtime id (server or agent)? Cheap sync check for route branching. */
+export function isLettaHarnessId(id: string): boolean {
+  return id === LETTA_SERVER_HARNESS_ID || id.startsWith(AGENT_ID_PREFIX)
+}
+
+/** Recover the raw Letta agent id from a `h_letta_<agentId>` harness id. */
+export function lettaAgentIdFromHarnessId(harnessId: string): string {
+  return harnessId.startsWith(AGENT_ID_PREFIX)
+    ? harnessId.slice(AGENT_ID_PREFIX.length)
+    : harnessId
+}
+
+/**
+ * Map a Letta agent (Postgres row) into a Harness (design §1c table). Container
+ * fields that have no per-agent analogue are zeroed/omitted; the UI branches on
+ * `runtime === 'letta'` to hide them rather than showing 0% CPU.
+ */
+export function lettaAgentToHarness(agent: LettaAgent, serverReachable: boolean): Harness {
+  const firstBlock = agent.memory_blocks?.find((b) => b.label === 'persona') ?? agent.memory_blocks?.[0]
+  return {
+    id: AGENT_ID_PREFIX + agent.id,
+    name: agent.name ?? agent.id,
+    runtime: 'letta',
+    // Collapse to reachable/unreachable — an agent has no idle/stopped/restarting.
+    status: serverReachable ? 'running' : 'error',
+    health: { errors: 0 },
+    persona: typeof firstBlock?.value === 'string' ? firstBlock.value : '',
+    tier: 'individual',
+    // NOT a messaging surface — distinct from Hermes' platform default.
+    platform: 'letta',
+    channel: '',
+    lastSeen: Date.now(),
+    models: agent.model ? [agent.model] : [],
+    // No per-agent container stats. Sourced later from Letta's usage API (Phase 4).
+    costToday: 0,
+    invocations: 0,
+    cpu: 0,
+    mem: 0,
+    tools: [],
+    // Points at the server's harness — models the server→agents tree (design §4c).
+    parentId: LETTA_SERVER_HARNESS_ID,
+  }
+}
+
+/** The Letta server itself, as a container-backed harness (design §1c "Server-as-a-Harness"). */
+export function lettaServerHarness(reachable: boolean): Harness {
+  return {
+    id: LETTA_SERVER_HARNESS_ID,
+    name: 'letta-server',
+    runtime: 'letta-server',
+    status: reachable ? 'running' : 'stopped',
+    health: { errors: 0 },
+    persona: 'Letta server — hosts N agents as Postgres rows',
+    tier: 'org',
+    platform: 'letta',
+    channel: ':8283',
+    lastSeen: Date.now(),
+    models: [],
+    costToday: 0,
+    invocations: 0,
+    cpu: 0,
+    mem: 0,
+    tools: [],
+    // Real compose target — DockerService verbs (start/stop/logs) work on it
+    // unchanged (design §1c). Lifecycle WIRING through HarnessService.get() is
+    // Phase 2 (get() is sync; this provider is async) — see class note below.
+    composeFile: LETTA_COMPOSE_FILE,
+    serviceName: LETTA_SERVICE_NAME,
+  }
+}
+
+export interface AgentResourceProvider {
+  runtime: 'letta'
+  list(): Promise<Harness[]>
+  get(harnessId: string): Promise<Harness | undefined>
+  serverHealth(): Promise<{ reachable: boolean }>
+}
+
+export class LettaAgentProvider implements AgentResourceProvider {
+  readonly runtime = 'letta' as const
+
+  constructor(private readonly letta: LettaService) {}
+
+  /** True if the Letta server answers GET /v1/agents. Doubles as the list fetch. */
+  async serverHealth(): Promise<{ reachable: boolean }> {
+    try {
+      await this.letta.listAgents()
+      return { reachable: true }
+    } catch {
+      return { reachable: false }
+    }
+  }
+
+  /**
+   * The Letta server harness followed by one harness per agent. If the server
+   * is unreachable, returns just the server harness (status 'stopped') so the
+   * fleet still shows the server tile rather than vanishing.
+   */
+  async list(): Promise<Harness[]> {
+    let agents: LettaAgent[]
+    try {
+      agents = await this.letta.listAgents()
+    } catch {
+      return [lettaServerHarness(false)]
+    }
+    return [
+      lettaServerHarness(true),
+      ...agents.map((a) => lettaAgentToHarness(a, true)),
+    ]
+  }
+
+  /** Resolve one Letta harness (server or agent) by its harness id. */
+  async get(harnessId: string): Promise<Harness | undefined> {
+    if (harnessId === LETTA_SERVER_HARNESS_ID) {
+      const { reachable } = await this.serverHealth()
+      return lettaServerHarness(reachable)
+    }
+    if (!harnessId.startsWith(AGENT_ID_PREFIX)) return undefined
+    const agentId = lettaAgentIdFromHarnessId(harnessId)
+    try {
+      const agent = await this.letta.getAgent(agentId)
+      return lettaAgentToHarness(agent, true)
+    } catch {
+      return undefined
+    }
+  }
+}
diff --git a/lib/services/runtime-adapter.ts b/lib/services/runtime-adapter.ts
new file mode 100644
index 0000000..000d25c
--- /dev/null
+++ b/lib/services/runtime-adapter.ts
@@ -0,0 +1,46 @@
+/**
+ * ContainerRuntimeAdapter — the container-runtime seam.
+ *
+ * Design: memory/specs/2026-07-18-letta-wizard-fork-design.md §1b.
+ *
+ * HSM's discovery/detail code currently hardcodes Hermes assumptions inline
+ * (the `hermes-`/`seraph-` name gate, `~/.hermes*` data dir, the SOUL/model
+ * readers). This interface factors those out so `HarnessService.discover()`
+ * dispatches on a runtime adapter instead of branching on string prefixes —
+ * making room for `claude-code-proxy`/`custom` later.
+ *
+ * SCOPE (slice 1): only the *discovery* surface is extracted — the fields
+ * `discover()` reads off a live container. The remaining container methods the
+ * full design lists (`generateCompose`, `scaffold`, `readImageRef`/
+ * `setImageRef`, `serviceName`) stay inline in harness.ts / harness-compose.ts
+ * for now; extracting them touches the Hermes *deploy* path and is deferred to
+ * Phase 2 (see design §5). Adding a member here is additive — nothing calls a
+ * method that doesn't exist yet.
+ *
+ * NOTE: Letta agents do NOT go through this adapter. They are not containers;
+ * they are enumerated from the Letta server over REST by the separate
+ * AgentResourceProvider (lib/services/letta-agent-provider.ts). This interface
+ * is exclusively the *container* seam.
+ */
+
+import type { Harness } from '@/lib/types'
+
+export interface ContainerRuntimeAdapter {
+  /** The `runtime` value stamped on harnesses this adapter discovers. */
+  runtime: Harness['runtime']
+
+  /**
+   * Discovery gate: does this live container belong to this runtime? Replaces
+   * the inline `containerName.startsWith('hermes-')` test in discover().
+   */
+  matches(containerName: string): boolean
+
+  /** Where the agent's world lives on disk (SOUL.md, config). */
+  dataDir(serviceName: string, containerName: string): string
+
+  /** Short persona/identity string read off the data dir. */
+  readPersona(dataDir: string): string
+
+  /** Configured model handles read off the data dir. */
+  readModels(dataDir: string): string[]
+}
diff --git a/lib/types.ts b/lib/types.ts
index d10f40f..2a411ba 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -13,7 +13,12 @@ export type RestartMode = 'quick' | 'recreate' | 'rebuild' | 'purge'
 export type Harness = {
   id: string
   name: string
-  runtime: 'hermes' | 'claude-code-proxy' | 'custom'
+  // 'letta'        — a Letta agent (a row in the Letta server's Postgres, not a
+  //                  container). Managed over REST via AgentResourceProvider.
+  // 'letta-server' — the Letta server itself, a real container-backed harness
+  //                  (docker/letta-compose.yml, service `letta`) that hosts N
+  //                  'letta' agents as children (parentId = its id).
+  runtime: 'hermes' | 'claude-code-proxy' | 'custom' | 'letta' | 'letta-server'
   parentId?: string
   status: HarnessStatus
   health: { errors: number; errorMsg?: string }

From 6374b176390f4b38b012095b2ded66537572dff8 Mon Sep 17 00:00:00 2001
From: Juniper Bevensee <juniperbevensee@users.noreply.github.com>
Date: Sun, 19 Jul 2026 19:00:58 +1000
Subject: [PATCH 3/3] =?UTF-8?q?refactor(runtime-seam):=20A1=20=E2=80=94=20?=
 =?UTF-8?q?extract=20provisioning=20+=20image-ref=20into=20ContainerRuntim?=
 =?UTF-8?q?eAdapter,=20fix=20overlay-fallback=20dispatch?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 2 of the wizard-fork design (memory/specs/2026-07-18-letta-wizard-fork-design.md §1b, §5):

- ContainerRuntimeAdapter gains the provisioning surface (serviceName,
  generateCompose, scaffold) and the CD image-ref surface (readImageRef,
  setImageRef, defaultImageRepo). hermesAdapter delegates to the same
  module functions the call sites used inline — zero behavior change.
- Fix the `adapter ?? hermesAdapter` landmine: discover()'s overlay-only
  branch now dispatches on the overlay's PERSISTED runtime via
  adapterForRuntime(), not a blind Hermes fallback. Pre-seam rows
  (no runtime field) keep Hermes semantics.
- HarnessService dispatch sites (resolveComposeTarget, currentImage,
  imageStatus, setAgentImage, duplicate, createOverlay, importFromDir)
  and the settings route now go through the adapter.
- registerContainerAdapter() for future runtimes (claude-code-proxy/custom).

727/727 tests, tsc clean. New: runtime-adapter.test.ts (selection + delegation).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 app/api/harnesses/[id]/settings/route.ts      |  4 +-
 .../__tests__/runtime-adapter.test.ts         | 74 ++++++++++++++++++
 lib/services/harness.ts                       | 76 ++++++++++++++-----
 lib/services/runtime-adapter.ts               | 35 +++++++--
 4 files changed, 163 insertions(+), 26 deletions(-)
 create mode 100644 lib/services/__tests__/runtime-adapter.test.ts

diff --git a/app/api/harnesses/[id]/settings/route.ts b/app/api/harnesses/[id]/settings/route.ts
index e045365..858773c 100644
--- a/app/api/harnesses/[id]/settings/route.ts
+++ b/app/api/harnesses/[id]/settings/route.ts
@@ -5,7 +5,7 @@ import os from 'os'
 import { buildSettingsEnvValue } from '@/lib/env-helpers'
 import { resolveIdentifier, expandSignalAllowlist } from '@/lib/resolvers'
 import { services } from '@/lib/services'
-import { generateStandaloneCompose } from '@/lib/services/harness-compose'
+import { adapterForRuntime } from '@/lib/services/harness'
 
 function agentDataDir(harnessId: string): string {
   const name = harnessId.replace(/^h_/, '').replace(/_/g, '-')
@@ -397,7 +397,7 @@ export async function PUT(
           })()
         : undefined
 
-      const compose = generateStandaloneCompose(harness.name, port, dataDir, {
+      const compose = adapterForRuntime(harness.runtime).generateCompose(harness.name, port, dataDir, {
         vpnEnabled: vpnForCompose,
         imageOrBuild,
         defaultImage: settings.defaultImage,
diff --git a/lib/services/__tests__/runtime-adapter.test.ts b/lib/services/__tests__/runtime-adapter.test.ts
new file mode 100644
index 0000000..6f48d00
--- /dev/null
+++ b/lib/services/__tests__/runtime-adapter.test.ts
@@ -0,0 +1,74 @@
+// @vitest-environment node
+import { describe, it, expect } from 'vitest'
+import {
+  hermesAdapter,
+  adapterForRuntime,
+  pickContainerAdapter,
+  registerContainerAdapter,
+} from '../harness'
+import type { ContainerRuntimeAdapter } from '../runtime-adapter'
+
+describe('hermesAdapter Phase-2 members (delegation)', () => {
+  it('serviceName follows the hermes-<name> convention', () => {
+    expect(hermesAdapter.serviceName('osint')).toBe('hermes-osint')
+  })
+
+  it('defaultImageRepo is the hermes-agent-mt repo', () => {
+    expect(hermesAdapter.defaultImageRepo).toBe('nimblecoai/hermes-agent-mt')
+  })
+
+  it('generateCompose emits the hermes-<name> service readImageRef/setImageRef operate on', () => {
+    const compose = hermesAdapter.generateCompose('echo', 8642, '/data/echo', {
+      defaultImage: 'ghcr.io/nimblecoai/hermes-agent-mt:latest',
+    })
+    expect(compose).toContain('hermes-echo:')
+    expect(hermesAdapter.readImageRef(compose)).toBe('ghcr.io/nimblecoai/hermes-agent-mt:latest')
+
+    const pinned = hermesAdapter.setImageRef(compose, 'ghcr.io/nimblecoai/hermes-agent-mt:2026-07-01')
+    expect(hermesAdapter.readImageRef(pinned)).toBe('ghcr.io/nimblecoai/hermes-agent-mt:2026-07-01')
+  })
+})
+
+describe('adapterForRuntime (overlay-fallback selection)', () => {
+  it('resolves hermes explicitly', () => {
+    expect(adapterForRuntime('hermes')).toBe(hermesAdapter)
+  })
+
+  it('falls back to hermes for undefined (pre-seam overlay rows)', () => {
+    expect(adapterForRuntime(undefined)).toBe(hermesAdapter)
+  })
+
+  it('falls back to hermes for runtimes with no container adapter (letta)', () => {
+    expect(adapterForRuntime('letta')).toBe(hermesAdapter)
+  })
+
+  // Registration mutates the module-global registry, so this block runs LAST
+  // in this file; vitest isolates modules per test file.
+  it('consults the persisted runtime once a second adapter is registered', () => {
+    const customAdapter: ContainerRuntimeAdapter = {
+      runtime: 'custom',
+      matches: (name) => name.startsWith('custom-'),
+      dataDir: (_s, c) => `/data/${c}`,
+      readPersona: () => '',
+      readModels: () => [],
+      serviceName: (name) => `custom-${name}`,
+      generateCompose: () => '',
+      scaffold: async () => {},
+      readImageRef: () => null,
+      setImageRef: (compose) => compose,
+      defaultImageRepo: 'example/custom',
+    }
+    registerContainerAdapter(customAdapter)
+    // duplicate registration is a no-op
+    registerContainerAdapter(customAdapter)
+
+    expect(adapterForRuntime('custom')).toBe(customAdapter)
+    // the fix: an overlay-only row with a persisted non-hermes runtime no
+    // longer silently degrades to hermes semantics
+    expect(adapterForRuntime('custom')).not.toBe(hermesAdapter)
+    // name-based discovery picks it up too
+    expect(pickContainerAdapter('custom-agent')).toBe(customAdapter)
+    // hermes selection is unaffected
+    expect(adapterForRuntime('hermes')).toBe(hermesAdapter)
+  })
+})
diff --git a/lib/services/harness.ts b/lib/services/harness.ts
index 2011e9e..ab0c818 100644
--- a/lib/services/harness.ts
+++ b/lib/services/harness.ts
@@ -696,13 +696,27 @@ export const hermesAdapter: ContainerRuntimeAdapter = {
   dataDir: (serviceName, containerName) => guessDataDir(serviceName, containerName),
   readPersona: (dataDir) => readSoul(dataDir),
   readModels: (dataDir) => readModelConfig(dataDir),
+  serviceName: (name) => `hermes-${name}`,
+  generateCompose: (name, port, dataDir, options) =>
+    generateStandaloneCompose(name, port, dataDir, options),
+  scaffold: (dataDir, name, port) => scaffoldAgentDir(dataDir, name, port),
+  readImageRef: (compose) => readComposeImage(compose),
+  setImageRef: (compose, ref) => setComposeImage(compose, ref),
+  defaultImageRepo: DEFAULT_IMAGE_REPO,
 }
 
-// Registry of container adapters. Hermes is the only member in slice 1;
+// Registry of container adapters. Hermes is the only member;
 // claude-code-proxy/custom slot in here later (design §1b). Letta is NOT here —
 // it's an AgentResourceProvider (REST), not a container adapter.
 const containerAdapters: ContainerRuntimeAdapter[] = [hermesAdapter]
 
+/** Register a container adapter (future runtimes; exported for tests). */
+export function registerContainerAdapter(adapter: ContainerRuntimeAdapter): void {
+  if (!containerAdapters.some((a) => a.runtime === adapter.runtime)) {
+    containerAdapters.push(adapter)
+  }
+}
+
 /** Pick the container adapter that owns this live container, if any. */
 export function pickContainerAdapter(
   containerName: string,
@@ -710,6 +724,16 @@ export function pickContainerAdapter(
   return containerAdapters.find((a) => a.matches(containerName))
 }
 
+/**
+ * Pick the adapter for a harness's *persisted* runtime. Falls back to Hermes
+ * for undefined/unknown runtimes — the historical default for overlay rows
+ * that predate the `runtime` field. Letta rows never reach the container
+ * paths that call this (they have no container to operate on).
+ */
+export function adapterForRuntime(runtime?: Harness['runtime']): ContainerRuntimeAdapter {
+  return containerAdapters.find((a) => a.runtime === runtime) ?? hermesAdapter
+}
+
 // Resolve a harness's data dir from its NAME, honoring the personal special-case
 // (personal lives at ~/.hermes; every other agent at ~/.hermes-<name>). The
 // name-keyed twin of guessDataDir — used by duplicate/remove, which work from
@@ -909,12 +933,13 @@ export class HarnessService {
 
       // Dispatch on the container-runtime seam (design §1b). A container is
       // included if a runtime adapter claims it OR it has a stored overlay.
-      // Overlay-only containers keep Hermes semantics (the historical default),
-      // so `effAdapter` falls back to hermesAdapter — behavior-identical to the
-      // old inline `isHermes`/`runtime:'hermes'`/guessDataDir path.
+      // Overlay-only containers dispatch on their PERSISTED runtime — not a
+      // blind Hermes fallback — so a container whose name no adapter claims
+      // still gets the adapter its overlay recorded. Rows without a runtime
+      // (pre-seam overlays) keep Hermes semantics, the historical default.
       const adapter = pickContainerAdapter(containerName)
       if (!adapter && !overlays[id]) continue
-      const effAdapter = adapter ?? hermesAdapter
+      const effAdapter = adapter ?? adapterForRuntime(overlays[id]?.runtime)
 
       const dataDir = effAdapter.dataDir(live.serviceName, containerName)
       const persona = effAdapter.readPersona(dataDir)
@@ -1082,7 +1107,10 @@ export class HarnessService {
       if (fs.existsSync(candidate)) composeFile = candidate
     }
     const serviceName =
-      harness.serviceName || (composeFile && harness.name ? `hermes-${harness.name}` : undefined)
+      harness.serviceName ||
+      (composeFile && harness.name
+        ? adapterForRuntime(harness.runtime).serviceName(harness.name)
+        : undefined)
     if (!composeFile || !serviceName) return undefined
     return { composeFile, serviceName }
   }
@@ -1279,7 +1307,7 @@ export class HarnessService {
     if (!target) return null
     try {
       const compose = fs.readFileSync(target.composeFile, 'utf-8')
-      return readComposeImage(compose) ?? 'local-build'
+      return adapterForRuntime(harness.runtime).readImageRef(compose) ?? 'local-build'
     } catch {
       return null
     }
@@ -1301,7 +1329,10 @@ export class HarnessService {
     const harness = this.get(id)
     if (!harness) throw new Error(`Harness ${id} not found`)
     const current = this.currentImage(id)
-    const repo = current && current !== 'local-build' ? parseImageRef(current).repo : DEFAULT_IMAGE_REPO
+    const repo =
+      current && current !== 'local-build'
+        ? parseImageRef(current).repo
+        : adapterForRuntime(harness.runtime).defaultImageRepo
     const latestDigest = await registry.getDigest(repo, 'latest')
     const updateAvailable =
       !!latestDigest && (current === 'local-build' || (!!harness.lastKnownDigest && harness.lastKnownDigest !== latestDigest))
@@ -1327,7 +1358,10 @@ export class HarnessService {
     if (!harness || !target) throw new Error(`Harness ${id} not found`)
     if (!fs.existsSync(target.composeFile)) throw new Error(`Harness ${id} compose file not found at ${target.composeFile}`)
     const compose = fs.readFileSync(target.composeFile, 'utf-8')
-    fs.writeFileSync(target.composeFile, setComposeImage(compose, ref))
+    fs.writeFileSync(
+      target.composeFile,
+      adapterForRuntime(harness.runtime).setImageRef(compose, ref),
+    )
     const parsed = parseImageRef(ref)
     const digest = parsed.digest ?? (parsed.tag ? await registry.getDigest(parsed.repo, parsed.tag) : null)
     this.updateConfig(id, { pinnedImageRef: ref, lastKnownDigest: digest ?? harness.lastKnownDigest })
@@ -1420,6 +1454,10 @@ export class HarnessService {
       reservedPorts: overlays.map((h) => h.apiPort).filter((p): p is number => typeof p === 'number'),
     })
 
+    // Provision through the source's runtime adapter — a duplicate is the
+    // same kind of agent as its source (pre-seam rows default to Hermes).
+    const dupAdapter = adapterForRuntime(source.runtime)
+
     // Copy source data directory if it exists, else scaffold fresh
     if (fs.existsSync(sourceDataDir) && !fs.existsSync(newDataDir)) {
       // Deep copy using recursive dir copy
@@ -1455,7 +1493,7 @@ export class HarnessService {
       // persona/name. A duplicate is a new agent; persona is customized afterward.
       fs.writeFileSync(path.join(newDataDir, 'SOUL.md'), defaultSoulContent(newName), 'utf-8')
     } else if (!fs.existsSync(newDataDir)) {
-      await scaffoldAgentDir(newDataDir, newName, port)
+      await dupAdapter.scaffold(newDataDir, newName, port)
     }
 
     // Generate standalone compose for the duplicate
@@ -1464,7 +1502,7 @@ export class HarnessService {
     const composePath = path.join(agentComposeDir, 'docker-compose.yml')
     if (!fs.existsSync(composePath)) {
       assertPortAvailable(overlays, port, newId)
-      fs.writeFileSync(composePath, generateStandaloneCompose(newName, port, newDataDir, { imageOrBuild: resolveImageOrBuild(settings), defaultImage: settings?.defaultImage }), 'utf-8')
+      fs.writeFileSync(composePath, dupAdapter.generateCompose(newName, port, newDataDir, { imageOrBuild: resolveImageOrBuild(settings), defaultImage: settings?.defaultImage }), 'utf-8')
     }
 
     const duplicate: Partial<Harness> = {
@@ -1474,7 +1512,7 @@ export class HarnessService {
       channel: `:${port}`,
       apiPort: port,
       composeFile: composePath,
-      serviceName: `hermes-${newName}`,
+      serviceName: dupAdapter.serviceName(newName),
       parentId: sourceId,
       platform: undefined, // reset — no surfaces connected yet
     }
@@ -1579,9 +1617,13 @@ export class HarnessService {
     // Agent data directory (where .env, config.yaml, SOUL.md live)
     const agentDir = path.join(os.homedir(), `.hermes-${input.name}`)
 
+    // createOverlay provisions Hermes agents only — the Letta path branches at
+    // the deploy route (design §3c) and never reaches container provisioning.
+    const adapter = hermesAdapter
+
     // Scaffold agent data directory if it doesn't exist
     if (!fs.existsSync(agentDir)) {
-      await scaffoldAgentDir(agentDir, input.name, port)
+      await adapter.scaffold(agentDir, input.name, port)
     }
 
     // Git auth is provisioned by the agent runtime at container boot (a
@@ -1594,7 +1636,7 @@ export class HarnessService {
     const composePath = path.join(agentComposeDir, 'docker-compose.yml')
     if (!fs.existsSync(composePath)) {
       assertPortAvailable(overlays, port, id)
-      fs.writeFileSync(composePath, generateStandaloneCompose(input.name, port, agentDir, { imageOrBuild: resolveImageOrBuild(settings), defaultImage: settings?.defaultImage }), 'utf-8')
+      fs.writeFileSync(composePath, adapter.generateCompose(input.name, port, agentDir, { imageOrBuild: resolveImageOrBuild(settings), defaultImage: settings?.defaultImage }), 'utf-8')
     }
 
     const overlay: Partial<Harness> = {
@@ -1607,7 +1649,7 @@ export class HarnessService {
       models: input.models ?? ['claude-sonnet-4-5'],
       tools: input.tools ?? [],
       composeFile: composePath,
-      serviceName: `hermes-${input.name}`,
+      serviceName: adapter.serviceName(input.name),
     }
 
     overlays.push(overlay)
@@ -1767,7 +1809,7 @@ If this is your very first startup ever, introduce yourself briefly in your home
       fs.mkdirSync(agentComposeDir, { recursive: true })
       fs.writeFileSync(
         composePath,
-        generateStandaloneCompose(slug, port, workDir, { imageOrBuild: resolveImageOrBuild(settings), defaultImage: settings?.defaultImage }),
+        hermesAdapter.generateCompose(slug, port, workDir, { imageOrBuild: resolveImageOrBuild(settings), defaultImage: settings?.defaultImage }),
         'utf-8'
       )
       composeGenerated = true
@@ -1814,7 +1856,7 @@ If this is your very first startup ever, introduce yourself briefly in your home
     if (persona) patches.persona = persona
     if (tools.length > 0) patches.tools = tools
     patches.composeFile = composePath
-    patches.serviceName = `hermes-${slug}`
+    patches.serviceName = hermesAdapter.serviceName(slug)
     // Persist the port the compose actually publishes — createOverlay above
     // allocated its own throwaway port, so pin the authoritative one here (and
     // align the display channel) for the next allocation to reserve.
diff --git a/lib/services/runtime-adapter.ts b/lib/services/runtime-adapter.ts
index 000d25c..6c7db10 100644
--- a/lib/services/runtime-adapter.ts
+++ b/lib/services/runtime-adapter.ts
@@ -9,13 +9,11 @@
  * dispatches on a runtime adapter instead of branching on string prefixes —
  * making room for `claude-code-proxy`/`custom` later.
  *
- * SCOPE (slice 1): only the *discovery* surface is extracted — the fields
- * `discover()` reads off a live container. The remaining container methods the
- * full design lists (`generateCompose`, `scaffold`, `readImageRef`/
- * `setImageRef`, `serviceName`) stay inline in harness.ts / harness-compose.ts
- * for now; extracting them touches the Hermes *deploy* path and is deferred to
- * Phase 2 (see design §5). Adding a member here is additive — nothing calls a
- * method that doesn't exist yet.
+ * SCOPE (slice A1 / design Phase 2): the full container surface — discovery
+ * (slice 1) plus provisioning (`serviceName`, `generateCompose`, `scaffold`)
+ * and the CD image-ref rewrite (`readImageRef`/`setImageRef`,
+ * `defaultImageRepo`). The Hermes implementation delegates to the same module
+ * functions the call sites used inline, so extraction is behavior-preserving.
  *
  * NOTE: Letta agents do NOT go through this adapter. They are not containers;
  * they are enumerated from the Letta server over REST by the separate
@@ -24,6 +22,7 @@
  */
 
 import type { Harness } from '@/lib/types'
+import type { ComposeOptions } from './harness-compose'
 
 export interface ContainerRuntimeAdapter {
   /** The `runtime` value stamped on harnesses this adapter discovers. */
@@ -43,4 +42,26 @@ export interface ContainerRuntimeAdapter {
 
   /** Configured model handles read off the data dir. */
   readModels(dataDir: string): string[]
+
+  // --- Provisioning (Phase 2) ---
+
+  /** Compose service/container name for an agent name (Hermes: `hermes-<name>`). */
+  serviceName(name: string): string
+
+  /** Render the standalone compose file for a new agent of this runtime. */
+  generateCompose(name: string, port: number, dataDir: string, options?: ComposeOptions): string
+
+  /** Write the scaffold files for a brand-new agent data directory. */
+  scaffold(dataDir: string, name: string, port: number): Promise<void>
+
+  // --- CD image-ref rewrite (Phase 2) ---
+
+  /** The image ref the agent service in this compose currently runs, or null if it builds from source. */
+  readImageRef(compose: string): string | null
+
+  /** Rewrite the agent service's source block to `image: <ref>`, returning the new compose text. */
+  setImageRef(compose: string, ref: string): string
+
+  /** Registry repo the CD path resolves `:latest` against when no pin exists. */
+  defaultImageRepo: string
 }