@sunshinelife83/hearth 1.0.0

package/dist/local-agent-manager.js

@@ -0,0 +1,715 @@
+import { resolve } from "node:path";
+import { Result } from "better-result";
+import { AgentConflictError, AgentScopeError, AgentTargetError, isLocalAgentError, isProgrammerDefect, } from "./local-agent-errors.js";
+import { isLocalAgentProvider, } from "./local-agent-profiles.js";
+import { resolveLocalAgentTarget, } from "./local-agent-targets.js";
+import { assertAllowedPath } from "./roots.js";
+import { isSubagentProviderEnabled, } from "./local-agent-config.js";
+/** Default watchdog budget per agent turn (30 minutes). */
+export const DEFAULT_AGENT_TURN_TIMEOUT_MS = 30 * 60 * 1000;
+/** Watchdog ceiling (7 days); larger values are clamped, not rejected. */
+export const MAX_AGENT_TURN_TIMEOUT_MS = 7 * 24 * 3600 * 1000;
+/** Defensive clamp: non-finite/non-positive fall back to the default. */
+export function normalizeTimeoutMs(value) {
+    if (value === undefined || !Number.isFinite(value) || value <= 0)
+        return DEFAULT_AGENT_TURN_TIMEOUT_MS;
+    return Math.min(Math.floor(value), MAX_AGENT_TURN_TIMEOUT_MS);
+}
+/**
+ * Bound for the persisted in-flight output tail (characters).
+ */
+const MAX_OUTPUT_CHARS = 64_000;
+/**
+ * Owns one durable Hearth agent's turn lifecycle. Provider runtimes remain
+ * below this seam; this class only translates records into provider inputs and
+ * persists the result.
+ */
+export class LocalAgentManager {
+    store;
+    drivers = new Map();
+    pool;
+    loadProfiles;
+    agentDir;
+    allowedRoots;
+    logger;
+    subagents;
+    activeTurns = new Map();
+    activeRuntimeKeys = new Map();
+    outputBuffers = new Map();
+    /**
+     * Stop/pause requests for agents with an in-flight turn. When the provider
+     * run fails because its runtime was force-closed, the terminal status is
+     * taken from here instead of persisting a provider error.
+     */
+    interruptedAgents = new Map();
+    /**
+     * Agents whose watchdog budget expired. Checked before interruptedAgents:
+     * a turn that outlived its budget is a timeout error even if a stop/pause
+     * landed in the same window.
+     */
+    timedOutAgents = new Set();
+    /** Budget recorded per tracked turn so timeout errors report the real value. */
+    turnTimeoutMs = new Map();
+    accepting = true;
+    closePromise;
+    constructor(options) {
+        this.store = options.store;
+        for (const driver of options.drivers)
+            this.drivers.set(driver.provider, driver);
+        this.pool = options.pool;
+        this.loadProfiles = options.loadProfiles;
+        this.agentDir = options.agentDir;
+        this.allowedRoots = options.allowedRoots;
+        this.logger = options.logger;
+        this.subagents = options.subagents;
+    }
+    reconcileActiveRuns(message) {
+        return this.store.reconcileActiveRunsResult(message);
+    }
+    async start(input) {
+        const manager = this;
+        return Result.gen(async function* () {
+            yield* manager.acceptingResult("start");
+            const workspaceRoot = yield* manager.authorizeWorkspace(input.workspaceRoot, input.workspaceId, "start");
+            const profiles = yield* Result.await(manager.loadProfilesResult(workspaceRoot, input.target));
+            const target = resolveLocalAgentTarget(input.target, profiles, input.model, input.effort, manager.subagents.providers);
+            if (!target) {
+                return Result.err(new AgentTargetError({
+                    code: "UNKNOWN_TARGET",
+                    target: input.target,
+                    retryable: false,
+                    message: `Unknown subagent profile or provider: ${input.target}.`,
+                }));
+            }
+            if (target.kind === "profile" && target.profile.disabled) {
+                return Result.err(new AgentTargetError({
+                    code: "PROVIDER_DISABLED",
+                    target: target.name,
+                    provider: target.provider,
+                    retryable: false,
+                    message: `Subagent profile is disabled: ${target.name}.`,
+                }));
+            }
+            yield* manager.providerEnabledResult(target.provider, target.name, "start");
+            yield* manager.driverResult(target.provider, "start");
+            const record = yield* manager.store.createResult({
+                workspaceId: input.workspaceId,
+                workspaceRoot,
+                profileName: target.name,
+                provider: target.provider,
+                model: target.model,
+                effort: target.effort,
+            });
+            return manager.begin(record, input.prompt, {
+                model: target.model,
+                effort: target.effort,
+                writeMode: input.writeMode,
+            }, input.workspaceId, input.timeoutMs);
+        });
+    }
+    async continue(agentId, prompt, overrides = {}, scope, timeoutMs) {
+        const manager = this;
+        return Result.gen(async function* () {
+            yield* manager.acceptingResult("continue", agentId);
+            const record = yield* manager.store.getByIdResult(agentId);
+            if (!record)
+                return Result.err(agentNotFound(agentId));
+            yield* manager.agentWorkspaceResult(record, scope, "continue");
+            const profiles = yield* Result.await(manager.loadProfilesResult(record.workspaceRoot, record.profileName));
+            yield* manager.profileForRecordResult(record, profiles);
+            yield* manager.providerEnabledResult(record.provider, record.profileName, "continue");
+            yield* manager.driverResult(record.provider, "continue", agentId);
+            return manager.begin(record, prompt, overrides, scope.workspaceId, timeoutMs);
+        });
+    }
+    get(agentId, scope) {
+        const lookup = this.store.getByIdResult(agentId);
+        if (lookup.isErr())
+            return lookup;
+        const record = lookup.value;
+        if (!record)
+            return Result.err(agentNotFound(agentId));
+        const scoped = this.agentWorkspaceResult(record, scope, "get");
+        if (scoped.isErr())
+            return scoped;
+        return Result.ok(record);
+    }
+    list(scope) {
+        return this.authorizeWorkspace(scope.workspaceRoot, scope.workspaceId, "list").andThen((workspaceRoot) => (this.store.listResult({
+            workspaceId: scope.workspaceId,
+            workspaceRoot,
+        })));
+    }
+    /**
+     * Pause an agent. Between turns this only flips the durable status; with
+     * `force` a running turn is interrupted by closing its runtime.
+     */
+    async pause(agentId, scope, options = {}) {
+        const lookup = this.store.getByIdResult(agentId);
+        if (lookup.isErr())
+            return lookup;
+        const record = lookup.value;
+        if (!record)
+            return Result.err(agentNotFound(agentId));
+        const scoped = this.agentWorkspaceResult(record, scope, "pause");
+        if (scoped.isErr())
+            return scoped;
+        if (this.activeTurns.has(agentId)) {
+            if (!options.force) {
+                return Result.err(new AgentConflictError({
+                    code: "AGENT_TURN_ACTIVE",
+                    agentId,
+                    operation: "pause",
+                    retryable: true,
+                    message: `Agent ${agentId} has a running turn. Wait for it to finish or pause with force.`,
+                }));
+            }
+            await this.interruptTurn(agentId, "paused");
+        }
+        return this.store.updateResult(agentId, {
+            status: "paused",
+            error: undefined,
+            errorCode: undefined,
+            errorRetryable: undefined,
+        });
+    }
+    /**
+     * Resume a paused agent (idle/error agents also resume) by starting a new
+     * turn on the durable provider session.
+     */
+    async resume(agentId, prompt, overrides = {}, scope, timeoutMs) {
+        const manager = this;
+        return Result.gen(async function* () {
+            yield* manager.acceptingResult("resume", agentId);
+            const record = yield* manager.store.getByIdResult(agentId);
+            if (!record)
+                return Result.err(agentNotFound(agentId));
+            yield* manager.agentWorkspaceResult(record, scope, "resume");
+            if (manager.activeTurns.has(agentId)) {
+                return Result.err(new AgentConflictError({
+                    code: "AGENT_CONFLICT",
+                    agentId,
+                    operation: "resume",
+                    retryable: true,
+                    message: `Agent ${agentId} already has a running turn.`,
+                }));
+            }
+            if (record.status === "starting" || record.status === "running") {
+                return Result.err(new AgentConflictError({
+                    code: "AGENT_CONFLICT",
+                    agentId,
+                    operation: "resume",
+                    retryable: true,
+                    message: `Agent ${agentId} is ${record.status}; resume applies to paused, idle, or error agents.`,
+                }));
+            }
+            const profiles = yield* Result.await(manager.loadProfilesResult(record.workspaceRoot, record.profileName));
+            yield* manager.profileForRecordResult(record, profiles);
+            yield* manager.providerEnabledResult(record.provider, record.profileName, "resume");
+            yield* manager.driverResult(record.provider, "resume", agentId);
+            return manager.begin(record, prompt ?? "Resume the task.", overrides, scope.workspaceId, timeoutMs);
+        });
+    }
+    /**
+     * Stop an agent. Between turns this flips the durable status to stopped;
+     * with `force` (or via cancel()) a running turn is interrupted.
+     */
+    async stop(agentId, scope, options = {}) {
+        const lookup = this.store.getByIdResult(agentId);
+        if (lookup.isErr())
+            return lookup;
+        const record = lookup.value;
+        if (!record)
+            return Result.err(agentNotFound(agentId));
+        const scoped = this.agentWorkspaceResult(record, scope, "stop");
+        if (scoped.isErr())
+            return scoped;
+        if (this.activeTurns.has(agentId)) {
+            if (!options.force) {
+                return Result.err(new AgentConflictError({
+                    code: "AGENT_TURN_ACTIVE",
+                    agentId,
+                    operation: "stop",
+                    retryable: true,
+                    message: `Agent ${agentId} has a running turn. Wait for it to finish or stop with force.`,
+                }));
+            }
+            await this.interruptTurn(agentId, "stopped");
+        }
+        return this.store.updateResult(agentId, {
+            status: "stopped",
+            error: undefined,
+            errorCode: undefined,
+            errorRetryable: undefined,
+        });
+    }
+    /** Unconditional stop: interrupts a running turn when one exists. */
+    async cancel(agentId, scope) {
+        return this.stop(agentId, scope, { force: true });
+    }
+    async interruptTurn(agentId, target) {
+        this.interruptedAgents.set(agentId, target);
+        const runtimeKey = this.activeRuntimeKeys.get(agentId);
+        if (runtimeKey) {
+            try {
+                await this.pool.cancelRuntimeKey(runtimeKey, `agent_${target}`);
+            }
+            finally {
+                this.activeRuntimeKeys.delete(agentId);
+            }
+        }
+    }
+    async close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.accepting = false;
+        const turns = Array.from(this.activeTurns.values());
+        this.closePromise = (async () => {
+            // Closing pooled runtimes is what interrupts provider turns. Waiting for
+            // those turns first can strand a provider process indefinitely.
+            await this.pool.close();
+            const turnResults = await Promise.allSettled(turns);
+            for (const result of turnResults) {
+                if (result.status === "rejected") {
+                    this.log("warn", "local_agent_close_failed", { error: errorMessage(result.reason) });
+                }
+            }
+            this.store.close();
+        })();
+        return this.closePromise;
+    }
+    get activeTurnCount() {
+        return this.activeTurns.size;
+    }
+    get runtimeCount() {
+        return this.pool.size;
+    }
+    async evictIdle(now) {
+        await this.pool.evictIdle(now);
+    }
+    begin(record, prompt, overrides, workspaceId, timeoutMs) {
+        if (this.activeTurns.has(record.id)) {
+            return Result.err(new AgentConflictError({
+                code: "AGENT_CONFLICT",
+                agentId: record.id,
+                operation: "continue",
+                retryable: true,
+                message: `Agent ${record.id} already has a running turn.`,
+            }));
+        }
+        const updated = this.store.updateResult(record.id, {
+            status: "running",
+            model: overrides.model ?? record.model,
+            effort: overrides.effort ?? record.effort,
+            latestResponse: undefined,
+            latestOutput: undefined,
+            error: undefined,
+            errorCode: undefined,
+            errorRetryable: undefined,
+        });
+        if (updated.isErr())
+            return updated;
+        this.outputBuffers.set(record.id, "");
+        // Defer invocation until after the tracking entry is visible. This keeps
+        // cleanup correct even if runTurn later gains a synchronous completion path.
+        const turn = Promise.resolve().then(() => (this.runTurn(updated.value, prompt, overrides, workspaceId, normalizeTimeoutMs(timeoutMs))));
+        this.turnTimeoutMs.set(record.id, normalizeTimeoutMs(timeoutMs));
+        this.activeTurns.set(record.id, turn);
+        void turn.catch(() => undefined);
+        return updated;
+    }
+    async runTurn(record, prompt, overrides, workspaceId, timeoutMs = DEFAULT_AGENT_TURN_TIMEOUT_MS) {
+        const startedAt = Date.now();
+        const watchdog = this.armWatchdog(record.id, timeoutMs);
+        this.log("info", "agent_run_started", {
+            provider: record.provider,
+            agentId: record.id,
+            providerSessionIdPrefix: record.providerSessionId?.slice(0, 8),
+        });
+        try {
+            const authorized = this.authorizeWorkspace(record.workspaceRoot, workspaceId, "run");
+            if (authorized.isErr()) {
+                this.persistRunError(record, authorized.error, startedAt);
+                return;
+            }
+            const workspaceRoot = authorized.value;
+            const authorizedRecord = workspaceRoot === record.workspaceRoot
+                ? record
+                : { ...record, workspaceRoot };
+            const profiles = await this.loadProfilesResult(workspaceRoot, record.profileName);
+            if (profiles.isErr()) {
+                this.persistRunError(record, profiles.error, startedAt);
+                return;
+            }
+            const profile = this.profileForRecordResult(record, profiles.value);
+            if (profile.isErr()) {
+                this.persistRunError(record, profile.error, startedAt);
+                return;
+            }
+            const input = this.buildRunInputResult(authorizedRecord, profile.value, prompt, overrides);
+            if (input.isErr()) {
+                this.persistRunError(record, input.error, startedAt);
+                return;
+            }
+            const driver = this.driverResult(record.provider, "run", record.id);
+            if (driver.isErr()) {
+                this.persistRunError(record, driver.error, startedAt);
+                return;
+            }
+            const context = {
+                agentId: record.id,
+                provider: driver.value.provider,
+                workspaceRoot,
+                providerSessionId: record.providerSessionId,
+                writeMode: input.value.writeMode,
+                model: input.value.model,
+                effort: input.value.effort,
+                agentDir: this.agentDir,
+            };
+            this.activeRuntimeKeys.set(record.id, driver.value.runtimeKey(context));
+            const callbacks = {
+                onSessionId: (providerSessionId) => {
+                    const current = this.store.getByIdResult(record.id);
+                    if (current.isErr())
+                        throw current.error;
+                    if (!current.value || current.value.providerSessionId === providerSessionId)
+                        return;
+                    const updated = this.store.updateResult(record.id, { providerSessionId });
+                    if (updated.isErr())
+                        throw updated.error;
+                },
+                onOutput: (delta) => {
+                    if (!delta)
+                        return;
+                    const buffer = ((this.outputBuffers.get(record.id) ?? "") + delta).slice(-MAX_OUTPUT_CHARS);
+                    this.outputBuffers.set(record.id, buffer);
+                    const persisted = this.store.updateResult(record.id, { latestOutput: buffer });
+                    if (persisted.isErr()) {
+                        this.log("warn", "agent_output_persist_failed", { agentId: record.id });
+                    }
+                },
+            };
+            const result = await this.pool.run(driver.value, context, input.value, callbacks);
+            if (result.isErr()) {
+                this.persistRunError(record, result.error, startedAt);
+                return;
+            }
+            const runResult = result.value;
+            const current = this.store.getByIdResult(record.id);
+            if (current.isErr())
+                throw current.error;
+            if (!current.value)
+                return;
+            const interrupted = this.interruptedAgents.get(record.id);
+            if (this.timedOutAgents.has(record.id)) {
+                this.persistTimeoutError(record, startedAt, timeoutMs);
+                return;
+            }
+            if (interrupted) {
+                this.store.updateResult(record.id, {
+                    providerSessionId: runResult.providerSessionId ?? current.value.providerSessionId,
+                    status: interrupted,
+                    error: undefined,
+                    errorCode: undefined,
+                    errorRetryable: undefined,
+                });
+                return;
+            }
+            const updated = this.store.updateResult(record.id, {
+                providerSessionId: runResult.providerSessionId ?? current.value.providerSessionId,
+                status: "idle",
+                latestResponse: runResult.finalResponse,
+                error: undefined,
+                errorCode: undefined,
+                errorRetryable: undefined,
+            });
+            if (updated.isErr())
+                throw updated.error;
+            this.log("info", "agent_run_completed", {
+                provider: updated.value.provider,
+                agentId: updated.value.id,
+                providerSessionIdPrefix: updated.value.providerSessionId?.slice(0, 8),
+                durationMs: Math.max(0, Date.now() - startedAt),
+            });
+        }
+        catch (error) {
+            if (isLocalAgentError(error)) {
+                this.persistRunError(record, error, startedAt);
+                return;
+            }
+            const persisted = this.store.updateResult(record.id, {
+                status: "error",
+                error: "Unexpected internal subagent failure.",
+                errorCode: "AGENT_INTERNAL_ERROR",
+                errorRetryable: false,
+            });
+            this.log("error", "agent_run_failed", {
+                provider: record.provider,
+                agentId: record.id,
+                providerSessionIdPrefix: record.providerSessionId?.slice(0, 8),
+                durationMs: Math.max(0, Date.now() - startedAt),
+                error: "Unexpected internal subagent failure.",
+                errorType: error instanceof Error ? error.name : typeof error,
+                persistenceFailed: persisted.isErr(),
+            });
+            throw error;
+        }
+        finally {
+            clearTimeout(watchdog);
+            this.timedOutAgents.delete(record.id);
+            this.turnTimeoutMs.delete(record.id);
+            this.activeTurns.delete(record.id);
+            this.activeRuntimeKeys.delete(record.id);
+            this.outputBuffers.delete(record.id);
+            this.interruptedAgents.delete(record.id);
+        }
+    }
+    /**
+     * Watchdog: when the budget expires while the turn is still tracked,
+     * interrupt the runtime; completion paths then persist a timeout error.
+     * The timer is unref'd so an idle manager never holds the process open.
+     */
+    armWatchdog(agentId, timeoutMs) {
+        const timer = setTimeout(() => {
+            if (!this.activeTurns.has(agentId))
+                return;
+            this.timedOutAgents.add(agentId);
+            void this.interruptTurn(agentId, "stopped").catch(() => undefined);
+        }, timeoutMs);
+        timer.unref?.();
+        return timer;
+    }
+    persistTimeoutError(record, startedAt, timeoutMs) {
+        const minutes = Math.round(timeoutMs / 60000);
+        const persisted = this.store.updateResult(record.id, {
+            status: "error",
+            error: `Agent turn exceeded its timeout budget of ${minutes} minute(s). Resume with a smaller task or a larger timeout.`,
+            errorCode: "AGENT_TIMEOUT",
+            errorRetryable: true,
+        });
+        this.log("warn", "agent_turn_timeout", {
+            provider: record.provider,
+            agentId: record.id,
+            timeoutMs,
+            durationMs: Math.max(0, Date.now() - startedAt),
+            persistenceFailed: persisted.isErr(),
+        });
+    }
+    persistRunError(record, error, startedAt) {
+        if (this.timedOutAgents.has(record.id)) {
+            this.persistTimeoutError(record, startedAt, this.turnTimeoutMs.get(record.id) ?? DEFAULT_AGENT_TURN_TIMEOUT_MS);
+            return;
+        }
+        const interrupted = this.interruptedAgents.get(record.id);
+        if (interrupted) {
+            const persisted = this.store.updateResult(record.id, {
+                status: interrupted,
+                error: undefined,
+                errorCode: undefined,
+                errorRetryable: undefined,
+            });
+            this.log("info", "agent_turn_interrupted", {
+                provider: record.provider,
+                agentId: record.id,
+                status: interrupted,
+                durationMs: Math.max(0, Date.now() - startedAt),
+                persistenceFailed: persisted.isErr(),
+            });
+            return;
+        }
+        const persisted = this.store.updateResult(record.id, {
+            status: "error",
+            error: error.message,
+            errorCode: error.code,
+            errorRetryable: error.retryable,
+        });
+        this.log("error", "agent_run_failed", {
+            provider: record.provider,
+            agentId: record.id,
+            providerSessionIdPrefix: record.providerSessionId?.slice(0, 8),
+            durationMs: Math.max(0, Date.now() - startedAt),
+            errorCode: error.code,
+            error: error.message,
+            causeType: safeCauseType("cause" in error ? error.cause : undefined),
+            persistenceFailed: persisted.isErr(),
+        });
+    }
+    buildRunInputResult(record, profile, prompt, overrides) {
+        const isRawProvider = record.profileName === record.provider;
+        if (!profile && !isRawProvider) {
+            return Result.err(new AgentTargetError({
+                code: "UNKNOWN_TARGET",
+                target: record.profileName,
+                provider: isLocalAgentProvider(record.provider) ? record.provider : undefined,
+                retryable: false,
+                message: `Subagent profile not found: ${record.profileName}.`,
+            }));
+        }
+        const body = profile?.body.trim();
+        const fullPrompt = body ? `${body}\n\nTask:\n${prompt}` : prompt;
+        return Result.ok({
+            prompt: fullPrompt,
+            workspaceRoot: record.workspaceRoot,
+            providerSessionId: record.providerSessionId,
+            writeMode: overrides.writeMode ?? "allowed",
+            model: record.model ?? profile?.model,
+            effort: record.effort ?? profile?.effort,
+            modelOverrideRequested: overrides.model !== undefined,
+            effortOverrideRequested: overrides.effort !== undefined,
+        });
+    }
+    profileForRecordResult(record, profiles) {
+        if (record.profileName === record.provider)
+            return Result.ok(undefined);
+        const profile = profiles.find((candidate) => candidate.name === record.profileName);
+        if (!profile) {
+            return Result.err(new AgentTargetError({
+                code: "UNKNOWN_TARGET",
+                target: record.profileName,
+                provider: isLocalAgentProvider(record.provider) ? record.provider : undefined,
+                retryable: false,
+                message: `Subagent profile not found: ${record.profileName}.`,
+            }));
+        }
+        if (profile.disabled) {
+            return Result.err(new AgentTargetError({
+                code: "PROVIDER_DISABLED",
+                target: profile.name,
+                provider: profile.provider,
+                retryable: false,
+                message: `Subagent profile is disabled: ${profile.name}.`,
+            }));
+        }
+        return Result.ok(profile);
+    }
+    driverResult(provider, operation, agentId) {
+        if (!isLocalAgentProvider(provider)) {
+            return Result.err(new AgentTargetError({
+                code: "PROVIDER_NOT_CONFIGURED",
+                target: provider,
+                operation,
+                retryable: false,
+                message: `No local agent driver is configured for provider: ${provider}.`,
+            }));
+        }
+        const driver = this.drivers.get(provider);
+        if (!driver) {
+            return Result.err(new AgentTargetError({
+                code: "PROVIDER_NOT_CONFIGURED",
+                target: agentId ?? provider,
+                provider,
+                operation,
+                retryable: false,
+                message: `No local agent driver is configured for provider: ${provider}.`,
+            }));
+        }
+        return Result.ok(driver);
+    }
+    providerEnabledResult(provider, target, operation) {
+        if (!isLocalAgentProvider(provider))
+            return Result.ok(undefined);
+        if (isSubagentProviderEnabled(this.subagents, provider))
+            return Result.ok(undefined);
+        return Result.err(new AgentTargetError({
+            code: "PROVIDER_DISABLED",
+            target,
+            provider,
+            operation,
+            retryable: false,
+            message: `Subagent provider is disabled: ${provider}.`,
+        }));
+    }
+    acceptingResult(operation, agentId) {
+        if (this.accepting)
+            return Result.ok(undefined);
+        return Result.err(new AgentConflictError({
+            code: "AGENT_CONFLICT",
+            agentId,
+            operation,
+            retryable: false,
+            message: "Local agent manager is closed.",
+        }));
+    }
+    authorizeWorkspace(workspaceRoot, workspaceId, operation) {
+        const normalized = resolve(workspaceRoot);
+        // Security: allowed roots apply to every caller. The previous behavior
+        // skipped the check when workspaceId was absent, which let MCP-shell
+        // invocations (`hearth agents run` via a shell tool) run agents
+        // anywhere on disk (audit finding SEC-04).
+        void workspaceId;
+        if (!this.allowedRoots)
+            return Result.ok(normalized);
+        try {
+            return Result.ok(assertAllowedPath(normalized, [...this.allowedRoots]));
+        }
+        catch (cause) {
+            return Result.err(new AgentScopeError({
+                code: "WORKSPACE_NOT_ALLOWED",
+                operation,
+                retryable: false,
+                cause,
+                message: "Workspace root is outside configured allowed roots.",
+            }));
+        }
+    }
+    agentWorkspaceResult(record, scope, operation) {
+        const workspaceRoot = this.authorizeWorkspace(scope.workspaceRoot, scope.workspaceId, operation);
+        if (workspaceRoot.isErr())
+            return workspaceRoot;
+        const idMismatch = scope.workspaceId !== undefined && record.workspaceId !== scope.workspaceId;
+        if (workspaceRoot.value !== record.workspaceRoot || idMismatch) {
+            return Result.err(new AgentScopeError({
+                code: "WORKSPACE_MISMATCH",
+                agentId: record.id,
+                workspaceId: scope.workspaceId,
+                operation,
+                retryable: false,
+                message: `Subagent ${record.id} belongs to a different workspace.`,
+            }));
+        }
+        return Result.ok(undefined);
+    }
+    async loadProfilesResult(workspaceRoot, target) {
+        try {
+            return Result.ok(await this.loadProfiles(workspaceRoot));
+        }
+        catch (cause) {
+            if (isProgrammerDefect(cause))
+                throw cause;
+            return Result.err(new AgentTargetError({
+                code: "TARGET_RESOLUTION_FAILED",
+                target,
+                retryable: false,
+                cause,
+                message: "Unable to load subagent profiles.",
+            }));
+        }
+    }
+    log(level, event, fields) {
+        this.logger?.(level, event, fields);
+    }
+}
+export function createLocalAgentManager(options) {
+    return new LocalAgentManager(options);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function safeCauseType(cause) {
+    if (cause instanceof Error)
+        return cause.name;
+    if (cause && typeof cause === "object" && "error" in cause) {
+        const nested = cause.error;
+        if (nested instanceof Error)
+            return nested.name;
+    }
+    return cause === undefined ? undefined : typeof cause;
+}
+function agentNotFound(agentId) {
+    return new AgentTargetError({
+        code: "AGENT_NOT_FOUND",
+        target: agentId,
+        retryable: false,
+        message: `Unknown subagent id: ${agentId}.`,
+    });
+}