@herdctl/core 5.10.1 → 5.12.0

package/dist/fleet-manager/fleet-manager.d.ts

@@ -11,9 +11,10 @@
  * @module fleet-manager
  */
 import { EventEmitter } from "node:events";
-import { type ResolvedAgent, type ResolvedConfig } from "../config/index.js";
+import { type AgentConfig, type ResolvedAgent, type ResolvedConfig } from "../config/index.js";
 import { Scheduler } from "../scheduler/index.js";
-import { type StateDirectory } from "../state/index.js";
+import { type ChatMessage, type DiscoveredSession, type StateDirectory } from "../state/index.js";
+import { type AddAgentOptions } from "./agent-management.js";
 import type { IChatManager } from "./chat-manager-interface.js";
 import type { FleetManagerContext } from "./context.js";
 import type { AgentInfo, CancelJobResult, ConfigChange, ConfigReloadedPayload, FleetManagerLogger, FleetManagerOptions, FleetManagerState, FleetManagerStatus, FleetManagerStopOptions, FleetStatus, ForkJobResult, JobModifications, LogEntry, LogStreamOptions, ScheduleInfo, TriggerOptions, TriggerResult } from "./types.js";
@@ -40,9 +41,12 @@ export declare class FleetManager extends EventEmitter implements FleetManagerCo
     private statusQueries;
     private scheduleManagement;
     private configReloadModule;
+    private agentManagement;
     private jobControl;
     private logStreaming;
     private scheduleExecutor;
+    private sessionDiscovery;
+    private sessionMetadataStore;
     private chatManagers;
     constructor(options: FleetManagerOptions);
     getConfig(): ResolvedConfig | null;
@@ -92,6 +96,142 @@ export declare class FleetManager extends EventEmitter implements FleetManagerCo
     disableSchedule(agentName: string, scheduleName: string): Promise<ScheduleInfo>;
     reload(): Promise<ConfigReloadedPayload>;
     computeConfigChanges(oldConfig: ResolvedConfig | null, newConfig: ResolvedConfig): ConfigChange[];
