agent-relay-server 0.36.1 → 0.37.0

package/src/services/dispatch-command.ts

@@ -0,0 +1,60 @@
+// Transport convergence (epic #342, slice #346) — the command-dispatch service.
+//
+// ONE home for "a command was dispatched" — previously inlined in HTTP `postCommand`
+// (routes/commands.ts) and bus `handleCommandFrame`'s create branch (bus.ts), each with
+// its OWN copy of the authorization-resource builder (one used `cleanString`, the other
+// `stringValue` — a silent drift waiting to happen) and its own emit call. Transports now
+// shrink to: parse wire → `authContextFrom*` → `dispatchCommand` → serialize. The parity
+// harness asserts HTTP and bus produce a byte-identical command row + emitted event here.
+//
+// NOTE: the MCP command paths (agent.spawn / agent.shutdown) build *typed* commands and are
+// owned by the spawn (#349) / shutdown (#347) slices — they are NOT generic dispatch and stay
+// out of this service.
+import { isRecord, stringValue } from "agent-relay-sdk";
+import { createCommand } from "../commands-db";
+import { emitCommandEvent } from "../command-events";
+import { isComponentAuthorizedFor } from "../security";
+import { ServiceAuthError } from "./errors";
+import type { AuthContext } from "./auth-context";
+import type { Command, CreateCommandInput } from "../types";
+
+/** THE single home for the command authorization resource. Was duplicated in
+ * routes/commands.ts and bus.ts (diverging on `cleanString` vs `stringValue`) plus their
+ * two command-UPDATE paths — all four now import this. `stringValue` (trim + drop-empty)
+ * is the convergent form; the values only feed `constraintsAllow` target matching. */
+export function commandAuthorizationResource(input: Pick<CreateCommandInput, "target" | "params">) {
+  const params = isRecord(input.params) ? input.params : {};
+  return {
+    target: input.target,
+    agentId: stringValue(params.agentId) ?? input.target,
+    policyName: stringValue(params.policyName),
+    orchestratorId: stringValue(params.orchestratorId),
+    cwd: stringValue(params.cwd),
+    spawnRequestId: stringValue(params.spawnRequestId),
+  };
+}
+
+/** Authorize a command dispatch from the unified auth context. Mirrors BOTH old paths
+ * exactly: only a COMPONENT token carries per-resource constraints, so the gate is a no-op
+ * for admin/system/integration principals (which already cleared the coarse `command:write`
+ * scope gate at the transport edge — HTTP middleware `isScopedRequestAuthorized`, bus
+ * `withRegistered`). HTTP `authorizeRoute` and bus `busCommandAuthorized` both reduce to this:
+ * "no component token ⇒ allow; else `isComponentAuthorizedFor(command:write, resource)`". */
+function assertCommandAuthorized(ctx: AuthContext, input: CreateCommandInput): void {
+  if (!ctx.component) return;
+  const ok = isComponentAuthorizedFor(ctx.component, {
+    scope: "command:write",
+    resource: commandAuthorizationResource(input),
+  });
+  if (!ok) throw new ServiceAuthError("component token lacks command scope");
+}
+
+export function dispatchCommand(input: CreateCommandInput, ctx: AuthContext): Command {
+  assertCommandAuthorized(ctx, input);
+  const command = createCommand(input);
+  // A freshly created command is always `pending`; emit the literal "command.requested"
+  // (the relay auto-fans-out the follow-up "command.dispatched"). HTTP used the status-derived
+  // `emitCommand`, bus used `emitCommandEvent(_, "command.requested")` — identical for pending.
+  emitCommandEvent(command, "command.requested");
+  return command;
+}

package/src/services/errors.ts

@@ -0,0 +1,26 @@
+// Transport convergence (epic #342) — service-layer error types.
+//
+// The domain services in `src/services/` are transport-agnostic: they never build a
+// Response / a bus result frame / an MCP error. They THROW these typed errors and each
+// transport adapter maps them to its own wire shape (HTTP status, bus result, MCP error).
+// One throw, three faithful translations — so an authorization failure can never drift
+// into "403 on HTTP but silently succeeds on the bus".
+
+/** The caller's token is valid but lacks the scope/constraints for this operation.
+ * HTTP → 403, bus → command-result "rejected", MCP → auth error. */
+export class ServiceAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ServiceAuthError";
+  }
+}
+
+/** A direct target reference matched more than one agent — the relay can't decide who to send
+ * to, so it rejects rather than guessing (categorically different from a not_found, which is
+ * stored for later). HTTP → 409, MCP → invalid-params. */
+export class AmbiguousTargetError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AmbiguousTargetError";
+  }
+}

