agent-relay-server 0.40.0 → 0.41.0

package/src/self-resume.ts

@@ -0,0 +1,232 @@
+import { isRecord } from "agent-relay-sdk";
+import { createCommand, listCommands } from "./commands-db";
+import { emitCommandEvent } from "./command-events";
+import { getSelfResumeConfig } from "./config-store";
+import {
+  archiveContinuationSegment,
+  ensureContinuationEnvelope,
+  getAgent,
+  getContinuationEnvelope,
+  updateContinuationAfterCompact,
+  ValidationError,
+} from "./db";
+import { emitRelayEvent } from "./events";
+import { notifySystemMessage } from "./notify";
+import type { AgentCard, Command, ContinuationEnvelope, ContinuationLedgerEntry, SelfResumeMode } from "./types";
+
+export interface CompactAndResumeInput {
+  agentId: string;
+  workingState: string;
+  ruledOut?: unknown;
+  mode?: SelfResumeMode;
+  objective?: string;
+}
+
+export interface CompactAndResumeResult {
+  ok: boolean;
+  mode: SelfResumeMode;
+  envelope: ContinuationEnvelope;
+  continuation?: string;
+  command: Command;
+  exhausted?: boolean;
+  reason?: string;
+}
+
+const VALID_RESUME_MODES = ["clear-inject", "native"] as const;
+
+export function compactAndResume(input: CompactAndResumeInput): CompactAndResumeResult {
+  const agent = getAgent(input.agentId);
+  if (!agent) throw new ValidationError("agent not found");
+  const config = getSelfResumeConfig();
+  const mode = input.mode ?? config.defaultMode;
+  if (!VALID_RESUME_MODES.includes(mode)) throw new ValidationError(`mode must be one of: ${VALID_RESUME_MODES.join(", ")}`);
+  assertResumeSupported(agent, mode);
+
+  const now = Date.now();
+  const envelope = ensureContinuationEnvelope({
+    agentId: agent.id,
+    objective: input.objective,
+    config,
+    now,
+  });
+  const exhausted = budgetExhaustion(envelope, now);
+  if (exhausted) {
+    const command = createCleanStop(agent, exhausted);
+    notifySelfResumeBudgetExhausted(agent, envelope, exhausted);
+    return { ok: false, mode, envelope, command, exhausted: true, reason: exhausted };
+  }
+
+  const workingState = input.workingState.trim();
+  if (!workingState) throw new ValidationError("workingState required");
+  const generation = envelope.generation + 1;
+  const ledgerEntries = parseRuledOut(input.ruledOut, generation, now);
+  const archive = archiveContinuationSegment({
+    agentId: agent.id,
+    generation,
+    segment: workingState,
+    now,
+  });
+  const updated = updateContinuationAfterCompact({
+    agentId: agent.id,
+    generation,
+    ledgerEntries,
+    workingState,
+    archiveRefs: [archive.ref],
+    spentTokens: typeof agent.context?.tokensUsed === "number" ? agent.context.tokensUsed : 0,
+    now,
+  });
+  const continuation = renderContinuation(updated);
+  const command = mode === "native"
+    ? createNativeCompact(agent.id, generation, continuation)
+    : createClearThenInject(agent.id, generation, continuation);
+  emitCommandEvent(command, "command.requested");
+  return { ok: true, mode, envelope: updated, continuation, command };
+}
+
+export function enqueueContinuationInjectionAfterClear(command: Command): Command | null {
+  if (command.type !== "agent.clearContext" || command.status !== "succeeded") return null;
+  const resume = isRecord(command.params.selfResume) ? command.params.selfResume : undefined;
+  const continuation = typeof resume?.continuation === "string" ? resume.continuation : undefined;
+  if (!continuation) return null;
+  const generation = typeof resume?.generation === "number" ? resume.generation : undefined;
+  const existing = listCommands({ target: command.target, type: "agent.injectContext", limit: 500 })
+    .find((item) => item.correlationId === command.id);
+  if (existing) return null;
+  const inject = createCommand({
+    type: "agent.injectContext",
+    source: "system",
+    target: command.target,
+    correlationId: command.id,
+    params: {
+      reason: "self-resume-continuation",
+      content: continuation,
+      selfResume: {
+        generation,
+        afterClearCommandId: command.id,
+      },
+    },
+  });
+  emitCommandEvent(inject, "command.requested");
+  return inject;
+}
+
+export function renderContinuation(envelope: ContinuationEnvelope): string {
+  const ledger = envelope.ledger.length
+    ? envelope.ledger.map((entry) => `- gen ${entry.gen} @ ${new Date(entry.at).toISOString()}: ${entry.ruledOut}${entry.why ? `; why: ${entry.why}` : ""}`).join("\n")
+    : "- none";
+  return [
+    `You have been resumed by Agent Relay — generation ${envelope.generation}.`,
+    "",
+    "Objective (verbatim, relay-owned):",
+    envelope.objective,
+    "",
+    "Ruled-out ledger (append-only):",
+    ledger,
+    "",
+    "Working state:",
+    envelope.workingState,
+    "",
+    "Archive refs:",
+    envelope.archiveRefs.length ? envelope.archiveRefs.join("\n") : "- none",
+  ].join("\n");
+}
+
+function assertResumeSupported(agent: AgentCard, mode: SelfResumeMode): void {
+  const context = agent.providerCapabilities?.context;
+  const resume = context?.resume ?? (context?.clear && context?.inject ? "clear-inject" : "none");
+  if (resume === "none") throw new ValidationError("self-resume unsupported, fresh-session handoff only");
+  if (mode === "native" && resume !== "native") throw new ValidationError("native self-resume unsupported for this provider");
+  if (mode === "clear-inject" && !(context?.clear && context?.inject)) {
+    throw new ValidationError("clear-inject self-resume unsupported for this provider");
+  }
+}
+
+function budgetExhaustion(envelope: ContinuationEnvelope, now: number): string | null {
+  if (envelope.generation >= envelope.budget.maxGenerations) return "max generations exhausted";
+  if (Math.max(0, now - envelope.createdAt) >= envelope.budget.maxWallClockMs) return "max wall clock exhausted";
+  if (envelope.budget.spent.tokens >= envelope.budget.maxTokens) return "max token budget exhausted";
+  return null;
+}
+
+function createNativeCompact(agentId: string, generation: number, continuation: string): Command {
+  return createCommand({
+    type: "agent.compact",
+    source: "system",
+    target: agentId,
+    params: {
+      reason: "self-resume",
+      instructions: continuation,
+      selfResume: { generation, mode: "native" },
+    },
+  });
+}
+
+function createClearThenInject(agentId: string, generation: number, continuation: string): Command {
+  return createCommand({
+    type: "agent.clearContext",
+    source: "system",
+    target: agentId,
+    params: {
+      reason: "self-resume",
+      selfResume: { generation, mode: "clear-inject", continuation },
+    },
+  });
+}
+
+function createCleanStop(agent: AgentCard, reason: string): Command {
+  const command = createCommand({
+    type: "agent.shutdown",
+    source: "system",
+    target: agent.id,
+    params: {
+      reason: `self-resume budget exhausted: ${reason}`,
+      graceful: true,
+      timeoutMs: 10_000,
+      preserveRegistration: true,
+      selfResume: { exhausted: true },
+    },
+  });
+  emitCommandEvent(command, "command.requested");
+  return command;
+}
+
+function notifySelfResumeBudgetExhausted(agent: AgentCard, envelope: ContinuationEnvelope, reason: string): void {
+  const payload = {
+    kind: "agent.resume_budget_exhausted",
+    agentId: agent.id,
+    parent: agent.spawnedBy,
+    reason,
+    generation: envelope.generation,
+  };
+  emitRelayEvent({ type: "agent.resume_budget_exhausted", source: "server", subject: agent.id, data: payload });
+  if (!agent.spawnedBy) return;
+  notifySystemMessage(agent.spawnedBy, {
+    subject: "Self-resume budget exhausted",
+    body: `Spawned agent \`${agent.id}\` stopped cleanly: ${reason}.`,
+    payload,
+    replyExpected: false,
+  });
+}
+
+function parseRuledOut(value: unknown, generation: number, now: number): ContinuationLedgerEntry[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) throw new ValidationError("ruledOut must be an array");
+  return value.map((item, index) => {
+    if (typeof item === "string") return ledgerEntry(item, "", generation, now);
+    if (!isRecord(item)) throw new ValidationError(`ruledOut[${index}] must be a string or object`);
+    const ruledOut = typeof item.ruledOut === "string" ? item.ruledOut.trim() : "";
+    const why = typeof item.why === "string" ? item.why.trim() : "";
+    if (!ruledOut) throw new ValidationError(`ruledOut[${index}].ruledOut required`);
+    return ledgerEntry(ruledOut, why, generation, now);
+  });
+}
+
+function ledgerEntry(ruledOut: string, why: string, generation: number, now: number): ContinuationLedgerEntry {
+  const cleaned = ruledOut.trim();
+  if (!cleaned) throw new ValidationError("ruledOut entries cannot be blank");
+  return { gen: generation, ruledOut: cleaned, why, at: now };
+}
+
+export function continuationForAgent(agentId: string): ContinuationEnvelope | null {
+  return getContinuationEnvelope(agentId);
+}