Fleet node structured logging: capabilities registered and actions invoked

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `agent-relay node up|down|status|metrics|tail`, `node agent …`, and `node workflow run|logs|sync` unify `local up` and `fleet serve` under one command group. `node up [--config <file>]` brings the current context's node online: the broker runs agents, and a project `agent-relay.{ts,…}` or `agent-relay.py` is served as a capability provider. A plain agent host needs no definition file.
 - **Node providers** — a node's actions are hosted by providers that connect directly to the engine and are invoked node-addressed (`POST /v1/nodes/:node/actions/:name/invoke`). Author TypeScript actions with `@agent-relay/fleet` (`defineNode`/`serveNode`); an action named `spawn:<harness>` wraps the broker's spawn so any language can adjust the command, env, or cwd before it runs.
 - Python `agent_relay.node.NodeProvider.from_enrollment()` serves node actions from Python, reading the node credentials from the enrollment. Install with the `node` extra.
+- `agent-relay node up` gains `--log-file <path>`, `--log-level <debug|info|warn|error>`, and `--log-json`: a served node logs each capability it registers (`debug`) and every action that hits it (`info`, with a duration and `node`/`kind`/`invocationId` fields; failures at `warn`). Without a flag the node stays quiet apart from warnings; `--verbose` raises the level to `debug`. An invalid `--log-level` is now rejected instead of silently disabling logs. Serving programmatically, inject any sink via `serveNode({ logger })`.
 - Swift SDK (`AgentRelaySDK`, `packages/sdk-swift`): `AgentClient` gains `invokeAction(_:input:timeout:pollInterval:)` — invoke a relay action and await its output — plus `channelHistory(_:limit:before:)` and `dmHistory(with:limit:before:)` for reading channel and 1:1 DM message history as oldest-first `RelayChannelEvent`s.
 
 ### Changed

packages/cli/src/cli/commands/core.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { exec, spawn as spawnProcess } from 'node:child_process';
 import { promisify } from 'node:util';
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 
 import { getProjectPaths, loadTeamsConfig } from '@agent-relay/config';
 import { HarnessDriverClient, type BrokerInitArgs } from '@agent-relay/harness-driver';