package/src/services/managed-running.ts

@@ -0,0 +1,130 @@
+// Transport convergence (epic #342) — the "managed agent came up running" core.
+//
+// ONE home for the state-transition + queue-flush that previously had three
+// separately-authored copies (HTTP `postAgent`, bus `onAgentRegistered`,
+// orchestrator-report `onOrchestratorManagedAgentsReported`). Those copies had
+// already drifted — backoffUntil cleared in 2 of 3, `message.new` emitted in 1 of 3,
+// two different managed-state emitters, `healthySince` reset-vs-preserve split.
+// This function is the single source of truth; the parity harness
+// (register-agent.parity.test.ts) asserts every transport produces identical
+// state + events through it.
+//
+// Composed by `registerAgent` (HTTP + bus registration) and called directly by the
+// orchestrator-report projection in lifecycle-manager. It does NOT upsert the agent
+// row — the agent registers itself over HTTP/bus; this only reconciles managed state.
+import { createActivityEvent, resolveQueuedPolicyMessages } from "../db";
+import { getManagedAgentState, updateManagedAgentState } from "../config-store";
+import { emitRelayEvent } from "../events";
+import { emitMessageAvailable, emitMessageDeliveryUpdated, emitNewMessage } from "../sse";
+import type { AuthContext } from "./auth-context";
+import type { ManagedAgentState } from "../types";
+
+export interface ManagedRunningInput {
+  policyName?: string;
+  spawnRequestId?: string;
+  agentId: string;
+  tmuxSession?: string | null;
+  /** Only the orchestrator-report path carries workspace identity. */
+  workspace?: { id?: string; worktreePath?: string; branch?: string };
+}
+
+/**
+ * Reconcile a managed agent to "running" and flush its queued policy messages.
+ * No-op for non-managed agents (no policy/spawnRequestId) and for a report that
+ * doesn't match the policy's live spawn — plain agents register through here too
+ * and must never touch managed state.
+ *
+ * Unified semantics (the drift reconciliation, per #345 strict-event-identity):
+ *  - `backoffUntil` is ALWAYS cleared on the transition to running.
+ *  - `healthySince` is set fresh when ENTERING running (from starting/backoff) and
+ *    PRESERVED on a re-register while already running — so a heartbeat re-register
+ *    doesn't reset the backoff-reset health clock, but a recovery does.
+ *  - the queue flush ALWAYS emits `message.available` + `message.new` + `message.delivery_updated`.
+ *  - the managed-state change emits via `emitManagedState` (source "lifecycle-manager"
+ *    + an activity-feed transition row), never the source-"server" `emitManagedAgentStateChanged`.
+ */
+export function markManagedAgentRunning(
+  input: ManagedRunningInput,
+  _ctx: AuthContext,
+  opts: { now?: () => number } = {},
+): void {
+  if (!input.policyName || !input.spawnRequestId) return;
+  const state = getManagedAgentState(input.policyName);
+  if (!state || state.spawnRequestId !== input.spawnRequestId) return;
+  const now = opts.now ?? (() => Date.now());
+
+  const fromState = state.status;
+  const next = updateManagedAgentState(input.policyName, {
+    status: "running",
+    agentId: input.agentId || state.agentId,
+    tmuxSession: input.tmuxSession ?? state.tmuxSession,
+    ...(input.workspace?.id !== undefined ? { workspaceId: input.workspace.id } : {}),
+    ...(input.workspace?.worktreePath !== undefined ? { workspacePath: input.workspace.worktreePath } : {}),
+    ...(input.workspace?.branch !== undefined ? { workspaceBranch: input.workspace.branch } : {}),
+    healthySince: fromState === "running" ? (state.healthySince ?? now()) : now(),
+    backoffUntil: undefined,
+    lastError: undefined,
+  });
+  if (next) emitManagedState(next, fromState);
+
+  const available = resolveQueuedPolicyMessages(input.policyName, input.agentId || state.agentId || "");
+  if (available.length) {
+    emitMessageAvailable(input.policyName, input.agentId || state.agentId || "", available);
+    for (const message of available) {
+      emitNewMessage(message);
+      // queued → pending flips delivery_status; the dashboard dedups message.new by
+      // id, so without an explicit delivery_updated the badge stays stale until the
+      // next poll (#265).
+      emitMessageDeliveryUpdated(message);
+    }
+  }
+}
+
+// --- Managed-state emitter (single home, shared with lifecycle-manager) -------
+// Extracted from LifecycleManager.emitState so registration and the lifecycle
+// reconciler emit the managed-state change identically: `policy.state.changed`
+// from source "lifecycle-manager" PLUS an activity-feed transition row on a real
+// from→to status change. Replaces the HTTP path's source-"server" emitter for
+// the came-up-running op.
+let transitionSeq = 0;
+
+export function emitManagedState(
+  state: ManagedAgentState,
+  fromState: string | undefined,
+  reason?: string,
+  now: () => number = () => Date.now(),
+): void {
+  emitRelayEvent({
+    type: "policy.state.changed",
+    source: "lifecycle-manager",
+    subject: state.policyName,
+    data: state as unknown as Record<string, unknown>,
+  });
+  if (fromState !== state.status) recordManagedTransition(state, fromState, reason, now);
+}
+
+function recordManagedTransition(
+  state: ManagedAgentState,
+  fromState: string | undefined,
+  reason: string | undefined,
+  now: () => number,
+): void {
+  const why = reason ?? state.lastError ?? undefined;
+  createActivityEvent({
+    clientId: `lifecycle-${state.policyName}-${state.status}-${now()}-${++transitionSeq}`,
+    kind: "state",
+    title: `${state.policyName}: ${fromState ?? "—"} → ${state.status}`,
+    body: why,
+    icon: "ti-arrows-exchange",
+    view: "managed-agents",
+    agentId: state.agentId,
+    metadata: {
+      source: "lifecycle-manager",
+      policyName: state.policyName,
+      spawnRequestId: state.spawnRequestId,
+      fromState: fromState ?? null,
+      toState: state.status,
+      reason: why ?? null,
+    },
+  });
+}

