@mono-agent/agent-app 0.20.11 → 0.21.0

package/dist/monitors-context.js

@@ -0,0 +1,194 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { classifyNotifySuppression, } from "@mono-agent/agent-contracts";
+import { runWithProcessJobWakeContext } from "./process-jobs-context.js";
+const wakeContext = new AsyncLocalStorage();
+/**
+ * Monitor wakes reuse the process-job delivery-key metadata symbol because the
+ * adapters already carry that exact non-JSON key through their queued proactive
+ * turns. The key VALUE namespaces the two: a monitor delivery key is always
+ * `monitor:<id>:<seq>`, so a lookup here can never resolve a job's flight.
+ */
+const HOST_WAKE_DELIVERY_METADATA = Symbol.for("mono-agent.process-job-wake.delivery-key.v1");
+const wakeContextByRequestMetadata = new WeakMap();
+const wakeFlightsByDeliveryKey = new Map();
+/**
+ * Wakes whose turn ran and deliberately said nothing.
+ *
+ * Adapters classify an empty answer as "not delivered", which is right for a
+ * proactive notification but wrong for a monitor: the batch WAS consumed, the
+ * model simply had nothing worth saying. Without this the host would count a
+ * successful silent turn as a lost batch and report a gap that never happened.
+ */
+const silentWakeDeliveryKeys = new Set();
+const MAX_SILENT_WAKE_KEYS = 512;
+/**
+ * Run a genuine channel turn as a monitor wake.
+ *
+ * This nests INSIDE the process-job wake context on purpose. Both features raise
+ * host-owned turns on the same conversation, and the steering registry admits
+ * exactly one active run per conversation: a second, parallel registration would
+ * make every steer ambiguous and silently downgrade process-job wakes to a
+ * follow-up turn. Sharing it also means a monitor wake inherits the same
+ * targeted-run steering and the same unforgeable chain-depth increment, so a
+ * monitor started from a wake turn cannot escape `maxChainDepth`.
+ */
+export async function runWithMonitorWakeContext(context, operation, deliveryKey) {
+    const flight = Object.freeze({ ...context, token: Object.freeze({}), deliveryKey });
+    const current = wakeFlightsByDeliveryKey.get(deliveryKey) ?? [];
+    wakeFlightsByDeliveryKey.set(deliveryKey, [...current, flight]);
+    try {
+        return await wakeContext.run(flight, async () => await runWithProcessJobWakeContext({ jobId: context.monitorId, chainDepth: context.chainDepth }, operation, deliveryKey));
+    }
+    finally {
+        const active = wakeFlightsByDeliveryKey.get(deliveryKey) ?? [];
+        const remaining = active.filter((candidate) => candidate.token !== flight.token);
+        if (remaining.length === 0)
+            wakeFlightsByDeliveryKey.delete(deliveryKey);
+        else
+            wakeFlightsByDeliveryKey.set(deliveryKey, remaining);
+    }
+}
+/**
+ * Capture an admitted monitor wake on the request identity that survives the
+ * responder-to-harness queue boundary, and suppress a sentinel-only answer.
+ *
+ * The suppression is the point of this wrapper. A monitor raises turns nobody
+ * asked for, so it must be able to conclude "nothing worth saying" without
+ * posting anything — but `NOTHING_TO_REPORT` is only honoured by the native
+ * cron/webhook notify path, which a channel wake turn does not go through.
+ * Blanking the answer here makes the adapters' existing "agent produced no
+ * answer" path do the suppressing, without teaching any adapter about monitors.
+ */
+export function bindMonitorWakeContextToResponder(responder, options = {}) {
+    const dispose = responder.dispose;
+    const startNewSession = responder.startNewSession;
+    return {
+        respond: async (request, stream) => {
+            const ambient = wakeContext.getStore();
+            const deliveryKey = monitorWakeDeliveryKey(request.metadata);
+            const flights = deliveryKey === undefined ? [] : wakeFlightsByDeliveryKey.get(deliveryKey) ?? [];
+            // HTTP callbacks reconstruct the host-only symbol outside AsyncLocalStorage.
+            // A key is authority only while exactly one registered flight owns it.
+            const context = deliveryKey === undefined
+                ? ambient
+                : flights.length === 1 ? flights[0] : undefined;
+            let installed;
+            if (context !== undefined) {
+                if (request.metadata === undefined) {
+                    throw new Error("A monitor wake request is missing its host-owned request identity.");
+                }
+                installed = { token: Object.freeze({}), flight: context };
+                const current = wakeContextByRequestMetadata.get(request.metadata) ?? [];
+                wakeContextByRequestMetadata.set(request.metadata, [...current, installed]);
+            }
+            try {
+                const response = await responder.respond(request, stream);
+                return context === undefined
+                    ? response
+                    : suppressSilentMonitorReply(response, context, options.logger);
+            }
+            finally {
+                if (installed !== undefined && request.metadata !== undefined) {
+                    const current = wakeContextByRequestMetadata.get(request.metadata) ?? [];
+                    const remaining = current.filter((candidate) => candidate.token !== installed.token);
+                    if (remaining.length === 0)
+                        wakeContextByRequestMetadata.delete(request.metadata);
+                    else
+                        wakeContextByRequestMetadata.set(request.metadata, remaining);
+                }
+            }
+        },
+        ...(responder.cancel === undefined ? {} : { cancel: responder.cancel.bind(responder) }),
+        ...(responder.liveInputOwnership === undefined ? {} : { liveInputOwnership: responder.liveInputOwnership }),
+        ...(responder.offerLiveInput === undefined
+            ? {}
+            : { offerLiveInput: (request) => responder.offerLiveInput(request) }),
+        ...(responder.deliverVerbatim === undefined
+            ? {}
+            : { deliverVerbatim: responder.deliverVerbatim.bind(responder) }),
+        ...(responder.importContext === undefined
+            ? {}
+            : { importContext: responder.importContext.bind(responder) }),
+        ...(responder.openReplyArtifact === undefined
+            ? {}
+            : { openReplyArtifact: responder.openReplyArtifact.bind(responder) }),
+        ...(responder.loadMcpApp === undefined ? {} : { loadMcpApp: responder.loadMcpApp.bind(responder) }),
+        ...(responder.requestMcpApp === undefined ? {} : { requestMcpApp: responder.requestMcpApp.bind(responder) }),
+        ...(startNewSession === undefined
+            ? {}
+            : { startNewSession: (conversationId) => startNewSession.call(responder, conversationId) }),
+        ...(dispose === undefined ? {} : { dispose: dispose.bind(responder) }),
+    };
+}
+/**
+ * Blank a monitor wake answer that ends with the sentinel. Attachments are
+ * dropped with it: a turn that decided it has nothing to say must not still post
+ * files. A `narrated-sentinel` is honoured but logged, exactly as the native
+ * notify path does, because it means the model wrote prose before the marker.
+ */
+export function suppressSilentMonitorReply(response, context, logger) {
+    const suppression = classifyNotifySuppression(response.text);
+    if (suppression === "none" || suppression === "empty")
+        return response;
+    if (suppression === "narrated-sentinel") {
+        logger?.warn?.("Monitor wake reply suppressed: the final answer ended with the NOTHING_TO_REPORT sentinel but was not the sentinel alone.", { monitorId: context.monitorId });
+    }
+    markSilentMonitorWake(context.deliveryKey);
+    const { text: _text, parts: _parts, ...rest } = response;
+    return { ...rest, text: "" };
+}
+function markSilentMonitorWake(deliveryKey) {
+    if (deliveryKey === undefined)
+        return;
+    // Bounded: a key is consumed by the settling wake, and this cap keeps a
+    // pathological run from retaining keys nobody will ever read.
+    if (silentWakeDeliveryKeys.size >= MAX_SILENT_WAKE_KEYS) {
+        const oldest = silentWakeDeliveryKeys.values().next().value;
+        if (oldest !== undefined)
+            silentWakeDeliveryKeys.delete(oldest);
+    }
+    silentWakeDeliveryKeys.add(deliveryKey);
+}
+/**
+ * Whether this wake's turn ran and chose silence. Consumed once: the settling
+ * wake is the only reader, and a stale key must not make a later batch look
+ * delivered.
+ */
+export function consumeSilentMonitorWake(deliveryKey) {
+    return silentWakeDeliveryKeys.delete(deliveryKey);
+}
+/** Resolve only an association previously issued by this app-owned seam. */
+export function monitorWakeContextForRequest(request) {
+    const bindings = request.metadata === undefined
+        ? []
+        : wakeContextByRequestMetadata.get(request.metadata) ?? [];
+    if (bindings.length > 0)
+        return resolveFlights(bindings.map((binding) => binding.flight));
+    const deliveryKey = monitorWakeDeliveryKey(request.metadata);
+    if (deliveryKey === undefined)
+        return { kind: "none" };
+    const flights = wakeFlightsByDeliveryKey.get(deliveryKey) ?? [];
+    // A host-marked wake cannot regain ordinary depth-zero capabilities after expiry.
+    if (flights.length === 0)
+        return { kind: "missed" };
+    return resolveFlights(flights);
+}
+function monitorWakeDeliveryKey(metadata) {
+    if (metadata === undefined)
+        return undefined;
+    try {
+        const descriptor = Object.getOwnPropertyDescriptor(metadata, HOST_WAKE_DELIVERY_METADATA);
+        const value = descriptor !== undefined && "value" in descriptor ? descriptor.value : undefined;
+        return typeof value === "string" && value.startsWith("monitor:") ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveFlights(flights) {
+    const distinct = [...new Map(flights.map((flight) => [flight.token, flight])).values()];
+    return distinct.length === 1
+        ? { kind: "resolved", context: Object.freeze({ monitorId: distinct[0].monitorId, chainDepth: distinct[0].chainDepth }) }
+        : { kind: "missed" };
+}
+//# sourceMappingURL=monitors-context.js.map

package/dist/monitors-context.js.map

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

package/dist/monitors-runtime.d.ts

@@ -0,0 +1,36 @@
+import type { AgentHarnessRuntimeOptionsInput } from "@mono-agent/agent-harness";
+import type { MonoAgentConfig } from "@mono-agent/config";
+import type { ChannelId } from "./channels.js";
+import type { MonitorsServiceHandle } from "./monitors-service.js";
+import type { ProcessJobOriginRecord } from "./process-jobs-store.js";
+import type { RuntimeOptionsExtension } from "./runtime-option-extensions.js";
+/** Channel schemes whose adapters can deliver a monitor wake to an exact conversation. */
+export declare const MONITOR_WAKE_CAPABLE_SCHEMES: ReadonlySet<string>;
+export interface MonitorsRuntimeExtensionOptions {
+    readonly next?: RuntimeOptionsExtension;
+    /** Optional because monitors stay unavailable when their service cannot open. */
+    readonly service: MonitorsServiceHandle | undefined;
+    readonly coreConfig: MonoAgentConfig;
+    readonly channelId: ChannelId | undefined;
+    readonly conversationScheme?: string | undefined;
+    readonly routesOnlyPiNative?: (metadata: Record<string, unknown> | undefined) => boolean;
+}
+/** Inject the monitor controller only for a Pi-native, wake-capable, allowed turn. */
+export declare function createMonitorsRuntimeExtension(options: MonitorsRuntimeExtensionOptions): RuntimeOptionsExtension;
+/** Strict host-origin classifier narrowed to schemes that can deliver a wake. */
+export declare function monitorOriginForRequest(input: Pick<AgentHarnessRuntimeOptionsInput, "request" | "runId">, channelId: ChannelId | undefined, conversationScheme?: string): ProcessJobOriginRecord | undefined;
+export interface MonitorsAvailabilityOptions {
+    readonly service: MonitorsServiceHandle | undefined;
+    readonly coreConfig: MonoAgentConfig;
+    readonly channelId: ChannelId | undefined;
+    readonly conversationScheme?: string | undefined;
+    readonly routesOnlyPiNative?: (metadata: Record<string, unknown> | undefined) => boolean;
+}
+/**
+ * The same gate the extension applies, minus the checks that only exist once a
+ * run is under way. Exported so prompt guidance and tool availability are
+ * decided by one predicate; it errs strict, because telling the model it can
+ * watch something it cannot is the worse failure.
+ */
+export declare function monitorsAvailableForRequest(input: Pick<AgentHarnessRuntimeOptionsInput, "request" | "runId">, options: MonitorsAvailabilityOptions): boolean;
+//# sourceMappingURL=monitors-runtime.d.ts.map

package/dist/monitors-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"monitors-runtime.d.ts","sourceRoot":"","sources":["../src/monitors-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,2BAA2B,CAAC;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AASnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AAE9E,0FAA0F;AAC1F,eAAO,MAAM,4BAA4B,EAAE,WAAW,CAAC,MAAM,CAAyC,CAAC;AAEvG,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,CAAC,EAAE,uBAAuB,CAAC;IACxC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAK,OAAO,CAAC;CAC1F;AAED,sFAAsF;AACtF,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,uBAAuB,CAiDzB;AAED,iFAAiF;AACjF,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,IAAI,CAAC,+BAA+B,EAAE,SAAS,GAAG,OAAO,CAAC,EACjE,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,kBAAkB,CAAC,EAAE,MAAM,GAC1B,sBAAsB,GAAG,SAAS,CAGpC;AAyBD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAK,OAAO,CAAC;CAC1F;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,IAAI,CAAC,+BAA+B,EAAE,SAAS,GAAG,OAAO,CAAC,EACjE,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAYT"}

package/dist/monitors-runtime.js

@@ -0,0 +1,103 @@
+import { monitorWakeContextForRequest } from "./monitors-context.js";
+import { processJobOriginForRequest, PROCESS_JOBS_PI_NATIVE_REQUIRED_ERROR, } from "./process-jobs-runtime.js";
+import { processJobSteeringDepth, processJobWakeContextForRequest, } from "./process-jobs-context.js";
+/** Channel schemes whose adapters can deliver a monitor wake to an exact conversation. */
+export const MONITOR_WAKE_CAPABLE_SCHEMES = new Set(["telegram", "slack", "web"]);
+/** Inject the monitor controller only for a Pi-native, wake-capable, allowed turn. */
+export function createMonitorsRuntimeExtension(options) {
+    return async (input) => {
+        let result;
+        try {
+            if (options.service !== undefined
+                && options.routesOnlyPiNative !== undefined
+                && !options.routesOnlyPiNative(input.request.metadata)) {
+                throw new Error(`${PROCESS_JOBS_PI_NATIVE_REQUIRED_ERROR} Not every route reachable for this request is Pi-native.`);
+            }
+            result = options.next === undefined
+                ? { runtimeOptions: {}, cleanup: async () => { } }
+                : await options.next(input);
+            let runtimeOptions = result.runtimeOptions ?? {};
+            const service = options.service;
+            if (service !== undefined) {
+                const origin = monitorOriginForRequest(input, options.channelId, options.conversationScheme);
+                // Chain depth comes from whichever host wake raised this turn. Monitor
+                // wakes nest inside the process-job wake context, so both resolvers see
+                // the same flight and the depth cannot be forged from either side.
+                const monitorWake = monitorWakeContextForRequest(input.request);
+                const hostWake = processJobWakeContextForRequest(input.request);
+                const missed = monitorWake.kind === "missed" || hostWake.kind === "missed";
+                const chainDepth = Math.max(monitorWake.kind === "resolved" ? monitorWake.context.chainDepth : 0, hostWake.kind === "resolved" ? hostWake.context.chainDepth : 0);
+                // The steering target is registered ONCE per run, by the process-jobs
+                // extension. Registering a second one here would make the conversation's
+                // active run ambiguous and silently break process-job steering, because
+                // that registry admits a steer only when exactly one candidate matches.
+                if (monitorsAdmissible(origin, missed, chainDepth, service, options.coreConfig)) {
+                    runtimeOptions = {
+                        ...runtimeOptions,
+                        monitors: service.controller(origin, () => steeringDepth(origin, chainDepth)),
+                    };
+                }
+            }
+            return { ...result, runtimeOptions };
+        }
+        catch (error) {
+            try {
+                await result?.cleanup?.();
+            }
+            finally {
+                await result?.settleCleanup?.();
+            }
+            throw error;
+        }
+    };
+}
+/** Strict host-origin classifier narrowed to schemes that can deliver a wake. */
+export function monitorOriginForRequest(input, channelId, conversationScheme) {
+    const origin = processJobOriginForRequest(input, channelId, conversationScheme);
+    return origin !== undefined && MONITOR_WAKE_CAPABLE_SCHEMES.has(origin.channel) ? origin : undefined;
+}
+function monitorsAdmissible(origin, missedWake, chainDepth, service, coreConfig) {
+    return origin !== undefined
+        && !missedWake
+        && service !== undefined
+        && chainDepth < service.settings.maxChainDepth
+        && hasAllowedMonitorTools(coreConfig);
+}
+/**
+ * Read the live depth from the shared steering registration when this run has
+ * one, so a monitor started after a wake was steered into this very turn still
+ * sees the raised depth rather than the depth the run began with.
+ */
+function steeringDepth(origin, fallback) {
+    return Math.max(fallback, processJobSteeringDepth(origin.baseConversationId) ?? fallback);
+}
+/**
+ * The same gate the extension applies, minus the checks that only exist once a
+ * run is under way. Exported so prompt guidance and tool availability are
+ * decided by one predicate; it errs strict, because telling the model it can
+ * watch something it cannot is the worse failure.
+ */
+export function monitorsAvailableForRequest(input, options) {
+    if (options.service === undefined)
+        return false;
+    if (options.routesOnlyPiNative?.(input.request.metadata) === false)
+        return false;
+    const origin = monitorOriginForRequest(input, options.channelId, options.conversationScheme);
+    const monitorWake = monitorWakeContextForRequest(input.request);
+    const hostWake = processJobWakeContextForRequest(input.request);
+    const missed = monitorWake.kind === "missed" || hostWake.kind === "missed";
+    const chainDepth = Math.max(monitorWake.kind === "resolved" ? monitorWake.context.chainDepth : 0, hostWake.kind === "resolved" ? hostWake.context.chainDepth : 0);
+    return monitorsAdmissible(origin, missed, chainDepth, options.service, options.coreConfig);
+}
+/**
+ * Both names must be reachable. A Monitor the model cannot stop is a capacity
+ * leak it has no way to repair, so denying MonitorStop denies Monitor too.
+ */
+function hasAllowedMonitorTools(config) {
+    const allowed = config.tools.allowedTools;
+    const denied = new Set(config.tools.disallowedTools.map((name) => name.toLowerCase()));
+    const allowAll = allowed.some((name) => name === "*");
+    return ["Monitor", "MonitorStop"].every((name) => !denied.has(name.toLowerCase())
+        && (allowAll || allowed.some((allowedName) => allowedName.toLowerCase() === name.toLowerCase())));
+}
+//# sourceMappingURL=monitors-runtime.js.map

package/dist/monitors-runtime.js.map

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

package/dist/monitors-service.d.ts

@@ -0,0 +1,71 @@
+import { type MonitorErrorCode, type MonitorProjection, type HostWakeDeliveryResult } from "@mono-agent/agent-contracts";
+import type { MonitorsController } from "@mono-agent/runtime-adapter";
+import { type OwnerPrivateLock } from "./owner-private-lock.js";
+import { type MonitorsSettings } from "./monitors-config.js";
+import { writeMonitorStore } from "./monitors-store.js";
+import { isSameProcessIncarnation, readProcessIncarnation, type ProcessIncarnation } from "./process-incarnation.js";
+import type { ProcessJobOriginRecord } from "./process-jobs-store.js";
+export declare class MonitorServiceError extends Error {
+    readonly code: MonitorErrorCode;
+    constructor(code: MonitorErrorCode);
+}
+export interface MonitorWakeInput {
+    readonly projection: MonitorProjection;
+    readonly prompt: string;
+    readonly conversationId: string;
+    readonly deliveryKey: string;
+    readonly chainDepth: number;
+}
+export interface OpenMonitorsServiceOptions {
+    /** The already-prepared, protected process-job private-state root. */
+    readonly stateDir: string;
+    readonly settings: MonitorsSettings;
+    readonly wake: (input: MonitorWakeInput) => Promise<HostWakeDeliveryResult>;
+    readonly logger?: {
+        info?(message: string, details?: Readonly<Record<string, unknown>>): void;
+        warn?(message: string, details?: Readonly<Record<string, unknown>>): void;
+    };
+    readonly now?: () => Date;
+    readonly platform?: NodeJS.Platform;
+    readonly randomId?: () => string;
+    readonly currentIncarnation?: () => Promise<ProcessIncarnation>;
+    readonly readIncarnation?: typeof readProcessIncarnation;
+    readonly sameIncarnation?: typeof isSameProcessIncarnation;
+    readonly signalProcess?: (pid: number, signal: NodeJS.Signals) => void;
+    readonly processGroupExists?: (pgid: number) => boolean;
+    readonly sleep?: (milliseconds: number) => Promise<void>;
+    readonly wakeRearmMs?: number;
+    /** Bounded wait for watchers and wakes at shutdown; a test seam, not a knob. */
+    readonly shutdownGraceMs?: number;
+    /** Test seam for blocking one durable write at an exact lifecycle boundary. */
+    readonly writeStore?: typeof writeMonitorStore;
+    /** Test seam for pausing inside the serialized wake-admission boundary. */
+    readonly beforeWakePreparation?: () => Promise<void>;
+    readonly acquireLock?: () => Promise<OwnerPrivateLock | undefined>;
+    readonly operatorSecret?: () => Promise<Uint8Array>;
+}
+export interface MonitorsServiceHandle {
+    readonly settings: MonitorsSettings;
+    /** The protected state root this service actually opened. */
+    readonly stateDir: string;
+    readonly operatorToken: string;
+    controller(origin: ProcessJobOriginRecord, chainDepth: number | (() => number)): MonitorsController;
+    list(): Promise<readonly MonitorProjection[]>;
+    get(monitorId: string): Promise<MonitorProjection | undefined>;
+    cancel(monitorId: string): Promise<MonitorProjection>;
+    activateWakes(): Promise<void>;
+    stop(): Promise<void>;
+}
+/** Acquire exclusive ownership, recover interrupted watches, and expose one controller. */
+export declare function openMonitorsService(options: OpenMonitorsServiceOptions): Promise<MonitorsServiceHandle>;
+/**
+ * The envelope has three jobs the model routinely gets wrong without it: this is
+ * not a user message, the fenced text is data and not instruction, and a batch
+ * that changes nothing should end the turn silently rather than posting noise.
+ */
+export declare function monitorWakePrompt(projection: MonitorProjection, payload: {
+    readonly lines: readonly string[];
+    readonly terminal: boolean;
+    readonly stderrTail: string;
+}): string;
+//# sourceMappingURL=monitors-service.d.ts.map

package/dist/monitors-service.d.ts.map

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