@mono-agent/agent-app 0.19.1 → 0.20.0

package/dist/agent-root-coordinator.d.ts

@@ -0,0 +1,101 @@
+import { type OwnerPrivateLock } from "./owner-private-lock.js";
+import type { ProcessIncarnation, SameProcessIncarnation } from "./process-incarnation.js";
+export declare const PROCESS_JOBS_GENERATION_DRAIN_TIMEOUT_MS = 30000;
+export declare const AGENT_ROOT_OWNED_ELSEWHERE_ERROR = "Another mono-agent process is already using this agent root. Stop that local agent before trying again.";
+export declare const AGENT_ROOT_REQUIRED_ERROR = "A configured local runtime requires an explicit agent-root cwd.";
+export declare const AGENT_ROOT_WORKSPACE_REQUIRED_ERROR = "runtime.workspace must reference an existing directory before mono-agent starts. Create it or choose an existing workspace.";
+export declare const PROCESS_JOBS_GENERATION_CHANGED_ERROR = "Process-job private-state protection changed before provider execution.";
+export declare const PROCESS_JOBS_GENERATION_DRAIN_TIMEOUT_ERROR = "Process-job private-state protection could not safely finish the live configuration switch.";
+export interface AgentRootProtectionGeneration {
+    readonly id: string;
+    readonly rootKeys: readonly string[];
+}
+export interface AgentRootRequestLease {
+    readonly generation: AgentRootProtectionGeneration;
+    releaseAfterSettlement(): void;
+}
+export interface AgentRootMutationGate {
+    readonly generation: AgentRootProtectionGeneration;
+    release(): void;
+}
+export interface AgentRootOwnership {
+    readonly agentRoot: string;
+    readonly coordinator: AgentRootCoordinator;
+    /** Release this in-process reference; the OS lease remains until every request truly settles. */
+    release(): void;
+}
+export interface AcquireAgentRootOwnershipOptions {
+    readonly homeDir?: string;
+    readonly pid?: number;
+    readonly now?: () => number;
+    readonly randomToken?: () => string;
+    readonly processIncarnation?: ProcessIncarnation;
+    readonly isSameProcessIncarnation?: SameProcessIncarnation;
+    readonly ownerlessGraceMs?: number;
+    readonly hooks?: {
+        readonly afterLeaseDirectoryCreated?: () => Promise<void>;
+        readonly beforeStaleLeaseRename?: () => Promise<void>;
+        /** Test-only fault seam for the final physical owner-lock release. */
+        readonly beforeLeaseRelease?: () => Promise<void>;
+    };
+}
+/** Stable owner-record path for an already-canonical agent root. */
+export declare function agentRootLeasePath(canonicalRoot: string, homeDir?: string): string;
+interface ActiveGeneration {
+    readonly roots: ReadonlySet<string>;
+    count: number;
+}
+interface CoordinatorEntry {
+    readonly agentRoot: string;
+    readonly lease: OwnerPrivateLock;
+    readonly leasePath: string;
+    readonly beforeLeaseRelease?: () => Promise<void>;
+    readonly active: Map<string, ActiveGeneration>;
+    readonly waiters: Set<() => void>;
+    ownerRefs: number;
+    current?: AgentRootProtectionGeneration;
+    mutationPending: boolean;
+    closing: boolean;
+    closeError?: Error;
+    closed: Promise<void>;
+    resolveClosed: () => void;
+}
+/**
+ * One process-global coordinator per canonical agent root. It combines the
+ * cross-process lifetime lease with in-process registry-generation settlement.
+ */
+export declare class AgentRootCoordinator {
+    #private;
+    constructor(entry: CoordinatorEntry);
+    get agentRoot(): string;
+    currentGeneration(): AgentRootProtectionGeneration | undefined;
+    publishGeneration(generation: AgentRootProtectionGeneration): void;
+    /** Adopt an already-durable generation without allowing a stale constructor to roll it back. */
+    synchronizeGeneration(generation: AgentRootProtectionGeneration): void;
+    acquireRequestLease(generation: AgentRootProtectionGeneration): AgentRootRequestLease;
+    /**
+     * Publish the durable generation, then wait only for older leases which did
+     * not cover the root about to be opened. Timeout is fail-closed: callers must
+     * not open or create the ProcessJobs store after rejection.
+     */
+    publishAndAcquireMutationGate(generation: AgentRootProtectionGeneration, requiredRootKey: string, options?: {
+        readonly timeoutMs?: number;
+    }): Promise<AgentRootMutationGate>;
+    /** Test/coordination seam: resolves only when no request lease remains. */
+    waitForSettlement(): Promise<void>;
+}
+/** Acquire the reentrant process lifetime owner for one canonical agent root. */
+export declare function acquireAgentRootOwnership(agentRoot: string | undefined, options?: AcquireAgentRootOwnershipOptions): Promise<AgentRootOwnership>;
+/**
+ * Release one logical owner and, only when it was the already-idle final
+ * reference, wait for the physical cross-process lease to disappear.
+ *
+ * Active request or mutation leases deliberately make this return `false`
+ * immediately. They retain the physical lock until true settlement so bounded
+ * app/harness teardown cannot create split ownership.
+ */
+export declare function releaseAgentRootOwnershipWhenIdle(ownership: AgentRootOwnership): Promise<boolean>;
+/** Reject the exceptional case where the global coordination lease is model-workspace reachable. */
+export declare function assertAgentRootLeaseOutsideWorkspace(ownership: AgentRootOwnership, workspace: string): void;
+export {};
+//# sourceMappingURL=agent-root-coordinator.d.ts.map