package/src/services/parity-harness.ts

@@ -0,0 +1,135 @@
+// Transport-convergence parity harness (epic #342, slice #350).
+//
+// A transport-agnostic engine for proving that ONE logical operation produces
+// IDENTICAL resulting DB state + emitted events through EVERY transport it can be
+// driven by (HTTP routes, WS bus, orchestrator-report projection, MCP …). Written
+// against the code as it stands, it goes RED on real drift; after the operation is
+// collapsed onto a single service it goes GREEN — and stays a ratchet against any
+// future re-divergence (sibling to duplication-ratchet.test.ts / file-size-ratchet.test.ts).
+//
+// Adding a new operation (shutdownAgent, spawnAgent, send-message) is dropping in a
+// new `ParityOp` descriptor — reset/seed/snapshot + a map of transports — NOT writing
+// a new framework. The engine here never changes.
+import { subscribeRelayEvents } from "../events";
+
+/** An emitted relay event, normalized to the fields parity compares — volatile
+ * `seq`/`timestamp` are deliberately dropped so only behavior, not ordering noise,
+ * is asserted. */
+export interface CapturedEvent {
+  type: string;
+  source: string;
+  subject?: string;
+  data: Record<string, unknown>;
+}
+
+/** Everything one transport run produced: the events it emitted, a snapshot of the
+ * resulting DB state (op-defined), and any side-effect probe values (state that an
+ * op mutates without emitting an event, e.g. a cleared watch). */
+export interface Capture<S> {
+  events: CapturedEvent[];
+  state: S;
+  probes: Record<string, unknown>;
+}
+
+/** One way to drive the operation. `invoke` performs the whole transport round-trip
+ * (incl. starting/stopping any server it needs) and resolves once the operation has
+ * settled so the harness can snapshot. Keep the abstraction swappable: a later slice
+ * can replace a direct-call transport with an end-to-end HTTP one without reshaping
+ * the harness. */
+export interface ParityTransport<C> {
+  id: string;
+  invoke(ctx: C): Promise<void>;
+}
+
+/** The contract every shared operation implements. `C` is the per-run scenario
+ * (knobs like policy name / re-register flags); `S` is the comparable DB snapshot. */
+export interface ParityOp<C, S> {
+  name: string;
+  /** Fresh DB + reset any in-memory singletons so runs don't leak into each other. */
+  reset(): void | Promise<void>;
+  /** Common preconditions shared by all transports (orchestrator, managed state, …). */
+  seed(ctx: C): void | Promise<void>;
+  /** The resulting DB state subset parity compares. */
+  snapshot(ctx: C): S;
+  /** Optional side-effect probes (no emitted event) — e.g. "was the watch cleared". */
+  probes?(ctx: C): Record<string, unknown>;
+  transports: Record<string, ParityTransport<C>>;
+}
+
+/** Drive one transport in isolation and capture everything it produced. */
+export async function captureTransport<C, S>(
+  op: ParityOp<C, S>,
+  transportId: string,
+  ctx: C,
+): Promise<Capture<S>> {
+  const transport = op.transports[transportId];
+  if (!transport) throw new Error(`parity op "${op.name}" has no transport "${transportId}"`);
+  await op.reset();
+  await op.seed(ctx);
+  const events: CapturedEvent[] = [];
+  const off = subscribeRelayEvents((e) =>
+    events.push({ type: e.type, source: e.source, subject: e.subject, data: e.data }),
+  );
+  try {
+    await transport.invoke(ctx);
+  } finally {
+    off();
+  }
+  return { events, state: op.snapshot(ctx), probes: op.probes?.(ctx) ?? {} };
+}
+
+/** Drive every named transport (each in its own fresh, seeded world) and return the
+ * captures keyed by transport id. Runs sequentially — each transport owns the DB. */
+export async function captureAll<C, S>(
+  op: ParityOp<C, S>,
+  transportIds: string[],
+  ctx: C,
+): Promise<Map<string, Capture<S>>> {
+  const out = new Map<string, Capture<S>>();
+  for (const id of transportIds) out.set(id, await captureTransport(op, id, ctx));
+  return out;
+}
+
+// --- comparison helpers (used by the per-op parity tests) --------------------
+
+/** Multiset of emitted events keyed `type|source`, optionally filtered (e.g. to one
+ * facet's event family). The key includes `source` so the "two emitters of one
+ * broadcast" drift (sse `server` vs lifecycle `lifecycle-manager`) surfaces. */
+export function eventKeyCounts(
+  events: CapturedEvent[],
+  filter?: (e: CapturedEvent) => boolean,
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  for (const e of events) {
+    if (filter && !filter(e)) continue;
+    const key = `${e.type}|${e.source}`;
+    counts[key] = (counts[key] ?? 0) + 1;
+  }
+  return counts;
+}
+
+/** True if any captured event matches type (and optional predicate on its data). */
+export function hasEvent(
+  cap: Capture<unknown>,
+  type: string,
+  where?: (e: CapturedEvent) => boolean,
+): boolean {
+  return cap.events.some((e) => e.type === type && (!where || where(e)));
+}
+
+/** Project each capture through `project` and return the distinct JSON shapes seen,
+ * with the transport ids that produced each. One entry ⇒ parity; more ⇒ drift, and
+ * the map shows exactly which transports diverged and how. */
+export function projectionGroups<S>(
+  captures: Map<string, Capture<S>>,
+  project: (cap: Capture<S>) => unknown,
+): Map<string, string[]> {
+  const groups = new Map<string, string[]>();
+  for (const [id, cap] of captures) {
+    const key = JSON.stringify(project(cap));
+    const ids = groups.get(key) ?? [];
+    ids.push(id);
+    groups.set(key, ids);
+  }
+  return groups;
+}

