agent-relay-runner 0.11.3 → 0.11.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.2"
+    "agent-relay-sdk": "0.2.4"
   },
   "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.11.3",
+  "version": "0.11.5",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/plugins/claude/monitors/relay-monitor.ts

@@ -1,6 +1,6 @@
 import type { Message } from "agent-relay-sdk";
 import { claudeProviderMessageText } from "../../../src/adapters/claude-delivery";
-import { CLAUDE_READ_ONLY_RELAY_CONTEXT, CLAUDE_RELAY_CONTEXT } from "../../../src/relay-instructions";
+import { CLAUDE_READ_ONLY_RELAY_CONTEXT, CLAUDE_RELAY_CONTEXT, workspaceDepsNoteFromEnv } from "../../../src/relay-instructions";
 
 const port = process.env.AGENT_RELAY_RUNNER_PORT;
 if (!port) process.exit(0);
@@ -16,6 +16,11 @@ ws.onmessage = (event) => {
   deliveryCount += 1;
   if (firstDelivery) {
     console.log(process.env.AGENT_RELAY_APPROVAL === "read-only" ? CLAUDE_READ_ONLY_RELAY_CONTEXT : CLAUDE_RELAY_CONTEXT);
+    const wsNote = workspaceDepsNoteFromEnv();
+    if (wsNote) {
+      console.log("");
+      console.log(wsNote);
+    }
     console.log("");
     firstDelivery = false;
   }

package/src/adapters/codex.ts

@@ -3,6 +3,13 @@ import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { ContextState, Message } from "agent-relay-sdk";
 import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
+import { workspaceDepsNoteFromEnv } from "../relay-instructions";
+
+/** Relay context prepended to a Codex agent's first turn: the standard relay
+ * blurb plus, when running in an isolated workspace, the deps caveat (#159). */
+function codexRelayContextBlock(): string {
+  return [RELAY_CONTEXT, workspaceDepsNoteFromEnv()].filter(Boolean).join("\n\n");
+}
 import { prepareCodexProfileHome, profileUsesHostProviderGlobals } from "../profile-home";
 import { CodexAppClient, type ClientEvent } from "./codex-client";
 
@@ -159,7 +166,7 @@ export class CodexAdapter implements ProviderAdapter {
       text,
     ].filter(Boolean).join("\n\n");
     if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
-      input = RELAY_CONTEXT + "\n\n" + input;
+      input = codexRelayContextBlock() + "\n\n" + input;
       process.meta = { ...(process.meta ?? {}), relayContextSent: true };
     }
     console.error(`[agent-relay] starting Codex initial prompt in thread ${threadId}`);
