agent-relay-runner 0.40.0 → 0.41.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.25"
+    "agent-relay-sdk": "0.2.26"
   },
   "devDependencies": {
     "@types/bun": "latest",

package/plugins/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-relay-runner",
   "description": "Thin Agent Relay runner bridge for Claude Code",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/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/adapters/claude.ts

@@ -15,6 +15,7 @@ import { claudeProviderMessageText } from "./claude-delivery";
 
 export class ClaudeAdapter implements ProviderAdapter {
   readonly provider = "claude";
+  readonly compactSupportsInstructions = true;
   // #352: initial prompt is seeded as Claude's positional launch arg (buildSpawnArgs) — reliable,
   // no send-keys/onboarding race; tells the runner to skip the redundant post-launch delivery.
   readonly seedsInitialPromptAtLaunch = true;
@@ -55,12 +56,13 @@ export class ClaudeAdapter implements ProviderAdapter {
     await terminateSingleProcess(process, opts);
   }
 
-  async compact(process: ManagedProcess): Promise<Record<string, unknown>> {
+  async compact(process: ManagedProcess, opts?: { instructions?: string }): Promise<Record<string, unknown>> {
     const session = process.meta?.tmuxSession as string | undefined;
     const socket = process.meta?.tmuxSocket as string | undefined;
     if (!session || !tmuxHasSession(session, socket)) throw new Error("no active tmux session for compact");
-    await submitTextToTmux(session, "/compact", socket);
-    return { method: "tmux-inject", command: "/compact" };
+    const command = opts?.instructions ? `/compact ${opts.instructions}` : "/compact";
+    await submitTextToTmux(session, command, socket);
+    return { method: "tmux-inject", command };
   }
 
   async clearContext(process: ManagedProcess): Promise<Record<string, unknown>> {
@@ -84,6 +86,15 @@ export class ClaudeAdapter implements ProviderAdapter {
     return collectClaudeSessionEvents(jsonl);
   }
 
+  async collectSessionArchiveSegment(_process: ManagedProcess, ctx: { transcriptPath?: string }): Promise<string | null> {
+    if (!ctx.transcriptPath) return null;
+    try {
+      return await readFile(ctx.transcriptPath, "utf8");
+    } catch {
+      return null;
+    }
+  }
+
   async interrupt(process: ManagedProcess): Promise<Record<string, unknown>> {
     const session = process.meta?.tmuxSession as string | undefined;
     const socket = process.meta?.tmuxSocket as string | undefined;

package/src/runner.ts

@@ -231,6 +231,8 @@ export class AgentRunner {
   // (transcript rotated, Codex buffer trimmed) resets the cursor.
   private insightsObserved = 0;
   private insightsCursorKey = "";
+  private archiveObservedChars = 0;
+  private archiveCursorKey = "";
   // Memoized repo-name project id for insight observations (resolved once; involves a
   // git toplevel lookup for direct agents). Aggregates by repo, not per-session worktree.
   private insightProjectName?: string;
@@ -737,7 +739,9 @@ export class AgentRunner {
       else if (type === "agent.reconnect") this.publishStatus();
       else if (type === "agent.compact") {
         if (!this.options.adapter.compact || !this.process) throw new Error("provider does not support compact");
-        providerResult = await this.options.adapter.compact(this.process);
+        providerResult = await this.options.adapter.compact(this.process, {
+          instructions: typeof params.instructions === "string" ? params.instructions : undefined,
+        });
       } else if (type === "agent.clearContext") {
         if (!this.options.adapter.clearContext || !this.process) throw new Error("provider does not support clearContext");
         providerResult = await this.options.adapter.clearContext(this.process);
@@ -768,7 +772,11 @@ export class AgentRunner {
     } finally {
       this.claims.finishClaim("command", commandId);
       if (exitAfterCommand) {
-        await this.http.deleteAgent(this.agentId).catch(() => {});
+        if (params.preserveRegistration === true) {
+          await this.http.setStatus(this.agentId, "offline", this.options.instanceId).catch(() => {});
+        } else {
+          await this.http.deleteAgent(this.agentId).catch(() => {});
+        }
         if (this.options.exitProcessOnShutdown !== false) {
           setTimeout(() => void this.stop().catch((error) => {
             logger.error("lifecycle", `stop after command failed: ${error}`);
@@ -1301,6 +1309,13 @@ export class AgentRunner {
         });
         return;
       }
+      if (record.kind === "continuation-archive") {
+        await this.http.recordContinuationArchive({
+          ...(record.payload as Parameters<RelayHttpClient["recordContinuationArchive"]>[0]),
+          occurredAt: record.occurredAt,
+        });
+        return;
+      }
       if (record.kind === "mcp-tool-call") {
         await this.deliverBufferedMcpCall(record);
         return;
@@ -1434,11 +1449,14 @@ export class AgentRunner {
       this.publishFinalizing(reason);
       try {
         await Promise.race([
-          this.captureContextRatio(reason, opts),
+          Promise.all([
+            this.captureContextRatio(reason, opts),
+            this.captureContinuationArchive(reason, opts),
+          ]).then(() => undefined),
           new Promise<void>((resolve) => setTimeout(resolve, PRE_DESTROY_TIMEOUT_MS)),
         ]);
       } catch (error) {
-        this.sessionLog(`insights: pre-destroy capture failed: ${errMessage(error)}`);
+        this.sessionLog(`pre-destroy capture failed: ${errMessage(error)}`);
       }
       // For exit-bound transitions the runner won't be alive afterward to drain the durable
       // outbox, so block (bounded) on delivering what capture just enqueued. This runs before
@@ -1478,6 +1496,30 @@ export class AgentRunner {
     return (this.insightProjectName ??= resolveProjectName(this.options.cwd, this.options.workspace));
   }
 
+  private async captureContinuationArchive(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.options.adapter;
+    if (!adapter.collectSessionArchiveSegment || !this.process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.lastTranscriptPath;
+    const archive = await adapter.collectSessionArchiveSegment(this.process, { transcriptPath });
+    if (!archive) return;
+    const key = transcriptPath ?? `session:${this.providerSessionId}`;
+    if (key !== this.archiveCursorKey || archive.length < this.archiveObservedChars) {
+      this.archiveCursorKey = key;
+      this.archiveObservedChars = 0;
+    }
+    const segment = archive.slice(this.archiveObservedChars).trim();
+    this.archiveObservedChars = archive.length;
+    if (!segment) return;
+    this.outbox.enqueue({
+      kind: "continuation-archive",
+      payload: {
+        agentId: this.agentId,
+        segment,
+      },
+    });
+    this.sessionLog(`continuation archive queued (${segment.length} chars, ${reason})`);
+  }
+
   private async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
     const adapter = this.options.adapter;
     if (!adapter.collectSessionEvents || !this.process) return;
@@ -2066,7 +2108,7 @@ export class AgentRunner {
     const meta: Record<string, unknown> = {
       providerCapabilities: runtimeProviderCapabilities(
         this.options,
-        context ? { source: context.source, confidence: context.confidence } : undefined,
+        context,
         probeModel,
       ),
       ...(terminalSession ? { tmuxSession: terminalSession } : {}),
@@ -2319,7 +2361,7 @@ interface ProbeModelInfo {
   effort?: string;
 }
 
-function runtimeProviderCapabilities(options: RunnerOptions, contextStats?: { source: "api" | "statusline" | "hook" | "estimate"; confidence: "exact" | "reported" | "estimated" }, probeModel?: ProbeModelInfo): ProviderCapabilities {
+function runtimeProviderCapabilities(options: RunnerOptions, contextState?: ContextState, probeModel?: ProbeModelInfo): ProviderCapabilities {
   const model = options.model ?? probeModel?.model;
   const effort = options.effort ?? probeModel?.effort;
   const modelSource = options.model ? "runtime" as const : probeModel?.model ? "provider" as const : "runtime" as const;
@@ -2349,7 +2391,7 @@ function runtimeProviderCapabilities(options: RunnerOptions, contextStats?: { so
       confidence: "reported",
       lastUpdatedAt: options.startedAt,
     },
-    ...runtimeProviderContextCapabilities(options, contextStats),
+    ...runtimeProviderContextCapabilities(options, contextState),
     ...runtimeProviderTerminalCapabilities(options),
     liveSession: {
       capture: true,
@@ -2418,14 +2460,22 @@ function appliedAgentProfileMetadata(provider: string, profile: AgentProfile): R
   };
 }
 
-function runtimeProviderContextCapabilities(options: RunnerOptions, contextStats?: { source: "api" | "statusline" | "hook" | "estimate"; confidence: "exact" | "reported" | "estimated" }): Pick<ProviderCapabilities, "context"> {
-  const context: NonNullable<ProviderCapabilities["context"]> = {};
-  if (contextStats) context.stats = contextStats;
-  if (options.provider === "codex" || (options.provider === "claude" && options.headless)) {
+function runtimeProviderContextCapabilities(options: RunnerOptions, contextState?: ContextState): Pick<ProviderCapabilities, "context"> {
+  const context: NonNullable<ProviderCapabilities["context"]> = { resume: "none" };
+  const supportsManagedContext = options.provider === "codex" || (options.provider === "claude" && options.headless);
+  if (contextState) {
+    context.stats = { source: contextState.source, confidence: contextState.confidence };
+    if (typeof contextState.tokensMax === "number" && Number.isFinite(contextState.tokensMax)) {
+      context.windowTokens = contextState.tokensMax;
+    }
+  }
+  if (supportsManagedContext) {
     context.compact = true;
     context.clear = true;
   }
   context.inject = true;
+  if (supportsManagedContext && options.adapter.compact && options.adapter.compactSupportsInstructions) context.resume = "native";
+  else if (supportsManagedContext && options.adapter.clearContext) context.resume = "clear-inject";
   return Object.keys(context).length ? { context } : {};
 }