agent-relay-runner 0.10.19 → 0.10.21

package/src/adapter.ts

@@ -1,6 +1,27 @@
-import type { Message } from "agent-relay-sdk";
+import type { AgentProfile, Message } from "agent-relay-sdk";
 
 export type SemanticStatus = "idle" | "busy" | "offline" | "error";
+type ProviderWorkKind = "provider-turn" | "subagent";
+
+export interface ProviderStatusEvent {
+  status: SemanticStatus;
+  providerSessionId?: string;
+  reason?: ProviderWorkKind;
+  clear?: ProviderWorkKind[];
+  timeline?: {
+    status: string;
+    id?: string;
+    timestamp?: number;
+  };
+  id?: string;
+  label?: string;
+  role?: string;
+  parentId?: string;
+  providerState?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+}
+
+export type ProviderStatusUpdate = SemanticStatus | ProviderStatusEvent;
 
 export interface ProviderConfig {
   command: string;
@@ -18,6 +39,8 @@ export interface ProviderConfig {
 
 export interface RunnerSpawnConfig {
   provider: string;
+  model?: string;
+  effort?: string;
   runnerId: string;
   instanceId: string;
   agentId: string;
@@ -27,7 +50,11 @@ export interface RunnerSpawnConfig {
   approvalMode: string;
   label?: string;
   rig?: string;
+  profile?: string;
+  agentProfile?: AgentProfile;
   prompt?: string;
+  systemPromptAppend?: string;
+  tmuxSession?: string;
   providerArgs: string[];
   providerConfig: ProviderConfig;
   env: Record<string, string>;
@@ -51,20 +78,194 @@ export interface ManagedProcess {
   meta?: Record<string, unknown>;
 }
 
+export interface TerminalAttachSpec {
+  mode: "guest";
+  provider: string;
+  cwd: string;
+  command: string[];
+  env?: Record<string, string>;
+  title?: string;
+  ttlMs?: number;
+}
+
+export type ProviderPermissionDecision = "approve" | "approve-session" | "deny" | "abort";
+
+export interface ProviderPermissionDecisionInput {
+  approvalId: string;
+  decision: ProviderPermissionDecision;
+  reason?: string;
+}
+
 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>;
+  clearContext?(process: ManagedProcess): Promise<Record<string, unknown> | void>;
+  terminalAttachSpec?(process: ManagedProcess): Promise<TerminalAttachSpec>;
+  respondToPermissionDecision?(process: ManagedProcess, input: ProviderPermissionDecisionInput): Promise<Record<string, unknown> | void>;
+  deliverInitialPrompt?(process: ManagedProcess, prompt: string): Promise<void>;
   deliver(process: ManagedProcess, messages: Message[]): Promise<void>;
-  onStatusChange(cb: (status: SemanticStatus) => void): void;
+  onStatusChange(cb: (status: ProviderStatusUpdate) => void): void;
+  // Headless providers with no tmux session (e.g. the Codex app-server) still
+  // warrant an automatic restart on unexpected exit. Returning true opts the
+  // provider into the runner's restart-with-backoff path.
+  supportsUnexpectedExitRestart?(): boolean;
   buildSpawnArgs(config: RunnerSpawnConfig, providerConfig: ProviderConfig): SpawnArgs;
 }
 
-export function providerMessageText(messages: Message[]): string {
+export function profileAllowsRelayFeature(config: RunnerSpawnConfig, feature: keyof AgentProfile["relay"]): boolean {
+  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_spawn_agent, and relay_shutdown_agent. 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`;
+
+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;
+  const refs = Array.isArray(payloadRefs) ? payloadRefs : Array.isArray(topLevelRefs) ? topLevelRefs : [];
+  return refs.filter(isRecord);
+}
+
+function attachmentLabel(ref: Record<string, unknown>): string {
+  const parts = [
+    typeof ref.kind === "string" ? ref.kind : undefined,
+    typeof ref.role === "string" ? ref.role : undefined,
+    typeof ref.title === "string" ? `"${ref.title}"` : undefined,
+  ].filter(Boolean);
+  return parts.length ? ` (${parts.join(", ")})` : "";
+}
+
+function attachmentCacheMetadata(ref: Record<string, unknown>): Record<string, unknown> | undefined {
+  const metadata = isRecord(ref.metadata) ? ref.metadata : undefined;
+  const agentRelay = metadata && isRecord(metadata.agentRelay) ? metadata.agentRelay : undefined;
+  return agentRelay;
+}
+
+function isMemoryInjection(message: Message): boolean {
+  return isRecord(message.payload) && message.payload.memoryInjection === true;
+}
+
+function isReactionNotification(message: Message): boolean {
+  const event = isRecord(message.payload?.event) ? message.payload.event : undefined;
+  return message.payload?.reactionNotification === true || event?.type === "message.reaction";
+}
+
+function isPersistedRelayMessage(message: Message): boolean {
+  return Number.isSafeInteger(message.id) && message.id > 0;
+}
+
+function latestReplyableMessage(messages: Message[]): Message | undefined {
   return messages
+    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message))
+    .at(-1);
+}
+
+function providerSenderLabel(message: Message): string {
+  if (message.from === "user") return "human user";
+  const source = isRecord(message.payload?.source) ? message.payload.source : undefined;
+  const isHumanChannel = Boolean(source && (
+    isRecord(source.telegram) ||
+    isRecord(source.slack) ||
+    isRecord(source.discord)
+  ));
+  return isHumanChannel ? `human user via ${message.from}` : message.from;
+}
+
+export function providerAttachmentText(message: Message): string | undefined {
+  const refs = attachmentRefs(message);
+  if (!refs.length) return undefined;
+  const lines = refs.flatMap((ref) => {
+    const artifactId = typeof ref.artifactId === "string" ? ref.artifactId : "unknown-artifact";
+    const source = isRecord(ref.ref)
+      ? [
+        typeof ref.ref.provider === "string" ? ref.ref.provider : undefined,
+        typeof ref.ref.id === "string" ? ref.ref.id : undefined,
+      ].filter(Boolean).join(":")
+      : "";
+    const cache = attachmentCacheMetadata(ref);
+    const localPath = typeof cache?.localPath === "string" ? cache.localPath : undefined;
+    const cacheError = typeof cache?.cacheError === "string" ? cache.cacheError : undefined;
+    return [
+      `- ${artifactId}${attachmentLabel(ref)}${source ? ` source=${source}` : ""}`,
+      ...(localPath ? [`  local: ${localPath}`] : []),
+      ...(cacheError ? [`  cache error: ${cacheError}`] : []),
+    ];
+  });
+  const hasLocalPaths = refs.some((ref) => typeof attachmentCacheMetadata(ref)?.localPath === "string");
+  const canFetchMessage = isPersistedRelayMessage(message);
+  const guidance = !canFetchMessage
+    ? []
+    : hasLocalPaths
+    ? [
+      "Use the local path above when inspecting the attachment.",
+      `Read attachment details: agent-relay get-message ${message.id} --json`,
+    ]
+    : [
+      `Read attachment details: agent-relay get-message ${message.id} --json`,
+      `Fetch content: curl -fsS -H "X-Agent-Relay-Token: $AGENT_RELAY_TOKEN" "$AGENT_RELAY_URL/api/artifacts/<artifactId>/content" -o <filename>`,
+    ];
+  return [
+    "Attachments:",
+    ...lines,
+    ...guidance,
+  ].join("\n");
+}
+
+export function providerMessageText(messages: Message[]): string {
+  const replyable = latestReplyableMessage(messages);
+  const sections = messages
     .map((message) => {
       const subject = message.subject ? `Subject: ${message.subject}\n` : "";
-      return `[relay message #${message.id} from ${message.from}]\n${subject}${message.body}`;
-    })
-    .join("\n\n");
+      const isMemoryContext = isMemoryInjection(message);
+      const canReferenceMessage = isPersistedRelayMessage(message) && !isMemoryContext && !isReactionNotification(message);
+      const shouldPreview = canReferenceMessage && message.body.length > PROVIDER_MESSAGE_BODY_PREVIEW_CHARS;
+      const preview = shouldPreview
+        ? {
+          body: message.body.slice(0, PROVIDER_MESSAGE_BODY_PREVIEW_CHARS),
+          truncated: true,
+        }
+        : {
+          body: message.body,
+          truncated: false,
+        };
+      const truncationGuidance = preview.truncated
+        ? [
+          `[truncated: showing first ${PROVIDER_MESSAGE_BODY_PREVIEW_CHARS} of ${message.body.length} chars]`,
+          `Read full: agent-relay get-message ${message.id}`,
+          `Body only: agent-relay get-message ${message.id} --body`,
+          `Long reply: agent-relay /reply ${message.id} --stdin < response.md`,
+        ].join("\n")
+        : undefined;
+      if (isMemoryContext) {
+        return [
+          `[agent-relay context from ${message.from}]`,
+          "Guide: agent-relay /guide",
+          providerAttachmentText(message),
+          `${subject}${preview.body}`,
+        ].join("\n");
+      }
+      return [
+        `[relay message #${message.id} from ${providerSenderLabel(message)}]`,
+        "Guide: agent-relay /guide",
+        truncationGuidance,
+        providerAttachmentText(message),
+        `${subject}${preview.body}`,
+      ].join("\n");
+    });
+  if (replyable) {
+    sections.push([
+      "[agent-relay reply reminder]",
+      `If this batch needs a response, send one useful reply to the latest relevant message: agent-relay /reply ${replyable.id} --stdin < response.md`,
+      "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
+      "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
+    ].join("\n"));
+  }
+  return sections.join("\n\n");
 }

package/src/adapters/claude-delivery.ts

@@ -0,0 +1,108 @@
+import type { Message } from "agent-relay-sdk";
+import { providerAttachmentText } from "../adapter";
+
+const PROVIDER_MESSAGE_BODY_PREVIEW_CHARS = 4000;
+const REMINDER_EVERY_DELIVERIES = 5;
+
+interface ClaudeDeliveryTextOptions {
+  deliveryCount: number;
+  readOnly?: boolean;
+}
+
+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;
+}
+
+function isReactionNotification(message: Message): boolean {
+  const event = isRecord(message.payload?.event) ? message.payload.event : undefined;
+  return message.payload?.reactionNotification === true || event?.type === "message.reaction";
+}
+
+function isPersistedRelayMessage(message: Message): boolean {
+  return Number.isSafeInteger(message.id) && message.id > 0;
+}
+
+function providerSenderLabel(message: Message): string {
+  if (message.from === "user") return "human user";
+  const source = isRecord(message.payload?.source) ? message.payload.source : undefined;
+  const isHumanChannel = Boolean(source && (
+    isRecord(source.telegram) ||
+    isRecord(source.slack) ||
+    isRecord(source.discord)
+  ));
+  return isHumanChannel ? `human user via ${message.from}` : message.from;
+}
+
+function shouldShowReplyReminder(deliveryCount: number): boolean {
+  return deliveryCount <= 1 || deliveryCount % REMINDER_EVERY_DELIVERIES === 0;
+}
+
+function latestReplyableMessage(messages: Message[]): Message | undefined {
+  return messages
+    .filter((message) => isPersistedRelayMessage(message) && !isMemoryInjection(message) && !isReactionNotification(message))
+    .at(-1);
+}
+
+function formatMessage(message: Message): string {
+  const subject = message.subject ? `Subject: ${message.subject}\n` : "";
+  const isMemoryContext = isMemoryInjection(message);
+  const canFetchMessage = isPersistedRelayMessage(message);
+  const shouldPreview = canFetchMessage && message.body.length > PROVIDER_MESSAGE_BODY_PREVIEW_CHARS;
+  const preview = shouldPreview
+    ? {
+      body: message.body.slice(0, PROVIDER_MESSAGE_BODY_PREVIEW_CHARS),
+      truncated: true,
+    }
+    : {
+      body: message.body,
+      truncated: false,
+    };
+  const truncationGuidance = preview.truncated
+    ? [
+      `[truncated: showing first ${PROVIDER_MESSAGE_BODY_PREVIEW_CHARS} of ${message.body.length} chars]`,
+      `Read full: agent-relay get-message ${message.id}`,
+      `Body only: agent-relay get-message ${message.id} --body`,
+    ].join("\n")
+    : undefined;
+
+  if (isMemoryContext) {
+    return [
+      `[agent-relay context from ${message.from}]`,
+      providerAttachmentText(message),
+      `${subject}${preview.body}`,
+      truncationGuidance,
+    ].filter(Boolean).join("\n");
+  }
+
+  return [
+    `[relay message #${message.id} from ${providerSenderLabel(message)}]`,
+    providerAttachmentText(message),
+    `${subject}${preview.body}`,
+    truncationGuidance,
+  ].filter(Boolean).join("\n");
+}
+
+function replyReminder(message: Message, readOnly: boolean): string {
+  const command = readOnly
+    ? `agent-relay /reply ${message.id} "<your reply>"`
+    : `agent-relay /reply ${message.id} --stdin < response.md`;
+  return [
+    "[agent-relay reply reminder]",
+    `If this batch needs a response, send one useful reply to the latest relevant message: ${command}`,
+    "If you already delivered the useful response through Relay, do not send a separate status-only confirmation.",
+    "If multiple messages arrived together, cover them in one reply instead of answering each line separately.",
+  ].join("\n");
+}
+
+export function claudeProviderMessageText(messages: Message[], options: ClaudeDeliveryTextOptions): string {
+  const sections = messages.map(formatMessage);
+  const replyable = latestReplyableMessage(messages);
+  if (replyable && shouldShowReplyReminder(options.deliveryCount)) {
+    sections.push(replyReminder(replyable, options.readOnly === true));
+  }
+  return sections.join("\n\n");
+}