+    /**
+     * Register an agent at runtime without writing YAML or calling `reload()`.
+     *
+     * The config is validated, merged with fleet defaults, normalized (working
+     * directory resolved to an absolute path), and wired into the running fleet
+     * so it is immediately triggerable and appears in fleet status. A
+     * `config:reloaded` event is emitted describing the change.
+     *
+     * This is the programmatic counterpart to editing `herdctl.yaml` and calling
+     * `reload()` — useful for apps that manage agents in memory rather than on
+     * disk.
+     *
+     * @param agent - The agent configuration to register (must include `name`)
+     * @param options - Resolution options (base dir, defaults merge, replace)
+     * @returns Info for the newly registered agent
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {ConfigurationError} If validation fails or the name collides
+     *
+     * @example
+     * ```typescript
+     * await fleet.addAgent({
+     *   name: "keeper-myproject",
+     *   working_directory: "/abs/projects/myproject",
+     *   runtime: "cli",
+     *   permission_mode: "acceptEdits",
+     * });
+     * await fleet.trigger("keeper-myproject", undefined, { prompt: "Hello" });
+     * ```
+     */
+    addAgent(agent: AgentConfig | (Record<string, unknown> & {
+        name: string;
+    }), options?: AddAgentOptions): Promise<AgentInfo>;
+    /**
+     * Unregister an agent at runtime.
+     *
+     * Removes the agent from the in-memory config and the scheduler. Accepts a
+     * qualified name or a local name. Running jobs are unaffected.
+     *
+     * @param name - The agent qualified name or local name to remove
+     * @returns `true` if an agent was removed, `false` if no match was found
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     */
+    removeAgent(name: string): Promise<boolean>;
+    /**
+     * List discovered Claude Code sessions for an agent.
+     *
+     * Derives the agent's working directory and Docker mode from the loaded
+     * config, so consumers don't have to map agent → working directory by hand.
+     * Sessions are returned sorted by modification time (newest first).
+     *
+     * Note: sessions are keyed by working directory. This method uses the agent's
+     * *configured* `working_directory`. If you triggered the agent with a
+     * per-trigger `workingDirectory` override (see {@link TriggerOptions}), the
+     * resulting sessions live under that override directory and will NOT appear
+     * here — list them by scanning that directory instead (e.g. the directory
+     * grouped `getAllSessions` view on the underlying `SessionDiscoveryService`).
+     *
+     * @param name - The agent qualified name or local name
+     * @param options - Optional `limit` for top-N enrichment
+     * @returns Array of discovered sessions (empty if the agent has no working
+     *   directory or no sessions yet)
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    getAgentSessions(name: string, options?: {
+        limit?: number;
+    }): Promise<DiscoveredSession[]>;
+    /**
+     * Get the parsed chat messages for one of an agent's sessions.
+     *
+     * Derives the working directory and Docker mode from the loaded config.
+     *
+     * @param name - The agent qualified name or local name
+     * @param sessionId - The session ID to read
+     * @returns Array of chat messages (empty if the agent has no working directory)
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    getAgentSessionMessages(name: string, sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Delete one of an agent's Claude Code session transcripts from disk.
+     *
+     * Resolves the agent's working directory and Docker mode from the loaded
+     * config, computes the CLI (or Docker) transcript file path with the same
+     * encoder Claude Code uses, deletes it, and invalidates the session-discovery
+     * cache so a subsequent {@link getAgentSessions} no longer lists it.
+     *
+     * The `sessionId` is validated (only `[A-Za-z0-9-]` is allowed) to prevent
+     * path traversal before any filesystem access.
+     *
+     * @param name - The agent qualified name or local name
+     * @param sessionId - The session ID whose transcript should be removed
+     * @returns `true` if a file was removed, `false` if no transcript existed (or
+     *   the agent has no working directory)
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     * @throws {Error} If `sessionId` contains invalid characters
+     */
+    deleteSession(name: string, sessionId: string): Promise<boolean>;
+    /**
+     * Set (or clear) the custom display name for one of an agent's sessions.
+     *
+     * Writes through this fleet's shared {@link SessionMetadataStore} — the same
+     * store the session-discovery service reads — so a subsequent
+     * {@link getAgentSessions} reflects the new `customName` immediately. Passing
+     * `null` or an empty/whitespace string clears any existing custom name.
+     *
+     * @param name - The agent qualified name or local name
+     * @param sessionId - The session ID to (re)name
+     * @param customName - The custom name to set, or `null`/empty to clear it
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    setSessionName(name: string, sessionId: string, customName: string | null): Promise<void>;
+    /**
+     * Drop the cached session listing for an agent so the next
+     * {@link getAgentSessions} call rebuilds it from disk.
+     *
+     * The underlying {@link SessionDiscoveryService} caches each working
+     * directory's listing for up to its TTL (default 30s). That cache is now
+     * mtime-aware, so a *newly created* transcript file is normally picked up
+     * immediately. Call this when you want to force a fresh listing regardless —
+     * e.g. after each chat turn, or on filesystems whose directory mtime has
+     * coarse (1-second) granularity where a same-second create might otherwise be
+     * masked until the TTL expires. It also drops the attribution index so a
+     * session created this turn (whose job record was just written) is attributed.
+     *
+     * Resolves the agent's working directory and Docker mode from the loaded
+     * config (no override directories — see {@link getAgentSessions}). A no-op
+     * when the agent has no working directory.
+     *
+     * @param name - The agent qualified name or local name
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    invalidateSessions(name: string): void;
     trigger(agentName: string, scheduleName?: string, options?: TriggerOptions): Promise<TriggerResult>;
     cancelJob(jobId: string, options?: {
         timeout?: number;
@@ -133,6 +273,30 @@ export declare class FleetManager extends EventEmitter implements FleetManagerCo
      * @throws ConfigurationError if duplicate qualified names are found
      */
     private validateUniqueAgentNames;
