agent-relay-runner 0.10.19 → 0.10.21

package/src/attachment-cache.ts

@@ -0,0 +1,190 @@
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import type { Artifact, Message } from "agent-relay-sdk";
+
+const DEFAULT_CACHE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+export interface AttachmentCacheClient {
+  downloadArtifact(id: string): Promise<{ stream: ReadableStream<Uint8Array>; meta: Artifact }>;
+}
+
+export interface AttachmentCacheOptions {
+  agentId: string;
+  rootDir?: string;
+  maxAgeMs?: number;
+  now?: number;
+  onError?: (message: string) => void;
+}
+
+interface CachedAttachment {
+  path: string;
+  filename: string;
+  mediaType: string;
+  size: number;
+  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;
+  const refs = Array.isArray(payloadRefs) ? payloadRefs : Array.isArray(topLevelRefs) ? topLevelRefs : [];
+  return refs.filter(isRecord);
+}
+
+export function attachmentCacheRoot(agentId: string, rootDir = process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR): string {
+  return join(attachmentCacheBase(rootDir), safePathPart(agentId));
+}
+
+function attachmentCacheBase(rootDir = process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR): string {
+  return rootDir || join(homedir(), ".agent-relay", "attachments");
+}
+
+export async function messagesWithCachedAttachments(
+  messages: Message[],
+  client: AttachmentCacheClient,
+  options: AttachmentCacheOptions,
+): Promise<Message[]> {
+  pruneAttachmentCache(options.agentId, options.rootDir, options.maxAgeMs ?? DEFAULT_CACHE_MAX_AGE_MS, options.now ?? Date.now());
+  const enriched: Message[] = [];
+  for (const message of messages) enriched.push(await messageWithCachedAttachments(message, client, options));
+  return enriched;
+}
+
+async function messageWithCachedAttachments(
+  message: Message,
+  client: AttachmentCacheClient,
+  options: AttachmentCacheOptions,
+): Promise<Message> {
+  const refs = attachmentRefs(message);
+  if (!refs.length) return message;
+  const nextRefs = [];
+  let changed = false;
+  for (const ref of refs) {
+    const artifactId = typeof ref.artifactId === "string" ? ref.artifactId.trim() : "";
+    if (!artifactId) {
+      nextRefs.push(ref);
+      continue;
+    }
+    try {
+      const cached = await cacheArtifact(client, artifactId, options);
+      nextRefs.push(withCacheMetadata(ref, cached));
+      changed = true;
+    } catch (error) {
+      options.onError?.(`attachment ${artifactId} cache failed: ${error instanceof Error ? error.message : String(error)}`);
+      nextRefs.push(withCacheError(ref, error));
+      changed = true;
+    }
+  }
+  if (!changed) return message;
+  return {
+    ...message,
+    payload: {
+      ...message.payload,
+      attachments: nextRefs,
+    },
+  };
+}
+
+async function cacheArtifact(client: AttachmentCacheClient, artifactId: string, options: AttachmentCacheOptions): Promise<CachedAttachment> {
+  const { stream, meta } = await client.downloadArtifact(artifactId);
+  const root = attachmentCacheRoot(options.agentId, options.rootDir);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  const filename = safeFilename(meta.filename || artifactId);
+  const digestPart = safePathPart((meta.digest || meta.blobDigest || artifactId).replace(/^sha256:/, "")).slice(0, 24) || safePathPart(artifactId);
+  const path = join(root, `${digestPart}-${filename}`);
+  if (existsSync(path)) {
+    const stat = statSync(path);
+    if (stat.isFile() && stat.size === meta.size) {
+      return { path, filename, mediaType: meta.mediaType, size: meta.size, digest: meta.digest };
+    }
+  }
+  const bytes = new Uint8Array(await new Response(stream).arrayBuffer());
+  if (bytes.byteLength !== meta.size) throw new Error(`artifact size mismatch: expected ${meta.size}, got ${bytes.byteLength}`);
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, bytes, { mode: 0o600 });
+  rmSync(path, { force: true });
+  renameSync(temp, path);
+  return { path, filename, mediaType: meta.mediaType, size: meta.size, digest: meta.digest };
+}
+
+function withCacheMetadata(ref: Record<string, unknown>, cached: CachedAttachment): Record<string, unknown> {
+  const metadata = isRecord(ref.metadata) ? ref.metadata : {};
+  const agentRelay = isRecord(metadata.agentRelay) ? metadata.agentRelay : {};
+  return {
+    ...ref,
+    metadata: {
+      ...metadata,
+      agentRelay: {
+        ...agentRelay,
+        localPath: cached.path,
+        filename: cached.filename,
+        mediaType: cached.mediaType,
+        size: cached.size,
+        digest: cached.digest,
+        cachedAt: new Date().toISOString(),
+      },
+    },
+  };
+}
+
+function withCacheError(ref: Record<string, unknown>, error: unknown): Record<string, unknown> {
+  const metadata = isRecord(ref.metadata) ? ref.metadata : {};
+  const agentRelay = isRecord(metadata.agentRelay) ? metadata.agentRelay : {};
+  return {
+    ...ref,
+    metadata: {
+      ...metadata,
+      agentRelay: {
+        ...agentRelay,
+        cacheError: error instanceof Error ? error.message : String(error),
+      },
+    },
+  };
+}
+
+export function pruneAttachmentCache(
+  agentId: string,
+  rootDir = process.env.AGENT_RELAY_ATTACHMENT_CACHE_DIR,
+  maxAgeMs = DEFAULT_CACHE_MAX_AGE_MS,
+  now = Date.now(),
+): void {
+  const base = attachmentCacheBase(rootDir);
+  if (!existsSync(base)) return;
+  const roots = [attachmentCacheRoot(agentId, rootDir)];
+  for (const entry of readdirSync(base)) roots.push(join(base, entry));
+  for (const root of [...new Set(roots)]) pruneAttachmentCacheDir(root, maxAgeMs, now);
+}
+
+function pruneAttachmentCacheDir(root: string, maxAgeMs: number, now: number): void {
+  if (!existsSync(root)) return;
+  const entries = readdirSync(root);
+  for (const entry of entries) {
+    const path = join(root, entry);
+    try {
+      const stat = statSync(path);
+      if (!stat.isFile()) continue;
+      if (now - stat.mtimeMs > maxAgeMs) rmSync(path, { force: true });
+    } catch {
+      // Best-effort cache cleanup only.
+    }
+  }
+  try {
+    if (readdirSync(root).length === 0) rmSync(root, { recursive: true, force: true });
+  } catch {
+    // Best-effort cache cleanup only.
+  }
+}
+
+function safeFilename(value: string): string {
+  const name = safePathPart(basename(value));
+  return name || "artifact";
+}
+
+function safePathPart(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_.-]/g, "_").replace(/_+/g, "_").slice(0, 180);
+}

