agent-relay-runner 0.17.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay-runner",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Unified provider lifecycle runner for Agent Relay",
   "type": "module",
   "bin": {
@@ -20,7 +20,7 @@
     "directory": "runner"
   },
   "dependencies": {
-    "agent-relay-sdk": "0.2.8"
+    "agent-relay-sdk": "0.2.9"
   },
   "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.17.0",
+  "version": "0.18.0",
   "agentRelayContracts": {
     "providerPluginProtocol": 1
   }

package/src/adapter.ts

@@ -1,4 +1,5 @@
 import type { AgentProfile, Message } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
 type ProviderWorkKind = "provider-turn" | "subagent";
@@ -160,10 +161,6 @@ export const RELAY_CONTEXT = `[agent-relay] You are connected to Agent Relay, a
 
 const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function attachmentRefs(message: Message): Record<string, unknown>[] {
   const payloadRefs = message.payload?.attachments;
   const topLevelRefs = (message as Message & { attachments?: unknown }).attachments;

package/src/adapters/claude-delivery.ts

@@ -1,4 +1,5 @@
 import type { Message } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
 import { providerAttachmentText } from "../adapter";
 
 const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
@@ -30,10 +31,6 @@ function stripRelayScaffolding(body: string): string {
   return lines.join("\n");
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function isMemoryInjection(message: Message): boolean {
   return isRecord(message.payload) && message.payload.memoryInjection === true;
 }

package/src/adapters/codex.ts

@@ -2,6 +2,7 @@ import { accessSync, constants, existsSync, readFileSync, realpathSync, readdirS
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import type { ContextState, Message } from "agent-relay-sdk";
+import { isRecord, stringValue } from "agent-relay-sdk";
 import { profileAllowsRelayFeature, providerMessageText, RELAY_CONTEXT, type ManagedProcess, type ProviderAdapter, type ProviderConfig, type ProviderPermissionDecisionInput, type ProviderSessionEvent, type ProviderStatusUpdate, type RunnerSpawnConfig, type SpawnArgs, type TerminalAttachSpec } from "../adapter";
 import { workspaceDepsNoteFromEnv } from "../relay-instructions";
 import { logger } from "../logger";
@@ -742,10 +743,6 @@ function activeFlags(value: unknown): string[] {
   return value.activeFlags.filter((flag): flag is string => typeof flag === "string" && flag.length > 0);
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value ? value : undefined;
-}
-
 function numberValue(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }
@@ -759,9 +756,6 @@ function isContextState(value: unknown): value is ContextState {
     typeof state.confidence === "string";
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 
 export function codexModelConfigArgs(model?: string, effort?: string): string[] {
   const args: string[] = [];

package/src/attachment-cache.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, write
 import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import type { Artifact, Message } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
 
 const DEFAULT_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -25,10 +26,6 @@ interface CachedAttachment {
   digest: string;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function attachmentRefs(message: Message): Record<string, unknown>[] {
   const payloadRefs = message.payload?.attachments;
   const topLevelRefs = (message as Message & { attachments?: unknown }).attachments;

package/src/config.ts

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { join, resolve } from "node:path";
+import { stringValue } from "agent-relay-sdk";
 import type { ProviderConfig } from "./adapter";
 
 interface GlobalRunnerConfig {
@@ -115,10 +116,6 @@ function readJson(path: string): Record<string, unknown> {
   }
 }
 
-function stringValue(value: unknown): string | undefined {
-  return typeof value === "string" && value.length > 0 ? value : undefined;
-}
-
 function positiveInteger(value: unknown): number | undefined {
   return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
 }

package/src/control-server.ts

@@ -1,5 +1,6 @@
 import type { Server, ServerWebSocket } from "bun";
 import type { Message, ReplyObligation } from "agent-relay-sdk";
+import { isRecord } from "agent-relay-sdk";
 import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 import { logger, parseLogLevel, LOG_LEVELS } from "./logger";
 
@@ -453,7 +454,3 @@ function parseJson(raw: string | Buffer): Record<string, unknown> | null {
     return null;
   }
 }
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}

package/src/index.ts

@@ -8,6 +8,7 @@ import { AgentRunner } from "./runner";
 import { loadGlobalConfig, loadProviderConfig, resolveCwd, runnerId } from "./config";
 import { VERSION } from "./version";
 import type { AgentProfile, WorkspaceMetadata } from "agent-relay-sdk";
+import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 
 interface CliOptions {
   provider: "claude" | "codex";
@@ -139,7 +140,7 @@ export async function resolveRunnerToken(input: {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
-        "X-Agent-Relay-Token": input.token,
+        [RELAY_TOKEN_HEADER]: input.token,
       },
       body: JSON.stringify({
         provider: input.provider,

package/src/relay-instructions.ts

@@ -45,6 +45,23 @@ export function workspaceDepsNote(input: { mode?: string | null; depsMode?: stri
   }
 }
 
+/**
+ * Lifecycle briefing for an agent spawned into an isolated workspace (#205).
+ * Tells it, in plain terms, that it is on an isolated branch off a base that
+ * other agents move in parallel, and how to hand off — so it doesn't re-derive
+ * "I seem to be in a clone, not on main" every session or hand-roll a rebase/push.
+ * Returns "" for shared workspaces. Branch/base come from the resolved metadata.
+ */
+export function workspaceLifecycleNote(input: { mode?: string | null; branch?: string | null; baseRef?: string | null }): string {
+  if (input.mode !== "isolated") return "";
+  const branch = input.branch ? `\`${input.branch}\`` : "an isolated agent branch";
+  const base = input.baseRef ? `\`${input.baseRef}\`` : "the base branch";
+  return [
+    `[agent-relay] Isolated workspace: you are in a git worktree on branch ${branch}, based on ${base} — NOT the main checkout. Other agents may work in parallel and land to ${base}, so ${base} will move under you. That is expected; don't fight it.`,
+    `Do NOT manually rebase, merge, or \`git push\` your branch. Just commit your work here. When the task is done, run \`agent-relay workspace ready\` — Relay rebases onto the latest ${base}, lands your work, and pushes for you. (\`agent-relay workspace status\` shows the current state.)`,
+  ].join("\n");
+}
+
 /**
  * Caveat for untracked paths symlinked from main into an isolated worktree
  * (WorkspaceConfig.symlinkPaths, e.g. AGENTS.md, .claude-rig). Edits to these
@@ -63,8 +80,9 @@ export function workspaceDepsNoteFromEnv(env: Record<string, string | undefined>
   const json = env.AGENT_RELAY_WORKSPACE_JSON;
   if (!json) return "";
   try {
-    const parsed = JSON.parse(json) as { mode?: string; deps?: { mode?: string }; symlinks?: { linked?: string[] } };
+    const parsed = JSON.parse(json) as { mode?: string; branch?: string; baseRef?: string; deps?: { mode?: string }; symlinks?: { linked?: string[] } };
     return [
+      workspaceLifecycleNote({ mode: parsed.mode ?? null, branch: parsed.branch ?? null, baseRef: parsed.baseRef ?? null }),
       workspaceDepsNote({ mode: parsed.mode ?? null, depsMode: parsed.deps?.mode ?? null }),
       parsed.mode === "isolated" ? workspaceSymlinksNote(parsed.symlinks?.linked ?? []) : "",
     ].filter(Boolean).join("\n\n");

package/src/version.ts

@@ -1,14 +1,16 @@
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { CONTRACT_VERSIONS } from "agent-relay-sdk";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "../package.json"), "utf8")) as { name?: string; version?: string };
 
 export const PACKAGE_NAME = pkg.name || "agent-relay-runner";
 export const VERSION = pkg.version || "0.0.0";
-export const RUNNER_PROTOCOL_VERSION = 1;
-export const PROVIDER_PLUGIN_PROTOCOL_VERSION = 1;
+// Protocol versions are owned by the SDK (CONTRACT_VERSIONS) — derive, never redeclare.
+export const RUNNER_PROTOCOL_VERSION = CONTRACT_VERSIONS.runnerProtocol;
+export const PROVIDER_PLUGIN_PROTOCOL_VERSION = CONTRACT_VERSIONS.providerPluginProtocol;
 
 export const CONTRACTS = {
   runnerProtocol: RUNNER_PROTOCOL_VERSION,