agent-relay-server 0.40.0 → 0.41.0

package/src/db/continuations.ts

@@ -0,0 +1,151 @@
+import { isRecord } from "agent-relay-sdk";
+import { parseJson } from "../utils";
+import { getDb, ValidationError } from "./connection.ts";
+import type { ContinuationBudget, ContinuationEnvelope, ContinuationLedgerEntry, SelfResumeConfig } from "../types";
+
+interface ContinuationRow {
+  agent_id: string;
+  objective: string;
+  generation: number;
+  ledger: string;
+  working_state: string;
+  archive_refs: string;
+  budget: string;
+  created_at: number;
+  updated_at: number;
+}
+
+export function getContinuationEnvelope(agentId: string): ContinuationEnvelope | null {
+  const row = getDb().query("SELECT * FROM agent_continuations WHERE agent_id = ?").get(agentId) as ContinuationRow | undefined;
+  return row ? rowToEnvelope(row) : null;
+}
+
+export function ensureContinuationEnvelope(input: {
+  agentId: string;
+  objective?: string;
+  config: SelfResumeConfig;
+  now?: number;
+}): ContinuationEnvelope {
+  const existing = getContinuationEnvelope(input.agentId);
+  if (existing) return existing;
+  const objective = input.objective;
+  if (!objective?.trim()) throw new ValidationError("objective required for first self-resume when no spawn prompt was recorded");
+  const now = input.now ?? Date.now();
+  const budget: ContinuationBudget = {
+    ...input.config.budget,
+    spent: { generations: 0, wallClockMs: 0, tokens: 0 },
+  };
+  getDb().query(`
+    INSERT INTO agent_continuations (agent_id, objective, generation, ledger, working_state, archive_refs, budget, created_at, updated_at)
+    VALUES (?, ?, 0, '[]', '', '[]', ?, ?, ?)
+  `).run(input.agentId, objective, JSON.stringify(budget), now, now);
+  return getContinuationEnvelope(input.agentId)!;
+}
+
+export function seedContinuationObjectiveFromSpawnPrompt(agentId: string, spawnRequestId: string | undefined, config: SelfResumeConfig, now = Date.now()): ContinuationEnvelope | null {
+  if (!spawnRequestId || getContinuationEnvelope(agentId)) return getContinuationEnvelope(agentId);
+  const row = getDb().query(`
+    SELECT params FROM commands
+    WHERE type = 'agent.spawn' AND correlation_id = ?
+    ORDER BY created_at DESC
+    LIMIT 1
+  `).get(spawnRequestId) as { params: string } | undefined;
+  const params = row ? parseJson<unknown>(row.params, {}) : {};
+  if (!isRecord(params) || typeof params.prompt !== "string" || !params.prompt.trim()) return null;
+  return ensureContinuationEnvelope({ agentId, objective: params.prompt, config, now });
+}
+
+export function updateContinuationAfterCompact(input: {
+  agentId: string;
+  generation: number;
+  ledgerEntries: ContinuationLedgerEntry[];
+  workingState: string;
+  archiveRefs?: string[];
+  spentTokens: number;
+  now?: number;
+}): ContinuationEnvelope {
+  const existing = getContinuationEnvelope(input.agentId);
+  if (!existing) throw new ValidationError("continuation envelope not found");
+  const now = input.now ?? Date.now();
+  const nextBudget: ContinuationBudget = {
+    ...existing.budget,
+    spent: {
+      generations: input.generation,
+      wallClockMs: Math.max(0, now - existing.createdAt),
+      tokens: existing.budget.spent.tokens + Math.max(0, input.spentTokens),
+    },
+  };
+  getDb().query(`
+    UPDATE agent_continuations
+    SET generation = ?, ledger = ?, working_state = ?, archive_refs = ?, budget = ?, updated_at = ?
+    WHERE agent_id = ?
+  `).run(
+    input.generation,
+    JSON.stringify([...existing.ledger, ...input.ledgerEntries]),
+    input.workingState,
+    JSON.stringify([...existing.archiveRefs, ...(input.archiveRefs ?? [])]),
+    JSON.stringify(nextBudget),
+    now,
+    input.agentId,
+  );
+  return getContinuationEnvelope(input.agentId)!;
+}
+
+export function appendContinuationArchiveRefs(agentId: string, archiveRefs: string[]): ContinuationEnvelope | null {
+  if (archiveRefs.length === 0) return getContinuationEnvelope(agentId);
+  const existing = getContinuationEnvelope(agentId);
+  if (!existing) return null;
+  const refs = [...existing.archiveRefs];
+  for (const ref of archiveRefs) {
+    if (!refs.includes(ref)) refs.push(ref);
+  }
+  getDb().query(`
+    UPDATE agent_continuations
+    SET archive_refs = ?, updated_at = ?
+    WHERE agent_id = ?
+  `).run(JSON.stringify(refs), Date.now(), agentId);
+  return getContinuationEnvelope(agentId);
+}
+
+function rowToEnvelope(row: ContinuationRow): ContinuationEnvelope {
+  return {
+    agentId: row.agent_id,
+    objective: row.objective,
+    generation: row.generation,
+    ledger: parseJson<ContinuationLedgerEntry[]>(row.ledger, []).filter(isLedgerEntry),
+    workingState: row.working_state,
+    archiveRefs: parseJson<string[]>(row.archive_refs, []).filter((value): value is string => typeof value === "string"),
+    budget: parseBudget(row.budget),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function parseBudget(raw: string): ContinuationBudget {
+  const parsed = parseJson<unknown>(raw, null);
+  if (!isRecord(parsed) || !isRecord(parsed.spent)) {
+    return { maxGenerations: 1, maxWallClockMs: 1, maxTokens: 1, spent: { generations: 0, wallClockMs: 0, tokens: 0 } };
+  }
+  return {
+    maxGenerations: numberValue(parsed.maxGenerations),
+    maxWallClockMs: numberValue(parsed.maxWallClockMs),
+    maxTokens: numberValue(parsed.maxTokens),
+    spent: {
+      generations: numberValue(parsed.spent.generations),
+      wallClockMs: numberValue(parsed.spent.wallClockMs),
+      tokens: numberValue(parsed.spent.tokens),
+    },
+  };
+}
+
+function isLedgerEntry(value: unknown): value is ContinuationLedgerEntry {
+  return isRecord(value)
+    && typeof value.gen === "number"
+    && typeof value.ruledOut === "string"
+    && typeof value.why === "string"
+    && typeof value.at === "number";
+}
+
+function numberValue(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}

package/src/db/index.ts

@@ -21,3 +21,5 @@ export * from "./stats.ts";
 export * from "./orchestrators.ts";
 export * from "./workspaces.ts";
 export * from "./merge-lease.ts";
+export * from "./continuations.ts";
+export * from "./continuation-archives.ts";

package/src/db/migrations.ts

@@ -15,6 +15,7 @@ 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 { getDb } from "./connection.ts";
+import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
 import { normalizeReactionEmoji } from "./mappers.ts";
 import type {
   AgentCard,
@@ -176,6 +177,34 @@ export function applyMigrations(): void {
   getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_delivery_status ON messages(delivery_status)");
   getDb().run("CREATE INDEX IF NOT EXISTS idx_msg_resolved_to_agent ON messages(resolved_to_agent)");
 
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS agent_continuations (
+      agent_id TEXT PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+      objective TEXT NOT NULL,
+      generation INTEGER NOT NULL DEFAULT 0,
+      ledger TEXT NOT NULL DEFAULT '[]',
+      working_state TEXT NOT NULL DEFAULT '',
+      archive_refs TEXT NOT NULL DEFAULT '[]',
+      budget TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run(`
+    CREATE TABLE IF NOT EXISTS continuation_archives (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      generation INTEGER NOT NULL,
+      segment TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    )
+  `);
+  getDb().run(`
+    CREATE INDEX IF NOT EXISTS idx_continuation_archives_agent_generation
+    ON continuation_archives(agent_id, generation, created_at DESC)
+  `);
+  ensureContinuationArchiveSearchSchema();
+
   const tokenCols = getDb().query("PRAGMA table_info(tokens)").all() as any[];
   const tokenColNames = tokenCols.map((c: any) => c.name);
   if (!tokenColNames.includes("constraints")) {

package/src/db/schema.ts

@@ -15,6 +15,7 @@ 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 { applyConnectionPragmas, getDb, setDb } from "./connection.ts";
+import { ensureContinuationArchiveSearchSchema } from "./continuation-archives.ts";
 import { applyMigrations } from "./migrations.ts";
 import type {
   AgentCard,
@@ -174,6 +175,28 @@ export function initDb(path: string = "agent-relay.db"): Database {
     );
     CREATE INDEX IF NOT EXISTS idx_context_snapshots_agent_time ON context_snapshots(agent_id, captured_at DESC);
 
+    CREATE TABLE IF NOT EXISTS agent_continuations (
+      agent_id TEXT PRIMARY KEY REFERENCES agents(id) ON DELETE CASCADE,
+      objective TEXT NOT NULL,
+      generation INTEGER NOT NULL DEFAULT 0,
+      ledger TEXT NOT NULL DEFAULT '[]',
+      working_state TEXT NOT NULL DEFAULT '',
+      archive_refs TEXT NOT NULL DEFAULT '[]',
+      budget TEXT NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS continuation_archives (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent_id TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
+      generation INTEGER NOT NULL,
+      segment TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_continuation_archives_agent_generation
+      ON continuation_archives(agent_id, generation, created_at DESC);
+
     CREATE TABLE IF NOT EXISTS memories (
       id TEXT PRIMARY KEY,
       type TEXT NOT NULL,
@@ -743,6 +766,7 @@ export function initDb(path: string = "agent-relay.db"): Database {
     CREATE INDEX IF NOT EXISTS idx_insights_obs_session ON insights_observations(session_id);
   `);
 
+  ensureContinuationArchiveSearchSchema();
   applyMigrations();
 
   // Bootstrap planner statistics on first run (sqlite_stat1 absent means ANALYZE

package/src/lifecycle-manager.ts

@@ -9,6 +9,7 @@ import {
   upsertManagedAgentState,
 } from "./config-store";
 import { emitRelayEvent } from "./events";
+import { handleContextPressure } from "./context-advisory";
 import { markManagedAgentRunning, emitManagedState } from "./services/managed-running";
 import { authContextFromSystem } from "./services/auth-context";
 import { emitCommandEvent } from "./command-events";
@@ -25,7 +26,6 @@ const STOP_TIMEOUT_MS = 60_000;
 const FAST_FAIL_RUNTIME_MS = 30_000;
 const MAX_FAST_FAILURES = 3;
 const DAY_MS = 24 * 60 * 60 * 1000;
-const DEFAULT_COMPACT_THRESHOLD = 0.75;
 const DEFAULT_COMPACT_TARGET = 0.3;
 const DEFAULT_MAX_TASKS_BEFORE_COMPACT = 10;
 const DEFAULT_COMPACT_COOLDOWN_MS = 60_000;
@@ -354,6 +354,7 @@ export class LifecycleManager {
         this.stopAgent(policy, true, "idle-timeout");
         return;
       }
+      if (handleContextPressure({ agent, now: this.now, hasActiveCommand: (target, type) => this.hasActiveCommand(target, type), compact: (reason) => this.compactAgent(policy, agent.id, reason, alwaysReloadTags(agent.tags)) })) return;
       if (this.shouldCompact(agent)) {
         this.compactAgent(policy, agent.id, "context-threshold", alwaysReloadTags(agent.tags));
         return;
@@ -524,7 +525,6 @@ export class LifecycleManager {
     if (agent.providerCapabilities?.context?.compact !== true) return false;
     if (this.hasActiveCommand(agent.id, "agent.compact")) return false;
 
-    if (context.utilization > DEFAULT_COMPACT_THRESHOLD) return true;
     if (context.tasksSinceCompact > DEFAULT_MAX_TASKS_BEFORE_COMPACT) return true;
     return context.lifecycleState === "cooling" &&
       this.now() - context.lastUpdatedAt >= DEFAULT_COMPACT_COOLDOWN_MS &&

package/src/mcp.ts

@@ -24,6 +24,7 @@ import {
   listAgents,
   listWorkspaces,
   ownedIsolatedWorkspace,
+  searchContinuationArchives,
   searchAgents,
   type AgentSearchFilter,
   type AgentSearchSort,
@@ -35,6 +36,7 @@ import {
 import { resolveCallerAgentId, type DeliveryReceipt } from "./agent-ref";
 import { ShutdownAuthError, ShutdownTargetError, shutdownAgent } from "./services/shutdown-agent";
 import { emitRelayEvent } from "./events";
+import { compactAndResume } from "./self-resume";
 import {
   getComponentAuth,
   getIntegrationAuth,
@@ -246,6 +248,52 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_compact_and_resume",
+    description: "Self-resume this same agent in place: Relay stores the continuation envelope, compacts or clears context, then resumes with the relay-built continuation. Use at a clean seam after a context advisory.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workingState: { type: "string", description: "Current replaceable working state for the next generation." },
+        ruledOut: {
+          type: "array",
+          items: {
+            oneOf: [
+              { type: "string" },
+              {
+                type: "object",
+                properties: {
+                  ruledOut: { type: "string" },
+                  why: { type: "string" },
+                },
+                required: ["ruledOut"],
+                additionalProperties: false,
+              },
+            ],
+          },
+        },
+        mode: { type: "string", enum: ["clear-inject", "native"] },
+        objective: { type: "string", description: "Seed-only objective. Used only on the first call when no spawn prompt seeded the envelope." },
+      },
+      required: ["workingState"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_recall",
+    description: "Recall this same agent's archived pre-compaction transcript segments by keyword/BM25 search. Self-only: caller identity comes from the MCP token; no agentId parameter is accepted.",
+    requiredScopes: ["memory:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keyword query over archived compact/clear segments." },
+        limit: { type: "integer", minimum: 1, maximum: 20 },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
   {
     name: "relay_spawn_agent",
     description: "Spawn a long-living provider agent through Relay's orchestrator, optionally handing it its first task via `prompt` in the same call. Defaults to your own host (override with orchestratorId) and returns the resolved agent id once it registers. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
@@ -506,6 +554,8 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_agent_status") result = relayAgentStatus(args);
     else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
     else if (name === "relay_whoami") result = relayWhoami(auth);
+    else if (name === "relay_compact_and_resume") result = relayCompactAndResume(auth, args);
+    else if (name === "relay_recall") result = relayRecall(auth, args);
     else if (name === "relay_spawn_agent") result = await relaySpawnAgent(auth, args);
     else if (name === "relay_spawn_targets") result = relaySpawnTargets(auth);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
@@ -557,6 +607,33 @@ function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
   };
 }
 
+function relayCompactAndResume(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (!agentId) throw new McpAuthError("relay_compact_and_resume requires a single caller agent identity");
+  return compactAndResume({
+    agentId,
+    workingState: stringField(args.workingState, "workingState", { required: true, maxBytes: MAX_BODY_BYTES }),
+    ruledOut: args.ruledOut,
+    mode: optionalEnum(args.mode, "mode", ["clear-inject", "native"] as const),
+    objective: optionalString(args.objective, "objective", 64_000),
+  }) as unknown as Record<string, unknown>;
+}
+
+function relayRecall(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const agentId = callerAgentId(auth);
+  if (!agentId) throw new McpAuthError("relay_recall requires a single caller agent identity");
+  const matches = searchContinuationArchives({
+    agentId,
+    query: stringField(args.query, "query", { required: true, max: 1000 }),
+    limit: optionalPositiveInt(args.limit, "limit"),
+  });
+  return {
+    query: stringField(args.query, "query", { required: true, max: 1000 }),
+    matches,
+    count: matches.length,
+  };
+}
+
 // MCP transport adapter over the shared send service (epic #342). The service owns from-resolution
 // (token identity via ctx.callerAgentId), reply routing, target resolution + the converged
 // store-ahead policy, authorization, persistence, and emit. This adapter only builds the input,

package/src/routes/commands.ts

@@ -15,6 +15,7 @@ import { ServiceAuthError } from "../services/errors";
 import { notifyBranchLanded } from "../branch-landed";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { handleReviewerMergeResult } from "../reviewer-pipeline";
+import { enqueueContinuationInjectionAfterClear } from "../self-resume";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
 
 const VALID_COMMAND_STATUSES = ["pending", "accepted", "running", "succeeded", "failed", "timed_out", "rejected", "canceled"] as const;
@@ -173,6 +174,7 @@ export const patchCommand: Handler = async (req, params) => {
       // hook so a command that landed in the wrong context gets flagged.
       getCompactionWatch().noteCommandSucceeded(command.type, command.id, command.target);
     }
+    enqueueContinuationInjectionAfterClear(command);
     if (command.type === "workspace.cleanup" && command.status === "succeeded" && isRecord(command.result)) {
       const workspaceId = cleanString(command.result.workspaceId, "result.workspaceId", { max: 160 });
       if (workspaceId) {

package/src/routes/continuation-archives.ts

@@ -0,0 +1,37 @@
+// Auto-split from routes.ts (#299). Domain: continuation archives.
+import { isRecord } from "agent-relay-sdk";
+import { resolveCallerAgentId } from "../agent-ref";
+import { archiveContinuationSegment, appendContinuationArchiveRefs, getAgent, listAgents, ValidationError } from "../db";
+import { getComponentAuth } from "../security";
+import { cleanEpoch, cleanPositiveId, cleanString } from "../validation";
+import { error, json, parseBody, type Handler } from "./_shared";
+
+export const postContinuationArchiveRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  if (!isRecord(parsed.body)) return error("JSON object body required", 400);
+  try {
+    const agentId = cleanString(parsed.body.agentId, "agentId", { required: true, max: 240 })!;
+    const denied = authorizeArchiveWriter(req, agentId);
+    if (denied) return denied;
+    if (!getAgent(agentId)) return error("agent not found", 404);
+    const archive = archiveContinuationSegment({
+      agentId,
+      segment: cleanString(parsed.body.segment, "segment", { required: true, max: 64_000 })!,
+      generation: cleanPositiveId(parsed.body.generation, "generation"),
+      now: cleanEpoch(parsed.body.occurredAt, "occurredAt"),
+    });
+    const envelope = appendContinuationArchiveRefs(agentId, [archive.ref]);
+    return json({ archive, envelope }, 201);
+  } catch (e) {
+    if (e instanceof ValidationError) return error(e.message, 400);
+    throw e;
+  }
+};
+
+function authorizeArchiveWriter(req: Request, agentId: string): Response | null {
+  const component = getComponentAuth(req);
+  if (!component) return null;
+  const caller = resolveCallerAgentId(component.constraints, listAgents);
+  return caller === agentId ? null : error("forbidden", 403);
+}

package/src/routes/index.ts

@@ -20,6 +20,7 @@ import { getApiDocs, getApiSpec } from "./spec";
 import { getChannelBindings, getChannels, getIntegrations, postChannelActivity, postChannelBinding, postChannelEvent, postIntegrationEvent, putIntegrationRegistryRoute } from "./integrations";
 import { getCommandById, getCommands, patchCommand, postCommand } from "./commands";
 import { getConnectorById, getConnectorConfig, getConnectors, postConnectorAction, postConnectorCall, postConnectorRegister, putConnectorConfig } from "./connectors";
+import { postContinuationArchiveRoute } from "./continuation-archives";
 import { getEvents } from "./sse";
 import { getHostDirectories, postAgent, postAgentSpawn, postRouteAdvice } from "./agents-spawn";
 import { getInsightsConfigRoute, getInsightsObservationsRoute, postInsightsObservationRoute, putInsightsConfigRoute } from "./insights";
@@ -170,6 +171,7 @@ const routes: Route[] = [
   route("PUT", "/api/insights/config", putInsightsConfigRoute),
   route("GET", "/api/insights/observations", getInsightsObservationsRoute),
   route("POST", "/api/insights/observations", postInsightsObservationRoute),
+  route("POST", "/api/continuation-archives", postContinuationArchiveRoute),
   route("GET", "/api/config/:namespace", getConfigNamespace),
   route("GET", "/api/config/:namespace/:key/history", getConfigKeyHistory),
   route("GET", "/api/config/:namespace/:key", getConfigKey),

package/src/security.ts

@@ -207,6 +207,7 @@ export function requiredScopeFor(method: string, pathname: string): string | nul
   // Insights config (the feature toggle) stays admin-only via the default; only the
   // mechanical observation feed is writable by lower-privilege callers.
   if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
+  if (pathname === "/api/continuation-archives") return "insights:write";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return null;
 }
@@ -281,6 +282,7 @@ export function requiredComponentScopeFor(method: string, pathname: string): str
   // below and every observation was 403-dropped — the whole Insights feed stayed empty.
   // Config (the feature toggle) intentionally keeps falling through to system:admin.
   if (pathname === "/api/insights/observations") return method === "GET" ? "insights:read" : "insights:write";
+  if (pathname === "/api/continuation-archives") return "insights:write";
   if (pathname.startsWith("/api/system/")) return "system:admin";
   return "system:admin";
 }

package/src/self-resume-config.ts

@@ -0,0 +1,44 @@
+import { isRecord } from "agent-relay-sdk";
+import { ValidationError } from "./db/connection.ts";
+import type { SelfResumeConfig } from "./types";
+
+export const DEFAULT_SELF_RESUME_CONFIG: SelfResumeConfig = {
+  defaultMode: "clear-inject",
+  budget: {
+    maxGenerations: 8,
+    maxWallClockMs: 24 * 60 * 60 * 1000,
+    maxTokens: 2_000_000,
+  },
+};
+
+const VALID_SELF_RESUME_MODES = ["clear-inject", "native"] as const;
+
+export function validateSelfResumeConfig(value: unknown): SelfResumeConfig {
+  if (!isRecord(value)) throw new ValidationError("self-resume config value must be an object");
+  const budget = isRecord(value.budget) ? value.budget : {};
+  return {
+    defaultMode: value.defaultMode === undefined || value.defaultMode === null
+      ? DEFAULT_SELF_RESUME_CONFIG.defaultMode
+      : cleanMode(value.defaultMode, "defaultMode"),
+    budget: {
+      maxGenerations: cleanPositiveInt(budget.maxGenerations, "budget.maxGenerations", DEFAULT_SELF_RESUME_CONFIG.budget.maxGenerations),
+      maxWallClockMs: cleanPositiveInt(budget.maxWallClockMs, "budget.maxWallClockMs", DEFAULT_SELF_RESUME_CONFIG.budget.maxWallClockMs),
+      maxTokens: cleanPositiveInt(budget.maxTokens, "budget.maxTokens", DEFAULT_SELF_RESUME_CONFIG.budget.maxTokens),
+    },
+  };
+}
+
+function cleanMode(value: unknown, field: string): SelfResumeConfig["defaultMode"] {
+  if (typeof value !== "string" || !VALID_SELF_RESUME_MODES.includes(value as any)) {
+    throw new ValidationError(`${field} must be one of: ${VALID_SELF_RESUME_MODES.join(", ")}`);
+  }
+  return value as SelfResumeConfig["defaultMode"];
+}
+
+function cleanPositiveInt(value: unknown, field: string, fallback: number): number {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new ValidationError(`${field} must be a positive integer`);
+  }
+  return value;
+}