package/dist/agent-root-coordinator.d.ts.map

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

package/dist/agent-root-coordinator.js

@@ -0,0 +1,470 @@
+import { createHash, randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { chmod, lstat, mkdir, realpath } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import process from "node:process";
+import { acquireOwnerPrivateLock, validateOwnerPrivateLockInputs, } from "./owner-private-lock.js";
+import { accountHomeDirectory } from "./account-home.js";
+const AGENT_ROOT_LEASE_SCHEMA = "mono-agent.agent-root-lease.v1";
+const AGENT_ROOT_LEASE_OWNERLESS_GRACE_MS = 5 * 60_000;
+const AGENT_ROOT_LEASE_ACQUIRE_ATTEMPTS = 4;
+export const PROCESS_JOBS_GENERATION_DRAIN_TIMEOUT_MS = 30_000;
+export const AGENT_ROOT_OWNED_ELSEWHERE_ERROR = "Another mono-agent process is already using this agent root. Stop that local agent before trying again.";
+export const AGENT_ROOT_REQUIRED_ERROR = "A configured local runtime requires an explicit agent-root cwd.";
+export const AGENT_ROOT_WORKSPACE_REQUIRED_ERROR = "runtime.workspace must reference an existing directory before mono-agent starts. Create it or choose an existing workspace.";
+export const PROCESS_JOBS_GENERATION_CHANGED_ERROR = "Process-job private-state protection changed before provider execution.";
+export const PROCESS_JOBS_GENERATION_DRAIN_TIMEOUT_ERROR = "Process-job private-state protection could not safely finish the live configuration switch.";
+/** Stable owner-record path for an already-canonical agent root. */
+export function agentRootLeasePath(canonicalRoot, homeDir = accountHomeDirectory()) {
+    const digest = rootDigest(canonicalRoot);
+    return join(resolve(homeDir), ".mono-agent", "agent-root-leases", `${digest}.lease`);
+}
+const entries = new Map();
+const acquisitions = new Map();
+const ownershipEntries = new WeakMap();
+const releasedOwnerships = new WeakSet();
+/**
+ * One process-global coordinator per canonical agent root. It combines the
+ * cross-process lifetime lease with in-process registry-generation settlement.
+ */
+export class AgentRootCoordinator {
+    #entry;
+    constructor(entry) {
+        this.#entry = entry;
+    }
+    get agentRoot() {
+        return this.#entry.agentRoot;
+    }
+    currentGeneration() {
+        return this.#entry.current;
+    }
+    publishGeneration(generation) {
+        assertGeneration(generation);
+        this.#entry.current = frozenGeneration(generation);
+        notifyWaiters(this.#entry);
+    }
+    /** Adopt an already-durable generation without allowing a stale constructor to roll it back. */
+    synchronizeGeneration(generation) {
+        assertGeneration(generation);
+        if (this.#entry.current === undefined) {
+            this.publishGeneration(generation);
+            return;
+        }
+        if (!sameGeneration(this.#entry.current, generation)) {
+            throw new Error(PROCESS_JOBS_GENERATION_CHANGED_ERROR);
+        }
+    }
+    acquireRequestLease(generation) {
+        if (this.#entry.closing) {
+            throw this.#entry.closeError
+                ?? new Error("Agent-root ownership is already being released.");
+        }
+        assertGeneration(generation);
+        const current = this.#entry.current;
+        if (current === undefined || !sameGeneration(current, generation)) {
+            throw new Error(PROCESS_JOBS_GENERATION_CHANGED_ERROR);
+        }
+        let active = this.#entry.active.get(generation.id);
+        if (active === undefined) {
+            active = { roots: new Set(generation.rootKeys), count: 0 };
+            this.#entry.active.set(generation.id, active);
+        }
+        else if (!sameRoots(active.roots, generation.rootKeys)) {
+            throw new Error(PROCESS_JOBS_GENERATION_CHANGED_ERROR);
+        }
+        active.count += 1;
+        let released = false;
+        return {
+            generation: frozenGeneration(generation),
+            releaseAfterSettlement: () => {
+                if (released)
+                    return;
+                released = true;
+                const held = this.#entry.active.get(generation.id);
+                if (held === undefined || held.count < 1)
+                    return;
+                held.count -= 1;
+                if (held.count === 0)
+                    this.#entry.active.delete(generation.id);
+                notifyWaiters(this.#entry);
+                scheduleFinalRelease(this.#entry);
+            },
+        };
+    }
+    /**
+     * Publish the durable generation, then wait only for older leases which did
+     * not cover the root about to be opened. Timeout is fail-closed: callers must
+     * not open or create the ProcessJobs store after rejection.
+     */
+    async publishAndAcquireMutationGate(generation, requiredRootKey, options = {}) {
+        if (this.#entry.closing) {
+            throw this.#entry.closeError
+                ?? new Error("Agent-root ownership is already being released.");
+        }
+        if (this.#entry.mutationPending) {
+            throw new Error(PROCESS_JOBS_GENERATION_CHANGED_ERROR);
+        }
+        this.publishGeneration(generation);
+        this.#entry.mutationPending = true;
+        const timeoutMs = options.timeoutMs ?? PROCESS_JOBS_GENERATION_DRAIN_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs < 1) {
+            this.#entry.mutationPending = false;
+            throw new TypeError("Process-job generation drain timeout must be a positive finite number.");
+        }
+        try {
+            await waitUntil(this.#entry, () => !hasIncompatibleLease(this.#entry, generation.id, requiredRootKey), timeoutMs);
+        }
+        catch (error) {
+            this.#entry.mutationPending = false;
+            notifyWaiters(this.#entry);
+            scheduleFinalRelease(this.#entry);
+            if (error instanceof DrainTimeoutError) {
+                throw new Error(PROCESS_JOBS_GENERATION_DRAIN_TIMEOUT_ERROR);
+            }
+            throw error;
+        }
+        let released = false;
+        return {
+            generation: frozenGeneration(generation),
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.#entry.mutationPending = false;
+                notifyWaiters(this.#entry);
+                scheduleFinalRelease(this.#entry);
+            },
+        };
+    }
+    /** Test/coordination seam: resolves only when no request lease remains. */
+    async waitForSettlement() {
+        await waitUntil(this.#entry, () => this.#entry.active.size === 0, undefined);
+    }
+}
+/** Acquire the reentrant process lifetime owner for one canonical agent root. */
+export async function acquireAgentRootOwnership(agentRoot, options = {}) {
+    if (agentRoot === undefined || agentRoot.trim().length === 0) {
+        throw new Error(AGENT_ROOT_REQUIRED_ERROR);
+    }
+    const canonicalRoot = await canonicalAgentRoot(agentRoot);
+    for (;;) {
+        const existing = entries.get(canonicalRoot);
+        if (existing !== undefined) {
+            if (existing.closing) {
+                await existing.closed;
+                if (existing.closeError !== undefined)
+                    throw existing.closeError;
+                continue;
+            }
+            existing.ownerRefs += 1;
+            return ownershipHandle(existing);
+        }
+        const pending = acquisitions.get(canonicalRoot);
+        if (pending !== undefined) {
+            const entry = await pending;
+            if (entry.closing) {
+                await entry.closed;
+                if (entry.closeError !== undefined)
+                    throw entry.closeError;
+                continue;
+            }
+            entry.ownerRefs += 1;
+            return ownershipHandle(entry);
+        }
+        const acquiring = createEntry(canonicalRoot, options);
+        acquisitions.set(canonicalRoot, acquiring);
+        try {
+            const entry = await acquiring;
+            entries.set(canonicalRoot, entry);
+            entry.ownerRefs = 1;
+            return ownershipHandle(entry);
+        }
+        finally {
+            if (acquisitions.get(canonicalRoot) === acquiring)
+                acquisitions.delete(canonicalRoot);
+        }
+    }
+}
+/**
+ * Release one logical owner and, only when it was the already-idle final
+ * reference, wait for the physical cross-process lease to disappear.
+ *
+ * Active request or mutation leases deliberately make this return `false`
+ * immediately. They retain the physical lock until true settlement so bounded
+ * app/harness teardown cannot create split ownership.
+ */
+export async function releaseAgentRootOwnershipWhenIdle(ownership) {
+    const entry = entryFor(ownership);
+    if (releasedOwnerships.has(ownership)) {
+        if (!entry.closing)
+            return false;
+        await entry.closed;
+        if (entry.closeError !== undefined)
+            throw entry.closeError;
+        return true;
+    }
+    const shouldWait = releaseOwnershipReference(ownership, entry);
+    if (!shouldWait)
+        return false;
+    await entry.closed;
+    if (entry.closeError !== undefined)
+        throw entry.closeError;
+    return true;
+}
+/** Reject the exceptional case where the global coordination lease is model-workspace reachable. */
+export function assertAgentRootLeaseOutsideWorkspace(ownership, workspace) {
+    const entry = entryFor(ownership);
+    const resolvedWorkspace = resolve(workspace);
+    let canonicalWorkspace;
+    try {
+        canonicalWorkspace = realpathSync(resolvedWorkspace);
+    }
+    catch (error) {
+        if (isErrno(error, "ENOENT"))
+            throw new Error(AGENT_ROOT_WORKSPACE_REQUIRED_ERROR);
+        throw error;
+    }
+    if (containsPath(resolvedWorkspace, entry.leasePath)
+        || containsPath(canonicalWorkspace, entry.leasePath)) {
+        throw new Error("The configured model workspace contains mono-agent's private process-coordination data. Choose a narrower workspace.");
+    }
+}
+function ownershipHandle(entry) {
+    const coordinator = new AgentRootCoordinator(entry);
+    const handle = {
+        agentRoot: entry.agentRoot,
+        coordinator,
+        release: () => {
+            releaseOwnershipReference(handle, entry);
+        },
+    };
+    ownershipEntries.set(handle, entry);
+    return handle;
+}
+function releaseOwnershipReference(ownership, entry) {
+    if (releasedOwnerships.has(ownership))
+        return false;
+    releasedOwnerships.add(ownership);
+    entry.ownerRefs = Math.max(0, entry.ownerRefs - 1);
+    const shouldWait = entry.ownerRefs === 0
+        && entry.active.size === 0
+        && !entry.mutationPending
+        && !entry.closing;
+    scheduleFinalRelease(entry);
+    return shouldWait;
+}
+function entryFor(ownership) {
+    const entry = ownershipEntries.get(ownership);
+    if (entry === undefined)
+        throw new Error("Agent-root ownership handle is invalid.");
+    return entry;
+}
+async function createEntry(canonicalRoot, options) {
+    try {
+        const home = resolve(options.homeDir ?? accountHomeDirectory());
+        const leaseRoot = await ensurePrivateLeaseRoot(home);
+        const digest = rootDigest(canonicalRoot);
+        const leasePath = agentRootLeasePath(canonicalRoot, home);
+        const pid = options.pid ?? process.pid;
+        const ownerlessGraceMs = options.ownerlessGraceMs ?? AGENT_ROOT_LEASE_OWNERLESS_GRACE_MS;
+        validateOwnerPrivateLockInputs("Agent-root lease", pid, ownerlessGraceMs);
+        const lease = await acquireOwnerPrivateLock({
+            path: leasePath,
+            label: "Agent-root lease",
+            schemaTag: AGENT_ROOT_LEASE_SCHEMA,
+            ownerlessGraceMs,
+            maxAcquireAttempts: AGENT_ROOT_LEASE_ACQUIRE_ATTEMPTS,
+            pid,
+            ...(options.now === undefined ? {} : { now: options.now }),
+            randomToken: options.randomToken ?? (() => randomUUID()),
+            ...(options.processIncarnation === undefined ? {} : { processIncarnation: options.processIncarnation }),
+            ...(options.isSameProcessIncarnation === undefined
+                ? {}
+                : { isSameProcessIncarnation: options.isSameProcessIncarnation }),
+            ownerFields: () => ({ rootDigest: digest }),
+            validateOwnerFields: (record) => record.rootDigest === digest,
+            invalidOwner: "error",
+            livenessError: () => "assume-live",
+            ...(options.hooks?.afterLeaseDirectoryCreated === undefined
+                ? {}
+                : { afterDirectoryCreated: options.hooks.afterLeaseDirectoryCreated }),
+            ...(options.hooks?.beforeStaleLeaseRename === undefined
+                ? {}
+                : { beforeStaleRename: options.hooks.beforeStaleLeaseRename }),
+            staleRace: "return",
+            stalePath: ({ now, pid: stalePid, token }) => join(leaseRoot, `.${digest}-${now}-${stalePid}-${token}.stale`),
+            releasedPath: ({ pid: ownerPid, token }) => join(leaseRoot, `.${digest}-${ownerPid}-${token}.released`),
+            abandonedPath: ({ pid: ownerPid, token }) => join(leaseRoot, `.${digest}-${ownerPid}-${token}.abandoned`),
+        });
+        if (lease === undefined)
+            throw new Error(AGENT_ROOT_OWNED_ELSEWHERE_ERROR);
+        let resolveClosed;
+        const closed = new Promise((resolveClosedPromise) => { resolveClosed = resolveClosedPromise; });
+        return {
+            agentRoot: canonicalRoot,
+            lease,
+            leasePath,
+            ...(options.hooks?.beforeLeaseRelease === undefined
+                ? {}
+                : { beforeLeaseRelease: options.hooks.beforeLeaseRelease }),
+            active: new Map(),
+            waiters: new Set(),
+            ownerRefs: 0,
+            mutationPending: false,
+            closing: false,
+            closed,
+            resolveClosed,
+        };
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === AGENT_ROOT_OWNED_ELSEWHERE_ERROR)
+            throw error;
+        throw new Error("Mono-agent could not establish private ownership of this agent root. Check the local owner and permissions, then retry.", { cause: error });
+    }
+}
+function scheduleFinalRelease(entry) {
+    if (entry.ownerRefs !== 0 || entry.active.size !== 0 || entry.mutationPending || entry.closing)
+        return;
+    entry.closing = true;
+    void (async () => {
+        try {
+            await entry.lease.release(entry.beforeLeaseRelease === undefined
+                ? undefined
+                : { beforeRename: entry.beforeLeaseRelease });
+            if (entries.get(entry.agentRoot) === entry)
+                entries.delete(entry.agentRoot);
+        }
+        catch (error) {
+            // The physical lock may be in an indeterminate release state. Keep this
+            // coordinator permanently closed so this process cannot loop or split
+            // into a second logical owner. Process restart is the recovery boundary.
+            entry.closeError = new Error("Mono-agent could not safely release ownership of this agent root. Restart the local process before retrying.", { cause: error });
+        }
+        finally {
+            entry.resolveClosed();
+        }
+    })();
+}
+function notifyWaiters(entry) {
+    for (const notify of [...entry.waiters])
+        notify();
+}
+async function waitUntil(entry, predicate, timeoutMs) {
+    if (predicate())
+        return;
+    await new Promise((resolvePromise, rejectPromise) => {
+        let timer;
+        const finish = () => {
+            if (!predicate())
+                return;
+            cleanup();
+            resolvePromise();
+        };
+        const cleanup = () => {
+            entry.waiters.delete(finish);
+            if (timer !== undefined)
+                clearTimeout(timer);
+        };
+        entry.waiters.add(finish);
+        if (timeoutMs !== undefined) {
+            timer = setTimeout(() => {
+                cleanup();
+                rejectPromise(new DrainTimeoutError());
+            }, timeoutMs);
+            timer.unref?.();
+        }
+        finish();
+    });
+}
+class DrainTimeoutError extends Error {
+}
+function hasIncompatibleLease(entry, currentGenerationId, requiredRootKey) {
+    for (const [generationId, active] of entry.active) {
+        if (active.count < 1)
+            continue;
+        if (generationId === currentGenerationId && active.roots.has(requiredRootKey))
+            continue;
+        if (!active.roots.has(requiredRootKey))
+            return true;
+    }
+    return false;
+}
+function assertGeneration(generation) {
+    if (generation.id.length === 0 || generation.rootKeys.some((root) => root.length === 0)) {
+        throw new TypeError("Agent-root protection generation is malformed.");
+    }
+    const sorted = [...new Set(generation.rootKeys)].sort();
+    if (!sameStringArrays(sorted, generation.rootKeys)) {
+        throw new TypeError("Agent-root protection roots must be unique and sorted.");
+    }
+}
+function frozenGeneration(generation) {
+    return Object.freeze({ id: generation.id, rootKeys: Object.freeze([...generation.rootKeys]) });
+}
+function sameGeneration(left, right) {
+    return left.id === right.id && sameStringArrays(left.rootKeys, right.rootKeys);
+}
+function sameRoots(left, right) {
+    return left.size === right.length && right.every((root) => left.has(root));
+}
+function sameStringArrays(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+async function canonicalAgentRoot(path) {
+    const canonical = await realpath(resolve(path));
+    const details = await lstat(canonical);
+    if (!details.isDirectory() || details.isSymbolicLink()) {
+        throw new Error("The agent root must be a real directory.");
+    }
+    assertOwned(details, "The agent root");
+    return canonical;
+}
+async function ensurePrivateLeaseRoot(home) {
+    const homeDetails = await lstat(home);
+    if (!homeDetails.isDirectory() || homeDetails.isSymbolicLink()) {
+        throw new Error("The effective-user home must be a real directory.");
+    }
+    assertOwned(homeDetails, "The effective-user home");
+    const managedRoot = join(home, ".mono-agent");
+    const leaseRoot = join(managedRoot, "agent-root-leases");
+    for (const path of [managedRoot, leaseRoot]) {
+        try {
+            await mkdir(path, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!isErrno(error, "EEXIST"))
+                throw error;
+        }
+        const before = await lstat(path);
+        if (!before.isDirectory() || before.isSymbolicLink()) {
+            throw new Error("The agent-root lease parent must be a real directory.");
+        }
+        assertOwned(before, "The agent-root lease parent");
+        await chmod(path, 0o700);
+        const after = await lstat(path);
+        if (before.dev !== after.dev || before.ino !== after.ino || (after.mode & 0o077) !== 0) {
+            throw new Error("The agent-root lease parent changed while it was secured.");
+        }
+        assertOwned(after, "The agent-root lease parent");
+    }
+    return leaseRoot;
+}
+function assertOwned(details, label) {
+    if (typeof process.getuid === "function" && details.uid !== process.getuid()) {
+        throw new Error(`${label} is not owned by the current user.`);
+    }
+}
+function containsPath(parent, child) {
+    const fromParent = relative(parent, child);
+    return fromParent === "" || (!fromParent.startsWith("..") && !isAbsolutePath(fromParent));
+}
+function rootDigest(canonicalRoot) {
+    return createHash("sha256").update(resolve(canonicalRoot)).digest("hex");
+}
+function isAbsolutePath(path) {
+    return resolve(path) === path;
+}
+function isErrno(error, code) {
+    return typeof error === "object" && error !== null && error.code === code;
+}
+//# sourceMappingURL=agent-root-coordinator.js.map

package/dist/agent-root-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-root-coordinator.js","sourceRoot":"","sources":["../src/agent-root-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/app-controller-channels.d.ts

@@ -1,11 +1,12 @@
 import type { MonoAgentConfig } from "@mono-agent/config";
-import type { AgentResponder } from "@mono-agent/agent-contracts";
+import type { AgentResponder, NotifyDeliveryContext } from "@mono-agent/agent-contracts";
 import type { ChannelDriver, ChannelId, MonoAgentAppLogger, RunningChannel, ChannelStatus } from "./channels.js";
 import type { ConfigApplyResult, TraceabilityStatus } from "./app-controller-types.js";
 import type { InteractionBridgeHandle } from "./interaction-bridge.js";
 import type { ContinuationServiceHandle } from "./continuation-service.js";
 import type { NotifyDeliveryResult } from "./proactive-notify.js";
 import type { NotifyDestination } from "./notify-destinations.js";
+import type { ProcessJobsServiceHandle } from "./process-jobs-service.js";
 export interface ChannelsControllerPort {
     readonly env: Record<string, string | undefined>;
     readonly cwd: string;
@@ -15,8 +16,15 @@ export interface ChannelsControllerPort {
     readonly driversById: ReadonlyMap<ChannelId, ChannelDriver>;
     readonly statuses: Map<ChannelId, ChannelStatus>;
     readonly running: Map<ChannelId, RunningChannel>;
+    readonly channelStartGenerations: Map<ChannelId, symbol>;
+    readonly startsInFlight: Map<ChannelId, Promise<ChannelStatus>>;
     readonly stopped: boolean;
     readonly traceabilityStatusValue: TraceabilityStatus;
+    readonly processJobsService: ProcessJobsServiceHandle | undefined;
+    readonly processJobsDegradation: {
+        readonly stateDir: string;
+        readonly reason: string;
+    } | undefined;
     setStatus(id: ChannelId, status: ChannelStatus): ChannelStatus;
     rememberSelectedSkills(coreConfig: MonoAgentConfig): void;
     ensureInteractionBridge(coreConfig: MonoAgentConfig): Promise<InteractionBridgeHandle | undefined>;
@@ -25,6 +33,7 @@ export interface ChannelsControllerPort {
     notifyDestination(conversationId: string, text: string, options?: {
         readonly verbatim?: boolean;
         readonly deliveryKey?: string;
+        readonly deliveryContext?: NotifyDeliveryContext;
     }): Promise<NotifyDeliveryResult>;
     listNotifyDestinations(): Promise<readonly NotifyDestination[]>;
     observabilityContext(): Promise<{
@@ -32,6 +41,7 @@ export interface ChannelsControllerPort {
         readonly sourceLabel?: string;
         readonly configPath?: string;
     }>;
+    refreshTraceSource(reason: string): Promise<void>;
     activeTransports(): readonly string[];
 }
 export declare function startChannel(controller: ChannelsControllerPort, driver: ChannelDriver, reason: string): Promise<ChannelStatus>;