agent-relay-server 0.40.0 → 0.41.0

package/runner/src/adapter.ts

@@ -136,7 +136,8 @@ export interface ProviderAdapter {
   provider: string;
   spawn(config: RunnerSpawnConfig): Promise<ManagedProcess>;
   shutdown(process: ManagedProcess, opts: { graceful: boolean; timeoutMs: number }): Promise<void>;
-  compact?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  compact?(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown> | void>;
+  compactSupportsInstructions?: boolean;
   clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
   // Normalize the session so far into the provider-agnostic SessionEvent stream the
   // Insights context-ratio signal (#183/#184) reduces. Called by the runner's
@@ -147,6 +148,10 @@ export interface ProviderAdapter {
   // ignore it and return their accumulated log. Return null when there is nothing to
   // measure. Best-effort: may be omitted by providers without a session view yet.
   collectSessionEvents?(process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<SessionEvent[] | null>;
+  // Full searchable transcript/archive source for destructive boundaries. The runner
+  // slices the returned stream by cursor, so adapters should return the session-so-far
+  // view when they have one.
+  collectSessionArchiveSegment?(process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<string | null>;
   // Interrupt the in-flight turn without ending the session (ESC for Claude's
   // tmux pane, turn/interrupt for the Codex app-server). Provider-independent at
   // the runner boundary; each adapter does what its provider actually supports.
@@ -185,7 +190,7 @@ export function profileAllowsRelayFeature(config: RunnerSpawnConfig, feature: ke
   return config.agentProfile?.relay?.[feature] !== false;
 }
 
-export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
+export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a real-time message bus between agents and users. When you receive a relay message: read it, do what it asks, and reply through the relay when a text response is needed. Use agent-relay /react <messageId> <emoji> for lightweight acknowledgement or approval. If Relay MCP tools are available, prefer relay_reply, relay_get_message, relay_get_thread, relay_send_message, relay_upload_artifact, relay_attach_artifact, relay_agent_status, relay_find_agents, relay_compact_and_resume, relay_recall, relay_spawn_agent, and relay_shutdown_agent. You never need to know or pass your own agent id — relay fills it from your token; use relay_whoami only if you need to reason about yourself. relay_compact_and_resume is for clean-seam self-resume after a context advisory: pass workingState and optional ruledOut; Relay owns the objective envelope. relay_recall searches your own archived pre-compaction segments by keyword when a discarded detail is needed. relay_spawn_targets / relay_spawn_agent / relay_shutdown_agent only appear if your profile grants spawning (a live-children quota); when present, call relay_spawn_targets FIRST for the live host/provider/model matrix + your quota, then stand up long-living child agents and shut down your own — find them later with relay_find_agents spawnedBy:me. CLI fallback: agent-relay /reply <messageId> --stdin < response.md; if a delivered message says it was truncated, fetch the full body with: agent-relay get-message <messageId>. For command details, run: agent-relay /guide`;
 
 // #306 — deliver the FULL message body by default. Only a pathological body beyond this
 // high cap truncates (with a get-message hint) so it can't nuke an agent's context; the 99%

package/src/bus.ts

@@ -12,6 +12,7 @@ import { commandAuthorizationResource, dispatchCommand } from "./services/dispat
 import { ServiceAuthError } from "./services/errors";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent, shutdownInputFromBusFrame } from "./services/shutdown-agent";
 import { applyCommandToRecipe } from "./recipe-runner";
+import { enqueueContinuationInjectionAfterClear } from "./self-resume";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
 import {
   BusProtocolError,
@@ -219,6 +220,7 @@ function handleCommandFrame(
       // Production command completions arrive here over the bus, not the HTTP
       // PATCH route — arm the stall watch for finished compact/clear commands.
       noteCompactionCommandCompleted(updated.type, updated.status, updated.id, updated.target);
+      enqueueContinuationInjectionAfterClear(updated);
     }
     sendCommandResult(ws, frameId, "succeeded", updated ? { command: updated } : undefined);
     return;

package/src/config-store.ts

@@ -1,5 +1,7 @@
 import { getDb, ValidationError } from "./db";
 import { cleanEnum, cleanString, cleanStringArray } from "./validation";
+import { DEFAULT_CONTEXT_THRESHOLD_CONFIG, validateContextThresholdConfig } from "./context-threshold-config";
+import { DEFAULT_SELF_RESUME_CONFIG, validateSelfResumeConfig } from "./self-resume-config";
 import { resolveProviderSelection, type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, VALID_EFFORTS, VALID_WORKSPACE_MODES } from "agent-relay-sdk";
 import type {
@@ -12,6 +14,7 @@ import type {
   ManagedAgentState,
   ManagedAgentStatus,
   NotificationsConfig,
+  SelfResumeConfig,
   SpawnApprovalMode,
   SpawnPolicy,
   SpawnProvider,
@@ -29,6 +32,8 @@ const INSIGHTS_NAMESPACE = "insights";
 const INSIGHTS_KEY = "default";
 const NOTIFICATIONS_NAMESPACE = "notifications";
 const NOTIFICATIONS_KEY = "default";
+const SELF_RESUME_NAMESPACE = "self-resume";
+const SELF_RESUME_KEY = "default";
 const WORKSPACE_NAMESPACE = "workspace";
 const WORKSPACE_KEY = "default";
 const LANDING_NAMESPACE = "landing";
@@ -475,17 +480,11 @@ function validateInsightsConfig(value: unknown): InsightsConfig {
 // Relay-driven lifecycle push notifications (#239 event bus). Default-on; the
 // operator can flip the master switch or individual events off via the generic
 // config route. Push messages wake recipients, so they must be suppressible.
-const NOTIFICATIONS_CONFIG_DEFAULTS: NotificationsConfig = {
-  enabled: true,
-  branchLanded: true,
-  agentReady: true,
-  agentExited: true,
-  agentSpawnFailed: true,
-};
+const NOTIFICATIONS_CONFIG_DEFAULTS: NotificationsConfig = { enabled: true, branchLanded: true, agentReady: true, agentExited: true, agentSpawnFailed: true, contextThreshold: DEFAULT_CONTEXT_THRESHOLD_CONFIG };
 
 function validateNotificationsConfig(value: unknown): NotificationsConfig {
   if (!isRecord(value)) throw new ValidationError("notifications config value must be an object");
-  const bool = (key: keyof NotificationsConfig): boolean =>
+  const bool = (key: "enabled" | "branchLanded" | "agentReady" | "agentExited" | "agentSpawnFailed"): boolean =>
     value[key] === undefined ? NOTIFICATIONS_CONFIG_DEFAULTS[key] : cleanBoolean(value[key], key);
   return {
     enabled: bool("enabled"),
@@ -493,6 +492,7 @@ function validateNotificationsConfig(value: unknown): NotificationsConfig {
     agentReady: bool("agentReady"),
     agentExited: bool("agentExited"),
     agentSpawnFailed: bool("agentSpawnFailed"),
+    contextThreshold: validateContextThresholdConfig(value.contextThreshold),
   };
 }
 
@@ -537,6 +537,7 @@ function normalizeValue(namespace: string, key: string, value: unknown): unknown
   if (namespace === STEWARD_NAMESPACE) return validateStewardConfig(value);
   if (namespace === INSIGHTS_NAMESPACE) return validateInsightsConfig(value);
   if (namespace === NOTIFICATIONS_NAMESPACE) return validateNotificationsConfig(value);
+  if (namespace === SELF_RESUME_NAMESPACE) return validateSelfResumeConfig(value);
   if (namespace === WORKSPACE_NAMESPACE) return validateWorkspaceConfig(value);
   if (namespace === LANDING_NAMESPACE) return validateLandingConfig(value);
   if (JSON.stringify(value) === undefined) throw new ValidationError("value must be valid JSON");
@@ -682,6 +683,17 @@ export function setInsightsConfig(value: unknown, updatedBy?: string): ConfigEnt
   return setConfig(INSIGHTS_NAMESPACE, INSIGHTS_KEY, value as InsightsConfig, updatedBy);
 }
 
+/** Relay-owned self-resume defaults (#316), merged over defaults (always usable). */
+export function getSelfResumeConfig(): SelfResumeConfig {
+  const entry = getConfig<Partial<SelfResumeConfig>>(SELF_RESUME_NAMESPACE, SELF_RESUME_KEY);
+  if (!entry) return { ...DEFAULT_SELF_RESUME_CONFIG, budget: { ...DEFAULT_SELF_RESUME_CONFIG.budget } };
+  return validateSelfResumeConfig({
+    ...DEFAULT_SELF_RESUME_CONFIG,
+    ...entry.value,
+    budget: { ...DEFAULT_SELF_RESUME_CONFIG.budget, ...(entry.value.budget ?? {}) },
+  });
+}
+
 /** Global workspace config, merged over defaults (always returns a usable value). */
 export function getWorkspaceConfig(): WorkspaceConfig {
   const entry = getConfig<Partial<WorkspaceConfig>>(WORKSPACE_NAMESPACE, WORKSPACE_KEY);

package/src/context-advisory.ts

@@ -0,0 +1,110 @@
+import { getNotificationsConfig } from "./config-store";
+import { getDb } from "./db/connection.ts";
+import { emitRelayEvent } from "./events";
+import { notifySystemMessage } from "./notify";
+import type { AgentCard, Command, ContextState } from "./types";
+
+interface ContextAdvisoryInput {
+  agentId: string;
+  tokens: number;
+  percent: number;
+  windowTokens: number;
+  band: number;
+  hardBackstopPercent: number;
+}
+
+/**
+ * #315 — context pressure is a relay-native signal: durable event for observers,
+ * plus an agent-facing system push when lifecycle notifications are enabled.
+ */
+function notifyContextAdvisory(input: ContextAdvisoryInput): void {
+  const payload = {
+    kind: "agent.context_threshold",
+    agentId: input.agentId,
+    tokens: input.tokens,
+    percent: input.percent,
+    windowTokens: input.windowTokens,
+    band: input.band,
+    hardBackstopPercent: input.hardBackstopPercent,
+  };
+
+  emitRelayEvent({
+    type: "agent.context_threshold",
+    source: "server",
+    subject: input.agentId,
+    data: payload,
+  });
+
+  const config = getNotificationsConfig();
+  if (!config.enabled || !config.contextThreshold.enabled) return;
+
+  notifySystemMessage(input.agentId, {
+    subject: "Context threshold reached",
+    body: `Context advisory: ${formatTokens(input.tokens)} / ${formatTokens(input.windowTokens)} tokens used (${input.percent}% of window, ${input.band}% band). Compact at a clean seam before the ${input.hardBackstopPercent}% hard backstop may request compaction.`,
+    payload,
+    replyExpected: false,
+  });
+}
+
+function contextAdvisoryBand(utilization: number, advisoryUtilization: number, bandSize: number): number | null {
+  if (!Number.isFinite(utilization) || utilization < advisoryUtilization) return null;
+  const percent = Math.min(100, Math.max(0, utilization * 100));
+  const step = Math.max(1, bandSize * 100);
+  return Math.min(100, Math.floor(percent / step) * step);
+}
+
+export function handleContextPressure(input: {
+  agent: AgentCard;
+  now: () => number;
+  hasActiveCommand: (target: string, type: string) => boolean;
+  compact: (reason: string) => Command | null;
+}): boolean {
+  const { agent, now } = input;
+  const context = agent.context;
+  if (!context || agent.status === "busy") return false;
+  if (context.lifecycleState === "compacting" || context.lifecycleState === "hibernating") return false;
+  if (typeof context.utilization !== "number" || !Number.isFinite(context.utilization)) return false;
+  const threshold = getNotificationsConfig().contextThreshold;
+  const band = contextAdvisoryBand(context.utilization, threshold.advisoryUtilization, threshold.bandSize);
+  if (band === null) {
+    if (context.lastContextAdvisoryBand !== undefined || context.lastContextAdvisoryAt !== undefined) {
+      persistContextState(agent.id, clearContextAdvisory(context));
+    }
+    return false;
+  }
+  if (context.utilization >= threshold.hardBackstopUtilization && context.lastContextAdvisoryAt !== undefined && agent.providerCapabilities?.context?.compact === true && !input.hasActiveCommand(agent.id, "agent.compact")) {
+    input.compact("context-hard-backstop");
+    return true;
+  }
+  if (context.lastContextAdvisoryBand === band) return false;
+  const tokens = finiteNumber(context.tokensUsed);
+  const windowTokens = finiteNumber(context.tokensMax);
+  if (tokens === undefined || windowTokens === undefined) return false;
+  notifyContextAdvisory({
+    agentId: agent.id,
+    tokens,
+    percent: Math.round(context.utilization * 100),
+    windowTokens,
+    band,
+    hardBackstopPercent: Math.round(threshold.hardBackstopUtilization * 100),
+  });
+  persistContextState(agent.id, { ...context, lastContextAdvisoryBand: band, lastContextAdvisoryAt: now() });
+  return true;
+}
+
+function clearContextAdvisory(context: ContextState): ContextState {
+  const { lastContextAdvisoryBand: _band, lastContextAdvisoryAt: _at, ...rest } = context;
+  return rest;
+}
+
+function persistContextState(agentId: string, context: ContextState): void {
+  getDb().query("UPDATE agents SET context_state = ? WHERE id = ?").run(JSON.stringify(context), agentId);
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function formatTokens(value: number): string {
+  return Math.round(value).toLocaleString("en-US");
+}

package/src/context-threshold-config.ts

@@ -0,0 +1,40 @@
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "./db/connection.ts";
+import type { NotificationsConfig } from "./types";
+
+export const DEFAULT_CONTEXT_THRESHOLD_CONFIG: NotificationsConfig["contextThreshold"] = {
+  enabled: true,
+  advisoryUtilization: 0.7,
+  hardBackstopUtilization: 0.9,
+  bandSize: 0.1,
+};
+
+export function validateContextThresholdConfig(value: unknown): NotificationsConfig["contextThreshold"] {
+  const input = isRecord(value) ? value : {};
+  const bandSize = cleanFraction(input.bandSize, "contextThreshold.bandSize", DEFAULT_CONTEXT_THRESHOLD_CONFIG.bandSize);
+  if (bandSize <= 0) throw new ValidationError("contextThreshold.bandSize must be greater than 0");
+  const advisoryUtilization = cleanFraction(input.advisoryUtilization, "contextThreshold.advisoryUtilization", DEFAULT_CONTEXT_THRESHOLD_CONFIG.advisoryUtilization);
+  const hardBackstopUtilization = cleanFraction(input.hardBackstopUtilization, "contextThreshold.hardBackstopUtilization", DEFAULT_CONTEXT_THRESHOLD_CONFIG.hardBackstopUtilization);
+  if (hardBackstopUtilization <= advisoryUtilization) {
+    throw new ValidationError("contextThreshold.hardBackstopUtilization must be greater than contextThreshold.advisoryUtilization");
+  }
+  return {
+    enabled: input.enabled === undefined ? DEFAULT_CONTEXT_THRESHOLD_CONFIG.enabled : cleanBoolean(input.enabled, "contextThreshold.enabled"),
+    advisoryUtilization,
+    hardBackstopUtilization,
+    bandSize,
+  };
+}
+
+function cleanBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new ValidationError(`${field} must be a boolean`);
+  return value;
+}
+
+function cleanFraction(value: unknown, field: string, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+    throw new ValidationError(`${field} must be a number between 0 and 1`);
+  }
+  return value;
+}

package/src/db/agents.ts

@@ -15,11 +15,13 @@ import {
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
 import { matchAgents } from "../agent-ref";
 import { evaluatePoolBindings, expectedChannelAgentId, upsertChannelForAgent } from "./channels.ts";
+import { seedContinuationObjectiveFromSpawnPrompt } from "./continuations.ts";
 import { ValidationError, getDb } from "./connection.ts";
 import { rowToAgent, rowToContextSnapshot } from "./mappers.ts";
 import { closeOpenPairsForAgent } from "./pairs.ts";
 import { TASK_SELECT, insertTaskEvent } from "./tasks.ts";
 import { electWorkspaceStewards, electWorkspaceStewardsForAgent } from "./workspaces.ts";
+import { DEFAULT_SELF_RESUME_CONFIG } from "../self-resume-config";
 import type {
   AgentCard,
   ActivityEvent,
@@ -153,6 +155,7 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
   const labelProvided = Object.prototype.hasOwnProperty.call(input, "label");
   const readyProvided = Object.prototype.hasOwnProperty.call(input, "ready");
   const instanceProvided = Boolean(input.instanceId);
+  const contextState = mergeRelayContextMarkers(input.id, input.context);
   const stmt = getDb().query(`
     INSERT INTO agents (id, name, kind, label, tags, machine, rig, capabilities, ready, status, instance_id, epoch, provider_capabilities, context_state, meta, spawned_by, last_seen, created_at)
     VALUES ($id, $name, $kind, $label, $tags, $machine, $rig, $capabilities, $ready, $status, $instanceId, $initialEpoch, $providerCapabilities, $contextState, $meta, $spawnedBy, $now, $now)
@@ -195,14 +198,15 @@ export function upsertAgent(input: RegisterAgentInput): AgentCard {
     $instanceProvided: instanceProvided ? 1 : 0,
     $initialEpoch: instanceProvided ? 1 : 0,
     $providerCapabilities: input.providerCapabilities ? JSON.stringify(input.providerCapabilities) : null,
-    $contextState: input.context ? JSON.stringify(input.context) : null,
+    $contextState: contextState ? JSON.stringify(contextState) : null,
     $meta: JSON.stringify(input.meta ?? {}),
     $spawnedBy: input.spawnedBy ?? null,
     $now: now,
   });
-  if (input.context) recordContextSnapshot(input.id, input.context, now);
+  if (contextState) recordContextSnapshot(input.id, contextState, now);
 
   const agent = getAgent(input.id)!;
+  seedContinuationObjectiveFromSpawnPrompt(agent.id, stringValue(agent.meta?.spawnRequestId), DEFAULT_SELF_RESUME_CONFIG, now);
   if (agent.kind === "channel") upsertChannelForAgent(agent);
   evaluatePoolBindings();
   // A (re)joining agent may revive a dormant repo steward — re-elect for the
@@ -335,6 +339,7 @@ export function heartbeat(
   if (!validateAgentSession(id, guard).ok) return false;
   const now = Date.now();
   if (runtime?.providerCapabilities || runtime?.context) {
+    const contextState = mergeRelayContextMarkers(id, runtime.context);
     const result = getDb()
       .query(`
         UPDATE agents SET
@@ -347,10 +352,10 @@ export function heartbeat(
       .run(
         now,
         runtime.providerCapabilities ? JSON.stringify(runtime.providerCapabilities) : null,
-        runtime.context ? JSON.stringify(runtime.context) : null,
+        contextState ? JSON.stringify(contextState) : null,
         id,
       );
-    if (result.changes > 0 && runtime.context) recordContextSnapshot(id, runtime.context, now);
+    if (result.changes > 0 && contextState) recordContextSnapshot(id, contextState, now);
     return result.changes > 0;
   }
   const result = getDb()
@@ -412,6 +417,18 @@ export function recordContextSnapshot(agentId: string, context: ContextState, no
   pruneContextSnapshots(agentId, now - DAY_MS);
 }
 
+function mergeRelayContextMarkers(agentId: string, next: ContextState | undefined): ContextState | undefined {
+  if (!next) return undefined;
+  const row = getDb().query("SELECT context_state FROM agents WHERE id = ?").get(agentId) as { context_state?: string | null } | undefined;
+  const previous = row?.context_state ? parseJson<ContextState | undefined>(row.context_state, undefined) : undefined;
+  if (!previous) return next;
+  return {
+    ...next,
+    lastContextAdvisoryBand: next.lastContextAdvisoryBand ?? previous.lastContextAdvisoryBand,
+    lastContextAdvisoryAt: next.lastContextAdvisoryAt ?? previous.lastContextAdvisoryAt,
+  };
+}
+
 
 export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
   const now = Date.now();
@@ -548,4 +565,3 @@ export function runtimeTokenJtisFromMeta(meta: Record<string, unknown>): string[
 }
 
 // --- Tasks ---
-

package/src/db/continuation-archives.ts

@@ -0,0 +1,179 @@
+import { MAX_BODY_BYTES } from "../config";
+import { getContinuationEnvelope } from "./continuations.ts";
+import { getDb, ValidationError } from "./connection.ts";
+
+export interface ContinuationArchive {
+  id: number;
+  ref: string;
+  agentId: string;
+  generation: number;
+  segment: string;
+  createdAt: number;
+}
+
+export interface ContinuationArchiveSearchResult extends ContinuationArchive {
+  score: number | null;
+  searchMode: "fts5" | "like";
+}
+
+interface ContinuationArchiveRow {
+  id: number;
+  agent_id: string;
+  generation: number;
+  segment: string;
+  created_at: number;
+  score?: number | null;
+}
+
+const MAX_RECALL_LIMIT = 20;
+
+export function ensureContinuationArchiveSearchSchema(): void {
+  if (process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS === "1") return;
+  try {
+    getDb().query(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS continuation_archive_segments
+      USING fts5(segment, content='continuation_archives', content_rowid='id')
+    `).run();
+    getDb().query(`
+      CREATE TRIGGER IF NOT EXISTS continuation_archives_ai AFTER INSERT ON continuation_archives BEGIN
+        INSERT INTO continuation_archive_segments(rowid, segment) VALUES (new.id, new.segment);
+      END
+    `).run();
+    getDb().query(`
+      CREATE TRIGGER IF NOT EXISTS continuation_archives_ad AFTER DELETE ON continuation_archives BEGIN
+        INSERT INTO continuation_archive_segments(continuation_archive_segments, rowid, segment)
+        VALUES('delete', old.id, old.segment);
+      END
+    `).run();
+    getDb().query(`
+      CREATE TRIGGER IF NOT EXISTS continuation_archives_au AFTER UPDATE ON continuation_archives BEGIN
+        INSERT INTO continuation_archive_segments(continuation_archive_segments, rowid, segment)
+        VALUES('delete', old.id, old.segment);
+        INSERT INTO continuation_archive_segments(rowid, segment) VALUES (new.id, new.segment);
+      END
+    `).run();
+    getDb().query("INSERT INTO continuation_archive_segments(continuation_archive_segments) VALUES('rebuild')").run();
+  } catch {
+    // FTS5 is expected in bun:sqlite, but recall stays available through LIKE when
+    // a custom SQLite build omits it.
+  }
+}
+
+export function archiveContinuationSegment(input: {
+  agentId: string;
+  segment: string;
+  generation?: number;
+  now?: number;
+}): ContinuationArchive {
+  const agentId = input.agentId.trim();
+  if (!agentId) throw new ValidationError("agentId required");
+  const segment = input.segment.trim();
+  if (!segment) throw new ValidationError("segment required");
+  if (new TextEncoder().encode(segment).byteLength > MAX_BODY_BYTES) throw new ValidationError(`segment exceeds ${MAX_BODY_BYTES} bytes`);
+  const generation = input.generation ?? nextContinuationArchiveGeneration(agentId);
+  if (!Number.isSafeInteger(generation) || generation < 0) throw new ValidationError("generation must be a non-negative integer");
+  const createdAt = input.now ?? Date.now();
+  const info = getDb().query(`
+    INSERT INTO continuation_archives (agent_id, generation, segment, created_at)
+    VALUES (?, ?, ?, ?)
+  `).run(agentId, generation, segment, createdAt);
+  return getContinuationArchive(Number(info.lastInsertRowid))!;
+}
+
+export function getContinuationArchive(id: number): ContinuationArchive | null {
+  const row = getDb().query("SELECT * FROM continuation_archives WHERE id = ?").get(id) as ContinuationArchiveRow | undefined;
+  return row ? rowToArchive(row) : null;
+}
+
+export function searchContinuationArchives(input: {
+  agentId: string;
+  query: string;
+  limit?: number;
+}): ContinuationArchiveSearchResult[] {
+  const agentId = input.agentId.trim();
+  if (!agentId) throw new ValidationError("agentId required");
+  const query = input.query.trim();
+  if (!query) throw new ValidationError("query required");
+  const limit = clampLimit(input.limit);
+  const fts = ftsQuery(query);
+  if (continuationArchiveSearchMode() === "fts5" && fts) {
+    try {
+      const rows = getDb().query(`
+        SELECT a.*, bm25(continuation_archive_segments) AS score
+        FROM continuation_archive_segments
+        JOIN continuation_archives a ON a.id = continuation_archive_segments.rowid
+        WHERE continuation_archive_segments MATCH ? AND a.agent_id = ?
+        ORDER BY score ASC, a.created_at DESC, a.id DESC
+        LIMIT ?
+      `).all(fts, agentId, limit) as ContinuationArchiveRow[];
+      return rows.map((row) => ({ ...rowToArchive(row), score: row.score ?? null, searchMode: "fts5" as const }));
+    } catch {
+      // Bad MATCH syntax should not make recall fail; the LIKE fallback is less
+      // precise but deterministic.
+    }
+  }
+  return searchContinuationArchivesLike(agentId, query, limit);
+}
+
+export function continuationArchiveSearchMode(): "fts5" | "like" {
+  if (process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS === "1") return "like";
+  const row = getDb().query(`
+    SELECT 1 FROM sqlite_master
+    WHERE type = 'table' AND name = 'continuation_archive_segments'
+  `).get();
+  return row ? "fts5" : "like";
+}
+
+function nextContinuationArchiveGeneration(agentId: string): number {
+  const row = getDb().query(`
+    SELECT max(generation) AS generation FROM continuation_archives WHERE agent_id = ?
+  `).get(agentId) as { generation: number | null } | undefined;
+  const archiveGeneration = typeof row?.generation === "number" ? row.generation : 0;
+  const envelopeGeneration = getContinuationEnvelope(agentId)?.generation ?? 0;
+  return Math.max(archiveGeneration, envelopeGeneration) + 1;
+}
+
+function searchContinuationArchivesLike(agentId: string, query: string, limit: number): ContinuationArchiveSearchResult[] {
+  const terms = likeTerms(query);
+  if (terms.length === 0) return [];
+  const clauses = terms.map(() => "lower(segment) LIKE ? ESCAPE '\\'").join(" AND ");
+  const rows = getDb().query(`
+    SELECT *, NULL AS score FROM continuation_archives
+    WHERE agent_id = ? AND ${clauses}
+    ORDER BY created_at DESC, id DESC
+    LIMIT ?
+  `).all(agentId, ...terms.map((term) => `%${escapeLike(term)}%`), limit) as ContinuationArchiveRow[];
+  return rows.map((row) => ({ ...rowToArchive(row), score: null, searchMode: "like" as const }));
+}
+
+function clampLimit(value: number | undefined): number {
+  if (value === undefined) return 5;
+  if (!Number.isSafeInteger(value) || value <= 0) throw new ValidationError("limit must be a positive integer");
+  return Math.min(value, MAX_RECALL_LIMIT);
+}
+
+function ftsQuery(query: string): string {
+  return likeTerms(query)
+    .slice(0, 16)
+    .map((term) => `"${term.replace(/"/g, '""')}"`)
+    .join(" ");
+}
+
+function likeTerms(query: string): string[] {
+  return [...new Set((query.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? []).filter(Boolean))];
+}
+
+function escapeLike(value: string): string {
+  return value.replace(/[\\%_]/g, (match) => `\\${match}`);
+}
+
+function rowToArchive(row: ContinuationArchiveRow): ContinuationArchive {
+  return {
+    id: row.id,
+    ref: String(row.id),
+    agentId: row.agent_id,
+    generation: row.generation,
+    segment: row.segment,
+    createdAt: row.created_at,
+  };
+}