@@ -171,7 +178,7 @@ export class CodexAdapter implements ProviderAdapter {
     const threadId = await ensureCodexThread(process);
     let text = [codexLaunchContext(process), providerMessageText(messages)].filter(Boolean).join("\n\n");
     if (codexRelayContextEnabled(process) && !process.meta?.relayContextSent) {
-      text = RELAY_CONTEXT + "\n\n" + text;
+      text = codexRelayContextBlock() + "\n\n" + text;
       process.meta = { ...(process.meta ?? {}), relayContextSent: true };
     }
     console.error(codexDeliveryNotice(messages, threadId));

package/src/relay-instructions.ts

@@ -23,3 +23,38 @@ export const CLAUDE_READ_ONLY_RELAY_CONTEXT = `${CLAUDE_RELAY_CONTEXT}
 This Claude session is running with restricted read-only Relay permissions. Do not invoke Agent Relay skills. If you need to reply, use this Bash command shape:
 
 agent-relay /reply <messageId> "<your reply>"`;
+
+/**
+ * Provider-agnostic caveat injected into every spawned agent that runs in an
+ * isolated workspace, regardless of which project it is working in. Isolated
+ * workspaces are git worktrees whose node_modules are provisioned by the
+ * orchestrator (see AGENT_RELAY_WORKSPACE_DEPS): symlinked from the main
+ * checkout by default. The agent needs to know this so it doesn't run a clean
+ * install that mutates the shared node_modules. Returns "" when no note applies
+ * (shared workspace, or deps installed fresh / unknown).
+ */
+export function workspaceDepsNote(input: { mode?: string | null; depsMode?: string | null }): string {
+  if (input.mode !== "isolated") return "";
+  switch (input.depsMode) {
+    case "symlink":
+      return "[agent-relay] Isolated workspace: this is a git worktree, and its node_modules are SYMLINKED from the main checkout — dependencies are already installed and ready to use. Do NOT run a clean dependency install (`bun install` / `npm install` / `pnpm install`): it writes through the symlink and mutates the main checkout's shared node_modules. Build caches written under node_modules are shared too. If you genuinely need to change dependencies in isolation, ask the host to spawn with AGENT_RELAY_WORKSPACE_DEPS=install.";
+    case "none":
+      return "[agent-relay] Isolated workspace: dependencies were not provisioned (AGENT_RELAY_WORKSPACE_DEPS=none). You may need to install node_modules before typecheck/test/build work.";
+    default:
+      return "";
+  }
+}
+
+/** Resolve the workspace deps caveat from the runner/monitor environment.
+ * AGENT_RELAY_WORKSPACE_JSON carries the resolved workspace metadata (mode +
+ * deps) and is the authoritative source. Best-effort: never throws. */
+export function workspaceDepsNoteFromEnv(env: Record<string, string | undefined> = process.env): string {
+  const json = env.AGENT_RELAY_WORKSPACE_JSON;
+  if (!json) return "";
+  try {
+    const parsed = JSON.parse(json) as { mode?: string; deps?: { mode?: string } };
+    return workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null });
+  } catch {
+    return "";
+  }
+}

package/src/runner.ts

@@ -361,6 +361,7 @@ export class AgentRunner {
     const deliverable: Message[] = [];
     const providerAlreadyBusy = this.claims.reasons().includes("provider-turn");
     for (const message of messages) {
+      let toDeliver = message;
       if (message.claimable) {
         const claimed = await this.http.claimMessageResult(message.id, this.agentId).catch(() => ({ ok: false, claimExpiresAt: undefined }));
         if (!claimed.ok) continue;
@@ -374,9 +375,12 @@ export class AgentRunner {
             agentId: this.agentId,
             metadata: { messageId: message.id, completedBy: "runner" },
           }).catch((error) => console.error(`[runner] task ${taskId} in_progress update failed: ${error}`));
+          // Runner owns claim + status here; drop the server's self-claim instruction
+          // so the agent doesn't improvise a stray claim send (see stripRunnerClaimedGuidance).
+          toDeliver = { ...message, body: stripRunnerClaimedGuidance(message.body) };
         }
       }
-      deliverable.push(message);
+      deliverable.push(toDeliver);
     }
     if (deliverable.length === 0) {
       this.delivering = false;
@@ -1075,6 +1079,19 @@ export function taskIdFromMessage(message: Pick<Message, "payload">): number | u
   return Number.isSafeInteger(taskId) ? taskId as number : undefined;
 }
 
+// The server appends a self-claim/status instruction to task message bodies
+// (taskMessageBody in src/db.ts: "Claim this task before working it, then update
+// task status when finished."). For runner-managed agents the runner already owns
+// claim + status, so that line is not only redundant but actively harmful: the
+// agent tries to follow it, has no real claim command, and improvises a stray
+// `agent-relay /send-claimable claim <id>` that leaves an orphan claimable message.
+// Strip the trailing guidance from messages the runner has auto-claimed.
+const RUNNER_CLAIMED_GUIDANCE_RE = /\s*Claim this task before working it, then update task status when finished\.\s*$/;
+
+export function stripRunnerClaimedGuidance(body: string): string {
+  return body.replace(RUNNER_CLAIMED_GUIDANCE_RE, "");
+}
+
 function csvTags(raw: string | undefined): string[] {
   return (raw || "").split(",").map((tag) => tag.trim()).filter(Boolean);
 }