@@ -270,6 +270,9 @@ export interface UpCommandOptions {
   stateDir?: string;
   brokerName?: string;
   config?: string;
+  logFile?: string;
+  logLevel?: string;
+  logJson?: boolean;
 }
 
 /**
@@ -287,7 +290,32 @@ export function addUpCommandOptions(command: Command): Command {
       '--state-dir <path>',
       'Directory for broker state and connection files (default: .agentworkforce/relay/)'
     )
-    .option('--broker-name <name>', 'Override the broker name (defaults to project directory basename)');
+    .option('--broker-name <name>', 'Override the broker name (defaults to project directory basename)')
+    .option(
+      '--log-file <path>',
+      'Write structured node logs (capabilities registered, actions invoked/completed) to a file'
+    )
+    .option(
+      '--log-level <level>',
+      'Node log verbosity: debug | info | warn | error (default: info)',
+      parseLogLevel
+    )
+    .option('--log-json', 'Emit node logs as JSON lines instead of text');
+}
+
+const LOG_LEVELS = ['debug', 'info', 'warn', 'error'] as const;
+
+/**
+ * Validate `--log-level` at parse time (case-insensitive). Rejecting a typo here
+ * — rather than passing it through — avoids the silent failure where an
+ * unrecognized `AGENT_RELAY_LOG_LEVEL` drops every log line.
+ */
+function parseLogLevel(value: string): string {
+  const normalized = value.toLowerCase();
+  if (!(LOG_LEVELS as readonly string[]).includes(normalized)) {
+    throw new InvalidArgumentError(`Expected one of: ${LOG_LEVELS.join(', ')}.`);
+  }
+  return normalized;
 }
 
 export function registerCoreCommands(

packages/cli/src/cli/lib/broker-lifecycle.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { HarnessDriverClient } from '@agent-relay/harness-driver';
 import { startServeNode, type FleetNodeDefinition, type RunningNode } from '@agent-relay/fleet';
+import { createLogger } from '@agent-relay/utils';
 
 import type { CoreDependencies, CoreProjectPaths, CoreRelay, SpawnedProcess } from '../commands/core.js';
 import { track } from '../telemetry/index.js';
@@ -32,6 +33,12 @@ type UpOptions = {
   discoverConfig?: boolean;
   /** Registered node name override (e.g. from a persisted Cloud enrollment). */
   nodeName?: string;
+  /** Write structured node logs (capabilities, action invocations) to this file. */
+  logFile?: string;
+  /** Log verbosity floor: debug | info | warn | error. Defaults to info. */
+  logLevel?: string;
+  /** Emit logs as JSON lines instead of human-readable text. */
+  logJson?: boolean;
 };
 
 type DownOptions = {
@@ -136,6 +143,30 @@ function vlog(deps: CoreDependencies, verbose: boolean | undefined, message: str
   }
 }
 
+/** True when any log flag (or `--verbose`) opts the node into structured logging. */
+function nodeLoggingEnabled(options: UpOptions): boolean {
+  return Boolean(options.logFile || options.logLevel || options.logJson || options.verbose);
+}
+
+/**
+ * Translate the `--log-*` (and `--verbose`) flags into the `AGENT_RELAY_LOG_*`
+ * environment the shared `createLogger` reads. `--verbose` alone raises the
+ * floor to DEBUG so per-capability registration lines surface; an explicit
+ * `--log-level` always wins. Called before the fleet sidecar starts.
+ */
+function applyNodeLogEnv(options: UpOptions, deps: CoreDependencies): void {
+  if (options.logFile) {
+    deps.env.AGENT_RELAY_LOG_FILE = options.logFile;
+  }
+  const level = options.logLevel ?? (options.verbose ? 'debug' : undefined);
+  if (level) {
+    deps.env.AGENT_RELAY_LOG_LEVEL = level.toUpperCase();
+  }
+  if (options.logJson) {
+    deps.env.AGENT_RELAY_LOG_JSON = '1';
+  }
+}
+
 type ErrorWithCode = { code?: unknown };
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -390,8 +421,14 @@ async function startNodeCapabilityProviders(
           providerName: nodeDefinition.name,
           ...(workspaceKey ? { triggers: createTriggerSyncClient({ workspaceKey, baseUrl }) } : {}),
           reconnect: true,
-          warn: (message) => deps.warn(message),
-          log: (message) => deps.log(message),
+          // With any --log-* flag (or --verbose), surface the node's full lifecycle
+          // — capabilities registered, every action invoked/completed — through the
+          // shared logger, which honors AGENT_RELAY_LOG_FILE/_LEVEL/_JSON. Without a
+          // flag, keep the prior behavior: the registration summary via log, warnings
+          // via warn.
+          ...(nodeLoggingEnabled(options)
+            ? { logger: createLogger('fleet') }
+            : { warn: (message) => deps.warn(message), log: (message) => deps.log(message) }),
         })
       );
     } catch (err) {
@@ -1099,6 +1136,10 @@ export async function runUpCommand(options: UpOptions, deps: CoreDependencies):
       deps.env.RELAY_API_KEY = options.workspaceKey;
     }
 
+    // Point the shared logger at a file / level / format before the fleet
+    // sidecar (which reads this env when it builds its logger) starts.
+    applyNodeLogEnv(options, deps);
+
     // Resolved BEFORE the broker starts so an explicit bad --config fails
     // fast instead of tearing down a broker that just came up.
     const nodeDefinition = await resolveNodeDefinitionForUp(paths, options, deps);

packages/fleet/README.md

