@relaycast/engine 6.1.0 → 6.2.0

package/dist/engine/invocationCompletion.js

@@ -1,5 +1,8 @@
+import { and, eq } from 'drizzle-orm';
+import { z } from 'zod';
 import { transformForClient } from './wsTransform.js';
 import { enqueueEvent } from './eventQueue.js';
+import { actionInvocations } from '../db/schema.js';
 import { sendNodeDeliveriesToAgents } from './nodeDeliver.js';
 import { appendAndPublishWorkspaceEvent } from './workspaceEvents.js';
 function buildEvent(type, workspaceId, data) {
@@ -40,22 +43,123 @@ export async function emitInvocationCompletionEffects(deps, workspaceId, result)
     // Through the durable log so observers can backfill action results too.
     fanoutTasks.push(appendAndPublishWorkspaceEvent({ db: deps.db, realtime: deps.realtime }, workspaceId, { type: eventType, payload }));
     await Promise.allSettled(fanoutTasks);
+    await enqueueAndSendWebhook(deps, workspaceId, eventType, result);
+}
+/**
+ * Push one event through the durable outbox + external webhook queue. Both steps
+ * are best-effort — a caller's state transition must never fail because the
+ * outbox insert or queue send did.
+ */
+async function enqueueAndSendWebhook(deps, workspaceId, eventType, data) {
     let outboxId;
     try {
-        outboxId = await enqueueEvent(deps.db, workspaceId, eventType, result);
+        outboxId = await enqueueEvent(deps.db, workspaceId, eventType, data);
     }
     catch {
         // Best-effort: if the durable outbox row can't be inserted, still try the queue send.
     }
     try {
-        await deps.webhookQueue.send(outboxId ? { type: eventType, workspaceId, data: result, outboxId } : {
+        await deps.webhookQueue.send(outboxId ? { type: eventType, workspaceId, data, outboxId } : {
             type: eventType,
             workspaceId,
-            data: result,
+            data,
         });
     }
     catch {
-        // Best-effort side effect; completion must not fail because webhook delivery did.
+        // Best-effort side effect; the state transition must not fail because webhook delivery did.
+    }
+}
+/** Shape of the `metadata.fleet.invocation_id` spawn correlation. Unknown keys
+ * are stripped by default, so extra metadata fields are tolerated. */
+const fleetInvocationSchema = z.object({
+    fleet: z.object({ invocation_id: z.string() }),
+});
+/**
+ * Extract the spawn invocation id an agent was registered under, if any. The
+ * `metadata.fleet.invocation_id` correlation is written by `registerAgentViaNode`
+ * on every via-node agent.
+ */
+export function fleetInvocationId(metadata) {
+    const parsed = fleetInvocationSchema.safeParse(metadata);
+    return parsed.success ? parsed.data.fleet.invocation_id : null;
+}
+/** Resolve the caller mailbox of a spawn invocation; best-effort (null on any error). */
+async function lookupSpawnCaller(db, workspaceId, invocationId) {
+    try {
+        const [row] = await db
+            .select({ callerId: actionInvocations.callerId })
+            .from(actionInvocations)
+            .where(and(eq(actionInvocations.workspaceId, workspaceId), eq(actionInvocations.id, invocationId)));
+        return row?.callerId ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fan out a durable `agent.exited` event across the same three channels as
+ * invocation completion: (1) the spawn caller's mailbox (when the exit
+ * correlates to a spawn invocation with a live caller), (2) the durable
+ * workspace event log + live observer stream, and (3) the webhook outbox.
+ *
+ * Best-effort by contract — every channel is isolated so the underlying agent
+ * state transition (deregister / inventory reconcile / release) never fails
+ * because an emission did.
+ */
+export async function emitAgentExitedEffects(deps, workspaceId, input) {
+    const eventType = 'agent.exited';
+    const eventData = {
+        agent_id: input.agentId,
+        agent_name: input.agentName,
+        node_id: input.nodeId,
+        invocation_id: input.invocationId,
+        reason: input.reason,
+    };
+    const event = buildEvent(eventType, workspaceId, eventData);
+    const payload = transformForClient(event);
+    const fanoutTasks = [];
+    // Notify the spawn caller's mailbox so a spawner learns its agent exited. The
+    // stable eventKey dedupes redundant emissions of the same logical exit.
+    const callerId = input.invocationId ? await lookupSpawnCaller(deps.db, workspaceId, input.invocationId) : null;
+    if (callerId) {
+        fanoutTasks.push(sendNodeDeliveriesToAgents({
+            db: deps.db,
+            nodeConnections: deps.nodeConnections,
+            workspaceId,
+            environment: deps.config?.environment,
+            httpPushProxy: deps.config?.httpPushProxy,
+        }, {
+            agentIds: [callerId],
+            event: eventType,
+            // Omit messageId so delivery falls back to this unique eventKey (agent +
+            // invocation + reason). A messageId keyed only on agentId would repeat
+            // across an agent's lifecycle sessions and a downstream dedup on it could
+            // drop later exit notifications.
+            eventKey: `${input.agentId}_${input.invocationId ?? 'none'}_${input.reason}`,
+            data: eventData,
+        }));
     }
+    fanoutTasks.push(appendAndPublishWorkspaceEvent({ db: deps.db, realtime: deps.realtime }, workspaceId, { type: eventType, payload }));
+    await Promise.allSettled(fanoutTasks);
+    await enqueueAndSendWebhook(deps, workspaceId, eventType, eventData);
+}
+/**
+ * Fan out a durable `node.status.online` / `node.status.offline` event. Node
+ * death has no single caller mailbox, so only the durable workspace log + live
+ * stream and the webhook outbox apply. Best-effort by contract.
+ */
+export async function emitNodeStatusEffects(deps, workspaceId, input) {
+    const eventType = input.status === 'online' ? 'node.status.online' : 'node.status.offline';
+    const eventData = {
+        node_id: input.nodeId,
+        node_name: input.nodeName,
+        ...(input.status === 'offline' && input.reason ? { reason: input.reason } : {}),
+    };
+    const event = buildEvent(eventType, workspaceId, eventData);
+    const payload = transformForClient(event);
+    await Promise.allSettled([
+        appendAndPublishWorkspaceEvent({ db: deps.db, realtime: deps.realtime }, workspaceId, { type: eventType, payload }),
+    ]);
+    await enqueueAndSendWebhook(deps, workspaceId, eventType, eventData);
 }
 //# sourceMappingURL=invocationCompletion.js.map

package/dist/engine/invocationCompletion.js.map

@@ -1 +1 @@
-{"version":3,"file":"invocationCompletion.js","sourceRoot":"","sources":["../../src/engine/invocationCompletion.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AAatE,SAAS,UAAU,CAAC,IAAY,EAAE,WAAmB,EAAE,IAA6B;IAClF,OAAO;QACL,IAAI;QACJ,YAAY,EAAE,WAAW;QACzB,IAAI;QACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,+BAA+B,CACnD,IAA8B,EAC9B,WAAmB,EACnB,MAAwB;IAExB,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,kBAAkB,CAAC;IACpF,MAAM,YAAY,GAAG;QACnB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,WAAW,EAAE,MAAM,CAAC,WAAW;QAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,KAAK,EAAE,MAAM,CAAC,KAAK;KACpB,CAAC;IACF,MAAM,KAAK,GAAG,UAAU,CAAC,SAAS,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;IAC/D,MAAM,OAAO,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAE1C,MAAM,WAAW,GAAuB,EAAE,CAAC;IAC3C,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QACrB,WAAW,CAAC,IAAI,CACd,0BAA0B,CAAC;YACzB,EAAE,EAAE,IAAI,CAAC,EAAE;YACX,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,WAAW;YACX,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,WAAW;YACrC,aAAa,EAAE,IAAI,CAAC,MAAM,EAAE,aAAa;SAC1C,EAAE;YACD,QAAQ,EAAE,CAAC,MAAM,CAAC,SAAS,CAAC;YAC5B,KAAK,EAAE,SAAS;YAChB,QAAQ,EAAE,MAAM,CAAC,aAAa;YAC9B,IAAI,EAAE,YAAY;YAClB,SAAS,EAAE,MAAM,CAAC,aAAa;SAChC,CAAC,CACH,CAAC;IACJ,CAAC;IACD,wEAAwE;IACxE,WAAW,CAAC,IAAI,CACd,8BAA8B,CAC5B,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,EACxC,WAAW,EACX,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAC7B,CACF,CAAC;IACF,MAAM,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;IAEtC,IAAI,QAA4B,CAAC;IACjC,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,SAAS,EAAE,MAAiC,CAAC,CAAC;IACpG,CAAC;IAAC,MAAM,CAAC;QACP,sFAAsF;IACxF,CAAC;IAED,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;YACjG,IAAI,EAAE,SAAS;YACf,WAAW;YACX,IAAI,EAAE,MAAM;SACb,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,kFAAkF;IACpF,CAAC;AACH,CAAC"}
+{"version":3,"file":"invocationCompletion.js","sourceRoot":"","sources":["../../src/engine/invocationCompletion.ts"],"names":[],"mappings":"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"}

package/dist/engine/node.d.ts

@@ -3,7 +3,7 @@ import type { getDb } from '../db/index.js';
 import { agents, nodes } from '../db/schema.js';
 import type { EngineDb } from '../ports/database.js';
 import { type NodeConnectionRegistry } from '../ports/realtime.js';
-import type { InvocationCompletionDeps } from './invocationCompletion.js';
+import type { InvocationCompletionDeps, NodeOfflineReason } from './invocationCompletion.js';
 type Db = ReturnType<typeof getDb>;
 type NodeRow = typeof nodes.$inferSelect;
 type AgentRow = typeof agents.$inferSelect;
@@ -148,6 +148,69 @@ export declare function getNodeByName(db: Db, workspaceId: string, name: string)
     lastHeartbeatAt: Date | null;
     createdAt: Date;
 }>;
+export declare function getNodeById(db: Db, workspaceId: string, nodeId: string): Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    tokenHash: string;
+    machineId: string | null;
+    kind: string;
+    role: string;
+    deliveryAdapter: string;
+    deliveryConfig: Record<string, unknown> | null;
+    capabilities: {
+        name: string;
+        kind?: string | undefined;
+        global?: boolean | undefined;
+        queue?: boolean | undefined;
+        metadata?: Record<string, import("@relaycast/types").FleetWireJsonValue> | undefined;
+    }[];
+    maxAgents: number;
+    activeAgents: number;
+    reservedAgents: number;
+    tags: string[];
+    version: string;
+    status: string;
+    handlersLive: boolean;
+    load: number;
+    lastHeartbeatAt: Date | null;
+    createdAt: Date;
+}>;
+/**
+ * Resolve the node an enroll (POST /v1/nodes) targets: by node_id when
+ * supplied, by name otherwise.
+ */
+export declare function resolveNodeForEnroll(db: Db, workspaceId: string, data: {
+    node_id?: string;
+    name: string;
+}): Promise<{
+    id: string;
+    workspaceId: string;
+    name: string;
+    tokenHash: string;
+    machineId: string | null;
+    kind: string;
+    role: string;
+    deliveryAdapter: string;
+    deliveryConfig: Record<string, unknown> | null;
+    capabilities: {
+        name: string;
+        kind?: string | undefined;
+        global?: boolean | undefined;
+        queue?: boolean | undefined;
+        metadata?: Record<string, import("@relaycast/types").FleetWireJsonValue> | undefined;
+    }[];
+    maxAgents: number;
+    activeAgents: number;
+    reservedAgents: number;
+    tags: string[];
+    version: string;
+    status: string;
+    handlersLive: boolean;
+    load: number;
+    lastHeartbeatAt: Date | null;
+    createdAt: Date;
+}>;
 export interface RegisterNodeResult {
     node: ReturnType<typeof publicNode>;
     acceptance: FleetCapabilityAcceptance[];
@@ -179,20 +242,23 @@ export declare function heartbeatNode(db: Db, workspaceId: string, nodeId: strin
     last_heartbeat_at: string | null;
     created_at: string;
 } | null>;
-export declare function markNodeOffline(db: Db, registry: NodeConnectionRegistry, workspaceId: string, nodeId: string): Promise<void>;
+export declare function markNodeOffline(db: Db, registry: NodeConnectionRegistry, workspaceId: string, nodeId: string, effects?: {
+    deps?: InvocationCompletionDeps;
+    reason?: NodeOfflineReason;
+}): Promise<void>;
 /**
  * A provider's control connection dropped. Its capability set persists (marked
  * offline) so the node still shows the manifest; agents it hosted go offline.
  * When it was the node's last connection the whole node goes offline.
  */
-export declare function handleProviderDisconnect(db: Db, registry: NodeConnectionRegistry, workspaceId: string, nodeId: string, providerName: string, hasRemainingConnections: boolean): Promise<void>;
+export declare function handleProviderDisconnect(db: Db, registry: NodeConnectionRegistry, workspaceId: string, nodeId: string, providerName: string, hasRemainingConnections: boolean, deps?: InvocationCompletionDeps): Promise<void>;
 /**
  * Provider-scoped deregister: removes the provider's attachment, persisted
  * capability set, and materialized actions. When it was the node's last
  * provider the node goes fully offline.
  */
-export declare function deregisterProvider(db: Db, registry: NodeConnectionRegistry, workspaceId: string, nodeId: string, providerName: string): Promise<void>;
-export declare function sweepOfflineNodes(db: Db, registry: NodeConnectionRegistry): Promise<number>;
+export declare function deregisterProvider(db: Db, registry: NodeConnectionRegistry, workspaceId: string, nodeId: string, providerName: string, deps?: InvocationCompletionDeps): Promise<void>;
+export declare function sweepOfflineNodes(db: Db, registry: NodeConnectionRegistry, deps?: InvocationCompletionDeps): Promise<number>;
 export declare function ensureDirectNodeForAgent(db: Db, workspaceId: string, agent: Pick<AgentRow, 'id' | 'name' | 'locationNodeId'>, opts?: {
     force?: boolean;
     online?: boolean;
@@ -261,7 +327,7 @@ export declare function registerAgentViaNode(db: Db, workspaceId: string, nodeId
 export declare function deregisterAgentViaNode(db: Db, workspaceId: string, nodeId: string, message: {
     agent_id?: string;
     name?: string;
-}): Promise<{
+}, deps?: InvocationCompletionDeps): Promise<{
     id: string;
     name: string;
     createdAt: Date;

package/dist/engine/node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/engine/node.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/engine/node.ts"],"names":[],"mappings":"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"}

package/dist/engine/node.js

@@ -10,7 +10,7 @@ import { isNodeLive, nodeHasCapability } from './placement.js';
 import { DEFAULT_PROVIDER_NAME, capabilityKind, heartbeatProvider, markProviderOffline, materializeProviderActions, recomputeNodeAggregate, removeProvider, upsertProvider, } from './nodeProvider.js';
 import { serializeNodeOp } from './nodeLock.js';
 import { completeNodeInvocation, dispatchCapacitySpawn, rescheduleInvocationsForLostNode, rescheduleNodeInvocation, } from './action.js';
-import { emitInvocationCompletionEffects } from './invocationCompletion.js';
+import { emitInvocationCompletionEffects, emitAgentExitedEffects, emitNodeStatusEffects, fleetInvocationId } from './invocationCompletion.js';
 import { ackDeliveriesUpToSeq, deliverPendingToNode } from './delivery.js';
 function resolveProviderIdentity(message, connectionId) {
     if (message.provider)
@@ -121,7 +121,24 @@ function normalizeLegacyAdapter(adapter) {
 export async function createNodeToken(db, workspaceId, data) {
     const token = `nt_live_${randomHex(24)}`;
     const tokenHash = await sha256Hex(token);
-    const existing = await getNodeByName(db, workspaceId, data.name);
+    const name = data.name.startsWith('#') ? data.name.slice(1) : data.name;
+    // Reject names that are empty or still #-prefixed after normalization: an
+    // empty name is unreachable via /v1/nodes/:name, and a residual "#" would
+    // dodge every name lookup (including the conflict check below).
+    if (!name || name.startsWith('#')) {
+        throw codedError('Node name must be non-empty and cannot begin with "#"', 'invalid_node_name', 400);
+    }
+    // Enrollment keys on node_id (the stable identity) when supplied; the name
+    // lookup is only a fallback for callers without a stable id. A name held by
+    // a *different* node id is a conflict — mirroring node.register — never a
+    // silent rewrite of the other node.
+    const existing = await resolveNodeForEnroll(db, workspaceId, data);
+    if (data.node_id !== undefined) {
+        const nameHolder = await getNodeByName(db, workspaceId, name);
+        if (nameHolder && nameHolder.id !== data.node_id) {
+            throw codedError(`Node name "${name}" is already enrolled by another node`, 'node_name_conflict', 409);
+        }
+    }
     const now = new Date();
     const existingShape = existing ? normalizeLegacyNodeShape(existing.kind, existing.role) : null;
     const normalized = normalizeLegacyNodeShape(data.kind ?? existing?.kind ?? 'ws', data.role ?? existing?.role ?? (data.max_agents !== undefined && data.max_agents > 1 ? 'broker' : undefined));
@@ -146,6 +163,7 @@ export async function createNodeToken(db, workspaceId, data) {
         const [updated] = await db
             .update(nodes)
             .set({
+            name,
             tokenHash,
             kind,
             role,
@@ -167,7 +185,7 @@ export async function createNodeToken(db, workspaceId, data) {
         .values({
         id: data.node_id ?? `node_${generateId()}`,
         workspaceId,
-        name: data.name,
+        name,
         tokenHash,
         kind,
         role,
@@ -198,6 +216,23 @@ export async function getNodeByName(db, workspaceId, name) {
         .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.name, normalized)));
     return node ?? null;
 }
+export async function getNodeById(db, workspaceId, nodeId) {
+    const [node] = await db
+        .select()
+        .from(nodes)
+        .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
+    return node ?? null;
+}
+/**
+ * Resolve the node an enroll (POST /v1/nodes) targets: by node_id when
+ * supplied, by name otherwise.
+ */
+export async function resolveNodeForEnroll(db, workspaceId, data) {
+    if (data.node_id !== undefined) {
+        return getNodeById(db, workspaceId, data.node_id);
+    }
+    return getNodeByName(db, workspaceId, data.name);
+}
 export async function registerNode(db, workspaceId, authenticatedNodeId, message, provider) {
     if (message.node_id !== authenticatedNodeId) {
         throw codedError('node_id does not match the authenticated node token', 'node_id_mismatch', 403);
@@ -346,7 +381,14 @@ export async function heartbeatNode(db, workspaceId, nodeId, providerName, messa
         .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
     return updated ? publicNode(updated) : null;
 }
-export async function markNodeOffline(db, registry, workspaceId, nodeId) {
+export async function markNodeOffline(db, registry, workspaceId, nodeId, effects) {
+    // Capture the node's name + prior status BEFORE flipping it so a durable
+    // node.status.offline is emitted only on a real online -> offline transition
+    // (never on a node that was already offline).
+    const [before] = await db
+        .select({ status: nodes.status, name: nodes.name })
+        .from(nodes)
+        .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
     await db
         .update(nodes)
         .set({
@@ -369,19 +411,27 @@ export async function markNodeOffline(db, registry, workspaceId, nodeId) {
         .set({ status: 'offline', lastSeen: new Date() })
         .where(and(eq(agents.workspaceId, workspaceId), eq(agents.locationType, 'via_node'), eq(agents.locationNodeId, nodeId)));
     await rescheduleInvocationsForLostNode(db, registry, workspaceId, nodeId);
+    if (effects?.deps && before && before.status === 'online') {
+        await emitNodeStatusEffects(effects.deps, workspaceId, {
+            status: 'offline',
+            nodeId,
+            nodeName: before.name,
+            reason: effects.reason,
+        });
+    }
 }
 /**
  * A provider's control connection dropped. Its capability set persists (marked
  * offline) so the node still shows the manifest; agents it hosted go offline.
  * When it was the node's last connection the whole node goes offline.
  */
-export async function handleProviderDisconnect(db, registry, workspaceId, nodeId, providerName, hasRemainingConnections) {
+export async function handleProviderDisconnect(db, registry, workspaceId, nodeId, providerName, hasRemainingConnections, deps) {
     // Serialized with node-control operations so a teardown can't race a
     // concurrent register's provider upsert / aggregate recompute (or, on
     // better-sqlite3, deadlock its isolated transaction).
     return serializeNodeOp(workspaceId, nodeId, async () => {
         if (!hasRemainingConnections) {
-            await markNodeOffline(db, registry, workspaceId, nodeId);
+            await markNodeOffline(db, registry, workspaceId, nodeId, { deps, reason: 'disconnected' });
             return;
         }
         await markProviderOffline(db, workspaceId, nodeId, providerName);
@@ -397,7 +447,7 @@ export async function handleProviderDisconnect(db, registry, workspaceId, nodeId
  * capability set, and materialized actions. When it was the node's last
  * provider the node goes fully offline.
  */
-export async function deregisterProvider(db, registry, workspaceId, nodeId, providerName) {
+export async function deregisterProvider(db, registry, workspaceId, nodeId, providerName, deps) {
     await removeProvider(db, workspaceId, nodeId, providerName);
     registry.detachProvider(workspaceId, nodeId, providerName);
     await db
@@ -409,17 +459,39 @@ export async function deregisterProvider(db, registry, workspaceId, nodeId, prov
         .from(nodeProviders)
         .where(and(eq(nodeProviders.workspaceId, workspaceId), eq(nodeProviders.nodeId, nodeId)));
     if (!remaining || remaining.count === 0) {
-        await markNodeOffline(db, registry, workspaceId, nodeId);
+        await markNodeOffline(db, registry, workspaceId, nodeId, { deps, reason: 'deregistered' });
     }
     else {
-        // Other providers remain: recompute the node aggregate but don't reschedule
-        // node-wide — that would disturb the surviving providers' in-flight invokes.
-        // Work dispatched to the removed provider is caught by the dispatch-timeout
-        // sweep, matching the provider-disconnect path.
+        // Other provider rows remain (possibly all offline): recompute the node
+        // aggregate but don't reschedule node-wide — that would disturb the surviving
+        // providers' in-flight invokes. Work dispatched to the removed provider is
+        // caught by the dispatch-timeout sweep, matching the provider-disconnect path.
+        // Capture status across the recompute so that when the deregistered provider
+        // was the node's last *online* one, the resulting online -> offline flip still
+        // emits a durable node.status.offline — recomputeNodeAggregate flips the
+        // column but never emits.
+        const [before] = await db
+            .select({ status: nodes.status, name: nodes.name })
+            .from(nodes)
+            .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
         await recomputeNodeAggregate(db, workspaceId, nodeId);
+        if (deps && before?.status === 'online') {
+            const [after] = await db
+                .select({ status: nodes.status, name: nodes.name })
+                .from(nodes)
+                .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
+            if (after && after.status !== 'online') {
+                await emitNodeStatusEffects(deps, workspaceId, {
+                    status: 'offline',
+                    nodeId,
+                    nodeName: after.name ?? before.name,
+                    reason: 'deregistered',
+                });
+            }
+        }
     }
 }
-export async function sweepOfflineNodes(db, registry) {
+export async function sweepOfflineNodes(db, registry, deps) {
     const rows = await db.select().from(nodes).where(eq(nodes.status, 'online'));
     const stale = rows.filter((node) => !isNodeLive(node));
     let swept = 0;
@@ -433,7 +505,7 @@ export async function sweepOfflineNodes(db, registry) {
                 .where(and(eq(nodes.workspaceId, node.workspaceId), eq(nodes.id, node.id)));
             if (!current || current.status !== 'online' || isNodeLive(current))
                 return false;
-            await markNodeOffline(db, registry, node.workspaceId, node.id);
+            await markNodeOffline(db, registry, node.workspaceId, node.id, { deps, reason: 'liveness_timeout' });
             return true;
         });
         if (offlined)
@@ -874,7 +946,7 @@ export async function registerAgentViaNode(db, workspaceId, nodeId, providerName
         };
     });
 }
-export async function deregisterAgentViaNode(db, workspaceId, nodeId, message) {
+export async function deregisterAgentViaNode(db, workspaceId, nodeId, message, deps) {
     const conditions = [
         eq(agents.workspaceId, workspaceId),
         eq(agents.locationType, 'via_node'),
@@ -908,6 +980,15 @@ export async function deregisterAgentViaNode(db, workspaceId, nodeId, message) {
             .where(and(eq(agents.workspaceId, workspaceId), eq(agents.id, updated.id)));
         await markDirectNodeOfflineForAgent(db, workspaceId, updated.id);
         await releaseNodeAgentSlots(db, workspaceId, activeNodeIds.filter((activeNodeId) => activeNodeId !== nodeId));
+        if (deps) {
+            await emitAgentExitedEffects(deps, workspaceId, {
+                agentId: updated.id,
+                agentName: updated.name,
+                nodeId,
+                invocationId: fleetInvocationId(updated.metadata),
+                reason: 'deregistered',
+            });
+        }
     }
     return updated ?? null;
 }
@@ -1032,7 +1113,7 @@ export async function reconcileInventory(db, registry, workspaceId, nodeId, prov
                 invocation_id: item.invocation_id ?? null,
                 session_ref: item.session_ref ?? null,
             },
-        });
+        }, completionDeps);
         if (completed) {
             completedInvocations++;
             if (completionDeps) {
@@ -1041,15 +1122,27 @@ export async function reconcileInventory(db, registry, workspaceId, nodeId, prov
         }
     }
     const nodeAgents = await db
-        .select({ id: agents.id, name: agents.name })
+        .select({ id: agents.id, name: agents.name, metadata: agents.metadata })
         .from(agents)
         .where(and(eq(agents.workspaceId, workspaceId), eq(agents.locationType, 'via_node'), eq(agents.locationNodeId, nodeId), eq(agents.providerName, providerName), eq(agents.status, 'active')));
-    const missing = nodeAgents.filter((agent) => !names.has(agent.name)).map((agent) => agent.id);
+    const missingAgents = nodeAgents.filter((agent) => !names.has(agent.name));
+    const missing = missingAgents.map((agent) => agent.id);
     if (missing.length > 0) {
         await db
             .update(agents)
             .set({ status: 'offline', lastSeen: new Date() })
             .where(inArray(agents.id, missing));
+        if (completionDeps) {
+            for (const agent of missingAgents) {
+                await emitAgentExitedEffects(completionDeps, workspaceId, {
+                    agentId: agent.id,
+                    agentName: agent.name,
+                    nodeId,
+                    invocationId: fleetInvocationId(agent.metadata),
+                    reason: 'missing_from_inventory',
+                });
+            }
+        }
     }
     let rescheduledInvocations = 0;
     for (const invocation of openInvocations) {
@@ -1095,6 +1188,29 @@ export async function getPublicNode(db, workspaceId, name) {
     const node = await getNodeByName(db, workspaceId, name);
     return node ? publicNode(node) : null;
 }
+/** The node's persisted `status` column, or undefined when the node is gone. */
+async function readNodeStatus(db, workspaceId, nodeId) {
+    const [row] = await db
+        .select({ status: nodes.status })
+        .from(nodes)
+        .where(and(eq(nodes.workspaceId, workspaceId), eq(nodes.id, nodeId)));
+    return row?.status;
+}
+/**
+ * Emit a durable `node.status.online` only on a real offline -> online
+ * transition: the node was not `online` before the register/heartbeat and the
+ * resulting descriptor reports online. A steady heartbeat (already online) or a
+ * register that leaves the node offline (no live provider) emits nothing.
+ */
+async function emitNodeOnlineTransition(deps, workspaceId, priorStatus, node) {
+    if (!deps || !node || priorStatus === 'online' || node.status !== 'online')
+        return;
+    await emitNodeStatusEffects(deps, workspaceId, {
+        status: 'online',
+        nodeId: node.id,
+        nodeName: node.name,
+    });
+}
 function sendControl(socket, payload) {
     if (!socket)
         return false;
@@ -1155,6 +1271,7 @@ export async function handleNodeControlMessage(args) {
                             throw codedError(conflict.message, conflict.code, 409);
                         }
                     }
+                    const priorStatus = await readNodeStatus(args.db, args.workspaceId, args.nodeId);
                     const registered = await registerNode(args.db, args.workspaceId, args.nodeId, message, provider);
                     const readinessSupported = supportsProviderDeliveryReadiness(args.registry);
                     const acceptance = registered.acceptance.map((capability) => (capability.name === FLEET_DELIVERY_CURSOR_CAPABILITY && !readinessSupported
@@ -1176,6 +1293,11 @@ export async function handleNodeControlMessage(args) {
                             accepted_capabilities: acceptance,
                         },
                     });
+                    // The node row is already persisted online, so emit the durable
+                    // transition before draining: a drainNode rejection must not skip the
+                    // node.status.online event. Isolated so its own failure can't either.
+                    await emitNodeOnlineTransition(args.completionDeps, args.workspaceId, priorStatus, registered.node)
+                        .catch((err) => console.error('[node.status] online event emission failed', err));
                     // Node is now marked online: flush any queued action.invoke frames so
                     // spawns queued while it was offline can reserve capacity and dispatch.
                     await args.registry.drainNode(args.workspaceId, args.nodeId);
@@ -1191,14 +1313,21 @@ export async function handleNodeControlMessage(args) {
                     }
                     return;
                 }
-                case 'node.heartbeat':
-                    await heartbeatNode(args.db, args.workspaceId, args.nodeId, frameProviderName, message);
+                case 'node.heartbeat': {
+                    const priorStatus = await readNodeStatus(args.db, args.workspaceId, args.nodeId);
+                    const beat = await heartbeatNode(args.db, args.workspaceId, args.nodeId, frameProviderName, message);
+                    // The node row is already persisted, so emit the durable online
+                    // transition before draining: a drainNode rejection must not skip the
+                    // node.status.online event. Isolated so its own failure can't either.
+                    await emitNodeOnlineTransition(args.completionDeps, args.workspaceId, priorStatus, beat)
+                        .catch((err) => console.error('[node.status] online event emission failed', err));
                     // Heartbeat refreshes online/capacity state; re-drain as a backstop in
                     // case a queued spawn could not reserve capacity at register time.
                     await args.registry.drainNode(args.workspaceId, args.nodeId);
                     return;
+                }
                 case 'node.deregister':
-                    await deregisterProvider(args.db, args.registry, args.workspaceId, args.nodeId, frameProviderName);
+                    await deregisterProvider(args.db, args.registry, args.workspaceId, args.nodeId, frameProviderName, args.completionDeps);
                     return;
                 case 'node.spawn': {
                     // Handler-context `ctx.spawnAgent`: capacity-direct delegation to this
@@ -1246,7 +1375,7 @@ export async function handleNodeControlMessage(args) {
                     return;
                 }
                 case 'agent.deregister':
-                    await deregisterAgentViaNode(args.db, args.workspaceId, args.nodeId, message);
+                    await deregisterAgentViaNode(args.db, args.workspaceId, args.nodeId, message, args.completionDeps);
                     return;
                 case 'inventory.sync': {
                     const result = await reconcileInventory(args.db, args.registry, args.workspaceId, args.nodeId, frameProviderName, message.agents, args.completionDeps);
@@ -1273,7 +1402,7 @@ export async function handleNodeControlMessage(args) {
                     const completed = await completeNodeInvocation(args.db, args.registry, args.workspaceId, args.nodeId, frameProviderName, message.invocation_id, {
                         ...(Object.prototype.hasOwnProperty.call(message, 'output') ? { output: message.output } : {}),
                         ...(message.error ? { error: message.error } : {}),
-                    });
+                    }, args.completionDeps);
                     if (completed && args.completionDeps) {
                         await emitInvocationCompletionEffects(args.completionDeps, args.workspaceId, completed);
                     }