package/src/services/register-agent.ts

@@ -0,0 +1,74 @@
+// Transport convergence (epic #342, slice #345) — the agent-registration service.
+//
+// ONE home for "an agent registered" — previously inlined in HTTP `postAgent` and
+// split across bus `handleRegister` + `lifecycle.onAgentRegistered`. Transports now
+// shrink to: parse wire → `authContextFrom*` → `registerAgent` → serialize. The
+// parity harness asserts HTTP and bus produce byte-identical state + events here.
+//
+// Owns ALL policy + side effects of registration: authoritative lineage, the
+// managed came-up-running reconcile (delegated to managed-running.ts), the single
+// status broadcast, the single timeline note, the spawned-child parent-wake, and
+// the first-registration audit row.
+import { createActivityEvent, getAgent, upsertAgent } from "../db";
+import { emitAgentStatus } from "../sse";
+import { noteAgentTimelineEvent } from "../compaction-watch";
+import { notifyAgentReady } from "../agent-lifecycle-events";
+import { resolveSpawnLineage } from "../security";
+import { markManagedAgentRunning } from "./managed-running";
+import type { AuthContext } from "./auth-context";
+import type { AgentCard, RegisterAgentInput } from "../types";
+
+function metaStr(meta: Record<string, unknown> | undefined, key: string): string | undefined {
+  const value = meta?.[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export function registerAgent(input: RegisterAgentInput, ctx: AuthContext): AgentCard {
+  // Lineage is authoritative from the registering token's signed constraints — never
+  // the client-sent body (a child can't forge its own parent). Set by relay at spawn.
+  const lineage = resolveSpawnLineage(ctx.constraints);
+  if (lineage) input.spawnedBy = lineage;
+
+  const existing = getAgent(input.id);
+  const agent = upsertAgent(input);
+
+  // Managed came-up-running reconcile — no-op for non-managed agents (the guard lives
+  // in markManagedAgentRunning). Clears backoff, flushes the policy queue, transitions
+  // managed state to running.
+  markManagedAgentRunning(
+    {
+      policyName: metaStr(agent.meta, "policyName"),
+      spawnRequestId: metaStr(agent.meta, "spawnRequestId"),
+      agentId: agent.id,
+      tmuxSession: metaStr(agent.meta, "tmuxSession"),
+    },
+    ctx,
+  );
+
+  // ONE status broadcast (branch-state-enriched, #236), ONE timeline note. A real
+  // PreCompact/SessionStart hook arrives as a latched meta.timelineEvent — clears any
+  // pending stall watch; the timestamp guard inside ignores stale latched events.
+  emitAgentStatus(agent.id);
+  noteAgentTimelineEvent(agent.id, agent.meta?.timelineEvent);
+
+  // #308/#351 — a spawned child registering already-ready (the common isolated-worktree
+  // case) wakes its block-polling parent. Fire on the first-ever ready, regardless of
+  // transport. notifyAgentReady no-ops for non-spawned agents and dedups repeats.
+  if (agent.ready && !existing?.ready) notifyAgentReady(agent.id);
+
+  if (!existing) {
+    createActivityEvent({
+      clientId: `server-agent-${agent.id}-registered`,
+      kind: "state",
+      title: "Agent registered",
+      body: agent.name,
+      meta: agent.id,
+      icon: "ti-robot",
+      view: "agents",
+      agentId: agent.id,
+      metadata: { actor: ctx.actor.id, actorKind: ctx.actor.kind },
+    });
+  }
+
+  return agent;
+}

package/src/services/send-message.ts

@@ -0,0 +1,159 @@
+// Transport convergence (epic #342, slice #346) — the message-send service.
+//
+// ONE home for "an agent sent a message" — previously inlined in HTTP `postMessage`
+// (routes/messages.ts) and split across MCP `relaySendMessage` + `relayReply` (mcp.ts),
+// which had drifted on: caller-identity (HTTP trusted the wire `from`; MCP overrode it with
+// the token identity), target resolution (HTTP STORED an unknown target / 422-rejected an
+// offline one; MCP THREW on unknown / stored the offline), the authorization TARGET (HTTP
+// authorized the RAW ref, MCP the RESOLVED canonical id — so a bare ref a constraint allowed
+// could pass one transport and 403 the other), and side effects (HTTP emitted + woke an
+// on-demand policy; MCP did neither). Transports now shrink to: parse wire → build a
+// SendMessageInput → `authContextFrom*` → `sendMessageService` → serialize.
+//
+// CONVERGED RULES (the parity test is the ratchet):
+//   from        — `ctx.callerAgentId` (the resolved agent behind the token) WINS over any wire
+//                 `from`; the wire value is a fallback only for identity-less tokens.
+//   resolution  — resolve FIRST, then authorize the canonical id. Ambiguous → reject. Unknown /
+//                 offline → STORE (store-ahead) with a truthful DeliveryReceipt (delivered:false);
+//                 the receipt, not a transport-specific rejection, is the single source of
+//                 delivery truth. [Decision flagged to coordinator; see #346.]
+//   side effects— emit (queued vs new) + on-demand policy wake, on EVERY transport.
+//
+// OUT OF SCOPE (transport-edge, excluded from the parity facet): automatic memory injection
+// (needs request-derived context) and per-transport audit (HTTP domain row vs MCP tool-call row).
+import { isMechanicalMessageKind, isRecord, isReservedAgentId } from "agent-relay-sdk";
+import { ValidationError, getMessage, listAgents, sendMessageWithResult } from "../db";
+import { planSend, type DeliveryReceipt } from "../agent-ref";
+import { emitMessageQueued, emitNewMessage } from "../sse";
+import { getLifecycleManager } from "../lifecycle-manager";
+import { isComponentAuthorizedFor, isIntegrationAllowed } from "../security";
+import { AmbiguousTargetError, ServiceAuthError } from "./errors";
+import type { AuthContext } from "./auth-context";
+import type { IntegrationTokenConfig } from "../config";
+import type { Message, SendMessageInput } from "../types";
+
+export interface SendMessageResult {
+  message: Message;
+  created: boolean;
+  /** Synchronous delivery receipt (live recipients / queued / store-ahead). */
+  receipt: DeliveryReceipt;
+}
+
+export interface SendMessageOptions {
+  /** The integration token when the MCP caller authenticated with one. AuthContext stays lean
+   * (foundation contract) — the integration-specific target policy rides here, not on the ctx. */
+  integration?: IntegrationTokenConfig | null;
+}
+
+/** `from` resolves from the token identity: `callerAgentId` (the resolved agent behind the
+ * token) cannot be spoofed and WINS over any wire `from`. The wire value is a fallback only
+ * for identity-less tokens (admin/server/integration/multi-agent).
+ *
+ * EXCEPTION — the reserved-sink observability lane (#284): a mechanical post to user/system is
+ * the runner reporting an agent's turn ON ITS BEHALF, so the wire `from` (the reported agent) is
+ * authoritative there and the token's own identity must NOT override it. This is the relay's own
+ * lane (not agent-directed), the agentId authz predicate is dropped for it too, and it preserves
+ * the pre-convergence behavior — a steward/runner token managing other agents can still mirror. */
+function resolveFrom(input: SendMessageInput, ctx: AuthContext, reservedSink: boolean): string {
+  const from = reservedSink ? (input.from || ctx.callerAgentId) : (ctx.callerAgentId ?? input.from);
+  if (!from) throw new ValidationError("from is required");
+  return from;
+}
+
+/** Reply routing: when `to` is omitted and `replyTo` is set, auto-route to the parent's sender,
+ * inherit its channel, and propagate channel replyContext. ONE home — was HTTP's applyReplyRouting
+ * and MCP's replyContext, behaviorally identical. */
+function applyReplyRouting(input: SendMessageInput): void {
+  if (input.to || !input.replyTo) return;
+  const parent = getMessage(input.replyTo);
+  if (!parent) return;
+  input.to = parent.from;
+  if (!input.channel && parent.channel) input.channel = parent.channel;
+  const parentPayload = parent.payload ?? {};
+  if (parentPayload.schema === "agent-relay.channel.v1" || parentPayload.conversation) {
+    const replyContext: Record<string, unknown> = {};
+    if (parent.channel) replyContext.channelId = parent.channel;
+    if (isRecord(parentPayload.conversation)) replyContext.conversationId = parentPayload.conversation.id;
+    if (isRecord(parentPayload.event)) replyContext.parentEventId = parentPayload.event.id;
+    if (parentPayload.source) replyContext.source = parentPayload.source;
+    input.payload = { ...input.payload, replyContext };
+  }
+}
+
+/** Resolve the target to its canonical id and produce a synchronous receipt. MUTATES `input.to`
+ * to the rewritten canonical id (so poll-time exact matching works). Ambiguous → reject; unknown
+ * → store-ahead (verbatim `to`, receipt says not-yet-reachable); offline/direct/fanout → adopt the
+ * receipt (which already reports offline as delivered:false — no separate offline rejection). */
+function resolveSendTarget(input: SendMessageInput, from: string): DeliveryReceipt {
+  // Mechanical lifecycle/observability kinds (system/control/session) are the reserved-sink lane,
+  // not agent-directed routing — they pass through unresolved.
+  if (isMechanicalMessageKind(input.kind)) {
+    return { delivered: true, expectReply: false, recipients: input.to ? [input.to] : [] };
+  }
+  // excludeId: a bare ref must never resolve back to its own author — that self-loop silently
+  // swallows the message (the reddit-briefing → telegram bridge break, #290).
+  const plan = planSend(input.to, listAgents(), { excludeId: from });
+  // Ambiguous is a real "can't decide" → reject on every transport (categorically unlike
+  // not_found, which stores). HTTP → 409, MCP → invalid-params.
+  if (plan.kind === "ambiguous") throw new AmbiguousTargetError(plan.message);
+  if (plan.kind === "not_found") {
+    // Store-ahead: keep `to` verbatim; delivered when that id registers and polls. The receipt
+    // names the ref so the caller knows nobody is reachable yet (the single delivery-truth).
+    return { delivered: false, expectReply: false, recipients: [], reason: plan.message };
+  }
+  // direct (incl. a single OFFLINE match — receipt already carries reason "recipient offline")
+  // / fanout / passthrough: adopt the canonical (possibly rewritten) id + the receipt.
+  input.to = plan.to;
+  return plan.receipt;
+}
+
+/** Authorize the send against the unified context. Scope (`message:send`) is gated at the
+ * transport edge (HTTP middleware, MCP `hasAnyScope`); this is the RESOURCE/constraint gate.
+ * Only component + integration tokens carry constraints, so it's a no-op for admin/server. */
+function authorizeSend(input: SendMessageInput, ctx: AuthContext, opts: SendMessageOptions, reservedSink: boolean): void {
+  // A mechanical post to a reserved sink (user/system) is the relay's own observability lane
+  // (#284): a managed token's recipient constraints must NOT gate it, or constrained tokens
+  // (telegram policy, codex steward) 403 → the runner outbox retries 12× → poisons the record →
+  // the dashboard silently loses the turn. Drop the target/agentId predicate; keep the channel.
+  const resource = reservedSink
+    ? { channel: input.channel }
+    : { target: input.to, channel: input.channel, agentId: input.from };
+  if (ctx.component && !isComponentAuthorizedFor(ctx.component, { scope: "message:send", resource })) {
+    throw new ServiceAuthError("component token cannot send to this target");
+  }
+  if (opts.integration && !isIntegrationAllowed(opts.integration, { target: input.to, channel: input.channel })) {
+    throw new ServiceAuthError("integration token cannot target this message");
+  }
+}
+
+export function sendMessageService(
+  input: SendMessageInput,
+  ctx: AuthContext,
+  opts: SendMessageOptions = {},
+): SendMessageResult {
+  applyReplyRouting(input);
+  if (!input.to) throw new ValidationError("to is required (or provide replyTo to auto-route)");
+  // The reserved-sink observability lane (#284) governs both `from` resolution (wire `from` is
+  // authoritative — the runner reports an agent's turn) and authorization (drop the recipient
+  // predicate). Compute once, after reply-routing has settled `to`.
+  const reservedSink = isMechanicalMessageKind(input.kind) && isReservedAgentId(input.to);
+  input.from = resolveFrom(input, ctx, reservedSink);
+  // Resolve BEFORE authorize so both run against the canonical id (kills the HTTP-authorizes-raw
+  // vs MCP-authorizes-resolved drift).
+  const receipt = resolveSendTarget(input, input.from);
+  authorizeSend(input, ctx, opts, reservedSink);
+
+  const result = sendMessageWithResult(input);
+  if (result.created) {
+    if (result.message.deliveryStatus === "queued") {
+      emitMessageQueued(result.message);
+      // Wake an on-demand managed policy that has no live agent attached yet.
+      if (result.message.to?.startsWith("policy:")) {
+        getLifecycleManager().onMessageForPolicy(result.message.to.slice("policy:".length));
+      }
+    } else {
+      emitNewMessage(result.message);
+    }
+  }
+  return { message: result.message, created: result.created, receipt };
+}