@desplega.ai/agent-swarm 1.75.0 → 1.76.0

package/src/hooks/hook.ts

@@ -4,13 +4,13 @@ import pkg from "../../package.json";
 import {
   buildRatingsFromLlm,
   buildSummaryWithRatingsPrompt,
-  extractSummaryFromClaudeStdout,
+  dedupeRetrievalsForRater,
   fetchRetrievalsForTask,
   isLlmRaterEnabled,
-  parseSummaryWithRatings,
   postRatings,
   type RetrievalRow,
 } from "../be/memory/raters/llm";
+import { runMemoryRater } from "../be/memory/raters/llm-summarizer";
 import type { Agent } from "../types";
 import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
 
@@ -205,6 +205,32 @@ async function restoreClaudeMdBackup(): Promise<void> {
   }
 }
 
+/**
+ * Resolve task context for the Stop-hook session-summary / memory-rater
+ * piggyback. Prefers the AGENT_SWARM_TASK_ID env var (set by the harness in
+ * `claude-adapter.ts`) so the rater still works when the on-disk TASK_FILE
+ * was already cleaned up — the silent-drop bug PR #444 traced.
+ */
+export async function resolveStopHookTaskContext(
+  env: Record<string, string | undefined> = process.env,
+): Promise<{ taskContext: string; taskId: string | undefined }> {
+  let taskContext = "";
+  let taskId: string | undefined = env.AGENT_SWARM_TASK_ID || undefined;
+  const taskFile = env.TASK_FILE;
+  if (taskFile) {
+    try {
+      const taskData = JSON.parse(await Bun.file(taskFile).text());
+      taskContext = `Task: ${taskData.task || "Unknown"}`;
+      if (!taskId) taskId = taskData.id;
+    } catch (err) {
+      // Don't blackhole the read failure — log it once so future regressions
+      // are visible. Same one-line debug pattern as PR #444's gate trace.
+      console.error("[memory-rater:llm] TASK_FILE read failed:", (err as Error).message);
+    }
+  }
+  return { taskContext, taskId };
+}
+
 /**
  * Main hook handler - processes Claude Code hook events
  */
@@ -1053,9 +1079,19 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
         }
       }
 