@@ -73,6 +73,33 @@ await running.stop();
 await serveNode({ definition, connection });
 ```
 
+### Logging
+
+The node runtime emits structured events — each capability it registers and every
+action that hits it (invoked / completed / failed, with a duration) — through a
+`logger` you inject. The shape matches `@agent-relay/utils`' `createLogger`, and
+every event carries a structured `extra` bag (`{ capability, action, invocationId,
+ms, … }`) so file and JSON sinks can key on the fields:
+
+```ts
+import { createLogger } from '@agent-relay/utils';
+
+await serveNode({ definition, connection, logger: createLogger('fleet') });
+```
+
+Via the CLI, `agent-relay node up` surfaces this without code:
+
+```bash
+agent-relay node up --config ./builder.node.ts --log-file ./node.log
+agent-relay node up --config ./builder.node.ts --log-level debug   # include per-capability lines
+agent-relay node up --config ./builder.node.ts --log-json          # one JSON object per line
+```
+
+Capability registration logs at `debug`; action invocations at `info`; failures at
+`warn`. With no `logger` the node is silent — pass a `logger` (or the older `log`/`warn`
+callbacks) to receive events. The CLI wires a `warn`-only sink when no `--log-*` flag is
+given, so `agent-relay node up` stays quiet apart from warnings until you opt in.
+
 ## Concepts
 
 - **Node** — a named host registered with the workspace. `defineNode` validates the manifest

packages/fleet/src/serve-node.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { z } from 'zod';
 
 import { action, defineNode, spawn } from './index.js';
-import { startServeNode, type FleetTriggerSyncClient } from './serve-node.js';
+import { startServeNode, type FleetLogger, type FleetTriggerSyncClient } from './serve-node.js';
 
 /**
  * A fake node-ws server: captures frames the client sends and lets the test
@@ -307,4 +307,104 @@ describe('serveNode', () => {
     ]);
     await running.stop();
   });
+
+  describe('structured logging', () => {
+    function recordingLogger() {
+      const entries: Array<{ level: string; message: string; extra?: Record<string, unknown> }> = [];
+      const record = (level: string) => (message: string, extra?: Record<string, unknown>) => {
+        entries.push({ level, message, ...(extra ? { extra } : {}) });
+      };
+      const logger: FleetLogger = {
+        debug: record('debug'),
+        info: record('info'),
+        warn: record('warn'),
+        error: record('error'),
+      };
+      return { logger, entries };
+    }
+
+    function loggingNode() {
+      return defineNode({
+        name: 'test-node',
+        capabilities: {
+          echo: action({ input: z.object({ value: z.string() }) }, async (input) => input),
+          explode: action({}, async () => {
+            throw new Error('boom');
+          }),
+        },
+      });
+    }
+
+    it('logs each registered capability at debug and a registration summary at info', async () => {
+      const { logger, entries } = recordingLogger();
+      const running = startServeNode({ definition: loggingNode(), connection, reconnect: false, logger });
+      const sock = socket();
+      sock.open();
+      sock.emit(acceptAll(sock.lastRegister()));
+      await flush();
+
+      const capabilities = entries.filter((entry) => entry.message.startsWith('Capability'));
+      expect(capabilities.map((entry) => entry.extra?.capability)).toEqual(['echo', 'explode']);
+      expect(capabilities.every((entry) => entry.level === 'debug')).toBe(true);
+      expect(capabilities[0]?.extra).toMatchObject({ node: 'test-node', capability: 'echo', kind: 'action' });
+
+      const summary = entries.find((entry) => entry.message.includes('with 2 capabilities'));
+      expect(summary?.level).toBe('info');
+      expect(summary?.extra).toMatchObject({ node: 'test-node', capabilities: 2 });
+
+      await running.stop();
+    });
+
+    it('logs an action invocation and its completion with a duration', async () => {
+      const { logger, entries } = recordingLogger();
+      const running = startServeNode({ definition: loggingNode(), connection, reconnect: false, logger });
+      const sock = socket();
+      sock.open();
+      sock.emit(acceptAll(sock.lastRegister()));
+      await flush();
+
+      sock.emit({
+        v: 1,
+        type: 'action.invoke',
+        invocation_id: 'inv-1',
+        action: 'echo',
+        input: { value: 'hi' },
+      });
+      await flush();
+
+      const invoked = entries.find((entry) => entry.message === 'Action "echo" invoked');
+      expect(invoked?.level).toBe('info');
+      expect(invoked?.extra).toMatchObject({
+        node: 'test-node',
+        action: 'echo',
+        kind: 'action',
+        invocationId: 'inv-1',
+      });
+
+      const completed = entries.find((entry) => entry.message === 'Action "echo" completed');
+      expect(completed?.level).toBe('info');
+      expect(completed?.extra).toMatchObject({ node: 'test-node', action: 'echo', invocationId: 'inv-1' });
+      expect(typeof completed?.extra?.ms).toBe('number');
+
+      await running.stop();
+    });
+
+    it('logs a failed action as a warning carrying the error', async () => {
+      const { logger, entries } = recordingLogger();
+      const running = startServeNode({ definition: loggingNode(), connection, reconnect: false, logger });
+      const sock = socket();
+      sock.open();
+      sock.emit(acceptAll(sock.lastRegister()));
+      await flush();
+
+      sock.emit({ v: 1, type: 'action.invoke', invocation_id: 'inv-2', action: 'explode', input: {} });
+      await flush();
+
+      const failed = entries.find((entry) => entry.message === 'Action "explode" failed');
+      expect(failed?.level).toBe('warn');
+      expect(failed?.extra).toMatchObject({ action: 'explode', invocationId: 'inv-2', error: 'boom' });
+
+      await running.stop();
+    });
+  });
 });