agent-relay-server 0.62.3 → 0.63.1

package/src/bus.ts

@@ -15,6 +15,7 @@ import { applyCommandToRecipe } from "./recipe-runner";
 import { enqueueContinuationInjectionAfterClear } from "./self-resume";
 import { messageMatchesAgent, targetMatchesAgent } from "./agent-ref";
 import { probeWorkspaceOnTurnEnd } from "./workspace-probe";
+import { busStaleGraceMs } from "./config";
 import {
   BusProtocolError,
   parseBusFrame,
@@ -107,11 +108,9 @@ export function getBusConnectionCount(): number {
   return busConnections.size;
 }
 
-export function expireStaleBusAgents(graceMs = Number(process.env.AGENT_RELAY_STALE_GRACE_MS) || 120_000): { agentIds: string[]; orphanedTasks: Task[] } {
+export function expireStaleBusAgents(graceMs = busStaleGraceMs()): { agentIds: string[]; orphanedTasks: Task[] } {
   const cutoff = Date.now() - graceMs;
-  const rows = getDb()
-    .query("SELECT id FROM agents WHERE status = 'stale' AND last_seen < ? AND id NOT IN ('user', 'system')")
-    .all(cutoff) as Array<{ id: string }>;
+  const rows = getDb().query("SELECT id FROM agents WHERE status = 'stale' AND last_seen < ? AND id NOT IN ('user', 'system')").all(cutoff) as Array<{ id: string }>;
   const orphanedTasks: Task[] = [];
   for (const row of rows) {
     // Bus-grace staleness across a relay restart/reconnect — the process may be alive.

package/src/cli/_shared.ts

@@ -5,11 +5,12 @@
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { RELAY_TOKEN_HEADER } from "agent-relay-sdk";
+import { cliRelayToken, cliRelayUrl } from "../config";
 
 export async function apiRequest(method: string, path: string, body?: unknown): Promise<unknown> {
-  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const baseUrl = cliRelayUrl();
   const headers: Record<string, string> = {};
-  const token = process.env.AGENT_RELAY_TOKEN;
+  const token = cliRelayToken();
   if (token) headers[RELAY_TOKEN_HEADER] = token;
   if (body !== undefined) headers["Content-Type"] = "application/json";
   const response = await fetch(new URL(path, baseUrl), {
@@ -27,9 +28,9 @@ export async function apiRequest(method: string, path: string, body?: unknown):
 }
 
 export async function apiRawRequest(method: string, path: string, body: BodyInit, extraHeaders: Record<string, string> = {}): Promise<unknown> {
-  const baseUrl = process.env.AGENT_RELAY_URL || "http://127.0.0.1:4850";
+  const baseUrl = cliRelayUrl();
   const headers: Record<string, string> = { ...extraHeaders };
-  const token = process.env.AGENT_RELAY_TOKEN;
+  const token = cliRelayToken();
   if (token) headers[RELAY_TOKEN_HEADER] = token;
   const response = await fetch(new URL(path, baseUrl), { method, headers, body });
   const text = await response.text();

package/src/cli/agent-detect.ts

@@ -5,6 +5,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { apiRequest, uniqueStrings } from "./_shared";
+import { agentIdFromEnv, codexStatePathFromEnv, contextPathFromEnv } from "../config";
 
 export async function detectActivePairId(agentId: string): Promise<string | undefined> {
   const pairs = await apiRequest("GET", `/api/pairs?agent=${encodeURIComponent(agentId)}&status=active`) as Array<{ id?: string }>;
@@ -12,15 +13,16 @@ export async function detectActivePairId(agentId: string): Promise<string | unde
 }
 
 export async function detectAgentId(): Promise<string | undefined> {
-  const explicit = process.env.AGENT_RELAY_ID;
+  const explicit = agentIdFromEnv();
   if (explicit) return explicit;
 
   const contextMatch = currentAgentContextId();
   if (contextMatch) return contextMatch;
 
   const cwd = process.cwd();
-  const explicitCodexState = process.env.AGENT_RELAY_CODEX_STATE_PATH
-    ? readCodexState(process.env.AGENT_RELAY_CODEX_STATE_PATH)
+  const explicitCodexStatePath = codexStatePathFromEnv();
+  const explicitCodexState = explicitCodexStatePath
+    ? readCodexState(explicitCodexStatePath)
     : null;
   if (explicitCodexState?.agentId) return explicitCodexState.agentId;
 
@@ -48,7 +50,7 @@ export async function detectAgentId(): Promise<string | undefined> {
 }
 
 function currentAgentContextId(): string | undefined {
-  const explicitPath = process.env.AGENT_RELAY_CONTEXT_PATH;
+  const explicitPath = contextPathFromEnv();
   if (explicitPath) {
     const explicit = readAgentContext(explicitPath);
     if (explicit?.agentId && contextMatchesCurrentProcess(explicit)) return explicit.agentId;

package/src/cli/introspect.ts

@@ -2,6 +2,7 @@
 // end-of-session self-view as a bounded, structured Insights observation (#185).
 import { apiRequest, readStdin } from "./_shared";
 import { detectAgentId } from "./agent-detect";
+import { projectFromEnv, providerSessionIdFromEnv } from "../config";
 
 // Insights #185: capture the agent's end-of-session self-view as a bounded, structured
 // artifact (epic #183, docs/self-improvement.md). Manual rail in v0 — the agent or
@@ -61,8 +62,8 @@ export async function handleIntrospectCommand(args: string[]): Promise<void> {
   if (!from) throw new Error("Could not detect current Agent Relay ID. Pass --from AGENT_ID or set AGENT_RELAY_ID.");
 
   const observation = await apiRequest("POST", "/api/insights/observations", {
-    sessionId: sessionId || process.env.AGENT_RELAY_PROVIDER_SESSION_ID || `manual-${from}`,
-    project: project || process.env.AGENT_RELAY_PROJECT || process.cwd().split("/").filter(Boolean).at(-1) || process.cwd(),
+    sessionId: sessionId || providerSessionIdFromEnv() || `manual-${from}`,
+    project: project || projectFromEnv() || process.cwd().split("/").filter(Boolean).at(-1) || process.cwd(),
     agentId: from,
     signal: "introspection",
     source: "agent",

package/src/cli/token.ts

@@ -1,6 +1,7 @@
 // Token commands — auto-split from cli.ts (#294). create/list/revoke/verify for
 // component JWTs.
 import { apiRequest, splitTagArgs } from "./_shared";
+import { cliRelayToken } from "../config";
 
 export async function handleTokenCommand(args: string[]): Promise<void> {
   const action = args[0] ?? "list";
@@ -45,7 +46,7 @@ export async function handleTokenCommand(args: string[]): Promise<void> {
     return;
   }
   if (action === "verify") {
-    const token = rest.find((arg) => !arg.startsWith("--")) ?? process.env.AGENT_RELAY_TOKEN;
+    const token = rest.find((arg) => !arg.startsWith("--")) ?? cliRelayToken();
     if (!token) throw new Error("Usage: agent-relay token verify TOKEN");
     const payload = decodeJwtPayload(token);
     if (!payload) throw new Error("not a component JWT");

package/src/cli/workspace.ts

@@ -7,13 +7,14 @@ import { describeWorkspacePhase, readyContract, type WorkspacePhaseView } from "
 import type { WorkspaceDepsRefreshResult } from "agent-relay-sdk";
 import { AUTO_MERGE_POLICIES } from "../workspace-merge";
 import type { WorkspaceAutoMergePolicy } from "../types";
+import { workspaceJsonFromEnv } from "../config";
 
 export const WORKSPACE_USAGE = "Usage: agent-relay workspace <status|diagnostics|ready|land|claim|release|list|cleanup-stale|deps> [--id ID] [--strategy ...] [--auto-merge on-green|on-approval|manual] [--reviewer HANDLE] [--purpose TEXT] [--repo PATH] [--wait] [--timeout SECONDS] [--check] [--execute] [--json]";
 
 // The agent's own isolated-workspace id, published in AGENT_RELAY_WORKSPACE_JSON
 // by the orchestrator at spawn. Undefined for shared-workspace / non-managed agents.
 function currentWorkspaceId(): string | undefined {
-  const json = process.env.AGENT_RELAY_WORKSPACE_JSON;
+  const json = workspaceJsonFromEnv();
   if (!json) return undefined;
   try {
     const parsed = JSON.parse(json) as { id?: string };

package/src/config.ts

@@ -1,8 +1,10 @@
 // Shared runtime constants. Import from here rather than redefining.
 
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { DEFAULT_RELAY_URL, RELAY_TOKEN_HEADER } from "agent-relay-sdk";
 import { CONTRACT_VERSIONS } from "./contracts";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -19,6 +21,31 @@ function envPositiveInt(name: string, fallback: number): number {
   return Math.floor(parsed);
 }
 
+function envNumberOrDefault(name: string, fallback: number): number {
+  return Number(process.env[name]) || fallback;
+}
+
+function envNonNegativeNumber(name: string, fallback: number): number {
+  const parsed = Number(process.env[name]);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function envSafePositiveInteger(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function envTrimmed(name: string): string {
+  return (process.env[name] || "").trim();
+}
+
+function envTrimmedOrUndefined(name: string): string | undefined {
+  const value = process.env[name]?.trim();
+  return value || undefined;
+}
+
 export const STALE_TTL_MS = envPositiveInt("STALE_TTL_MS", 120_000); // 2min without heartbeat → offline
 // #451 — default TTL for fire-and-forget FAN-OUT messages (broadcast/tag/cap/label/team) that the
 // sender didn't bound. A stale fan-out push must not wake an agent that matches the target hours
@@ -42,12 +69,160 @@ export const MAIN_MERGE_PAUSE_TTL_MS = envPositiveInt("AGENT_RELAY_MAIN_MERGE_PA
 export const MAX_BODY_BYTES = 64 * 1024;
 export const INTEGRATION_RATE_LIMIT_PER_MINUTE = envPositiveInt("AGENT_RELAY_INTEGRATION_RATE_LIMIT_PER_MINUTE", 120);
 
-export const AUTH_TOKEN = process.env.AGENT_RELAY_TOKEN || "";
+export const AUTOMATION_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_AUTOMATION_INTERVAL_MS", 30 * 1000);
+export const IDLE_TIMEOUT_SECONDS = envNumberOrDefault("AGENT_RELAY_IDLE_TIMEOUT_SECONDS", 255);
+export const LOG_REQUESTS = process.env.AGENT_RELAY_LOG_REQUESTS === "1";
+
+const AUTH_TOKEN = process.env.AGENT_RELAY_TOKEN || "";
 export const CORS_ORIGINS = (process.env.AGENT_RELAY_CORS_ORIGINS || "")
   .split(",")
   .map((origin) => origin.trim())
   .filter(Boolean);
 
+export function relayToken(): string {
+  return process.env.AGENT_RELAY_TOKEN ?? AUTH_TOKEN;
+}
+
+export function relayAuthHeaders(base: Record<string, string> = {}): Record<string, string> {
+  const token = relayToken();
+  return token ? { ...base, [RELAY_TOKEN_HEADER]: token } : base;
+}
+
+export function allowUnauthenticated(): boolean {
+  return process.env.AGENT_RELAY_ALLOW_UNAUTH === "1";
+}
+
+export function tokenSecretFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN_SECRET;
+}
+
+export function corsOriginsFromEnv(): string[] | undefined {
+  const raw = process.env.AGENT_RELAY_CORS_ORIGINS;
+  if (raw === undefined) return undefined;
+  return raw.split(",").map((origin) => origin.trim()).filter(Boolean);
+}
+
+export function connectorsDirFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CONNECTORS_DIR;
+}
+
+export function connectorActionTimeoutMs(fallback: number): number {
+  const raw = Number(process.env.AGENT_RELAY_CONNECTOR_ACTION_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+
+export function rateLimitFallbackMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_RATE_LIMIT_FALLBACK_MS", 60 * 60 * 1000);
+}
+
+export function artifactsDir(): string {
+  return process.env.AGENT_RELAY_ARTIFACTS_DIR || "~/.agent-relay/artifacts";
+}
+
+export function maxArtifactBytesFromEnv(fallback: number): number {
+  return envSafePositiveInteger("AGENT_RELAY_MAX_ARTIFACT_BYTES", fallback);
+}
+
+export const OUTBOX_RETENTION_MS = envNumberOrDefault("AGENT_RELAY_OUTBOX_RETENTION_MS", 60 * 60 * 1000);
+export const TOKEN_RECORD_RETENTION_SECONDS = envNumberOrDefault("AGENT_RELAY_TOKEN_RECORD_RETENTION_SECONDS", 7 * 24 * 60 * 60);
+export const CONFLICT_SCAN_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_CONFLICT_SCAN_INTERVAL_MS", 10 * 60 * 1000);
+export const WORKSPACE_RETENTION_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_RETENTION_MS", DAY_MS);
+export const DB_MAINTENANCE_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_DB_MAINTENANCE_INTERVAL_MS", DAY_MS);
+export const DB_VACUUM_EVERY = envNumberOrDefault("AGENT_RELAY_DB_VACUUM_EVERY", 7);
+export const WORKSPACE_REVIEW_TTL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_REVIEW_TTL_MS", 3 * DAY_MS);
+export const WORKSPACE_GC_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_GC_INTERVAL_MS", 60 * 60 * 1000);
+export const WORKSPACE_ORPHAN_REAPER_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_ORPHAN_REAPER_INTERVAL_MS", 30 * 60 * 1000);
+export const WORKSPACE_AUTO_MERGE_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_AUTO_MERGE_INTERVAL_MS", CONFLICT_SCAN_INTERVAL_MS);
+export const ORPHAN_REAPER_INTERVAL_MS = envNumberOrDefault("AGENT_RELAY_ORPHAN_REAPER_INTERVAL_MS", 5 * 60 * 1000);
+export const STEWARD_WAKE_COOLDOWN_MS = envNumberOrDefault("AGENT_RELAY_STEWARD_WAKE_COOLDOWN_MS", 10 * 60 * 1000);
+export const UNLANDED_FLAG_COOLDOWN_MS = envNumberOrDefault("AGENT_RELAY_ORPHAN_FLAG_COOLDOWN_MS", 6 * 60 * 60 * 1000);
+export const STEWARD_CLAIM_TTL_MS = envNumberOrDefault("AGENT_RELAY_WORKSPACE_CLAIM_TTL_MS", 15 * 60_000);
+export const DB_SLOW_QUERY_MS = envNumberOrDefault("AGENT_RELAY_DB_SLOW_MS", 0);
+
+export function stewardEscalationMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_WORKSPACE_STEWARD_ESCALATION_MS", 60 * 60 * 1000);
+}
+
+export function stewardFallbackTarget(): string {
+  return envTrimmed("AGENT_RELAY_WORKSPACE_STEWARD_FALLBACK");
+}
+
+export function envMsOrDefault(name: string, fallback: number): number {
+  return envNonNegativeNumber(name, fallback);
+}
+
+export function orphanGraceMs(): number {
+  return envMsOrDefault("AGENT_RELAY_ORPHAN_GRACE_MS", 30 * 60 * 1000);
+}
+
+export function orphanReapCooldownMs(): number {
+  return envMsOrDefault("AGENT_RELAY_ORPHAN_REAP_COOLDOWN_MS", 5 * 60 * 1000);
+}
+
+export function orphanReapEnabled(): boolean {
+  return process.env.AGENT_RELAY_ORPHAN_REAP !== "0";
+}
+
+export function orphanWorktreeReapEnabled(): boolean {
+  return process.env.AGENT_RELAY_ORPHAN_WORKTREE_REAP !== "0";
+}
+
+export function workspaceAutoMergeEnabled(): boolean {
+  return process.env.AGENT_RELAY_WORKSPACE_AUTO_MERGE !== "0";
+}
+
+export function continuationArchiveFtsEnabled(): boolean {
+  return process.env.AGENT_RELAY_DISABLE_CONTINUATION_ARCHIVE_FTS !== "1";
+}
+
+export function busStaleGraceMs(): number {
+  return envNumberOrDefault("AGENT_RELAY_STALE_GRACE_MS", 120_000);
+}
+
+export function defaultIssueRepo(): string | undefined {
+  return process.env.AGENT_RELAY_DEFAULT_ISSUE_REPO || process.env.GITHUB_REPOSITORY || undefined;
+}
+
+export function cliRelayUrl(): string {
+  return process.env.AGENT_RELAY_URL || DEFAULT_RELAY_URL;
+}
+
+export function cliRelayToken(): string | undefined {
+  return process.env.AGENT_RELAY_TOKEN;
+}
+
+export function workspaceJsonFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_WORKSPACE_JSON;
+}
+
+export function providerSessionIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_PROVIDER_SESSION_ID;
+}
+
+export function projectFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_PROJECT;
+}
+
+export function agentIdFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_ID;
+}
+
+export function codexStatePathFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CODEX_STATE_PATH;
+}
+
+export function contextPathFromEnv(): string | undefined {
+  return process.env.AGENT_RELAY_CONTEXT_PATH;
+}
+
+export function localOrchestratorIdFromEnv(): string | undefined {
+  return envTrimmedOrUndefined("AGENT_RELAY_ORCHESTRATOR_ID");
+}
+
+export function providerConfigHomeFromEnv(): string {
+  return process.env.AGENT_RELAY_HOME || join(process.env.HOME || ".", ".agent-relay");
+}
+
 export type IntegrationTokenConfig = {
   name: string;
   token: string;

package/src/connectors.ts

@@ -5,6 +5,7 @@ import type { ConnectorAction, ConnectorActionResult, ConnectorManifest, Connect
 import { ValidationError } from "./db";
 import { isRecord } from "agent-relay-sdk";
 import { registerConnectorConfigSetting, validateConnectorConfig } from "./settings/modules";
+import { connectorActionTimeoutMs as configuredConnectorActionTimeoutMs, connectorsDirFromEnv } from "./config";
 
 const CONNECTOR_SCHEMA = "agent-relay.connector.v1";
 const VALID_KINDS = new Set(["channel", "event", "provider", "orchestrator"]);
@@ -12,7 +13,7 @@ const VALID_ACTIONS = new Set(["install", "uninstall", "enable", "disable", "sta
 const DEFAULT_ACTION_TIMEOUT_MS = 30_000;
 
 function connectorRegistryDir(): string {
-  const configured = process.env.AGENT_RELAY_CONNECTORS_DIR;
+  const configured = connectorsDirFromEnv();
   if (configured) return resolveHome(configured);
   return join(homedir(), ".agent-relay", "connectors");
 }
@@ -177,8 +178,7 @@ export function writeConnectorConfig(id: string, config: Record<string, unknown>
 }
 
 function connectorActionTimeoutMs(): number {
-  const raw = Number(process.env.AGENT_RELAY_CONNECTOR_ACTION_TIMEOUT_MS);
-  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_ACTION_TIMEOUT_MS;
+  return configuredConnectorActionTimeoutMs(DEFAULT_ACTION_TIMEOUT_MS);
 }
 
 const LIFECYCLE_ACTIONS = new Set(["install", "uninstall", "start", "stop", "restart", "enable", "disable"]);

package/src/db/activity.ts

@@ -98,7 +98,7 @@ export interface RecordIssueActivityInput {
   metadata?: Record<string, unknown>;
 }
 
-export interface IssueActivityAgentSummary {
+interface IssueActivityAgentSummary {
   agentId: string;
   agentName?: string;
   agentKind?: string;

package/src/db/agent-predicates.ts

@@ -0,0 +1,9 @@
+import type { AgentCard } from "../types";
+
+export function isDeliveryAgent(agent: AgentCard): boolean {
+  return agent.status !== "offline" &&
+    agent.id !== "user" &&
+    agent.id !== "system" &&
+    agent.kind !== "channel" &&
+    agent.meta?.kind !== "channel";
+}

package/src/db/agent-search.ts

@@ -105,9 +105,9 @@ export interface AgentSearchSort {
   limit?: number;
 }
 
-export const AGENT_SEARCH_MAX_LIMIT = 200;
+const AGENT_SEARCH_MAX_LIMIT = 200;
 
-export function searchValues(value: string | string[] | undefined): string[] {
+function searchValues(value: string | string[] | undefined): string[] {
   if (value == null) return [];
   return (Array.isArray(value) ? value : [value]).filter((v): v is string => typeof v === "string" && v.length > 0);
 }

package/src/db/agents.ts

@@ -14,13 +14,15 @@ import {
 } from "../contracts";
 import { STALE_TTL_MS, DAY_MS, CLAIM_LEASE_MS, POOL_CLAIM_LEASE_MS, WORKSPACE_MERGE_LEASE_MS } from "../config";
 import { matchAgents } from "../agent-ref";
-import { evaluatePoolBindings, expectedChannelAgentId, upsertChannelForAgent } from "./channels.ts";
+import { expectedChannelAgentId } from "./channel-identity.ts";
+import { evaluatePoolBindings, upsertChannelForAgent } from "./channels.ts";
 import { seedContinuationObjectiveFromSpawnPrompt } from "./continuations.ts";
 import { messageTaskClosed } from "./claim-sql.ts";
 import { ValidationError, getDb } from "./connection.ts";
 import { rowToAgent, rowToContextSnapshot } from "./mappers.ts";
-import { closeOpenPairsForAgent } from "./pairs.ts";
-import { TASK_SELECT, insertTaskEvent } from "./tasks.ts";
+import { closeOpenPairsForAgent } from "./pair-maintenance.ts";
+import { parseStringArray } from "./shared.ts";
+import { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
 import { electWorkspaceStewards, electWorkspaceStewardsForAgent } from "./workspaces.ts";
 import { DEFAULT_SELF_RESUME_CONFIG } from "../self-resume-config";
 import type { TokenRevokeReason } from "../security";
@@ -89,17 +91,13 @@ import type {
 
 const CONTEXT_SNAPSHOT_DEBOUNCE_MS = 60_000;
 
-export function parseStringArray(raw: string): string[] {
-  const parsed = parseJson<unknown>(raw, []);
-  if (!Array.isArray(parsed)) return [];
-  return parsed.filter((value): value is string => typeof value === "string");
-}
+export { parseStringArray } from "./shared.ts";
 
 export function normalizeTags(tags: string[] | undefined): string[] {
   return [...new Set((tags ?? []).map((tag) => tag.trim()).filter(Boolean))];
 }
 
-export function inferAgentKind(input: Pick<RegisterAgentInput, "id" | "kind" | "tags" | "capabilities" | "meta">): AgentKind {
+function inferAgentKind(input: Pick<RegisterAgentInput, "id" | "kind" | "tags" | "capabilities" | "meta">): AgentKind {
   if (input.kind) return input.kind;
   if (input.id === "user") return "user";
   if (input.id === "system") return "system";
@@ -110,7 +108,7 @@ export function inferAgentKind(input: Pick<RegisterAgentInput, "id" | "kind" | "
   return "provider";
 }
 
-export function inferProviderTag(input: RegisterAgentInput): "claude" | "codex" | undefined {
+function inferProviderTag(input: RegisterAgentInput): "claude" | "codex" | undefined {
   if (inferAgentKind(input) !== "provider") return undefined;
   const meta = input.meta ?? {};
   const values = [
@@ -134,7 +132,7 @@ export function inferProviderTag(input: RegisterAgentInput): "claude" | "codex"
   return undefined;
 }
 
-export function tagsWithProvider(input: RegisterAgentInput): string[] {
+function tagsWithProvider(input: RegisterAgentInput): string[] {
   const tags = normalizeTags(input.tags);
   const provider = inferProviderTag(input);
   if (!provider || tags.includes(provider)) return tags;
@@ -392,14 +390,14 @@ export function listContextSnapshots(agentId: string, options: { since?: number;
   return (getDb().query(sql).all(...params) as any[]).map(rowToContextSnapshot);
 }
 
-export function pruneContextSnapshots(agentId?: string, olderThan = Date.now() - DAY_MS): number {
+function pruneContextSnapshots(agentId?: string, olderThan = Date.now() - DAY_MS): number {
   const result = agentId
     ? getDb().query("DELETE FROM context_snapshots WHERE agent_id = ? AND captured_at < ?").run(agentId, olderThan)
     : getDb().query("DELETE FROM context_snapshots WHERE captured_at < ?").run(olderThan);
   return result.changes;
 }
 
-export function recordContextSnapshot(agentId: string, context: ContextState, now: number): void {
+function recordContextSnapshot(agentId: string, context: ContextState, now: number): void {
   const latest = getDb()
     .query("SELECT captured_at FROM context_snapshots WHERE agent_id = ? ORDER BY captured_at DESC LIMIT 1")
     .get(agentId) as { captured_at: number } | undefined;
@@ -464,33 +462,7 @@ export function reapStaleAgents(ttlMs: number = STALE_TTL_MS): string[] {
   return rows.map((r: any) => r.id);
 }
 
-// On-demand automation tasks (targetMode=on_demand_agent) are bound to a single
-// ephemeral agent spawned just for that task. When that agent's claim is released —
-// clean shutdown, prune, lease expiry, or orphan-grace — the task must NOT return to
-// the claimable pool: its target is a unique `label:automation-…` that no other agent
-// will ever match, so a re-opened task lingers forever as an orphaned claim. Resolve
-// those as done instead; automation reconcile then settles the run as succeeded.
-// Run this BEFORE the generic re-open UPDATE at each release site, with the same WHERE
-// condition: it flips matching single-target tasks to 'done', which the subsequent
-// re-open (gated on status IN claimed/in_progress/blocked/orphaned) then skips.
-export function settleSingleTargetOnDemandTasks(condition: string, params: any[], now: number, reason: string): void {
-  const selectSql = `${TASK_SELECT} WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`;
-  const rows = getDb().query(selectSql).all(...params) as any[];
-  if (rows.length === 0) return;
-  getDb().query(
-    `UPDATE tasks SET status = 'done', claim_expires_at = NULL, updated_at = ?, last_seen_at = ? WHERE (${condition}) AND json_extract(metadata, '$.targetMode') = 'on_demand_agent' AND status IN ('claimed', 'in_progress', 'blocked', 'orphaned')`
-  ).run(now, now, ...params);
-  for (const row of rows) {
-    insertTaskEvent(row.id, {
-      source: "agent-relay",
-      type: "task.auto-completed",
-      severity: row.severity,
-      title: "On-demand task auto-resolved",
-      body: `On-demand agent ${row.claimed_by ?? "(unknown)"} exited (${reason}); task resolved so it does not orphan`,
-      metadata: { agentId: row.claimed_by, reason, completedBy: "relay" },
-    }, now);
-  }
-}
+export { settleSingleTargetOnDemandTasks } from "./task-maintenance.ts";
 
 export function pruneOfflineAgents(maxOfflineMs: number = DAY_MS): string[] {
   const cutoff = Date.now() - maxOfflineMs;
@@ -578,7 +550,7 @@ export function revokeRuntimeTokensForAgent(agentId: string, now = Date.now(), r
   return rows.map((item) => item.jti);
 }
 
-export function runtimeTokenJtisFromMeta(meta: Record<string, unknown>): string[] {
+function runtimeTokenJtisFromMeta(meta: Record<string, unknown>): string[] {
   const jtis = new Set<string>();
   const auth = isRecord(meta.auth) ? meta.auth : undefined;
   const direct = typeof auth?.jti === "string" ? auth.jti : typeof meta.runtimeTokenJti === "string" ? meta.runtimeTokenJti : undefined;

package/src/db/artifacts.ts

@@ -82,28 +82,28 @@ import type {
 // --- Artifacts ---
 
 export const VALID_ARTIFACT_KINDS = new Set<ArtifactKind>(["image", "audio", "video", "document", "archive", "other"]);
-export const VALID_ARTIFACT_VISIBILITIES = new Set<ArtifactVisibility>(["private", "project", "org"]);
+const VALID_ARTIFACT_VISIBILITIES = new Set<ArtifactVisibility>(["private", "project", "org"]);
 export const VALID_ARTIFACT_SENSITIVITIES = new Set<ArtifactSensitivity>(["public", "normal", "sensitive", "secret"]);
-export const VALID_ARTIFACT_LINK_ENTITY_TYPES = new Set<ArtifactLink["entityType"]>(["message", "task", "recipeRun", "recipeStep", "channelEvent"]);
+const VALID_ARTIFACT_LINK_ENTITY_TYPES = new Set<ArtifactLink["entityType"]>(["message", "task", "recipeRun", "recipeStep", "channelEvent"]);
 export const VALID_ARTIFACT_ROLES = new Set<NonNullable<ArtifactLink["role"]>>(["media", "patch", "report", "log", "output", "input"]);
 
 export function artifactId(): string {
   return `art_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
 }
 
-export function artifactLinkId(): string {
+function artifactLinkId(): string {
   return `alink_${randomUUID().replace(/-/g, "").slice(0, 16)}`;
 }
 
-export function normalizeArtifactKind(kind: unknown): ArtifactKind {
+function normalizeArtifactKind(kind: unknown): ArtifactKind {
   return typeof kind === "string" && VALID_ARTIFACT_KINDS.has(kind as ArtifactKind) ? kind as ArtifactKind : "other";
 }
 
-export function normalizeArtifactVisibility(visibility: unknown): ArtifactVisibility {
+function normalizeArtifactVisibility(visibility: unknown): ArtifactVisibility {
   return typeof visibility === "string" && VALID_ARTIFACT_VISIBILITIES.has(visibility as ArtifactVisibility) ? visibility as ArtifactVisibility : "project";
 }
 
-export function normalizeArtifactSensitivity(sensitivity: unknown): ArtifactSensitivity {
+function normalizeArtifactSensitivity(sensitivity: unknown): ArtifactSensitivity {
   return typeof sensitivity === "string" && VALID_ARTIFACT_SENSITIVITIES.has(sensitivity as ArtifactSensitivity) ? sensitivity as ArtifactSensitivity : "normal";
 }
 
@@ -212,7 +212,7 @@ export function deleteArtifact(id: string): boolean {
   })();
 }
 
-export function listArtifactLinks(artifactId: string): ArtifactLink[] {
+function listArtifactLinks(artifactId: string): ArtifactLink[] {
   return (getDb().query("SELECT * FROM artifact_links WHERE artifact_id = ? ORDER BY created_at ASC").all(artifactId) as any[]).map(rowToArtifactLink);
 }
 
@@ -271,7 +271,7 @@ export function artifactBlobReferenceCount(digest: string): number {
   return row.count ?? 0;
 }
 
-export function unreferencedArtifactBlobs(): ArtifactBlob[] {
+function unreferencedArtifactBlobs(): ArtifactBlob[] {
   return (getDb().query(`
     SELECT b.*
     FROM artifact_blobs b

package/src/db/channel-identity.ts

@@ -0,0 +1,38 @@
+import { stringValue } from "agent-relay-sdk";
+import type { AgentCard, RegisterAgentInput } from "../types";
+
+export function channelProviderForAgent(agent: AgentCard): string {
+  return stringValue(agent.meta?.provider) ??
+    stringValue(agent.meta?.channelType) ??
+    stringValue(agent.meta?.transport) ??
+    agent.tags.find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
+    "custom";
+}
+
+function channelProviderForInput(input: Pick<RegisterAgentInput, "tags" | "meta">): string {
+  return stringValue(input.meta?.provider) ??
+    stringValue(input.meta?.channelType) ??
+    stringValue(input.meta?.transport) ??
+    (input.tags ?? []).find((tag) => tag.startsWith("channel:"))?.slice("channel:".length) ??
+    "custom";
+}
+
+export function channelAccountIdForAgent(agent: AgentCard, provider: string): string {
+  const accountId = stringValue(agent.meta?.accountId);
+  if (accountId) return accountId;
+  const prefix = `${provider}:`;
+  return agent.id.startsWith(prefix) ? agent.id.slice(prefix.length) : agent.id;
+}
+
+function channelAccountIdForInput(input: Pick<RegisterAgentInput, "id" | "meta">, provider: string): string {
+  const accountId = stringValue(input.meta?.accountId);
+  if (accountId) return accountId;
+  const prefix = `${provider}:`;
+  return input.id.startsWith(prefix) ? input.id.slice(prefix.length) : input.id;
+}
+
+export function expectedChannelAgentId(input: Pick<RegisterAgentInput, "id" | "tags" | "meta">): string {
+  const provider = channelProviderForInput(input);
+  const accountId = channelAccountIdForInput(input, provider);
+  return `${provider}:${accountId}`;
+}