@rk0429/agentic-relay 0.4.0 → 0.5.0

package/dist/relay.mjs

@@ -190,7 +190,7 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       sessionId: "",
       exitCode: 1,
       stdout: "",
-      stderr: `Backend "${input.backend}" is not installed`
+      stderr: `Backend "${input.backend}" is not available. Use list_available_backends to see available options.`
     };
   }
   const session = await sessionManager2.create({
@@ -219,29 +219,40 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
     }
   }
   try {
-    const result = await adapter.execute({
-      prompt: input.prompt,
-      agent: input.agent,
-      model: input.model,
-      maxTurns: input.maxTurns,
-      resume: input.resumeSessionId,
-      mcpContext: {
-        parentSessionId: session.relaySessionId,
-        depth: envContext.depth + 1,
-        maxDepth: guard.getConfig().maxDepth,
-        traceId: envContext.traceId
+    let result;
+    if (input.resumeSessionId) {
+      if (!adapter.continueSession) {
+        return {
+          sessionId: session.relaySessionId,
+          exitCode: 1,
+          stdout: "",
+          stderr: `Backend "${input.backend}" does not support session continuation (continueSession).`
+        };
       }
-    });
+      result = await adapter.continueSession(input.resumeSessionId, input.prompt);
+    } else {
+      result = await adapter.execute({
+        prompt: input.prompt,
+        agent: input.agent,
+        systemPrompt: input.systemPrompt,
+        model: input.model,
+        maxTurns: input.maxTurns,
+        mcpContext: {
+          parentSessionId: session.relaySessionId,
+          depth: envContext.depth + 1,
+          maxDepth: guard.getConfig().maxDepth,
+          traceId: envContext.traceId
+        }
+      });
+    }
     if (contextMonitor2) {
       const estimatedTokens = Math.ceil(
         (result.stdout.length + result.stderr.length) / 4
       );
-      const maxTokens = input.backend === "gemini" ? 128e3 : 2e5;
       contextMonitor2.updateUsage(
         session.relaySessionId,
         input.backend,
-        estimatedTokens,
-        maxTokens
+        estimatedTokens
       );
     }
     guard.recordSpawn(context);
@@ -270,7 +281,8 @@ async function executeSpawnAgent(input, registry2, sessionManager2, guard, hooks
       sessionId: session.relaySessionId,
       exitCode: result.exitCode,
       stdout: result.stdout,
-      stderr: result.stderr
+      stderr: result.stderr,
+      nativeSessionId: result.nativeSessionId
     };
   } catch (error) {
     await sessionManager2.update(session.relaySessionId, { status: "error" });
@@ -293,6 +305,7 @@ var init_spawn_agent = __esm({
       backend: z2.enum(["claude", "codex", "gemini"]),
       prompt: z2.string(),
       agent: z2.string().optional(),
+      systemPrompt: z2.string().optional(),
       resumeSessionId: z2.string().optional(),
       model: z2.string().optional(),
       maxTurns: z2.number().optional()
@@ -339,8 +352,14 @@ async function executeGetContextStatus(input, sessionManager2, contextMonitor2)
     if (usage) {
       return {
         sessionId: input.sessionId,
+        backendId: usage.backendId,
         usagePercent: usage.usagePercent,
-        isEstimated: usage.isEstimated
+        isEstimated: usage.isEstimated,
+        contextWindow: usage.contextWindow,
+        compactThreshold: usage.compactThreshold,
+        estimatedTokens: usage.estimatedTokens,
+        remainingBeforeCompact: usage.remainingBeforeCompact,
+        notifyThreshold: usage.notifyThreshold
       };
     }
   }
@@ -360,6 +379,24 @@ var init_get_context_status = __esm({
   }
 });
 
+// src/mcp-server/tools/list-available-backends.ts
+async function executeListAvailableBackends(registry2) {
+  const backends = [];
+  for (const adapter of registry2.list()) {
+    const health = await adapter.checkHealth();
+    backends.push({
+      id: adapter.id,
+      ...health
+    });
+  }
+  return backends;
+}
+var init_list_available_backends = __esm({
+  "src/mcp-server/tools/list-available-backends.ts"() {
+    "use strict";
+  }
+});
+
 // src/mcp-server/server.ts
 var server_exports = {};
 __export(server_exports, {
@@ -379,6 +416,7 @@ var init_server = __esm({
     init_spawn_agent();
     init_list_sessions();
     init_get_context_status();
+    init_list_available_backends();
     init_logger();
     RelayMCPServer = class {
       constructor(registry2, sessionManager2, guardConfig, hooksEngine2, contextMonitor2) {
@@ -398,11 +436,14 @@ var init_server = __esm({
       registerTools() {
         this.server.tool(
           "spawn_agent",
-          "Spawn a sub-agent on the specified backend CLI (Claude Code, Codex CLI, or Gemini CLI). The agent executes the given prompt in non-interactive mode and returns the result.",
+          "Spawn a sub-agent on the specified backend CLI (Claude Code, Codex CLI, or Gemini CLI). The agent executes the given prompt in non-interactive mode and returns the result. Use 'agent' for named agent configurations (Claude only), or 'systemPrompt' for custom role instructions (all backends).",
           {
             backend: z5.enum(["claude", "codex", "gemini"]),
             prompt: z5.string(),
-            agent: z5.string().optional(),
+            agent: z5.string().optional().describe("Named agent configuration (Claude only)"),
+            systemPrompt: z5.string().optional().describe(
+              "System prompt / role instructions for the sub-agent (all backends)"
+            ),
             resumeSessionId: z5.string().optional(),
             model: z5.string().optional(),
             maxTurns: z5.number().optional()
@@ -494,6 +535,30 @@ ${result.stdout}`;
             }
           }
         );
+        this.server.tool(
+          "list_available_backends",
+          "List all registered backends with their health status. Use this before spawn_agent to check which backends are available.",
+          {},
+          async () => {
+            try {
+              const result = await executeListAvailableBackends(this.registry);
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                  }
+                ]
+              };
+            } catch (error) {
+              const message = error instanceof Error ? error.message : String(error);
+              return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true
+              };
+            }
+          }
+        );
       }
       async start(options) {
         const transportType = options?.transport ?? "stdio";
@@ -698,6 +763,42 @@ var BaseAdapter = class {
     }
     return result.stdout.trim();
   }
+  async continueSession(_nativeSessionId, _prompt) {
+    return {
+      exitCode: 1,
+      stdout: "",
+      stderr: `continueSession not supported for ${this.id}`
+    };
+  }
+  async checkHealth() {
+    const HEALTH_TIMEOUT = 5e3;
+    const installed = await Promise.race([
+      this.isInstalled(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => false);
+    if (!installed) {
+      return {
+        installed: false,
+        authenticated: false,
+        healthy: false,
+        message: `${this.id} is not installed`
+      };
+    }
+    const version = await Promise.race([
+      this.getVersion(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => void 0);
+    return {
+      installed: true,
+      authenticated: true,
+      healthy: true,
+      version
+    };
+  }
   async getMCPConfig() {
     logger.warn(`getMCPConfig not implemented for ${this.id}`);
     return [];
@@ -799,6 +900,48 @@ var ClaudeAdapter = class extends BaseAdapter {
   getConfigPath() {
     return join(homedir(), ".claude.json");
   }
+  async checkHealth() {
+    const HEALTH_TIMEOUT = 5e3;
+    const installed = await Promise.race([
+      this.isInstalled(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => false);
+    if (!installed) {
+      return {
+        installed: false,
+        authenticated: false,
+        healthy: false,
+        message: "claude is not installed"
+      };
+    }
+    const version = await Promise.race([
+      this.getVersion(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => void 0);
+    let authenticated = true;
+    try {
+      const result = await Promise.race([
+        this.processManager.execute(this.command, ["auth", "status"]),
+        new Promise(
+          (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+        )
+      ]);
+      authenticated = result.exitCode === 0;
+    } catch {
+      authenticated = true;
+    }
+    return {
+      installed: true,
+      authenticated,
+      healthy: authenticated,
+      version,
+      ...!authenticated ? { message: "claude authentication not configured" } : {}
+    };
+  }
   mapFlags(flags) {
     return {
       args: mapCommonToNative("claude", flags)
@@ -825,7 +968,8 @@ var ClaudeAdapter = class extends BaseAdapter {
         env,
         cwd: process.cwd(),
         ...flags.model ? { model: flags.model } : {},
-        ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {}
+        ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {},
+        ...flags.systemPrompt ? { systemPrompt: flags.systemPrompt } : {}
       };
       if (permissionMode === "bypassPermissions") {
         options.permissionMode = "bypassPermissions";
@@ -877,7 +1021,8 @@ var ClaudeAdapter = class extends BaseAdapter {
         env,
         cwd: process.cwd(),
         ...flags.model ? { model: flags.model } : {},
-        ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {}
+        ...flags.maxTurns ? { maxTurns: flags.maxTurns } : {},
+        ...flags.systemPrompt ? { systemPrompt: flags.systemPrompt } : {}
       };
       if (permissionMode === "bypassPermissions") {
         options.permissionMode = "bypassPermissions";
@@ -942,6 +1087,44 @@ var ClaudeAdapter = class extends BaseAdapter {
       };
     }
   }
+  async continueSession(nativeSessionId, prompt) {
+    try {
+      const { query } = await loadClaudeSDK();
+      const permissionMode = this.getPermissionMode();
+      const options = {
+        resume: nativeSessionId,
+        maxTurns: 1,
+        cwd: process.cwd()
+      };
+      if (permissionMode === "bypassPermissions") {
+        options.permissionMode = "bypassPermissions";
+        options.allowDangerouslySkipPermissions = true;
+      }
+      const q = query({
+        prompt,
+        options
+      });
+      let resultText = "";
+      for await (const message of q) {
+        if (message.type === "result") {
+          if (message.subtype === "success") {
+            resultText = message.result;
+          }
+        }
+      }
+      return {
+        exitCode: 0,
+        stdout: resultText,
+        stderr: ""
+      };
+    } catch (error) {
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
   async resumeSession(sessionId, flags) {
     await this.processManager.spawnInteractive(
       this.command,
@@ -1157,6 +1340,48 @@ var CodexAdapter = class extends BaseAdapter {
   getConfigPath() {
     return join2(homedir2(), ".codex", "config.toml");
   }
+  async checkHealth() {
+    const HEALTH_TIMEOUT = 5e3;
+    const installed = await Promise.race([
+      this.isInstalled(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => false);
+    if (!installed) {
+      return {
+        installed: false,
+        authenticated: false,
+        healthy: false,
+        message: "codex is not installed"
+      };
+    }
+    const version = await Promise.race([
+      this.getVersion(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => void 0);
+    let authenticated = true;
+    try {
+      const result = await Promise.race([
+        this.processManager.execute(this.command, ["login", "status"]),
+        new Promise(
+          (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+        )
+      ]);
+      authenticated = result.exitCode === 0;
+    } catch {
+      authenticated = true;
+    }
+    return {
+      installed: true,
+      authenticated,
+      healthy: authenticated,
+      version,
+      ...!authenticated ? { message: "codex authentication not configured" } : {}
+    };
+  }
   mapFlags(flags) {
     const args = mapCommonToNative("codex", flags);
     if (flags.outputFormat === "json") {
@@ -1174,15 +1399,39 @@ var CodexAdapter = class extends BaseAdapter {
     }
     await this.processManager.spawnInteractive(this.command, args);
   }
+  /**
+   * Resolve the effective system prompt from flags.
+   * Priority: systemPrompt > agent fallback > none
+   */
+  resolveSystemPrompt(flags) {
+    if (flags.systemPrompt) return flags.systemPrompt;
+    if (flags.agent) {
+      return `You are acting as the "${flags.agent}" agent. Follow the instructions and role defined for this agent.`;
+    }
+    return void 0;
+  }
+  /**
+   * Build the effective prompt with system instructions prepended if needed.
+   * Codex SDK does not support a native instructions/systemPrompt parameter,
+   * so we inject role context via a prompt prefix.
+   */
+  buildEffectivePrompt(prompt, systemPrompt) {
+    if (!systemPrompt) return prompt;
+    return `[System Instructions]
+${systemPrompt}
+
+[User Request]
+${prompt}`;
+  }
   async execute(flags) {
     if (!flags.prompt) {
       throw new Error("execute requires a prompt (-p flag)");
     }
-    if (flags.agent) {
-      logger.warn(
-        `Codex CLI does not support --agent flag. Ignoring agent "${flags.agent}".`
-      );
-    }
+    const systemPrompt = this.resolveSystemPrompt(flags);
+    const effectivePrompt = this.buildEffectivePrompt(
+      flags.prompt,
+      systemPrompt
+    );
     try {
       const { Codex } = await loadCodexSDK();
       const codexOptions = {};
@@ -1200,11 +1449,12 @@ var CodexAdapter = class extends BaseAdapter {
         workingDirectory: process.cwd(),
         approvalPolicy: "never"
       });
-      const result = await thread.run(flags.prompt);
+      const result = await thread.run(effectivePrompt);
       return {
         exitCode: 0,
         stdout: result.finalResponse,
-        stderr: ""
+        stderr: "",
+        ...thread.id ? { nativeSessionId: thread.id } : {}
       };
     } catch (error) {
       return {
@@ -1218,11 +1468,11 @@ var CodexAdapter = class extends BaseAdapter {
     if (!flags.prompt) {
       throw new Error("executeStreaming requires a prompt (-p flag)");
     }
-    if (flags.agent) {
-      logger.warn(
-        `Codex CLI does not support --agent flag. Ignoring agent "${flags.agent}".`
-      );
-    }
+    const systemPrompt = this.resolveSystemPrompt(flags);
+    const effectivePrompt = this.buildEffectivePrompt(
+      flags.prompt,
+      systemPrompt
+    );
     try {
       const { Codex } = await loadCodexSDK();
       const codexOptions = {};
@@ -1240,10 +1490,13 @@ var CodexAdapter = class extends BaseAdapter {
         workingDirectory: process.cwd(),
         approvalPolicy: "never"
       });
-      const streamedTurn = await thread.runStreamed(flags.prompt);
+      const streamedTurn = await thread.runStreamed(effectivePrompt);
       const completedMessages = [];
+      let threadId;
       for await (const event of streamedTurn.events) {
-        if (event.type === "item.started") {
+        if (event.type === "thread.started") {
+          threadId = event.thread_id;
+        } else if (event.type === "item.started") {
           const item = event.item;
           if (item?.type === "agent_message" && item.text) {
             yield { type: "text", text: item.text };
@@ -1291,13 +1544,15 @@ var CodexAdapter = class extends BaseAdapter {
           const finalResponse = completedMessages.join("\n");
           yield {
             type: "done",
-            result: { exitCode: 0, stdout: finalResponse, stderr: "" }
+            result: { exitCode: 0, stdout: finalResponse, stderr: "" },
+            nativeSessionId: threadId ?? thread.id ?? void 0
           };
         } else if (event.type === "turn.failed") {
           const errorMessage = event.error?.message ?? "Turn failed";
           yield {
             type: "done",
-            result: { exitCode: 1, stdout: "", stderr: errorMessage }
+            result: { exitCode: 1, stdout: "", stderr: errorMessage },
+            nativeSessionId: threadId ?? thread.id ?? void 0
           };
         } else if (event.type === "error") {
           yield {
@@ -1315,6 +1570,28 @@ var CodexAdapter = class extends BaseAdapter {
       };
     }
   }
+  async continueSession(nativeSessionId, prompt) {
+    try {
+      const { Codex } = await loadCodexSDK();
+      const codex = new Codex();
+      const thread = codex.resumeThread(nativeSessionId, {
+        workingDirectory: process.cwd(),
+        approvalPolicy: "never"
+      });
+      const result = await thread.run(prompt);
+      return {
+        exitCode: 0,
+        stdout: result.finalResponse,
+        stderr: ""
+      };
+    } catch (error) {
+      return {
+        exitCode: 1,
+        stdout: "",
+        stderr: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
   async resumeSession(sessionId, flags) {
     const args = [];
     if (flags.model) {
@@ -1408,6 +1685,38 @@ var GeminiAdapter = class extends BaseAdapter {
   getConfigPath() {
     return join3(homedir3(), ".gemini", "settings.json");
   }
+  async checkHealth() {
+    const HEALTH_TIMEOUT = 5e3;
+    const installed = await Promise.race([
+      this.isInstalled(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => false);
+    if (!installed) {
+      return {
+        installed: false,
+        authenticated: false,
+        healthy: false,
+        message: "gemini is not installed"
+      };
+    }
+    const version = await Promise.race([
+      this.getVersion(),
+      new Promise(
+        (_, reject) => setTimeout(() => reject(new Error("timeout")), HEALTH_TIMEOUT)
+      )
+    ]).catch(() => void 0);
+    const hasApiKey = !!process.env["GEMINI_API_KEY"];
+    const hasGoogleAdc = !!process.env["GOOGLE_APPLICATION_CREDENTIALS"] || !!process.env["CLOUDSDK_CONFIG"];
+    const authenticated = hasApiKey || hasGoogleAdc || true;
+    return {
+      installed: true,
+      authenticated,
+      healthy: true,
+      version
+    };
+  }
   mapFlags(flags) {
     const args = mapCommonToNative("gemini", flags);
     if (flags.outputFormat) {
@@ -1428,15 +1737,34 @@ var GeminiAdapter = class extends BaseAdapter {
     }
     await this.processManager.spawnInteractive(this.command, args);
   }
+  /**
+   * Resolve the effective prompt with system instructions prepended if needed.
+   * Gemini CLI has no native system prompt flag, so we use a prompt prefix.
+   * Priority: systemPrompt > agent fallback > none
+   */
+  buildEffectivePrompt(flags) {
+    const prompt = flags.prompt;
+    if (flags.systemPrompt) {
+      return `[System Instructions]
+${flags.systemPrompt}
+
+[User Request]
+${prompt}`;
+    }
+    if (flags.agent) {
+      return `[System Instructions]
+You are acting as the "${flags.agent}" agent.
+
+[User Request]
+${prompt}`;
+    }
+    return prompt;
+  }
   async execute(flags) {
     if (!flags.prompt) {
       throw new Error("execute requires a prompt (-p flag)");
     }
-    if (flags.agent) {
-      logger.warn(
-        `Gemini CLI does not support --agent flag. Ignoring agent "${flags.agent}".`
-      );
-    }
+    const effectivePrompt = this.buildEffectivePrompt(flags);
     const args = [];
     if (flags.model) {
       args.push("--model", flags.model);
@@ -1447,7 +1775,7 @@ var GeminiAdapter = class extends BaseAdapter {
     if (flags.verbose) {
       args.push("--verbose");
     }
-    args.push("-p", flags.prompt);
+    args.push("-p", effectivePrompt);
     return this.processManager.execute(this.command, args);
   }
   async resumeSession(sessionId, flags) {
@@ -1721,6 +2049,10 @@ var hookDefinitionSchema = z.object({
 var hooksConfigSchema = z.object({
   definitions: z.array(hookDefinitionSchema)
 });
+var backendContextConfigSchema = z.object({
+  contextWindow: z.number().positive().optional(),
+  compactThreshold: z.number().positive().optional()
+}).optional();
 var relayConfigSchema = z.object({
   defaultBackend: backendIdSchema.optional(),
   mcpServers: z.record(mcpServerConfigSchema).optional(),
@@ -1731,9 +2063,16 @@ var relayConfigSchema = z.object({
   }).optional(),
   hooks: hooksConfigSchema.optional(),
   contextMonitor: z.object({
-    enabled: z.boolean(),
-    thresholdPercent: z.number().min(0).max(100),
-    notifyMethod: z.enum(["stderr", "hook"])
+    enabled: z.boolean().optional(),
+    thresholdPercent: z.number().min(0).max(100).optional(),
+    notifyThreshold: z.number().positive().optional(),
+    notifyPercent: z.number().min(0).max(100).optional(),
+    notifyMethod: z.enum(["stderr", "hook"]).optional(),
+    backends: z.object({
+      claude: backendContextConfigSchema,
+      codex: backendContextConfigSchema,
+      gemini: backendContextConfigSchema
+    }).optional()
   }).optional(),
   mcpServerMode: z.object({
     maxDepth: z.number().int().positive(),
@@ -2129,34 +2468,75 @@ var HooksEngine = class _HooksEngine {
 };
 
 // src/core/context-monitor.ts
+var DEFAULT_BACKEND_CONTEXT = {
+  claude: { contextWindow: 2e5, compactThreshold: 19e4 },
+  codex: { contextWindow: 272e3, compactThreshold: 258400 },
+  gemini: { contextWindow: 1048576, compactThreshold: 524288 }
+};
+var DEFAULT_NOTIFY_PERCENT = 70;
 var DEFAULT_CONFIG = {
   enabled: true,
-  thresholdPercent: 75,
-  notifyMethod: "stderr"
+  notifyMethod: "hook"
 };
 var ContextMonitor = class {
   constructor(hooksEngine2, config) {
     this.hooksEngine = hooksEngine2;
     this.config = { ...DEFAULT_CONFIG, ...config };
+    if (this.config.thresholdPercent !== void 0 && this.config.notifyPercent === void 0 && this.config.notifyThreshold === void 0) {
+      this.config.notifyPercent = this.config.thresholdPercent;
+    }
   }
   config;
   usageMap = /* @__PURE__ */ new Map();
+  /** Get backend context config, merging user overrides with defaults */
+  getBackendConfig(backendId) {
+    const defaults = DEFAULT_BACKEND_CONTEXT[backendId];
+    const overrides = this.config.backends?.[backendId];
+    return {
+      contextWindow: overrides?.contextWindow ?? defaults.contextWindow,
+      compactThreshold: overrides?.compactThreshold ?? defaults.compactThreshold
+    };
+  }
+  /** Calculate the notification threshold in tokens for a given backend */
+  getNotifyThreshold(backendId) {
+    if (this.config.notifyThreshold !== void 0) {
+      return this.config.notifyThreshold;
+    }
+    const backendConfig = this.getBackendConfig(backendId);
+    const notifyPercent = this.config.notifyPercent ?? DEFAULT_NOTIFY_PERCENT;
+    return Math.round(backendConfig.contextWindow * notifyPercent / 100);
+  }
   /** Update token usage for a session and check threshold */
-  updateUsage(sessionId, backendId, estimatedTokens, maxTokens) {
+  updateUsage(sessionId, backendId, estimatedTokens) {
     if (!this.config.enabled) return;
-    const usagePercent = maxTokens > 0 ? Math.round(estimatedTokens / maxTokens * 100) : 0;
+    const backendConfig = this.getBackendConfig(backendId);
+    const contextWindow = backendConfig.contextWindow;
+    const usagePercent = contextWindow > 0 ? Math.round(estimatedTokens / contextWindow * 100) : 0;
     const existing = this.usageMap.get(sessionId);
-    const wasNotified = existing?.notified ?? false;
+    let wasNotified = existing?.notified ?? false;
+    if (existing && estimatedTokens < existing.estimatedTokens * 0.7) {
+      wasNotified = false;
+    }
     this.usageMap.set(sessionId, {
       estimatedTokens,
-      maxTokens,
+      contextWindow,
+      compactThreshold: backendConfig.compactThreshold,
       usagePercent,
       backendId,
       notified: wasNotified
     });
-    if (usagePercent >= this.config.thresholdPercent && !wasNotified) {
-      this.usageMap.get(sessionId).notified = true;
-      this.notify(sessionId, backendId, usagePercent);
+    const notifyAt = this.getNotifyThreshold(backendId);
+    if (estimatedTokens >= notifyAt && !wasNotified) {
+      const entry = this.usageMap.get(sessionId);
+      entry.notified = true;
+      this.notify(
+        sessionId,
+        backendId,
+        usagePercent,
+        estimatedTokens,
+        contextWindow,
+        backendConfig.compactThreshold
+      );
     }
   }
   /** Get usage info for a session */
@@ -2165,17 +2545,31 @@ var ContextMonitor = class {
     if (!entry) return null;
     return {
       usagePercent: entry.usagePercent,
-      isEstimated: true
+      isEstimated: true,
+      backendId: entry.backendId,
+      contextWindow: entry.contextWindow,
+      compactThreshold: entry.compactThreshold,
+      estimatedTokens: entry.estimatedTokens,
+      remainingBeforeCompact: Math.max(
+        0,
+        entry.compactThreshold - entry.estimatedTokens
+      ),
+      notifyThreshold: this.getNotifyThreshold(entry.backendId)
     };
   }
   /** Remove usage tracking for a session */
   removeSession(sessionId) {
     this.usageMap.delete(sessionId);
   }
-  notify(sessionId, backendId, usagePercent) {
+  notify(sessionId, backendId, usagePercent, currentTokens, contextWindow, compactThreshold) {
+    const remainingBeforeCompact = Math.max(
+      0,
+      compactThreshold - currentTokens
+    );
+    const warningMessage = `${backendId} session ${sessionId} at ${usagePercent}% (${currentTokens}/${contextWindow} tokens). Compact in ~${remainingBeforeCompact} tokens. Save your work state now.`;
     if (this.config.notifyMethod === "stderr") {
       process.stderr.write(
-        `[relay] Context usage warning: session ${sessionId} is at ${usagePercent}% (threshold: ${this.config.thresholdPercent}%)
+        `[relay] Context warning: ${warningMessage}
 `
       );
     } else if (this.config.notifyMethod === "hook" && this.hooksEngine) {
@@ -2186,7 +2580,10 @@ var ContextMonitor = class {
         timestamp: (/* @__PURE__ */ new Date()).toISOString(),
         data: {
           usagePercent,
-          thresholdPercent: this.config.thresholdPercent
+          currentTokens,
+          contextWindow,
+          compactThreshold,
+          remainingBeforeCompact
         }
       };
       void this.hooksEngine.emit("on-context-threshold", hookInput);
@@ -2323,6 +2720,7 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
       try {
         if (flags.prompt) {
           logger.debug(`Executing prompt on ${backendId}`);
+          let nativeSessionId;
           if (adapter.executeStreaming) {
             for await (const event of adapter.executeStreaming(flags)) {
               switch (event.type) {
@@ -2353,18 +2751,17 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
                   break;
                 case "usage": {
                   if (contextMonitor2 && relaySessionId) {
-                    const maxTokens = backendId === "gemini" ? 128e3 : 2e5;
                     contextMonitor2.updateUsage(
                       relaySessionId,
                       backendId,
-                      event.inputTokens + event.outputTokens,
-                      maxTokens
+                      event.inputTokens + event.outputTokens
                     );
                   }
                   break;
                 }
                 case "done":
                   process.exitCode = event.result.exitCode;
+                  nativeSessionId = event.nativeSessionId;
                   if (event.nativeSessionId && sessionManager2 && relaySessionId) {
                     try {
                       await sessionManager2.update(relaySessionId, {
@@ -2381,6 +2778,7 @@ function createBackendCommand(backendId, registry2, sessionManager2, hooksEngine
             if (result.stdout) process.stdout.write(result.stdout);
             if (result.stderr) process.stderr.write(result.stderr);
             process.exitCode = result.exitCode;
+            nativeSessionId = result.nativeSessionId;
             if (result.nativeSessionId && sessionManager2 && relaySessionId) {
               try {
                 await sessionManager2.update(relaySessionId, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rk0429/agentic-relay",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Unified CLI proxy for Claude Code, Codex CLI, and Gemini CLI with MCP-based multi-layer sub-agent orchestration",
   "type": "module",
   "license": "Apache-2.0",