agent-relay-server 0.61.1 → 0.62.0

package/src/mcp-issue-ref-tools.ts

@@ -0,0 +1,174 @@
+import { deleteIssueRef, getIssueRef, listIssueRefs, resolveIssueRefByExternalKey, resolveIssueRefFromString, updateIssueRef, upsertIssueRef } from "./db/issue-refs";
+import { McpNotFoundError } from "./mcp-errors";
+import { cleanEnum, cleanString, optionalEnum } from "./validation";
+import { ISSUE_PROVIDERS, ISSUE_REF_STATUSES, isRecord, type IssueProvider, type IssueRefStatus } from "./types";
+import { ValidationError } from "./db";
+
+export const ISSUE_REF_TOOLS = [
+  {
+    name: "relay_issue_ref_upsert",
+    description: "Create or update the canonical IssueRef for provider/repo/externalKey. Idempotent for the same external issue.",
+    requiredScopes: ["issue:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        repo: { type: "string" },
+        externalKey: { type: "string" },
+        url: { type: "string" },
+        title: { type: "string" },
+        status: { type: "string", enum: ISSUE_REF_STATUSES },
+        statusSyncedAt: { type: "integer", minimum: 0 },
+      },
+      required: ["provider", "repo", "externalKey", "url"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_ref_resolve",
+    description: "Resolve a raw issue string (`#466`, `edimuj/agent-relay#466`, GitHub issue URL, or `issue_<uuid>`) or provider/repo/externalKey to the canonical IssueRef.",
+    requiredScopes: ["issue:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        ref: { type: "string" },
+        defaultRepo: { type: "string" },
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        repo: { type: "string" },
+        externalKey: { type: "string" },
+        url: { type: "string" },
+        title: { type: "string" },
+        status: { type: "string", enum: ISSUE_REF_STATUSES },
+        statusSyncedAt: { type: "integer", minimum: 0 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_ref_get",
+    description: "Fetch one IssueRef by its opaque internal id.",
+    requiredScopes: ["issue:read"],
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false },
+  },
+  {
+    name: "relay_issue_ref_list",
+    description: "List IssueRefs, optionally filtered by provider, repo, or cached status.",
+    requiredScopes: ["issue:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        provider: { type: "string", enum: ISSUE_PROVIDERS },
+        repo: { type: "string" },
+        status: { type: "string", enum: ISSUE_REF_STATUSES },
+        limit: { type: "integer", minimum: 1, maximum: 500 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_ref_update",
+    description: "Update cached IssueRef display fields without changing provider/repo/externalKey.",
+    requiredScopes: ["issue:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: { type: "string" },
+        url: { type: "string" },
+        title: { type: "string" },
+        status: { type: "string", enum: ISSUE_REF_STATUSES },
+        statusSyncedAt: { type: "integer", minimum: 0 },
+      },
+      required: ["id"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_issue_ref_delete",
+    description: "Delete an IssueRef mapping row. Foundation-only cleanup; lifecycle automation lives elsewhere.",
+    requiredScopes: ["issue:write"],
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"], additionalProperties: false },
+  },
+] satisfies Array<{ name: string; description: string; requiredScopes: string[]; inputSchema: Record<string, unknown> }>;
+
+type IssueRefToolAuth = { kind: string; actor: string; scopes?: string[] };
+
+function providerArg(value: unknown): IssueProvider {
+  return cleanEnum(value, "provider", ISSUE_PROVIDERS) as IssueProvider;
+}
+
+function statusArg(value: unknown): IssueRefStatus | undefined {
+  return optionalEnum(value, "status", ISSUE_REF_STATUSES) as IssueRefStatus | undefined;
+}
+
+function timestampArg(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new ValidationError("statusSyncedAt must be a non-negative integer");
+  return value;
+}
+
+export function relayIssueRefTool(_auth: IssueRefToolAuth, name: string, args: Record<string, unknown>): Record<string, unknown> {
+  if (name === "relay_issue_ref_upsert") {
+    return upsertIssueRef({
+      provider: providerArg(args.provider),
+      repo: cleanString(args.repo, "repo", { required: true, max: 500 })!,
+      externalKey: cleanString(args.externalKey, "externalKey", { required: true, max: 240 })!,
+      url: cleanString(args.url, "url", { required: true, max: 2000 })!,
+      title: cleanString(args.title, "title", { max: 500 }),
+      status: statusArg(args.status),
+      statusSyncedAt: timestampArg(args.statusSyncedAt),
+    }) as unknown as Record<string, unknown>;
+  }
+  if (name === "relay_issue_ref_resolve") {
+    const ref = cleanString(args.ref, "ref", { max: 1000 });
+    return (ref
+      ? resolveIssueRefFromString({
+        ref,
+        defaultRepo: cleanString(args.defaultRepo ?? args.repo, "defaultRepo", { max: 500 }),
+        provider: optionalEnum(args.provider, "provider", ISSUE_PROVIDERS, "github") as IssueProvider,
+        title: cleanString(args.title, "title", { max: 500 }),
+        status: statusArg(args.status),
+        statusSyncedAt: timestampArg(args.statusSyncedAt),
+      })
+      : resolveIssueRefByExternalKey({
+        provider: providerArg(args.provider),
+        repo: cleanString(args.repo, "repo", { required: true, max: 500 })!,
+        externalKey: cleanString(args.externalKey, "externalKey", { required: true, max: 240 })!,
+        url: cleanString(args.url, "url", { max: 2000 }),
+        title: cleanString(args.title, "title", { max: 500 }),
+        status: statusArg(args.status),
+        statusSyncedAt: timestampArg(args.statusSyncedAt),
+      })) as unknown as Record<string, unknown>;
+  }
+  if (name === "relay_issue_ref_get") {
+    const issueRef = getIssueRef(cleanString(args.id, "id", { required: true, max: 120 })!);
+    if (!issueRef) throw new McpNotFoundError("issue ref not found");
+    return { issueRef };
+  }
+  if (name === "relay_issue_ref_list") {
+    return {
+      issueRefs: listIssueRefs({
+        provider: optionalEnum(args.provider, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined,
+        repo: cleanString(args.repo, "repo", { max: 500 }),
+        status: statusArg(args.status),
+        limit: typeof args.limit === "number" ? args.limit : undefined,
+      }),
+    };
+  }
+  if (name === "relay_issue_ref_update") {
+    const issueRef = updateIssueRef(cleanString(args.id, "id", { required: true, max: 120 })!, {
+      url: cleanString(args.url, "url", { max: 2000 }),
+      title: cleanString(args.title, "title", { max: 500 }),
+      status: statusArg(args.status),
+      statusSyncedAt: timestampArg(args.statusSyncedAt),
+    });
+    if (!issueRef) throw new McpNotFoundError("issue ref not found");
+    return { issueRef };
+  }
+  if (name === "relay_issue_ref_delete") {
+    const deleted = deleteIssueRef(cleanString(args.id, "id", { required: true, max: 120 })!);
+    if (!deleted) throw new McpNotFoundError("issue ref not found");
+    return { deleted };
+  }
+  if (!isRecord(args)) throw new ValidationError("arguments must be an object");
+  throw new ValidationError(`unknown tool: ${name}`);
+}

package/src/mcp-team-tools.ts

@@ -11,7 +11,7 @@ const OUTCOME_STATUSES = ["success", "partial", "failed"] as const;
 export const TEAM_TOOLS = [
   {
     name: "relay_team_get",
-    description: "Return the caller's team row, live roster, shared brief/definition of done, and any bound plan.",
+    description: "Return the caller's team row, live roster, shared brief/definition of done, associated issues, and any bound plan.",
     requiredScopes: ["teams:read"],
     inputSchema: {
       type: "object",

package/src/mcp.ts

@@ -49,7 +49,7 @@ import { ServiceAuthError } from "./services/errors";
 import { PLAN_TOOLS, relayPlanTool } from "./mcp-plan-tools";
 import { TEAM_TOOLS, relayTeamTool } from "./mcp-team-tools";
 import { BLACKBOARD_TOOLS, relayBlackboardTool } from "./mcp-blackboard-tools";
-import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools";
+import { PROJECT_TOOLS, relayProjectTool } from "./mcp-project-tools"; import { ISSUE_REF_TOOLS, relayIssueRefTool } from "./mcp-issue-ref-tools"; import { ISSUE_ASSOCIATION_TOOLS, relayIssueAssociationTool } from "./mcp-issue-association-tools"; import { ISSUE_ACTIVITY_TOOLS, relayIssueActivityTool } from "./mcp-issue-activity-tools"; import { ISSUE_LIFECYCLE_TOOLS, relayIssueLifecycleTool } from "./mcp-issue-lifecycle-tools";
 import { NOTIFICATION_SUBSCRIPTION_TOOLS, relayNotificationSubscriptionTool } from "./mcp-notification-subscription-tools"; import { MERGE_TOOLS, relayMergeTool } from "./mcp-merge-tools";
 import { PROJECT_INSTRUCTION_POLICY_NAMES, parseProjectInstructions } from "./project-instructions";
 import { AGENT_ACTION_TOOL, relayAgentAction } from "./mcp-agent-action"; import { providerCatalogToolInputSchema } from "./mcp-provider-catalog";
@@ -461,7 +461,7 @@ const TOOLS: ToolDefinition[] = [
     },
   },
   ...MERGE_TOOLS, ...TEAM_TOOLS,
-  ...PLAN_TOOLS,
+  ...PLAN_TOOLS, ...ISSUE_REF_TOOLS, ...ISSUE_ASSOCIATION_TOOLS, ...ISSUE_ACTIVITY_TOOLS, ...ISSUE_LIFECYCLE_TOOLS,
   ...BLACKBOARD_TOOLS,
   ...PROJECT_TOOLS,
   ...NOTIFICATION_SUBSCRIPTION_TOOLS,
@@ -580,7 +580,7 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name.startsWith("relay_merge_")) result = relayMergeTool(auth, name, args); else if (name.startsWith("relay_team_")) result = await relayTeamTool(auth, name, args);
     else if (name.startsWith("relay_plan_")) result = relayPlanTool(auth, name, args);
     else if (name.startsWith("relay_blackboard_")) result = relayBlackboardTool(auth, name, args);
-    else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args);
+    else if (name.startsWith("relay_project_")) result = relayProjectTool(auth, name, args); else if (name.startsWith("relay_issue_ref_")) result = relayIssueRefTool(auth, name, args); else if (name.startsWith("relay_issue_association_")) result = relayIssueAssociationTool(auth, name, args); else if (name.startsWith("relay_issue_activity_")) result = relayIssueActivityTool(auth, name, args); else if (name.startsWith("relay_issue_lifecycle_")) result = await relayIssueLifecycleTool(auth, name, args);
     else if (name === "relay_subscribe" || name === "relay_unsubscribe" || name === "relay_list_subscriptions") result = relayNotificationSubscriptionTool(auth, name, args);
     else throw new ValidationError(`unknown tool: ${name}`);
 

package/src/provider-config-store.ts

@@ -123,21 +123,43 @@ export function providerConfigPublic(entry: ProviderConfigEntry, opts: { maskEnv
   };
 }
 
+/**
+ * Idempotently seed central provider-config rows for `host` from raw per-provider
+ * config objects (#465). A real stored row (version >= 1) always wins — a stale
+ * local file never clobbers it. Unknown providers and malformed bodies are skipped.
+ * This is the server-authority write path: callers are in-process (local migration
+ * or the orchestrator command-bus result handler), so no HTTP scope is required.
+ */
+export function seedProviderConfigs(host: string, rawByProvider: Record<string, unknown>): ProviderConfigEntry[] {
+  const seeded: ProviderConfigEntry[] = [];
+  for (const [provider, raw] of Object.entries(rawByProvider)) {
+    if (!VALID_PROVIDER_CONFIGS.includes(provider as SpawnProvider)) continue;
+    const key = providerConfigKey(host, provider);
+    if (getConfig(PROVIDER_CONFIG_NAMESPACE, key)) continue;
+    // Shallow-merge defaults so a partial local file (e.g. missing `command`)
+    // still validates; the relay owns the schema, the reporter stays dumb.
+    const value = { ...providerConfigDefaults(provider), ...(isRecord(raw) ? raw : {}) };
+    try {
+      const entry = setProviderConfig(provider, value, { host, updatedBy: `migration:${host}` });
+      emitConfigChanged(entry.namespace, entry.key, entry.version);
+      seeded.push(entry);
+    } catch {
+      // A single invalid provider config shouldn't abort seeding the rest.
+    }
+  }
+  return seeded;
+}
+
 export function migrateLocalProviderConfigs(home = agentRelayHome(), host = defaultProviderConfigHost()): ProviderConfigEntry[] {
   const dir = join(home, "providers");
   if (!existsSync(dir)) return [];
-  const migrated: ProviderConfigEntry[] = [];
+  const raw: Record<string, unknown> = {};
   for (const file of readdirSync(dir)) {
     const provider = file.endsWith(".json") ? file.slice(0, -".json".length) : "";
     if (!VALID_PROVIDER_CONFIGS.includes(provider as SpawnProvider)) continue;
-    const key = providerConfigKey(host, provider);
-    if (getConfig(PROVIDER_CONFIG_NAMESPACE, key)) continue;
-    const local = loadLocalProviderConfig(provider, home);
-    const entry = setProviderConfig(provider, local, { host, updatedBy: `migration:${host}` });
-    emitConfigChanged(entry.namespace, entry.key, entry.version);
-    migrated.push(entry);
+    raw[provider] = loadLocalProviderConfig(provider, home);
   }
-  return migrated;
+  return seedProviderConfigs(host, raw);
 }
 
 function normalizeProviderConfigHost(host: string): string {

package/src/routes/activity.ts

@@ -5,8 +5,9 @@ import { emitActivityEvent } from "../sse";
 import { error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
 import { isRecord } from "agent-relay-sdk";
 import { type ActivityEventInput, type ActivityKind } from "../types";
+import { ISSUE_ACTIVITY_ACTIONS } from "../services/issue-activity";
 
-const VALID_ACTIVITY_KINDS = ["message", "reply", "question", "operator", "pair", "task", "state"] as const;
+const VALID_ACTIVITY_KINDS = ["message", "reply", "question", "operator", "pair", "task", "state", "issue"] as const;
 
 function normalizeActivityInput(body: unknown): ActivityEventInput {
   if (!isRecord(body)) throw new ValidationError("JSON object body required");
@@ -24,6 +25,8 @@ function normalizeActivityInput(body: unknown): ActivityEventInput {
     pairId: cleanString(body.pairId, "pairId", { max: 120 }),
     taskId: cleanPositiveId(body.taskId, "taskId"),
     agentId: cleanString(body.agentId, "agentId", { max: 200 }),
+    issueRefId: cleanString(body.issueRefId, "issueRefId", { max: 120 }),
+    issueAction: optionalEnum(body.issueAction, "issueAction", ISSUE_ACTIVITY_ACTIONS),
     metadata: cleanMeta(body.metadata),
   };
 }
@@ -38,6 +41,8 @@ export const getActivityEvents: Handler = (req) => {
     return json(listActivityEvents({
       operatorId: cleanString(url.searchParams.get("operatorId") ?? undefined, "operatorId", { max: 200 }),
       agentId: cleanString(url.searchParams.get("agentId") ?? undefined, "agentId", { max: 200 }),
+      issueRefId: cleanString(url.searchParams.get("issueRefId") ?? undefined, "issueRefId", { max: 120 }),
+      issueAction: optionalEnum(url.searchParams.get("issueAction") ?? undefined, "issueAction", ISSUE_ACTIVITY_ACTIONS),
       limit: limitRaw ?? 200,
       since: sinceRaw ?? undefined,
     }));

package/src/routes/commands.ts

@@ -13,8 +13,10 @@ import { authContextFromRequest } from "../services/auth-context";
 import { commandAuthorizationResource as dispatchCommandAuthorizationResource, dispatchCommand } from "../services/dispatch-command";
 import { ServiceAuthError } from "../services/errors";
 import { notifyBranchLanded } from "../branch-landed";
+import { seedProviderConfigs } from "../provider-config-store";
 import { notifyAgentSpawnFailed } from "../agent-lifecycle-events";
 import { handleReviewerMergeResult } from "../reviewer-pipeline";
+import { scheduleRepoMerge } from "../workspace-auto-merge";
 import { enqueueContinuationInjectionAfterClear } from "../self-resume";
 import { type Command, type CommandStatus, type CreateCommandInput, type WorkspaceStatus } from "../types";
 
@@ -189,6 +191,12 @@ export const patchCommand: Handler = async (req, params) => {
       // base merge can proceed (issue #157).
       if (command.status === "succeeded" || command.status === "failed") {
         releaseMergeLease({ commandId: command.id });
+        // #237: the lease just freed — drain the next ready/review_requested row for
+        // this repo right now instead of waiting for the backstop sweep. This is the
+        // on-settle link of the sequential per-repo drain chain (no-op if nothing else
+        // is queued, or if AUTO_MERGE is disabled).
+        const settledRepoRoot = typeof command.params.repoRoot === "string" ? command.params.repoRoot : undefined;
+        scheduleRepoMerge(settledRepoRoot);
       }
       if (command.status === "succeeded" && isRecord(command.result)) {
         if (handleReviewerMergeResult(command, command.result)) {
@@ -357,6 +365,27 @@ export const patchCommand: Handler = async (req, params) => {
         });
       }
     }
+    if (command.type === "orchestrator.migrate-provider-config" && command.status === "succeeded" && isRecord(command.result)) {
+      // The orchestrator reported its host-local provider config files; seed the
+      // central rows with server authority (#465). Idempotent — a real stored row wins.
+      const host = cleanString(command.result.host, "result.host", { max: 120 });
+      const configs = isRecord(command.result.configs) ? command.result.configs : undefined;
+      if (host && configs) {
+        const seeded = seedProviderConfigs(host, configs);
+        if (seeded.length) {
+          auditEvent({
+            clientId: `server-provider-config-migrated-${host}-${command.id}`,
+            kind: "state",
+            title: "Provider config migrated",
+            body: `${host}: ${seeded.map((entry) => entry.key.split("/").at(-1)).join(", ")}`,
+            meta: host,
+            icon: "ti-arrow-up-circle",
+            view: "orchestrators",
+            metadata: { host, commandId: command.id, providers: seeded.map((entry) => entry.key) },
+          });
+        }
+      }
+    }
     settleFailedOrchestratorUpgrade(command);
     emitCommand(command);
     auditCommandOutcome(command);

package/src/routes/index.ts

@@ -28,6 +28,10 @@ import { getOrchestratorDirectories, getOrchestratorFileRead, getOrchestratorFil
 import { getPairById, getPairs, postAcceptPair, postHangupPair, postPair, postPairMessage, postRejectPair } from "./pairs";
 import { getPlanByIdRoute, getPlansRoute } from "./plans";
 import { getBlackboardEntryRoute, getBlackboardRoute } from "./blackboard";
+import { deleteIssueAssociationRoute, getIssueAssociationEntityIssuesRoute, getIssueAssociationIssueEntitiesRoute, postIssueAssociationRoute } from "./issue-associations";
+import { getAgentIssueActivityRoute, getIssueActivityAgentsRoute, postIssueActivityRoute } from "./issue-activity";
+import { postIssueLifecycleReopenRoute } from "./issue-lifecycle";
+import { deleteIssueRefRoute, getIssueRefRoute, listIssueRefsRoute, patchIssueRefRoute, postIssueRefRoute, resolveIssueRefRoute } from "./issue-refs";
 import { getProjectEntriesRoute, getProjectEntryRoute, getProjectRoute, getProjectsRoute } from "./projects";
 import { getRecipeByName, getRecipeInstanceArtifacts, getRecipeInstanceById, getRecipeInstances, getRecipes, postRecipeInstanceArtifacts, postRecipeStart, postRecipeStop } from "./recipes";
 import { getSettingRoute, getSettingsNamespaceRoute, getSettingsRoute, putSettingRoute, putSettingsDefaultRoute } from "./settings";
@@ -298,6 +302,21 @@ const routes: Route[] = [
   route("GET", "/api/plans/:id", getPlanByIdRoute),
   route("GET", "/api/blackboard", getBlackboardRoute),
   route("GET", "/api/blackboard/:id", getBlackboardEntryRoute),
+  route("POST", "/api/issue-associations", postIssueAssociationRoute),
+  route("DELETE", "/api/issue-associations", deleteIssueAssociationRoute),
+  route("GET", "/api/issue-associations/entities/:entityType/:entityId/issues", getIssueAssociationEntityIssuesRoute),
+  route("GET", "/api/issue-associations/issues/:issueRefId/entities", getIssueAssociationIssueEntitiesRoute),
+  route("POST", "/api/issue-activity", postIssueActivityRoute),
+  route("GET", "/api/issue-activity/issues", getIssueActivityAgentsRoute),
+  route("GET", "/api/issue-activity/agents/:id", getAgentIssueActivityRoute),
+  route("POST", "/api/issue-lifecycle/reopen", postIssueLifecycleReopenRoute),
+  route("POST", "/api/issue-refs", postIssueRefRoute),
+  route("GET", "/api/issue-refs", listIssueRefsRoute),
+  route("GET", "/api/issue-refs/resolve", resolveIssueRefRoute),
+  route("POST", "/api/issue-refs/resolve", resolveIssueRefRoute),
+  route("GET", "/api/issue-refs/:id", getIssueRefRoute),
+  route("PATCH", "/api/issue-refs/:id", patchIssueRefRoute),
+  route("DELETE", "/api/issue-refs/:id", deleteIssueRefRoute),
   route("GET", "/api/projects", getProjectsRoute),
   route("GET", "/api/projects/:id", getProjectRoute),
   route("GET", "/api/projects/:id/entries", getProjectEntriesRoute),

package/src/routes/issue-activity.ts

@@ -0,0 +1,78 @@
+import { ValidationError } from "../db";
+import { getIssueRef } from "../services/issue-refs";
+import {
+  ISSUE_ACTIVITY_ACTIONS,
+  listAgentIssueActivity,
+  listIssueActivityAgents,
+  recordAndEmitIssueActivity,
+  type IssueActivityAction,
+} from "../services/issue-activity";
+import { cleanEnum, cleanMeta, cleanString, optionalEnum } from "../validation";
+import { error, json, parseBody, parseQueryInt, type Handler } from "./_shared";
+import { ISSUE_PROVIDERS, isRecord, type IssueProvider } from "../types";
+
+function cleanProvider(value: unknown): IssueProvider | undefined {
+  return optionalEnum(value, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined;
+}
+
+function cleanAction(value: unknown): IssueActivityAction {
+  return cleanEnum(value, "action", ISSUE_ACTIVITY_ACTIONS) as IssueActivityAction;
+}
+
+function cleanLimit(req: Request): number | undefined | Response {
+  const url = new URL(req.url);
+  const rawLimit = parseQueryInt(url.searchParams.get("limit"), { min: 1, max: 500, clamp: true });
+  if (Number.isNaN(rawLimit)) return error("limit must be an integer");
+  return rawLimit ?? undefined;
+}
+
+export const postIssueActivityRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    if (!isRecord(parsed.body)) throw new ValidationError("issue activity body required");
+    const event = recordAndEmitIssueActivity({
+      agentId: cleanString(parsed.body.agentId, "agentId", { required: true, max: 200 })!,
+      action: cleanAction(parsed.body.action),
+      issueRefId: cleanString(parsed.body.issueRefId, "issueRefId", { max: 120 }),
+      issueRef: cleanString(parsed.body.issueRef ?? parsed.body.ref, "issueRef", { max: 1000 }),
+      defaultRepo: cleanString(parsed.body.defaultRepo ?? parsed.body.repo, "defaultRepo", { max: 500 }),
+      provider: cleanProvider(parsed.body.provider),
+      clientId: cleanString(parsed.body.clientId, "clientId", { max: 240 }),
+      title: cleanString(parsed.body.title, "title", { max: 200 }),
+      body: cleanString(parsed.body.body, "body", { max: 1000 }),
+      metadata: cleanMeta(parsed.body.metadata),
+    });
+    return json({ event }, 201);
+  } catch (err) {
+    if (err instanceof ValidationError) return error(err.message, 400);
+    throw err;
+  }
+};
+
+export const getIssueActivityAgentsRoute: Handler = (req) => {
+  try {
+    const url = new URL(req.url);
+    const limit = cleanLimit(req);
+    if (limit instanceof Response) return limit;
+    const issueRefId = cleanString(url.searchParams.get("issueRefId") ?? undefined, "issueRefId", { required: true, max: 120 })!;
+    const issueRef = getIssueRef(issueRefId);
+    if (!issueRef) return error("issue ref not found", 404);
+    return json({ issueRef, agents: listIssueActivityAgents(issueRef.id, { limit }) });
+  } catch (err) {
+    if (err instanceof ValidationError) return error(err.message, 400);
+    throw err;
+  }
+};
+
+export const getAgentIssueActivityRoute: Handler = (req, params) => {
+  try {
+    const limit = cleanLimit(req);
+    if (limit instanceof Response) return limit;
+    const agentId = cleanString(params.id, "agentId", { required: true, max: 200 })!;
+    return json({ agentId, issues: listAgentIssueActivity(agentId, { limit }) });
+  } catch (err) {
+    if (err instanceof ValidationError) return error(err.message, 400);
+    throw err;
+  }
+};

package/src/routes/issue-associations.ts

@@ -0,0 +1,76 @@
+import { ISSUE_ASSOCIATION_ENTITY_TYPES, ISSUE_PROVIDERS, isRecord, type IssueAssociationEntityType, type IssueProvider } from "../types";
+import { associateIssueRef, listIssueEntities, listIssueRefsForEntity, removeIssueAssociation, resolveAssociationIssueRef } from "../services/issue-associations";
+import { cleanEnum, cleanString, optionalEnum } from "../validation";
+import { error, json, parseBody, type Handler } from "./_shared";
+
+function cleanEntityType(value: unknown): IssueAssociationEntityType {
+  return cleanEnum(value, "entityType", ISSUE_ASSOCIATION_ENTITY_TYPES) as IssueAssociationEntityType;
+}
+
+function cleanIssueInput(value: Record<string, unknown>) {
+  return {
+    issueRefId: cleanString(value.issueRefId, "issueRefId", { max: 120 }),
+    ref: cleanString(value.ref, "ref", { max: 1000 }),
+    defaultRepo: cleanString(value.defaultRepo, "defaultRepo", { max: 500 }),
+    provider: optionalEnum(value.provider, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined,
+    repo: cleanString(value.repo, "repo", { max: 500 }),
+    externalKey: cleanString(value.externalKey, "externalKey", { max: 240 }),
+    url: cleanString(value.url, "url", { max: 2000 }),
+    title: cleanString(value.title, "title", { max: 500 }),
+  };
+}
+
+function cleanAssociationBody(body: unknown) {
+  if (!isRecord(body)) throw new Error("issue association body required");
+  return {
+    ...cleanIssueInput(body),
+    entityType: cleanEntityType(body.entityType),
+    entityId: cleanString(body.entityId, "entityId", { required: true, max: 240 })!,
+  };
+}
+
+function routeError(err: unknown): Response {
+  return error(err instanceof Error ? err.message : "issue associations route failed");
+}
+
+export const postIssueAssociationRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json(associateIssueRef(cleanAssociationBody(parsed.body)));
+  } catch (err) {
+    return routeError(err);
+  }
+};
+
+export const getIssueAssociationEntityIssuesRoute: Handler = (_req, params) => {
+  try {
+    return json({
+      issues: listIssueRefsForEntity(
+        cleanEntityType(params.entityType),
+        cleanString(params.entityId, "entityId", { required: true, max: 240 })!,
+      ),
+    });
+  } catch (err) {
+    return routeError(err);
+  }
+};
+
+export const getIssueAssociationIssueEntitiesRoute: Handler = (_req, params) => {
+  try {
+    const issueRef = resolveAssociationIssueRef({ issueRefId: cleanString(params.issueRefId, "issueRefId", { required: true, max: 120 })! });
+    return json({ issueRef, entities: listIssueEntities(issueRef.id) });
+  } catch (err) {
+    return routeError(err);
+  }
+};
+
+export const deleteIssueAssociationRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    return json(removeIssueAssociation(cleanAssociationBody(parsed.body)));
+  } catch (err) {
+    return routeError(err);
+  }
+};

package/src/routes/issue-lifecycle.ts

@@ -0,0 +1,34 @@
+import { reopenIssueLifecycle } from "../services/issue-lifecycle";
+import { cleanEnum, cleanString, optionalEnum } from "../validation";
+import { error, json, parseBody, type Handler } from "./_shared";
+import { ISSUE_ASSOCIATION_ENTITY_TYPES, ISSUE_PROVIDERS, isRecord, type IssueAssociationEntityType, type IssueProvider } from "../types";
+
+function cleanReopenBody(body: unknown) {
+  if (!isRecord(body)) throw new Error("issue lifecycle reopen body required");
+  return {
+    issueRefId: cleanString(body.issueRefId, "issueRefId", { max: 120 }),
+    ref: cleanString(body.ref, "ref", { max: 1000 }),
+    defaultRepo: cleanString(body.defaultRepo ?? body.repo, "defaultRepo", { max: 500 }),
+    provider: optionalEnum(body.provider, "provider", ISSUE_PROVIDERS) as IssueProvider | undefined,
+    repo: cleanString(body.repo, "repo", { max: 500 }),
+    externalKey: cleanString(body.externalKey, "externalKey", { max: 240 }),
+    url: cleanString(body.url, "url", { max: 2000 }),
+    title: cleanString(body.title, "title", { max: 500 }),
+    comment: cleanString(body.comment, "comment", { max: 2000 }),
+    agentId: cleanString(body.agentId, "agentId", { max: 200 }),
+    entityType: body.entityType === undefined ? undefined : cleanEnum(body.entityType, "entityType", ISSUE_ASSOCIATION_ENTITY_TYPES) as IssueAssociationEntityType,
+    entityId: cleanString(body.entityId, "entityId", { max: 240 }),
+  };
+}
+
+export const postIssueLifecycleReopenRoute: Handler = async (req) => {
+  const parsed = await parseBody<unknown>(req);
+  if (!parsed.ok) return error(parsed.error, parsed.status);
+  try {
+    const result = await reopenIssueLifecycle(cleanReopenBody(parsed.body));
+    if (result.action === "failed") return error(result.error, 502);
+    return json(result);
+  } catch (err) {
+    return error(err instanceof Error ? err.message : "issue lifecycle route failed");
+  }
+};