+    /**
+     * Get (lazily creating) the shared SessionMetadataStore bound to this fleet's
+     * state directory. Shared with the SessionDiscoveryService so metadata writes
+     * (e.g. {@link setSessionName}) and reads (during discovery) use one cache.
+     */
+    private getSessionMetadataStore;
+    /**
+     * Get (lazily creating) the SessionDiscoveryService bound to this fleet's
+     * state directory. Reused across calls so its caches are shared. The
+     * service shares this fleet's {@link SessionMetadataStore} so custom-name
+     * writes are immediately visible to discovery.
+     */
+    private getSessionDiscovery;
+    /**
+     * Look up an agent by qualified or local name and derive the inputs the
+     * SessionDiscoveryService needs (working directory + Docker mode).
+     *
+     * @param name - The agent qualified name or local name
+     * @param operation - The public operation name, used for the
+     *   {@link InvalidStateError} message when the fleet is uninitialized
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    private resolveAgentForSessions;
     private initializeStateDir;
     private startSchedulerAsync;
     private handleScheduleTrigger;

package/dist/fleet-manager/fleet-manager.d.ts.map

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

package/dist/fleet-manager/fleet-manager.js

@@ -11,19 +11,23 @@
  * @module fleet-manager
  */
 import { EventEmitter } from "node:events";
+import { rm } from "node:fs/promises";
 import { resolve } from "node:path";
 import { ConfigError, ConfigNotFoundError, loadConfig, } from "../config/index.js";
+import { getCliSessionFile, getDockerSessionFile } from "../runner/runtime/cli-session-path.js";
 import { Scheduler } from "../scheduler/index.js";
-import { initStateDirectory } from "../state/index.js";
+import { initStateDirectory, SessionDiscoveryService, SessionMetadataStore, } from "../state/index.js";
 import { createLogger } from "../utils/logger.js";
+import { AgentManagement } from "./agent-management.js";
 import { ConfigReload, computeConfigChanges } from "./config-reload.js";
-import { ConfigurationError, FleetManagerShutdownError, FleetManagerStateDirError, InvalidStateError, } from "./errors.js";
+import { AgentNotFoundError, ConfigurationError, FleetManagerShutdownError, FleetManagerStateDirError, InvalidStateError, } from "./errors.js";
 import { JobControl } from "./job-control.js";
 import { LogStreaming } from "./log-streaming.js";
 import { ScheduleExecutor } from "./schedule-executor.js";
 import { ScheduleManagement } from "./schedule-management.js";
 // Module classes
 import { StatusQueries } from "./status-queries.js";
