agent-relay-server 0.121.5 → 0.122.1

package/runner/src/runner-helpers.ts

@@ -0,0 +1,435 @@
+import { closeSync, openSync, readSync, statSync } from "node:fs";
+import type { AgentProfile, ContextState, Message, ProviderCapabilities, ProviderState, QuotaState } from "agent-relay-sdk";
+import { errMessage, isSpawnProvider } from "agent-relay-sdk";
+import { getManifest } from "agent-relay-providers";
+import type { BooleanCapabilityDefault, ProviderCapabilityCondition } from "agent-relay-providers";
+import { targetMatchesAgentIdentity } from "agent-relay-sdk/agent-target";
+import type { ProviderAdapter, ProviderConfig, RunnerSpawnConfig, SemanticStatus } from "./adapter";
+import { agentProfileProjectionReport } from "./profile-projection";
+import { assembleLaunch } from "./launch-assembly";
+
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const LOG_TAIL_BYTES = 128 * 1024;
+const RUNNER_CLAIMED_GUIDANCE_RE = /\s*Claim this task before working it, then update task status when finished\.\s*$/;
+
+interface RuntimeProviderOptions {
+  provider: string;
+  model?: string;
+  effort?: string;
+  approvalMode: string;
+  headless: boolean;
+  startedAt: number;
+  adapter: ProviderAdapter;
+}
+
+export interface ProbeModelInfo {
+  model?: string;
+  effort?: string;
+}
+
+export function runnerMessageMatches(message: Pick<Message, "to" | "resolvedToAgent">, target: {
+  agentId: string;
+  label?: string;
+  provider: string;
+  tags: string[];
+  capabilities: string[];
+  defaultTags: string[];
+  defaultCapabilities: string[];
+  allowBroadTargets?: boolean;
+}): boolean {
+  if (message.resolvedToAgent === target.agentId) return true;
+  if (message.to === target.agentId) return true;
+  if (target.label && message.to === `label:${target.label}`) return true;
+  if (target.allowBroadTargets === false) return false;
+  return targetMatchesAgentIdentity(message.to, {
+    id: target.agentId,
+    label: target.label,
+    tags: [...target.tags, ...target.defaultTags, target.provider],
+    capabilities: [...target.capabilities, ...target.defaultCapabilities],
+  });
+}
+
+export function runnerMessageShouldDirtyObligations(message: Pick<Message, "from">, agentId: string): boolean {
+  return message.from !== agentId;
+}
+
+export function taskIdFromMessage(message: Pick<Message, "payload">): number | undefined {
+  const taskId = message.payload?.taskId;
+  return Number.isSafeInteger(taskId) ? taskId as number : undefined;
+}
+
+export function stripRunnerClaimedGuidance(body: string): string {
+  return body.replace(RUNNER_CLAIMED_GUIDANCE_RE, "");
+}
+
+// Bound a runner's INITIAL relay registration. `connect` resolves on the first `registered`
+// frame and otherwise loops forever, so a token the relay rejects (401 at the WS upgrade)
+// hangs here silently. Race it against `timeoutMs`; on timeout, surface a fatal reason, tear
+// down the bus (stop the retry loop) and throw so the process exits and the orchestrator
+// observes it instead of a silent zombie. Reconnects after first registration stay infinite.
+export async function registerWithinDeadline(
+  bus: { connect: () => Promise<void>; close: () => Promise<void> },
+  timeoutMs: number,
+  relayUrl: string,
+  onFatal: (reason: string) => void,
+): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new Error(
+      `runner failed to register with the relay within ${timeoutMs}ms — aborting so the orchestrator `
+      + `observes the exit instead of a silent hang (relay ${relayUrl}; check the relay is reachable `
+      + `and the runner token is valid).`,
+    )), timeoutMs);
+  });
+  try {
+    await Promise.race([bus.connect(), deadline]);
+  } catch (error) {
+    onFatal(errMessage(error));
+    await bus.close().catch(() => {});
+    throw error;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export function csvTags(raw: string | undefined): string[] {
+  return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
+}
+
+export function relayBusUrl(relayUrl: string): string {
+  const url = new URL(relayUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/bus`;
+  url.search = "";
+  return url.toString();
+}
+
+export function runnerAgentStatus(status: "idle" | "busy" | "offline" | "error"): "idle" | "busy" | "offline" {
+  return status === "error" ? "offline" : status;
+}
+
+export function runnerBusErrorAction(code: string, stopped: boolean): "ignore" | "log" | "stop" {
+  if (code === "STALE_SESSION") return stopped ? "ignore" : "stop";
+  return "log";
+}
+
+export function runnerShouldResolveProviderExit(status: SemanticStatus, exitCommandInProgress: boolean): boolean {
+  return !exitCommandInProgress && (status === "offline" || status === "error");
+}
+
+export function runnerShouldRestartUnexpectedProviderExit(
+  status: SemanticStatus,
+  input: {
+    exitCommandInProgress: boolean;
+    stopped: boolean;
+    restartInProgress: boolean;
+    provider?: string;
+    headless: boolean;
+    hasTerminalSession: boolean;
+  },
+): boolean {
+  return status === "offline"
+    && !input.exitCommandInProgress
+    && !input.stopped
+    && !input.restartInProgress
+    && input.headless
+    && input.hasTerminalSession;
+}
+
+function resumeLogExtractionRe(provider: string): RegExp | undefined {
+  const manifest = getManifest(provider);
+  const resume = manifest?.resume as { supported: boolean; idPattern?: string } | undefined;
+  if (!resume?.supported || !resume.idPattern || !manifest?.probe?.command) return undefined;
+  return new RegExp(`\\b${manifest.probe.command}\\s+--resume\\s+(${resume.idPattern})\\b`, "gi");
+}
+
+export function latestResumeIdFromText(provider: string, text: string): string | undefined {
+  const re = resumeLogExtractionRe(provider);
+  if (!re) return undefined;
+  let latest: string | undefined;
+  for (let match = re.exec(text); match; match = re.exec(text)) {
+    latest = match[1];
+  }
+  return latest;
+}
+
+export function latestResumeIdFromLogFile(provider: string, path: string): string | undefined {
+  let fd: number | undefined;
+  try {
+    const stat = statSync(path);
+    const length = Math.min(stat.size, LOG_TAIL_BYTES);
+    const offset = Math.max(0, stat.size - length);
+    const buffer = Buffer.alloc(length);
+    fd = openSync(path, "r");
+    readSync(fd, buffer, 0, length, offset);
+    return latestResumeIdFromText(provider, buffer.toString("utf8"));
+  } catch {
+    return undefined;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function providerExitDiagnostics(input: {
+  status: SemanticStatus;
+  runtimeMs: number;
+  processMeta?: Record<string, unknown>;
+  hasProcess: boolean;
+  exitCommandInProgress: boolean;
+  stopped: boolean;
+  restartInProgress: boolean;
+  restartPending: boolean;
+  headless: boolean;
+  provider: string;
+  logFile?: string;
+}): Record<string, unknown> {
+  const tmuxSession = typeof input.processMeta?.tmuxSession === "string" ? input.processMeta.tmuxSession : undefined;
+  const tmuxSocket = typeof input.processMeta?.tmuxSocket === "string" ? input.processMeta.tmuxSocket : undefined;
+  const exitSource = tmuxSession ? "tmux-session-ended" : input.hasProcess ? "process-exit" : "provider-status";
+  const claudeResumeId = getManifest(input.provider)?.resume?.supported && input.logFile ? latestResumeIdFromLogFile(input.provider, input.logFile) : undefined;
+  return {
+    status: input.status,
+    runtimeMs: Number.isFinite(input.runtimeMs) ? input.runtimeMs : null,
+    exitSource,
+    exitCommandInProgress: input.exitCommandInProgress,
+    stopped: input.stopped,
+    restartInProgress: input.restartInProgress,
+    restartPending: input.restartPending,
+    headless: input.headless,
+    hasTerminalSession: Boolean(tmuxSession),
+    tmuxSession: tmuxSession ?? null,
+    tmuxSocket: tmuxSocket ?? null,
+    claudeResumeId: claudeResumeId ?? null,
+  };
+}
+
+export function commandTimeoutMs(params: Record<string, unknown>, fallback = 10_000): number {
+  const raw = params.timeoutMs;
+  if (typeof raw !== "number" || !Number.isSafeInteger(raw) || raw <= 0) return fallback;
+  return Math.min(raw, 60_000);
+}
+
+export function shouldLogDeliveryFailure(error: unknown): boolean {
+  const message = errMessage(error);
+  return message !== "no Claude monitor connected";
+}
+
+export function runtimeTokenRenewDelayMs(expiresAtSeconds: number, nowMs = Date.now()): number | undefined {
+  const expiresAtMs = expiresAtSeconds * 1000;
+  const ttlMs = expiresAtMs - nowMs;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) return undefined;
+  const leadMs = Math.min(60 * 60 * 1000, Math.max(60_000, Math.floor(ttlMs * 0.2)));
+  const jitterMs = Math.floor(Math.random() * Math.min(30_000, Math.max(0, leadMs / 2)));
+  return Math.max(1_000, ttlMs - leadMs - jitterMs);
+}
+
+export function runtimeTokenRenewTimerSchedule(delayMs: number): { delayMs: number; renew: boolean } | undefined {
+  if (!Number.isFinite(delayMs) || delayMs <= 0) return undefined;
+  if (delayMs > MAX_TIMER_DELAY_MS) return { delayMs: MAX_TIMER_DELAY_MS, renew: false };
+  return { delayMs, renew: true };
+}
+
+export function lifecycleCapabilities(): Record<string, true> {
+  return {
+    shutdownHard: true,
+    restartHard: true,
+    semanticStatus: true,
+    transportReconnect: true,
+  };
+}
+
+function resolveCondition(condition: ProviderCapabilityCondition, options: RuntimeProviderOptions): boolean {
+  switch (condition) {
+    case "always": return true;
+    case "never": return false;
+    case "headless": return options.headless;
+    case "interactive": return !options.headless;
+    case "approval:read-only": return options.approvalMode === "read-only";
+    case "approval:not-read-only": return options.approvalMode !== "read-only";
+    case "adapter:compact-supports-instructions": return Boolean(options.adapter.compactSupportsInstructions);
+    case "adapter:clear-context": return Boolean(options.adapter.clearContext);
+    default: return false;
+  }
+}
+
+function resolveBooleanDefault(def: BooleanCapabilityDefault, options: RuntimeProviderOptions): boolean {
+  if (typeof def === "boolean") return def;
+  return resolveCondition(def.when, options) ? def.value : def.otherwise;
+}
+
+export function runtimeProviderCapabilities(options: RuntimeProviderOptions, contextState?: ContextState, probeModel?: ProbeModelInfo, quotaState?: QuotaState): ProviderCapabilities {
+  const manifest = getManifest(options.provider);
+  const capDefaults = manifest?.capabilityDefaults;
+  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;
+  const shellMode = runtimeShellMode(options);
+  return {
+    lifecycle: {
+      managed: capDefaults?.lifecycle?.managed ?? true,
+      shutdownHard: capDefaults?.lifecycle?.shutdownHard !== undefined ? resolveBooleanDefault(capDefaults.lifecycle.shutdownHard, options) : true,
+      restartHard: capDefaults?.lifecycle?.restartHard !== undefined ? resolveBooleanDefault(capDefaults.lifecycle.restartHard, options) : true,
+      semanticStatus: capDefaults?.lifecycle?.semanticStatus ?? true,
+      reconnect: capDefaults?.lifecycle?.reconnect ?? true,
+    },
+    model: {
+      provider: options.provider,
+      alias: model,
+      id: model,
+      effort,
+      source: modelSource,
+      confidence: options.model ? "reported" : probeModel?.model ? "reported" : "unknown",
+      lastUpdatedAt: options.startedAt,
+    },
+    session: {
+      approvalMode: options.approvalMode,
+      fileRead: true,
+      fileWrite: options.approvalMode !== "read-only",
+      shell: shellMode !== "none",
+      shellMode,
+      source: "runtime",
+      confidence: "reported",
+      lastUpdatedAt: options.startedAt,
+    },
+    ...runtimeProviderContextCapabilities(options, contextState),
+    ...runtimeProviderQuotaCapabilities(options, quotaState),
+    ...runtimeProviderTerminalCapabilities(options),
+    liveSession: {
+      capture: true,
+      inject: Boolean(options.adapter.deliverInitialPrompt),
+      interrupt: Boolean(options.adapter.interrupt),
+      promptEcho: true,
+      reasoning: true,
+      slashCommands: capDefaults?.liveSession?.slashCommands ?? false,
+    },
+    source: "runtime",
+    confidence: "reported",
+    lastUpdatedAt: options.startedAt,
+  };
+}
+
+function runtimeShellMode(options: RuntimeProviderOptions): NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]> {
+  const manifest = getManifest(options.provider);
+  const shellModeMap = manifest?.capabilityDefaults?.session?.shellMode;
+  if (options.approvalMode === "read-only") return (shellModeMap?.readOnly ?? "none") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+  if (options.approvalMode === "open") return (shellModeMap?.open ?? "unrestricted") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+  return (shellModeMap?.guarded ?? "guarded") as NonNullable<NonNullable<ProviderCapabilities["session"]>["shellMode"]>;
+}
+
+function runtimeProviderTerminalCapabilities(options: RuntimeProviderOptions): Pick<ProviderCapabilities, "terminal"> {
+  const manifest = getManifest(options.provider);
+  const termDefaults = manifest?.capabilityDefaults?.terminal;
+  if (!termDefaults || termDefaults.mode === "none") return {};
+  if (termDefaults.condition && !resolveCondition(termDefaults.condition, options)) return {};
+  if (termDefaults.mode === "live" && termDefaults.live) {
+    return { terminal: { live: termDefaults.live } };
+  }
+  if (termDefaults.mode === "attach" && termDefaults.attach) {
+    return { terminal: { attach: termDefaults.attach } };
+  }
+  return {};
+}
+
+// #557 — the agent-card projection now DESCRIBES the assembled launch (same source the
+// adapter turns into args), so it can't drift from reality. `config`/`providerConfig` are
+// the spawn inputs; when present we assemble (pure — no disk writes here) and report that.
+export function appliedAgentProfileMetadata(
+  provider: string,
+  profile: AgentProfile,
+  config?: RunnerSpawnConfig,
+  providerConfig?: ProviderConfig,
+): Record<string, unknown> {
+  const projection = isSpawnProvider(provider) && config && providerConfig
+    ? agentProfileProjectionReport({ assembled: assembleLaunch(provider, config, providerConfig) })
+    : undefined;
+  return {
+    name: profile.name,
+    base: profile.base,
+    provider: profile.provider ?? "any",
+    relay: profile.relay,
+    instructions: {
+      repoInstructions: profile.instructions.repoInstructions,
+      globalInstructions: profile.instructions.globalInstructions,
+      appendCount: profile.instructions.append.length,
+      hasSystem: Boolean(profile.instructions.system),
+    },
+    skills: profile.skills.filter((item) => item.enabled).length,
+    plugins: profile.plugins.filter((item) => item.enabled).length,
+    mcp: { mode: profile.mcp.mode },
+    hooks: { mode: profile.hooks.mode },
+    permissions: profile.permissions,
+    projection,
+  };
+}
+
+function runtimeProviderContextCapabilities(options: RuntimeProviderOptions, contextState?: ContextState): Pick<ProviderCapabilities, "context"> {
+  const manifest = getManifest(options.provider);
+  const ctxDefaults = manifest?.capabilityDefaults?.context;
+  const context: NonNullable<ProviderCapabilities["context"]> = { resume: "none" };
+  const supportsManagedContext = ctxDefaults?.managed ? resolveCondition(ctxDefaults.managed, options) : false;
+  if (contextState) {
+    context.stats = { source: contextState.source, confidence: contextState.confidence };
+    if (typeof contextState.tokensMax === "number" && Number.isFinite(contextState.tokensMax)) {
+      context.windowTokens = contextState.tokensMax;
+    }
+  }
+  if (ctxDefaults) {
+    if (resolveBooleanDefault(ctxDefaults.compact, options)) context.compact = true;
+    if (resolveBooleanDefault(ctxDefaults.clear, options)) context.clear = true;
+    context.inject = ctxDefaults.inject;
+  }
+  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 } : {};
+}
+
+function runtimeProviderQuotaCapabilities(options: RuntimeProviderOptions, quotaState?: QuotaState): Pick<ProviderCapabilities, "quota"> {
+  const manifest = getManifest(options.provider);
+  const quotaDefaults = manifest?.capabilityDefaults?.quota;
+  if (!quotaDefaults?.supported) return {};
+  return {
+    quota: {
+      supported: true,
+      source: quotaState?.source ?? "probe",
+      unit: quotaState?.windows[0]?.unit ?? "%",
+      windows: quotaState?.windows.map((window) => ({
+        name: window.name,
+        unit: window.unit,
+        reset: window.resetsAt !== undefined,
+      })) ?? manifest!.quotaWindows.map(w => ({ name: w.name, unit: w.unit as "%" | "tokens" | "requests", reset: w.reset })),
+    },
+  };
+}
+
+export function providerStateFromActiveWork(activeWork: Array<{ kind: string; metadata?: Record<string, unknown> }>): ProviderState | null {
+  const providerTurn = activeWork.find((item) => item.kind === "provider-turn");
+  const state = providerTurn?.metadata?.providerState;
+  return state && typeof state === "object" && !Array.isArray(state) && typeof (state as { state?: unknown }).state === "string"
+    ? state as ProviderState
+    : null;
+}
+
+export function isHttpAuthError(error: unknown): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === 401 || status === 403;
+}
+
+export function isHttpStatusError(error: unknown, code: number): boolean {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  return status === code;
+}
+
+export function httpErrorKey(error: unknown): string {
+  const status = typeof error === "object" && error !== null ? (error as { status?: unknown }).status : undefined;
+  if (typeof status === "number") return `status:${status}`;
+  return String(error);
+}
+
+export function isContextState(value: unknown): value is ContextState {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const state = value as Record<string, unknown>;
+  return typeof state.utilization === "number" &&
+    typeof state.lifecycleState === "string" &&
+    typeof state.source === "string" &&
+    typeof state.confidence === "string";
+}

package/runner/src/runner-insights.ts

@@ -0,0 +1,105 @@
+import type { WorkspaceMetadata } from "agent-relay-sdk";
+import type { ManagedProcess, ProviderAdapter } from "./adapter";
+import type { Outbox } from "./outbox";
+import type { SessionDestroyReason } from "./session-destroy";
+import { resolveProjectName } from "./config";
+import { computeContextRatio } from "./session-insights";
+import { boundContinuationArchiveSegment } from "./continuation-archive";
+
+interface RunnerInsightsDeps {
+  agentId: string;
+  cwd: string;
+  workspace?: WorkspaceMetadata;
+  getOutbox(): Outbox;
+  getProviderSessionId(): string;
+  getProcess(): ManagedProcess | undefined;
+  getAdapter(): ProviderAdapter;
+  getLastTranscriptPath(): string | undefined;
+  sessionLog(message: string): void;
+}
+
+export class RunnerInsights {
+  private insightsObserved = 0;
+  private insightsCursorKey = "";
+  private archiveObservedChars = 0;
+  private archiveCursorKey = "";
+  private projectName?: string;
+
+  constructor(private readonly deps: RunnerInsightsDeps) {}
+
+  project(): string {
+    return (this.projectName ??= resolveProjectName(this.deps.cwd, this.deps.workspace));
+  }
+
+  queueHookFatal(report: { hook: string; error: string }): void {
+    this.deps.getOutbox().enqueue({
+      kind: "insight",
+      payload: {
+        sessionId: this.deps.getProviderSessionId(),
+        project: this.project(),
+        agentId: this.deps.agentId,
+        signal: "hook_fatal",
+        value: { hook: report.hook, error: report.error },
+        source: "server",
+      },
+    });
+  }
+
+  async captureContinuationArchive(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.deps.getAdapter();
+    const process = this.deps.getProcess();
+    if (!adapter.collectSessionArchiveSegment || !process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.deps.getLastTranscriptPath();
+    const archive = await adapter.collectSessionArchiveSegment(process, { transcriptPath });
+    if (!archive) return;
+    const key = transcriptPath ?? `session:${this.deps.getProviderSessionId()}`;
+    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;
+    const bounded = boundContinuationArchiveSegment(segment);
+    if (bounded.droppedBytes > 0) this.deps.sessionLog(`continuation archive truncated at ${bounded.keptBytes} bytes; dropped ${bounded.droppedBytes} bytes (${reason})`);
+    this.deps.getOutbox().enqueue({
+      kind: "continuation-archive",
+      payload: {
+        agentId: this.deps.agentId,
+        segment: bounded.segment,
+      },
+    });
+    this.deps.sessionLog(`continuation archive queued (${bounded.segment.length} chars, ${reason})`);
+  }
+
+  async captureContextRatio(reason: SessionDestroyReason, opts?: { transcriptPath?: string }): Promise<void> {
+    const adapter = this.deps.getAdapter();
+    const process = this.deps.getProcess();
+    if (!adapter.collectSessionEvents || !process) return;
+    const transcriptPath = opts?.transcriptPath ?? this.deps.getLastTranscriptPath();
+    const events = await adapter.collectSessionEvents(process, { transcriptPath });
+    if (!events) return;
+    const key = transcriptPath ?? `session:${this.deps.getProviderSessionId()}`;
+    if (key !== this.insightsCursorKey || events.length < this.insightsObserved) {
+      this.insightsCursorKey = key;
+      this.insightsObserved = 0;
+    }
+    const segment = events.slice(this.insightsObserved);
+    this.insightsObserved = events.length;
+    const analysis = computeContextRatio(segment);
+    if (!analysis) return;
+    this.deps.getOutbox().enqueue({
+      kind: "insight",
+      payload: {
+        sessionId: this.deps.getProviderSessionId(),
+        project: this.project(),
+        agentId: this.deps.agentId,
+        signal: "context_ratio",
+        value: { ...analysis.metric, endReason: reason },
+        outcome: { ...analysis.outcome },
+        source: "server",
+      },
+    });
+    this.deps.sessionLog(`insights: context_ratio ${analysis.metric.ratio.toFixed(2)} (${analysis.metric.gatheringCalls}/${analysis.metric.totalToolCalls} gathering, ${reason}) queued`);
+  }
+}

package/runner/src/runner.ts

@@ -0,0 +1,14 @@
+export { AgentRunner } from "./runner-core";
+export {
+  latestResumeIdFromText,
+  runnerAgentStatus,
+  runnerBusErrorAction,
+  runnerMessageMatches,
+  runnerShouldResolveProviderExit,
+  runnerShouldRestartUnexpectedProviderExit,
+  runtimeTokenRenewDelayMs,
+  runtimeTokenRenewTimerSchedule,
+  shouldLogDeliveryFailure,
+  stripRunnerClaimedGuidance,
+  taskIdFromMessage,
+} from "./runner-helpers";

package/runner/src/session-destroy.ts

@@ -0,0 +1,22 @@
+export type SessionDestroyReason = "compact" | "clear" | "restart" | "shutdown" | "kill" | "crash";
+
+export type LifecycleAction =
+  | "shutting-down" | "killing" | "restarting"
+  | `finalizing-${SessionDestroyReason}`;
+
+export const PRE_DESTROY_TIMEOUT_MS = 4_000;
+
+export function reasonExitsRunner(reason: SessionDestroyReason): boolean {
+  return reason === "shutdown" || reason === "kill" || reason === "crash";
+}
+
+export function boundaryReasonForCommand(type: string): SessionDestroyReason | undefined {
+  switch (type) {
+    case "agent.compact": return "compact";
+    case "agent.clearContext": return "clear";
+    case "agent.restart": return "restart";
+    case "agent.shutdown": return "shutdown";
+    case "agent.kill": return "kill";
+    default: return undefined;
+  }
+}