package/src/claim-tracker.ts

@@ -1,5 +1,6 @@
 type ClaimKind = "message" | "task" | "command";
-type RunnerBusyReason = "provider-turn" | ClaimKind;
+type RunnerWorkKind = "provider-turn" | "subagent";
+type RunnerBusyReason = RunnerWorkKind | ClaimKind;
 type RunnerSemanticStatus = "idle" | "busy" | "offline" | "error";
 
 interface ClaimRecord {
@@ -9,14 +10,52 @@ interface ClaimRecord {
   expiresAt?: number;
 }
 
+interface WorkRecord {
+  id: string;
+  kind: RunnerWorkKind;
+  label?: string;
+  role?: string;
+  parentId?: string;
+  metadata?: Record<string, unknown>;
+  startedAt: number;
+}
+
 export class ClaimTracker {
-  private providerBusy = false;
   private status: RunnerSemanticStatus = "idle";
   private readonly claims = new Map<string, ClaimRecord>();
+  private readonly work = new Map<string, WorkRecord>();
 
   setProviderBusy(busy: boolean): boolean {
+    return busy ? this.startWork("provider-turn", "provider-turn") : this.finishWork("provider-turn", "provider-turn");
+  }
+
+  startWork(kind: RunnerWorkKind, id: string = kind, details: Omit<Partial<WorkRecord>, "id" | "kind" | "startedAt"> = {}): boolean {
     const before = this.currentStatus();
-    this.providerBusy = busy;
+    const key = `${kind}:${id}`;
+    const existing = this.work.get(key);
+    this.work.set(key, {
+      id,
+      kind,
+      label: details.label ?? existing?.label,
+      role: details.role ?? existing?.role,
+      parentId: details.parentId ?? existing?.parentId,
+      metadata: details.metadata ?? existing?.metadata,
+      startedAt: existing?.startedAt ?? Date.now(),
+    });
+    return before !== this.currentStatus();
+  }
+
+  finishWork(kind: RunnerWorkKind, id: string = kind): boolean {
+    const before = this.currentStatus();
+    this.work.delete(`${kind}:${id}`);
+    return before !== this.currentStatus();
+  }
+
+  clearWorkKind(kind: RunnerWorkKind): boolean {
+    const before = this.currentStatus();
+    for (const key of [...this.work.keys()]) {
+      if (key.startsWith(`${kind}:`)) this.work.delete(key);
+    }
     return before !== this.currentStatus();
   }
 
@@ -62,12 +101,12 @@ export class ClaimTracker {
 
   currentStatus(): RunnerSemanticStatus {
     if (this.status === "offline" || this.status === "error") return this.status;
-    return this.providerBusy || this.claims.size > 0 ? "busy" : "idle";
+    return this.work.size > 0 || this.claims.size > 0 ? "busy" : "idle";
   }
 
   reasons(): RunnerBusyReason[] {
     const reasons = new Set<RunnerBusyReason>();
-    if (this.providerBusy) reasons.add("provider-turn");
+    for (const item of this.work.values()) reasons.add(item.kind);
     for (const claim of this.claims.values()) reasons.add(claim.kind);
     return [...reasons];
   }
@@ -75,4 +114,8 @@ export class ClaimTracker {
   activeClaims(): ClaimRecord[] {
     return [...this.claims.values()];
   }
+
+  activeWork(): WorkRecord[] {
+    return [...this.work.values()];
+  }
 }

package/src/control-server.ts

@@ -1,6 +1,6 @@
 import type { Server, ServerWebSocket } from "bun";
-import type { Message } from "agent-relay-sdk";
-import type { SemanticStatus } from "./adapter";
+import type { Message, ReplyObligation } from "agent-relay-sdk";
+import type { ProviderPermissionDecisionInput, ProviderStatusEvent, SemanticStatus, TerminalAttachSpec } from "./adapter";
 
 interface MonitorSocketData {
   kind: "monitor";
@@ -13,15 +13,19 @@ export interface ControlServer {
   url: string;
   stop(): void;
   deliverToMonitor(messages: Message[], timeoutMs?: number): Promise<number[]>;
+  resolvePermissionDecision(input: ProviderPermissionDecisionInput): boolean;
 }
 
 interface ControlServerOptions {
-  onStatus(status: SemanticStatus): void;
+  onStatus(status: ProviderStatusEvent): void;
+  onTerminalAttachSpec?(): Promise<TerminalAttachSpec>;
+  onReplyObligations?(): Promise<ReplyObligation[]>;
 }
 
 export function startControlServer(options: ControlServerOptions): ControlServer {
   const monitors = new Set<MonitorSocket>();
   const pendingDeliveries = new Map<string, { resolve(ids: number[]): void; timer: Timer }>();
+  const pendingPermissionRequests = new Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>();
   let server!: Server<MonitorSocketData>;
 
   server = Bun.serve<MonitorSocketData>({
@@ -34,6 +38,27 @@ export function startControlServer(options: ControlServerOptions): ControlServer
       if (url.pathname === "/status" && req.method === "POST") {
         return handleStatus(req, options);
       }
+      if (url.pathname === "/terminal/attach-spec" && req.method === "GET") {
+        if (!options.onTerminalAttachSpec) return Response.json({ error: "terminal attach is unavailable" }, { status: 404 });
+        return options.onTerminalAttachSpec()
+          .then((spec) => Response.json(spec))
+          .catch((error) => Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 409 }));
+      }
+      if (url.pathname === "/reply-obligations" && req.method === "GET") {
+        if (!options.onReplyObligations) return Response.json({ pending: false, count: 0 });
+        return options.onReplyObligations()
+          .then((obligations) => Response.json(replyObligationSummary(obligations)))
+          .catch((error) => Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 503 }));
+      }
+      if (url.pathname === "/reply-obligations/claude-stop" && req.method === "GET") {
+        if (!options.onReplyObligations) return Response.json({});
+        return options.onReplyObligations()
+          .then((obligations) => Response.json(replyObligationStopDecision(obligations)))
+          .catch((error) => Response.json({ error: error instanceof Error ? error.message : String(error) }, { status: 503 }));
+      }
+      if (url.pathname === "/permissions/request" && req.method === "POST") {
+        return handlePermissionRequest(req, options, pendingPermissionRequests);
+      }
       if (url.pathname === "/monitor") {
         const upgraded = srv.upgrade(req, { data: { kind: "monitor" } });
         return upgraded ? undefined : new Response("WebSocket upgrade failed", { status: 400 });
@@ -71,6 +96,8 @@ export function startControlServer(options: ControlServerOptions): ControlServer
     stop() {
       for (const pending of pendingDeliveries.values()) clearTimeout(pending.timer);
       pendingDeliveries.clear();
+      for (const pending of pendingPermissionRequests.values()) clearTimeout(pending.timer);
+      pendingPermissionRequests.clear();
       server.stop(true);
     },
     async deliverToMonitor(messages: Message[], timeoutMs = 30_000): Promise<number[]> {
@@ -86,17 +113,173 @@ export function startControlServer(options: ControlServerOptions): ControlServer
         for (const monitor of monitors) monitor.send(payload);
       });
     },
+    resolvePermissionDecision(input: ProviderPermissionDecisionInput): boolean {
+      const pending = pendingPermissionRequests.get(input.approvalId);
+      if (!pending) return false;
+      clearTimeout(pending.timer);
+      pendingPermissionRequests.delete(input.approvalId);
+      pending.resolve(input);
+      options.onStatus({
+        status: "busy",
+        reason: "provider-turn",
+        providerState: {
+          state: "active",
+          reason: "permissionResolved",
+          label: "Claude approval resolved",
+          source: "claude",
+          updatedAt: Date.now(),
+        },
+      });
+      return true;
+    },
+  };
+}
+
+function replyObligationSummary(obligations: ReplyObligation[]): Record<string, unknown> {
+  const obligation = obligations[0];
+  if (!obligation) return { pending: false, count: 0 };
+  const subject = obligation.subject ? ` (${obligation.subject})` : "";
+  return {
+    pending: true,
+    count: obligations.length,
+    obligation,
+    reason: `Pending Agent Relay response for message #${obligation.messageId} from ${obligation.from}${subject}. If it still needs an answer, run: ${obligation.replyCommand}. If multiple delivered messages are part of one current request, answer once to the latest relevant message. If the useful response was already delivered through Relay, do not send a separate status-only confirmation.`,
+  };
+}
+
+function replyObligationStopDecision(obligations: ReplyObligation[]): Record<string, unknown> {
+  const summary = replyObligationSummary(obligations);
+  if (summary.pending !== true) return {};
+  return {
+    decision: "block",
+    reason: summary.reason,
+  };
+}
+
+async function handlePermissionRequest(
+  req: Request,
+  options: ControlServerOptions,
+  pendingPermissionRequests: Map<string, { resolve(input: ProviderPermissionDecisionInput): void; timer: Timer }>,
+): Promise<Response> {
+  const body = await req.json().catch(() => null);
+  if (!isRecord(body)) return Response.json({});
+  const approvalId = crypto.randomUUID();
+  const view = claudePermissionApprovalView(approvalId, body);
+  options.onStatus({
+    status: "busy",
+    reason: "provider-turn",
+    providerState: {
+      state: "blocked",
+      reason: "permissionRequest",
+      label: view.title,
+      recommendedAction: "Review the permission request in Agent Relay.",
+      source: "claude",
+      pendingApproval: view,
+      updatedAt: Date.now(),
+    },
+  });
+
+  const decision = await new Promise<ProviderPermissionDecisionInput>((resolve) => {
+    const timer = setTimeout(() => {
+      pendingPermissionRequests.delete(approvalId);
+      resolve({ approvalId, decision: "deny", reason: "permission request timed out" });
+    }, 15 * 60 * 1000);
+    pendingPermissionRequests.set(approvalId, { resolve, timer });
+  });
+
+  return Response.json(claudePermissionHookResponse(decision, body));
+}
+
+function claudePermissionApprovalView(id: string, body: Record<string, unknown>): Record<string, unknown> {
+  const toolName = typeof body.tool_name === "string" ? body.tool_name : "Tool";
+  const toolInput = isRecord(body.tool_input) ? body.tool_input : {};
+  const command = typeof toolInput.command === "string" ? toolInput.command : "";
+  const description = typeof toolInput.description === "string" ? toolInput.description : "";
+  const bodyText = [
+    command || description || JSON.stringify(toolInput),
+    typeof body.cwd === "string" ? `CWD: ${body.cwd}` : "",
+    typeof body.permission_mode === "string" ? `Mode: ${body.permission_mode}` : "",
+  ].filter(Boolean).join("\n");
+  return {
+    id,
+    provider: "claude",
+    kind: toolName.toLowerCase() === "bash" ? "command" : "tool",
+    title: `Approve ${toolName}`,
+    body: bodyText,
+    choices: [
+      { id: "approve", label: "Approve" },
+      { id: "approve-session", label: "Approve session" },
+      { id: "deny", label: "Deny" },
+      { id: "abort", label: "Abort" },
+    ],
+  };
+}
+
+function claudePermissionHookResponse(decision: ProviderPermissionDecisionInput, body: Record<string, unknown>): Record<string, unknown> {
+  const hookEventName = "PermissionRequest";
+  if (decision.decision === "approve" || decision.decision === "approve-session") {
+    const suggestions = Array.isArray(body.permission_suggestions) ? body.permission_suggestions : [];
+    return {
+      hookSpecificOutput: {
+        hookEventName,
+        decision: {
+          behavior: "allow",
+          ...(decision.decision === "approve-session" && suggestions.length ? { updatedPermissions: suggestions } : {}),
+        },
+      },
+    };
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName,
+      decision: {
+        behavior: "deny",
+        message: decision.reason || "Denied from Agent Relay dashboard",
+        interrupt: decision.decision === "abort",
+      },
+    },
   };
 }
 
 async function handleStatus(req: Request, options: ControlServerOptions): Promise<Response> {
-  const body = await req.json().catch(() => null) as { status?: unknown } | null;
+  const body = await req.json().catch(() => null) as Partial<ProviderStatusEvent> | null;
   const status = body?.status;
   if (status !== "idle" && status !== "busy" && status !== "offline" && status !== "error") {
     return Response.json({ error: "status must be idle, busy, offline, or error" }, { status: 400 });
   }
-  options.onStatus(status);
-  return Response.json({ ok: true, status });
+  const reason = body?.reason;
+  if (reason !== undefined && reason !== "provider-turn" && reason !== "subagent") {
+    return Response.json({ error: "reason must be provider-turn or subagent" }, { status: 400 });
+  }
+  const clear = Array.isArray(body?.clear)
+    ? body.clear.filter((item): item is "provider-turn" | "subagent" => item === "provider-turn" || item === "subagent")
+    : undefined;
+  const timeline = statusTimelineEvent(body);
+  const update: ProviderStatusEvent = {
+    status,
+    ...(typeof body?.providerSessionId === "string" ? { providerSessionId: body.providerSessionId } : {}),
+    ...(reason ? { reason } : {}),
+    ...(clear?.length ? { clear: [...new Set(clear)] } : {}),
+    ...(timeline ? { timeline } : {}),
+    ...(typeof body?.id === "string" ? { id: body.id } : {}),
+    ...(typeof body?.label === "string" ? { label: body.label } : {}),
+    ...(typeof body?.role === "string" ? { role: body.role } : {}),
+    ...(typeof body?.parentId === "string" ? { parentId: body.parentId } : {}),
+    ...(body?.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata) ? { metadata: body.metadata as Record<string, unknown> } : {}),
+  };
+  options.onStatus(update);
+  return Response.json({ ok: true, ...update });
+}
+
+function statusTimelineEvent(body: Partial<ProviderStatusEvent> | null): ProviderStatusEvent["timeline"] | undefined {
+  const timeline = body?.timeline;
+  if (!timeline || typeof timeline !== "object" || Array.isArray(timeline)) return undefined;
+  if (typeof timeline.status !== "string" || !timeline.status) return undefined;
+  return {
+    status: timeline.status,
+    ...(typeof timeline.id === "string" ? { id: timeline.id } : {}),
+    ...(typeof timeline.timestamp === "number" && Number.isFinite(timeline.timestamp) ? { timestamp: timeline.timestamp } : {}),
+  };
 }
 
 function parseJson(raw: string | Buffer): Record<string, unknown> | null {
@@ -107,3 +290,7 @@ 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));
+}