-      // Session summarization via Claude Haiku
-      // Skip if this is a child session spawned by the summarization itself (prevents recursion)
-      if (agentInfo?.id && msg.transcript_path && !process.env.SKIP_SESSION_SUMMARY) {
+      // Session summarization + LLM rater piggyback via OpenRouter (Vercel AI SDK).
+      //
+      // No-op when OPENROUTER_API_KEY is unset — self-hosters / OSS users
+      // without OpenRouter skip session summary + LLM ratings entirely. The
+      // previous `claude -p` path silently produced "Not logged in · Please
+      // run /login" rows after the 2026-05-05 CLAUDE_CODE_VERSION bump
+      // stopped propagating CLAUDE_CODE_OAUTH_TOKEN to hook subprocesses.
+      if (
+        agentInfo?.id &&
+        msg.transcript_path &&
+        !process.env.SKIP_SESSION_SUMMARY &&
+        process.env.OPENROUTER_API_KEY
+      ) {
         try {
           let transcript = "";
           try {
@@ -1067,19 +1103,10 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
           }
 
           if (transcript.length > 100) {
-            // Read task context if available
-            let taskContext = "";
-            let taskId: string | undefined;
-            const taskFile = process.env.TASK_FILE;
-            if (taskFile) {
-              try {
-                const taskData = JSON.parse(await Bun.file(taskFile).text());
-                taskContext = `Task: ${taskData.task || "Unknown"}`;
-                taskId = taskData.id;
-              } catch {
-                /* no task file */
-              }
-            }
+            // Prefer AGENT_SWARM_TASK_ID env var; fall back to TASK_FILE on
+            // disk. PR #444 gate-trace showed the file disappears mid-session
+            // and the silent catch dropped every LLM rater piggyback.
+            const { taskContext, taskId } = await resolveStopHookTaskContext();
 
             const apiUrl =
               process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
@@ -1091,15 +1118,17 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
             const llmRaterEnabled = isLlmRaterEnabled();
             let retrievals: RetrievalRow[] = [];
             if (llmRaterEnabled && taskId) {
-              retrievals = await fetchRetrievalsForTask({
+              const rawRetrievals = await fetchRetrievalsForTask({
                 apiUrl,
                 apiKey,
                 agentId: agentInfo.id,
                 taskId,
               });
+              // Dedup self-similar cron-task memories before sending to the
+              // rater — see `dedupeRetrievalsForRater` doc for the why.
+              retrievals = dedupeRetrievalsForRater(rawRetrievals);
             }
 
-            // Summarize with Claude Haiku — extract only high-value learnings
             const baseSummarizePrompt = `You are summarizing an AI agent's work session. Extract ONLY high-value learnings.
 
 DO NOT include:
@@ -1119,85 +1148,76 @@ ${taskContext ? `\nTask context: ${taskContext}` : ""}
 Transcript:
 ${transcript}`;
 
-            const wantsRatings = llmRaterEnabled && retrievals.length > 0;
-            const summarizePrompt = wantsRatings
-              ? buildSummaryWithRatingsPrompt(baseSummarizePrompt, retrievals)
-              : baseSummarizePrompt;
-
-            const tmpFile = `/tmp/session-summary-${Date.now()}.txt`;
-            await Bun.write(tmpFile, summarizePrompt);
-            const proc = Bun.spawn(
-              ["bash", "-c", `cat "${tmpFile}" | claude -p --model haiku --output-format json`],
-              {
-                stdout: "pipe",
-                stderr: "pipe",
-                env: { ...process.env, SKIP_SESSION_SUMMARY: "1" },
-              },
-            );
-            const timeoutId = setTimeout(() => proc.kill(), 30000);
-            const result = { stdout: await new Response(proc.stdout).text() };
-            clearTimeout(timeoutId);
-            await Bun.$`rm -f ${tmpFile}`.quiet();
-
-            let summary: string;
-            let parsedRatings: ReturnType<typeof parseSummaryWithRatings> = null;
-            if (wantsRatings) {
-              parsedRatings = parseSummaryWithRatings(result.stdout);
-            }
-            if (parsedRatings) {
-              summary = parsedRatings.summary;
-            } else {
-              // Fallback: never index raw JSON. extractSummaryFromClaudeStdout
-              // pulls the `summary` field out of a structured-output payload
-              // whose ratings failed schema validation; otherwise behaves
-              // like the previous unstructured envelope.result extraction.
-              summary = extractSummaryFromClaudeStdout(result.stdout);
-            }
+            // Always ask for the structured (summary + ratings) payload — same
+            // cost as the unstructured path. Empty retrievals → empty memory
+            // block → ratings: []; the postRatings gate below still skips the
+            // POST when there's nothing to send.
+            const summarizePrompt = buildSummaryWithRatingsPrompt(baseSummarizePrompt, retrievals);
 
-            // Skip indexing if the session had no significant learnings
-            if (
-              summary &&
-              summary.length > 20 &&
-              !summary.trim().toLowerCase().includes("no significant learnings")
-            ) {
-              await fetch(`${apiUrl}/api/memory/index`, {
-                method: "POST",
-                headers: {
-                  "Content-Type": "application/json",
-                  ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
-                  "X-Agent-ID": agentInfo.id,
-                },
-                body: JSON.stringify({
-                  agentId: agentInfo.id,
-                  content: summary,
-                  name: taskContext
-                    ? `Session: ${taskContext.slice(0, 80)}`
-                    : `Session: ${new Date().toISOString().slice(0, 16)}`,
-                  scope: "agent",
-                  source: "session_summary",
-                  ...(taskId ? { sourceTaskId: taskId } : {}),
-                }),
+            const raterResult = await runMemoryRater({
+              prompt: summarizePrompt,
+              apiKey: process.env.OPENROUTER_API_KEY,
+            });
+            if (!raterResult.ok) {
+              console.error("[memory-rater:llm] runMemoryRater returned non-ok", {
+                reason: raterResult.reason,
+                ...(raterResult.status !== undefined ? { status: raterResult.status } : {}),
               });
-            }
-
-            // Best-effort: post LLM ratings. Never blocks summary indexing.
-            if (parsedRatings && parsedRatings.ratings.length > 0) {
-              try {
-                const events = buildRatingsFromLlm(parsedRatings.ratings, retrievals);
-                if (events.length > 0) {
-                  await postRatings({
-                    apiUrl,
-                    apiKey,
+            } else {
+              const summary = raterResult.data.summary;
+              const ratings = raterResult.data.ratings;
+
+              // Skip indexing if the session had no significant learnings
+              if (
+                summary &&
+                summary.length > 20 &&
+                !summary.trim().toLowerCase().includes("no significant learnings")
+              ) {
+                await fetch(`${apiUrl}/api/memory/index`, {
+                  method: "POST",
+                  headers: {
+                    "Content-Type": "application/json",
+                    ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}),
+                    "X-Agent-ID": agentInfo.id,
+                  },
+                  body: JSON.stringify({
                     agentId: agentInfo.id,
-                    taskId,
-                    events,
-                  });
+                    content: summary,
+                    name: taskContext
+                      ? `Session: ${taskContext.slice(0, 80)}`
+                      : `Session: ${new Date().toISOString().slice(0, 16)}`,
+                    scope: "agent",
+                    source: "session_summary",
+                    ...(taskId ? { sourceTaskId: taskId } : {}),
+                  }),
+                });
+              }
+
+              // Best-effort: post LLM ratings. Never blocks summary indexing.
+              if (llmRaterEnabled && taskId && retrievals.length > 0 && ratings.length === 0) {
+                console.error("[memory-rater:llm] piggyback produced no ratings", {
+                  retrievalsLen: retrievals.length,
+                  ratingsLen: 0,
+                });
+              }
+              if (llmRaterEnabled && taskId && ratings.length > 0) {
+                try {
+                  const events = buildRatingsFromLlm(ratings, retrievals);
+                  if (events.length > 0) {
+                    await postRatings({
+                      apiUrl,
+                      apiKey,
+                      agentId: agentInfo.id,
+                      taskId,
+                      events,
+                    });
+                  }
+                } catch (err) {
+                  console.error(
+                    "[memory-rater:llm] piggyback rating emission failed:",
+                    (err as Error).message,
+                  );
                 }
-              } catch (err) {
-                console.error(
-                  "[memory-rater:llm] piggyback rating emission failed:",
-                  (err as Error).message,
-                );
               }
             }
           }

package/src/http/agents.ts

@@ -10,15 +10,18 @@ import {
   getDb,
   getSwarmConfigs,
   resetEmptyPollCount,
+  setAgentHarnessProvider,
   updateAgentActivity,
   updateAgentCredentialState,
+  updateAgentCredStatus,
   updateAgentMaxTasks,
   updateAgentName,
   updateAgentProfile,
   updateAgentProvider,
   updateAgentStatus,
+  upsertSwarmConfig,
 } from "../be/db";
-import { ProviderNameSchema } from "../types";
+import { AgentCredStatusSchema, ProviderNameSchema } from "../types";
 import { route } from "./route-def";
 import { agentWithCapacity, json, jsonError } from "./utils";
 
@@ -38,6 +41,12 @@ const registerAgent = route({
     capabilities: z.array(z.string()).optional(),
     maxTasks: z.number().int().optional(),
     provider: ProviderNameSchema.optional(),
+    /**
+     * Phase 1.5 (cloud-personalization): worker-pushed canonical harness
+     * provider. Persists to `agents.harness_provider`. Validated against
+     * the canonical list — unknown values reject the request with 400.
+     */
+    harness_provider: ProviderNameSchema.optional(),
   }),
   responses: {
     200: { description: "Agent re-registered (already existed)" },
@@ -46,6 +55,25 @@ const registerAgent = route({
   },
 });
 
+const setAgentHarnessProviderRoute = route({
+  method: "patch",
+  path: "/api/agents/{id}/harness-provider",
+  pattern: ["api", "agents", null, "harness-provider"],
+  summary: "Re-assign an agent's harness_provider (live)",
+  description:
+    "Updates `agents.harness_provider` and upserts `swarm_config` (scope=agent, key=HARNESS_PROVIDER) so the worker's poll-loop reconciliation picks up the new provider within ~10s. No restart required. The swarm_config row is what actually drives the worker; the column mirrors the latest set value for dashboards.",
+  tags: ["Agents"],
+  params: z.object({ id: z.string() }),
+  body: z.object({
+    harness_provider: ProviderNameSchema,
+  }),
+  responses: {
+    200: { description: "Updated agent row" },
+    400: { description: "Validation error (unknown provider)" },
+    404: { description: "Agent not found" },
+  },
+});
+
 const listAgents = route({
   method: "get",
   path: "/api/agents",
@@ -150,6 +178,13 @@ const credentialStatusBody = z.object({
   ready: z.boolean(),
   /** Env-var names (or absolute file paths) the worker is blocked on. Empty/null when ready. */
   missing: z.array(z.string()).optional().nullable(),
+  /**
+   * Migration 055: full credential snapshot (presence + live test). Optional
+   * for backward compat — older workers may only POST `{ready, missing}`.
+   * When present, written to `agents.cred_status` as JSON; the dashboard
+   * reads the row instead of running its own check.
+   */
+  cred_status: AgentCredStatusSchema.optional().nullable(),
 });
 
 const updateAgentCredentialStatusRoute = route({
@@ -219,6 +254,17 @@ export async function handleAgentRegister(
         if (parsed.body.provider && parsed.body.provider !== existingAgent.provider) {
           updateAgentProvider(existingAgent.id, parsed.body.provider);
         }
+        // Phase 1.5: worker-pushed harness_provider always wins on
+        // re-registration. Env-driven, by design (per-agent live override
+        // belongs to DES-359). NULL => leave existing column untouched
+        // so PATCH /harness-provider doesn't get clobbered by re-register
+        // payloads from older workers.
+        if (
+          parsed.body.harness_provider &&
+          parsed.body.harness_provider !== existingAgent.harnessProvider
+        ) {
+          setAgentHarnessProvider(existingAgent.id, parsed.body.harness_provider);
+        }
         resetEmptyPollCount(existingAgent.id);
         return { agent: getAgentById(agentId), created: false };
       }
@@ -233,6 +279,7 @@ export async function handleAgentRegister(
         capabilities: parsed.body.capabilities ?? [],
         maxTasks: parsed.body.maxTasks ?? 1,
         provider: parsed.body.provider,
+        harnessProvider: parsed.body.harness_provider ?? null,
       });
 
       return { agent, created: true };
@@ -399,6 +446,28 @@ export async function handleAgentsRest(
     return true;
   }
 
+  if (setAgentHarnessProviderRoute.match(req.method, pathSegments)) {
+    const parsed = await setAgentHarnessProviderRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const agent = setAgentHarnessProvider(parsed.params.id, parsed.body.harness_provider);
+    if (!agent) {
+      jsonError(res, "Agent not found", 404);
+      return true;
+    }
+    // Mirror to swarm_config (scope=agent) so the worker's reconciliation
+    // loop actually reads the new value. The column above is for dashboard
+    // visibility; this row is the live override.
+    upsertSwarmConfig({
+      scope: "agent",
+      scopeId: parsed.params.id,
+      key: "HARNESS_PROVIDER",
+      value: parsed.body.harness_provider,
+      description: "Set via PATCH /api/agents/{id}/harness-provider",
+    });
+    json(res, agentWithCapacity(agent));
+    return true;
+  }
+
   // Bulk credential-status MUST be matched BEFORE single-agent routes — the
   // path "api/agents/credential-status" otherwise looks like an agent id.
   if (listCredentialStatusRoute.match(req.method, pathSegments)) {
@@ -413,6 +482,8 @@ export async function handleAgentsRest(
         status: a.status,
         missing: a.credentialMissing ?? [],
         provider: a.provider ?? null,
+        harnessProvider: a.harnessProvider ?? null,
+        credStatus: a.credStatus ?? null,
         lastCheckedAt: a.lastUpdatedAt,
       }));
     json(res, { agents });
@@ -436,7 +507,14 @@ export async function handleAgentsRest(
       jsonError(res, "Agent not found", 404);
       return true;
     }
-    json(res, agentWithCapacity(agent));
+    // Phase 055: persist the richer worker-reported snapshot when sent.
+    // We accept `null` to explicitly clear (e.g. on harness change), and
+    // `undefined` to leave the existing row value untouched.
+    const finalAgent =
+      parsed.body.cred_status !== undefined
+        ? (updateAgentCredStatus(parsed.params.id, parsed.body.cred_status ?? null) ?? agent)
+        : agent;
+    json(res, agentWithCapacity(finalAgent));
     return true;
   }
 
@@ -454,6 +532,8 @@ export async function handleAgentsRest(
       status: agent.status,
       missing: agent.credentialMissing ?? [],
       provider: agent.provider ?? null,
+      harnessProvider: agent.harnessProvider ?? null,
+      credStatus: agent.credStatus ?? null,
       lastCheckedAt: agent.lastUpdatedAt,
     });
     return true;

package/src/http/config.ts

@@ -9,7 +9,11 @@ import {
   maskSecrets,
   upsertSwarmConfig,
 } from "../be/db";
-import { isReservedConfigKey, reservedKeyError } from "../be/swarm-config-guard";
+import {
+  isReservedConfigKey,
+  reservedKeyError,
+  validateConfigValue,
+} from "../be/swarm-config-guard";
 import { reloadGlobalConfigsAndIntegrations } from "./core";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
@@ -230,6 +234,12 @@ export async function handleConfig(
       return true;
     }
 
+    const validationError = validateConfigValue(key, value);
+    if (validationError) {
+      jsonError(res, validationError, 400);
+      return true;
+    }
+
     try {
       const includeSecrets = queryParams.get("includeSecrets") === "true";
       const config = upsertSwarmConfig({

package/src/http/inbox-state.ts

@@ -0,0 +1,89 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { listInboxState, upsertInboxState } from "../be/db";
+import { InboxItemStatusSchema, InboxItemTypeSchema } from "../types";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const listState = route({
+  method: "get",
+  path: "/api/inbox-state",
+  pattern: ["api", "inbox-state"],
+  summary: "List inbox-item state rows for a user",
+  tags: ["Inbox State"],
+  query: z.object({
+    userId: z.string(),
+    status: InboxItemStatusSchema.optional(),
+    itemType: InboxItemTypeSchema.optional(),
+  }),
+  responses: {
+    200: { description: "Inbox state rows" },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
+const upsertState = route({
+  method: "patch",
+  path: "/api/inbox-state",
+  pattern: ["api", "inbox-state"],
+  summary: "Upsert per-user dismiss/snooze/done state for an inbox item",
+  tags: ["Inbox State"],
+  body: z.object({
+    userId: z.string(),
+    itemType: InboxItemTypeSchema,
+    itemId: z.string().min(1),
+    status: InboxItemStatusSchema,
+    snoozeUntil: z.string().datetime().optional(),
+  }),
+  responses: {
+    200: { description: "Upserted inbox state row" },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleInboxState(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listState.match(req.method, pathSegments)) {
+    const parsed = await listState.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const items = listInboxState({
+      userId: parsed.query.userId,
+      status: parsed.query.status,
+      itemType: parsed.query.itemType,
+    });
+    json(res, { items });
+    return true;
+  }
+
+  if (upsertState.match(req.method, pathSegments)) {
+    const parsed = await upsertState.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    try {
+      const item = upsertInboxState({
+        userId: parsed.body.userId,
+        itemType: parsed.body.itemType,
+        itemId: parsed.body.itemId,
+        status: parsed.body.status,
+        snoozeUntil: parsed.body.snoozeUntil,
+      });
+      json(res, { item });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to upsert inbox state", 500);
+    }
+    return true;
+  }
+
+  return false;
+}

package/src/http/index.ts

@@ -29,6 +29,7 @@ import { handleDbQuery } from "./db-query";
 import { handleEcosystem } from "./ecosystem";
 import { handleEvents } from "./events";
 import { handleHeartbeat } from "./heartbeat";
+import { handleInboxState } from "./inbox-state";
 import { handleIntegrations } from "./integrations";
 import { handleMcp } from "./mcp";
 import { handleMcpOAuth, startMcpOAuthPendingGc, stopMcpOAuthPendingGc } from "./mcp-oauth";
@@ -40,10 +41,14 @@ import { handlePromptTemplates } from "./prompt-templates";
 import { handleRepos } from "./repos";
 import { handleSchedules } from "./schedules";
 import { handleSessionData } from "./session-data";
+import { handleSessions } from "./sessions";
 import { handleSkills } from "./skills";
 import { handleStats } from "./stats";
+import { handleStatus } from "./status";
+import { handleTaskTemplates } from "./task-templates";
 import { handleTasks } from "./tasks";
 import { handleTrackers } from "./trackers";
+import { handleUsers } from "./users";
 import { getPathSegments, parseQueryParams, setCorsHeaders } from "./utils";
 import { handleWebhooks } from "./webhooks";
 import { handleWorkflowEvents } from "./workflow-events";
@@ -126,6 +131,7 @@ const httpServer = createHttpServer(async (req, res) => {
     () => handleContext(req, res, pathSegments, queryParams, myAgentId),
     () => handleTasks(req, res, pathSegments, queryParams, myAgentId),
     () => handleStats(req, res, pathSegments, queryParams),
+    () => handleStatus(req, res, pathSegments, queryParams),
     () => handleActiveSessions(req, res, pathSegments, queryParams, myAgentId),
     () => handlePricing(req, res, pathSegments, queryParams, myAgentId),
     () => handleSchedules(req, res, pathSegments, queryParams, myAgentId),
@@ -144,6 +150,10 @@ const httpServer = createHttpServer(async (req, res) => {
     () => handleApiKeys(req, res, pathSegments, queryParams),
     () => handleHeartbeat(req, res, pathSegments),
     () => handleEvents(req, res, pathSegments, queryParams, myAgentId),
+    () => handleUsers(req, res, pathSegments, queryParams),
+    () => handleSessions(req, res, pathSegments, queryParams),
+    () => handleInboxState(req, res, pathSegments, queryParams),
+    () => handleTaskTemplates(req, res, pathSegments, queryParams),
     () => handleMcp(req, res, transports),
   ];
 

package/src/http/sessions.ts

@@ -0,0 +1,86 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { getRootTaskChain, getTaskById, listRecentSessions } from "../be/db";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const listSessions = route({
+  method: "get",
+  path: "/api/sessions",
+  pattern: ["api", "sessions"],
+  summary: "List recent task sessions (root tasks + chain summary)",
+  tags: ["Sessions"],
+  query: z.object({
+    limit: z.coerce.number().int().optional(),
+    offset: z.coerce.number().int().optional(),
+    /** Comma-separated source filter (e.g. `ui,slack`). Omit to include all. */
+    source: z.string().optional(),
+    /** Case-insensitive substring match against the root task's text. */
+    q: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Recent sessions ordered by chain-wide last activity" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
+const getSession = route({
+  method: "get",
+  path: "/api/sessions/{rootTaskId}",
+  pattern: ["api", "sessions", null],
+  summary: "Get a session — root task + the entire descendant chain",
+  tags: ["Sessions"],
+  params: z.object({ rootTaskId: z.string() }),
+  responses: {
+    200: { description: "Root task + chain (ordered by createdAt)" },
+    401: { description: "Unauthorized" },
+    404: { description: "Root task not found" },
+  },
+  auth: { apiKey: true },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleSessions(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listSessions.match(req.method, pathSegments)) {
+    const parsed = await listSessions.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const sources = parsed.query.source
+      ? parsed.query.source
+          .split(",")
+          .map((s) => s.trim())
+          .filter(Boolean)
+      : undefined;
+    const sessions = listRecentSessions({
+      limit: parsed.query.limit,
+      offset: parsed.query.offset,
+      source: sources,
+      q: parsed.query.q,
+    });
+    json(res, { sessions });
+    return true;
+  }
+
+  if (getSession.match(req.method, pathSegments)) {
+    const parsed = await getSession.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const root = getTaskById(parsed.params.rootTaskId);
+    if (!root) {
+      jsonError(res, "Root task not found", 404);
+      return true;
+    }
+    const chain = getRootTaskChain(parsed.params.rootTaskId);
+    json(res, { root, chain });
+    return true;
+  }
+
+  return false;
+}