+import { resolveWorkingDirectory } from "./working-directory-helper.js";
 const DEFAULT_CHECK_INTERVAL = 1000;
 function createDefaultLogger() {
     return createLogger("fleet-manager");
@@ -55,9 +59,16 @@ export class FleetManager extends EventEmitter {
     statusQueries;
     scheduleManagement;
     configReloadModule;
+    agentManagement;
     jobControl;
     logStreaming;
     scheduleExecutor;
+    // Lazily-created session discovery service (for getAgentSessions/* helpers)
+    sessionDiscovery = null;
+    // Lazily-created session metadata store, shared with sessionDiscovery so a
+    // setSessionName() write is reflected by a subsequent getAgentSessions()
+    // without a stale in-memory cache.
+    sessionMetadataStore = null;
     // Chat managers (Discord, Slack, etc.)
     // Key is platform name (e.g., "discord", "slack")
     chatManagers = new Map();
@@ -385,6 +396,218 @@ export class FleetManager extends EventEmitter {
     computeConfigChanges(oldConfig, newConfig) {
         return computeConfigChanges(oldConfig, newConfig);
     }
+    // Programmatic Agent Management
+    /**
+     * Register an agent at runtime without writing YAML or calling `reload()`.
+     *
+     * The config is validated, merged with fleet defaults, normalized (working
+     * directory resolved to an absolute path), and wired into the running fleet
+     * so it is immediately triggerable and appears in fleet status. A
+     * `config:reloaded` event is emitted describing the change.
+     *
+     * This is the programmatic counterpart to editing `herdctl.yaml` and calling
+     * `reload()` — useful for apps that manage agents in memory rather than on
+     * disk.
+     *
+     * @param agent - The agent configuration to register (must include `name`)
+     * @param options - Resolution options (base dir, defaults merge, replace)
+     * @returns Info for the newly registered agent
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {ConfigurationError} If validation fails or the name collides
+     *
+     * @example
+     * ```typescript
+     * await fleet.addAgent({
+     *   name: "keeper-myproject",
+     *   working_directory: "/abs/projects/myproject",
+     *   runtime: "cli",
+     *   permission_mode: "acceptEdits",
+     * });
+     * await fleet.trigger("keeper-myproject", undefined, { prompt: "Hello" });
+     * ```
+     */
+    async addAgent(agent, options) {
+        return this.agentManagement.addAgent(agent, options);
+    }
+    /**
+     * Unregister an agent at runtime.
+     *
+     * Removes the agent from the in-memory config and the scheduler. Accepts a
+     * qualified name or a local name. Running jobs are unaffected.
+     *
+     * @param name - The agent qualified name or local name to remove
+     * @returns `true` if an agent was removed, `false` if no match was found
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     */
+    async removeAgent(name) {
+        return this.agentManagement.removeAgent(name);
+    }
+    // Session Access (convenience wrappers over SessionDiscoveryService)
+    /**
+     * List discovered Claude Code sessions for an agent.
+     *
+     * Derives the agent's working directory and Docker mode from the loaded
+     * config, so consumers don't have to map agent → working directory by hand.
+     * Sessions are returned sorted by modification time (newest first).
+     *
+     * Note: sessions are keyed by working directory. This method uses the agent's
+     * *configured* `working_directory`. If you triggered the agent with a
+     * per-trigger `workingDirectory` override (see {@link TriggerOptions}), the
+     * resulting sessions live under that override directory and will NOT appear
+     * here — list them by scanning that directory instead (e.g. the directory
+     * grouped `getAllSessions` view on the underlying `SessionDiscoveryService`).
+     *
+     * @param name - The agent qualified name or local name
+     * @param options - Optional `limit` for top-N enrichment
+     * @returns Array of discovered sessions (empty if the agent has no working
+     *   directory or no sessions yet)
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    async getAgentSessions(name, options) {
+        const { agent, workingDirectory, dockerEnabled } = this.resolveAgentForSessions(name, "getAgentSessions");
+        if (!workingDirectory) {
+            return [];
+        }
+        return this.getSessionDiscovery().getAgentSessions(agent.qualifiedName, workingDirectory, dockerEnabled, options);
+    }
+    /**
+     * Get the parsed chat messages for one of an agent's sessions.
+     *
+     * Derives the working directory and Docker mode from the loaded config.
+     *
+     * @param name - The agent qualified name or local name
+     * @param sessionId - The session ID to read
+     * @returns Array of chat messages (empty if the agent has no working directory)
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    async getAgentSessionMessages(name, sessionId) {
+        const { workingDirectory, dockerEnabled } = this.resolveAgentForSessions(name, "getAgentSessionMessages");
+        if (!workingDirectory) {
+            return [];
+        }
+        return this.getSessionDiscovery().getSessionMessages(workingDirectory, sessionId, {
+            dockerEnabled,
+        });
+    }
+    /**
+     * Delete one of an agent's Claude Code session transcripts from disk.
+     *
+     * Resolves the agent's working directory and Docker mode from the loaded
+     * config, computes the CLI (or Docker) transcript file path with the same
+     * encoder Claude Code uses, deletes it, and invalidates the session-discovery
+     * cache so a subsequent {@link getAgentSessions} no longer lists it.
+     *
+     * The `sessionId` is validated (only `[A-Za-z0-9-]` is allowed) to prevent
+     * path traversal before any filesystem access.
+     *
+     * @param name - The agent qualified name or local name
+     * @param sessionId - The session ID whose transcript should be removed
+     * @returns `true` if a file was removed, `false` if no transcript existed (or
+     *   the agent has no working directory)
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     * @throws {Error} If `sessionId` contains invalid characters
+     */
+    async deleteSession(name, sessionId) {
+        const { workingDirectory, dockerEnabled } = this.resolveAgentForSessions(name, "deleteSession");
+        if (!workingDirectory) {
+            return false;
+        }
+        // Compute the transcript path. getCliSessionFile/getDockerSessionFile both
+        // reject a sessionId containing anything other than [A-Za-z0-9-], so this
+        // throws before touching the filesystem when traversal is attempted.
+        const sessionFile = dockerEnabled
+            ? getDockerSessionFile(this.stateDir, sessionId)
+            : getCliSessionFile(workingDirectory, sessionId);
+        let removed;
+        try {
+            await rm(sessionFile);
+            removed = true;
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                // No transcript on disk — nothing to remove.
+                removed = false;
+            }
+            else {
+                throw error;
+            }
+        }
+        // Invalidate the discovery cache so the deleted session disappears from
+        // subsequent listings even within the cache TTL window.
+        this.getSessionDiscovery().invalidateCache(workingDirectory, { dockerEnabled });
+        this.logger.debug(`deleteSession: ${removed ? "removed" : "no file for"} session "${sessionId}" of agent "${name}"`);
+        return removed;
+    }
+    /**
+     * Set (or clear) the custom display name for one of an agent's sessions.
+     *
+     * Writes through this fleet's shared {@link SessionMetadataStore} — the same
+     * store the session-discovery service reads — so a subsequent
+     * {@link getAgentSessions} reflects the new `customName` immediately. Passing
+     * `null` or an empty/whitespace string clears any existing custom name.
+     *
+     * @param name - The agent qualified name or local name
+     * @param sessionId - The session ID to (re)name
+     * @param customName - The custom name to set, or `null`/empty to clear it
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    async setSessionName(name, sessionId, customName) {
+        // Resolve to validate state + agent existence and to key metadata by the
+        // agent's qualified name (consistent with how discovery stores custom names).
+        const { agent } = this.resolveAgentForSessions(name, "setSessionName");
+        const store = this.getSessionMetadataStore();
+        const trimmed = customName?.trim();
+        if (trimmed) {
+            await store.setCustomName(agent.qualifiedName, sessionId, trimmed);
+            this.logger.debug(`setSessionName: set custom name for session "${sessionId}" of agent "${agent.qualifiedName}"`);
+        }
+        else {
+            await store.removeCustomName(agent.qualifiedName, sessionId);
+            this.logger.debug(`setSessionName: cleared custom name for session "${sessionId}" of agent "${agent.qualifiedName}"`);
+        }
+        // Custom names are read live (not part of the directory listing cache), and
+        // the metadata store is shared with discovery, so the change is already
+        // visible. Invalidate the directory listing too for safety/consistency.
+        const workingDirectory = resolveWorkingDirectory(agent);
+        if (workingDirectory) {
+            this.getSessionDiscovery().invalidateCache(workingDirectory, {
+                dockerEnabled: agent.docker?.enabled === true,
+            });
+        }
+    }
+    /**
+     * Drop the cached session listing for an agent so the next
+     * {@link getAgentSessions} call rebuilds it from disk.
+     *
+     * The underlying {@link SessionDiscoveryService} caches each working
+     * directory's listing for up to its TTL (default 30s). That cache is now
+     * mtime-aware, so a *newly created* transcript file is normally picked up
+     * immediately. Call this when you want to force a fresh listing regardless —
+     * e.g. after each chat turn, or on filesystems whose directory mtime has
+     * coarse (1-second) granularity where a same-second create might otherwise be
+     * masked until the TTL expires. It also drops the attribution index so a
+     * session created this turn (whose job record was just written) is attributed.
+     *
+     * Resolves the agent's working directory and Docker mode from the loaded
+     * config (no override directories — see {@link getAgentSessions}). A no-op
+     * when the agent has no working directory.
+     *
+     * @param name - The agent qualified name or local name
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    invalidateSessions(name) {
+        const { workingDirectory, dockerEnabled } = this.resolveAgentForSessions(name, "invalidateSessions");
+        if (!workingDirectory) {
+            return;
+        }
+        this.getSessionDiscovery().invalidateWorkingDirectory(workingDirectory, { dockerEnabled });
+        this.logger.debug(`invalidateSessions: cleared session cache for agent "${name}"`);
+    }
     // Job Control
     async trigger(agentName, scheduleName, options) {
         return this.jobControl.trigger(agentName, scheduleName, options);
@@ -417,6 +640,9 @@ export class FleetManager extends EventEmitter {
         this.configReloadModule = new ConfigReload(this, () => this.loadConfiguration(), (config) => {
             this.config = config;
         });
+        this.agentManagement = new AgentManagement(this, (config) => {
+            this.config = config;
+        }, (name) => this.statusQueries.getAgentInfoByName(name));
         this.jobControl = new JobControl(this, () => this.statusQueries.getAgentInfo());
         this.logStreaming = new LogStreaming(this);
         this.scheduleExecutor = new ScheduleExecutor(this);
@@ -576,6 +802,67 @@ export class FleetManager extends EventEmitter {
             throw new ConfigurationError(`Duplicate agent qualified names found: ${duplicateList}. Agent names must be unique within a fleet.`);
         }
     }
+    /**
+     * Get (lazily creating) the shared SessionMetadataStore bound to this fleet's
+     * state directory. Shared with the SessionDiscoveryService so metadata writes
+     * (e.g. {@link setSessionName}) and reads (during discovery) use one cache.
+     */
+    getSessionMetadataStore() {
+        if (!this.sessionMetadataStore) {
+            this.sessionMetadataStore = new SessionMetadataStore(this.stateDir);
+        }
+        return this.sessionMetadataStore;
+    }
+    /**
+     * Get (lazily creating) the SessionDiscoveryService bound to this fleet's
+     * state directory. Reused across calls so its caches are shared. The
+     * service shares this fleet's {@link SessionMetadataStore} so custom-name
+     * writes are immediately visible to discovery.
+     */
+    getSessionDiscovery() {
+        if (!this.sessionDiscovery) {
+            this.sessionDiscovery = new SessionDiscoveryService({
+                stateDir: this.stateDir,
+                sessionMetadataStore: this.getSessionMetadataStore(),
+            });
+        }
+        return this.sessionDiscovery;
+    }
+    /**
+     * Look up an agent by qualified or local name and derive the inputs the
+     * SessionDiscoveryService needs (working directory + Docker mode).
+     *
+     * @param name - The agent qualified name or local name
+     * @param operation - The public operation name, used for the
+     *   {@link InvalidStateError} message when the fleet is uninitialized
+     * @throws {InvalidStateError} If the fleet manager is not yet initialized
+     * @throws {AgentNotFoundError} If no agent with that name exists
+     */
+    resolveAgentForSessions(name, operation) {
+        // Guard against pre-init calls. Without this, an uninitialized fleet has a
+        // null config, so the agent lookup below would throw AgentNotFoundError —
+        // masking the real cause and contradicting the documented behavior (these
+        // helpers throw InvalidStateError before initialize()).
+        if (this.status === "uninitialized" || !this.config) {
+            throw new InvalidStateError(operation, this.status, [
+                "initialized",
+                "starting",
+                "running",
+                "stopping",
+                "stopped",
+            ]);
+        }
+        const agents = this.config.agents;
+        const agent = agents.find((a) => a.qualifiedName === name) ?? agents.find((a) => a.name === name);
+        if (!agent) {
+            throw new AgentNotFoundError(name);
+        }
+        return {
+            agent,
+            workingDirectory: resolveWorkingDirectory(agent),
+            dockerEnabled: agent.docker?.enabled === true,
+        };
+    }
     async initializeStateDir() {
         try {
             return await initStateDirectory({ path: this.stateDir });