@mono-agent/agent-app 0.20.11 → 0.21.0

package/dist/monitors-command.js

@@ -0,0 +1,217 @@
+import { isAbsolute, resolve } from "node:path";
+import { isLoopbackHost, parseMonitorProjection, parseMonitorProjections, } from "@mono-agent/agent-contracts";
+import { listTraceSources } from "@mono-agent/observability";
+import { readBoundedOwnerOnlyFile } from "./continuation-store-fs.js";
+import { discoverJobsSource } from "./jobs-command.js";
+import { monitorOperatorToken } from "./monitors-store.js";
+import { PROCESS_JOB_SECRET_FILE } from "./process-jobs-store.js";
+import { tuiEndpointOf } from "./tui-command.js";
+/** Monitor projections carry no output, so a live agent's whole list stays small. */
+const MAX_MONITORS_RESPONSE_BYTES = 1024 * 1024;
+/**
+ * Authenticated, loopback-only monitor operator client for one live agent.
+ *
+ * Deliberately a separate command rather than a `--kind` flag on `jobs`: a
+ * monitor and a background job share a state root but nothing else — different
+ * states, different counters, different bearer — and one command that renders
+ * two unrelated projections reads worse than two that each render one.
+ */
+export async function runMonitorsCommand(options) {
+    const stdout = options.stdout ?? ((text) => process.stdout.write(text));
+    const stderr = options.stderr ?? ((text) => process.stderr.write(text));
+    const [action = "list", monitorId, ...extra] = options.positionals;
+    if (extra.length > 0 || !validUsage(action, monitorId)) {
+        stderr("Usage: mono-agent monitors [list|get <monitor-id>|cancel <monitor-id>] [--agent <label|sourceId>] [--json]\n");
+        return 2;
+    }
+    let source;
+    try {
+        source = await discoverJobsSource(options);
+    }
+    catch (error) {
+        return writeFailure(stderr, options.json === true, codeOf(error) ?? "agent_unreachable", reasonOf(error));
+    }
+    const baseUrlValue = tuiEndpointOf(source);
+    if (baseUrlValue === undefined) {
+        return writeFailure(stderr, options.json === true, "agent_unreachable", "The selected agent has no running operator endpoint.");
+    }
+    let baseUrl;
+    try {
+        baseUrl = new URL(baseUrlValue);
+    }
+    catch {
+        return writeFailure(stderr, options.json === true, "agent_unreachable", "The selected agent advertised an invalid operator endpoint.");
+    }
+    if ((baseUrl.protocol !== "http:" && baseUrl.protocol !== "https:")
+        || !isLoopbackHost(baseUrl.hostname)
+        || baseUrl.username.length > 0
+        || baseUrl.password.length > 0) {
+        return writeFailure(stderr, options.json === true, "remote_refused", "Monitor operator commands refuse non-loopback endpoints.");
+    }
+    let token;
+    try {
+        const stateDir = monitorStateDir(source);
+        if (stateDir === undefined) {
+            throw coded("monitor_disabled", "The selected live agent has no monitor controller.");
+        }
+        token = monitorOperatorToken(await readOwnerSecret(resolve(stateDir, PROCESS_JOB_SECRET_FILE)));
+    }
+    catch (error) {
+        return writeFailure(stderr, options.json === true, codeOf(error) ?? "agent_unreachable", `Monitor operator credentials are unavailable: ${reasonOf(error)}`);
+    }
+    let response;
+    try {
+        response = await request(options.fetchImpl ?? fetch, baseUrl.toString().replace(/\/$/u, ""), token, action, monitorId);
+    }
+    catch (error) {
+        return writeFailure(stderr, options.json === true, "agent_unreachable", `Agent is unreachable: ${reasonOf(error)}`);
+    }
+    let body;
+    try {
+        body = await readBoundedJson(response);
+    }
+    catch (error) {
+        return writeFailure(stderr, options.json === true, codeOf(error) ?? "monitor_invalid", `Agent returned an invalid monitor response: ${reasonOf(error)}`);
+    }
+    if (!response.ok) {
+        return writeFailure(stderr, options.json === true, errorCode(body) ?? "monitor_invalid", errorMessage(body, response.status));
+    }
+    try {
+        const result = action === "list"
+            ? { monitors: parseMonitorProjections(recordOf(body)?.monitors) }
+            : parseMonitorProjection(body);
+        stdout(options.json === true ? `${JSON.stringify(result, null, 2)}\n` : renderHuman(action, result));
+        return 0;
+    }
+    catch (error) {
+        return writeFailure(stderr, options.json === true, "monitor_invalid", `Agent returned an invalid monitor projection: ${reasonOf(error)}`);
+    }
+}
+async function request(fetchImpl, baseUrl, token, action, monitorId) {
+    const headers = { authorization: `Bearer ${token}` };
+    if (action === "list")
+        return await fetchImpl(`${baseUrl}/v1/monitors`, { headers, redirect: "error" });
+    const path = `${baseUrl}/v1/monitors/${encodeURIComponent(monitorId)}`;
+    return await fetchImpl(action === "cancel" ? `${path}/cancel` : path, {
+        ...(action === "cancel" ? { method: "POST" } : {}),
+        headers,
+        redirect: "error",
+    });
+}
+function validUsage(action, monitorId) {
+    return action === "list"
+        ? monitorId === undefined
+        : (action === "get" || action === "cancel")
+            && monitorId !== undefined
+            && monitorId.trim().length > 0
+            && monitorId.length <= 256;
+}
+async function readBoundedJson(response) {
+    if (response.body === null)
+        throw coded("monitor_invalid", "response body is empty");
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > MAX_MONITORS_RESPONSE_BYTES) {
+                throw coded("monitor_response_too_large", `response exceeds ${String(MAX_MONITORS_RESPONSE_BYTES)} bytes`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+    return JSON.parse(Buffer.concat(chunks.map((chunk) => Buffer.from(chunk)), total).toString("utf8"));
+}
+function renderHuman(action, result) {
+    if (action !== "list") {
+        const monitor = result;
+        return [
+            `${monitor.monitorId}: ${monitor.state}${monitor.persistent ? " (persistent)" : ""} ${monitor.description}`,
+            `Wake policy: ${monitor.limits.wakeOn}, dedupe ${monitor.limits.dedupe}, minimum interval ${String(monitor.limits.minWakeIntervalMs)} ms`,
+            `Suppressed: ${String(monitor.counters.batchesSuppressed)} batches / ${String(monitor.counters.linesSuppressed)} lines`,
+            `Wakes: ${String(monitor.counters.followUpWakes)} follow-up / ${String(monitor.counters.steeredWakes)} steered / ${String(monitor.counters.unknownDispositionWakes)} unknown disposition`,
+            "",
+        ].join("\n");
+    }
+    const monitors = result.monitors;
+    if (monitors.length === 0)
+        return "No monitors recorded.\n";
+    return [
+        "MONITOR                              STATE        SEQ   DROPPED  SUPPRESSED  FOLLOW-UP STEERED UNKNOWN  STARTED                  DESCRIPTION",
+        ...monitors.map((monitor) => [
+            monitor.monitorId.padEnd(36),
+            monitor.state.padEnd(12),
+            String(monitor.counters.seq).padEnd(5),
+            String(monitor.counters.droppedLines).padEnd(8),
+            String(monitor.counters.linesSuppressed).padEnd(11),
+            String(monitor.counters.followUpWakes).padEnd(9),
+            String(monitor.counters.steeredWakes).padEnd(7),
+            String(monitor.counters.unknownDispositionWakes).padEnd(8),
+            monitor.timestamps.startedAt.padEnd(24),
+            monitor.description,
+        ].join(" ")),
+        "",
+    ].join("\n");
+}
+async function readOwnerSecret(path) {
+    const encoded = (await readBoundedOwnerOnlyFile(path, 256, "Monitor operator secret")).trim();
+    const secret = Buffer.from(encoded, "base64url");
+    if (secret.length !== 32 || secret.toString("base64url") !== encoded) {
+        throw new Error("secret contents are invalid");
+    }
+    return secret;
+}
+/**
+ * Monitors share the process-job protected state root, so the live agent
+ * advertises exactly one state directory and both operator surfaces read the
+ * same owner-private secret file under different HMAC labels.
+ */
+function monitorStateDir(source) {
+    const channels = recordOf(source.metadata?.channels);
+    const tui = recordOf(channels?.tui);
+    const monitors = recordOf(tui?.monitors);
+    if (monitors === undefined || tui?.kind !== "running")
+        return undefined;
+    // The monitor service publishes the root it actually opened. Falling back to
+    // the process-job entry keeps an older live agent readable, but a monitor
+    // controller that is up while process-job publication is degraded must still
+    // be operable.
+    const value = monitors.stateDir ?? recordOf(tui.processJobs)?.stateDir;
+    return typeof value === "string" && isAbsolute(value) && value.length <= 16_384
+        ? resolve(value)
+        : undefined;
+}
+function writeFailure(stderr, json, code, message) {
+    stderr(json ? `${JSON.stringify({ error: { code, message } })}\n` : `${code}: ${message}\n`);
+    return 1;
+}
+function coded(code, message) {
+    return Object.assign(new Error(message), { code });
+}
+function codeOf(error) {
+    return typeof error === "object" && error !== null && typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
+function reasonOf(error) { return error instanceof Error ? error.message : String(error); }
+function recordOf(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function errorCode(value) {
+    const error = recordOf(recordOf(value)?.error);
+    return typeof error?.code === "string" ? error.code : undefined;
+}
+function errorMessage(value, status) {
+    const error = recordOf(recordOf(value)?.error);
+    return typeof error?.message === "string" ? error.message : `HTTP ${String(status)}`;
+}
+//# sourceMappingURL=monitors-command.js.map

package/dist/monitors-command.js.map

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

package/dist/monitors-config.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Host-only `monitors` configuration.
+ *
+ * Monitors are a STREAMING class of the background process-job substrate: they
+ * reuse its protected private-state root, its registration proof, its sandbox
+ * protection, and its origin binding, and therefore require
+ * `processJobs.enabled`. What they do not share is capacity — a persistent watch
+ * that held an ordinary background slot would starve real background work — so
+ * every limit below is counted independently of `processJobs.*`.
+ */
+export declare const MONITORS_DEFAULTS: Readonly<{
+    enabled: false;
+    maxActive: 8;
+    maxActivePerConversation: 2;
+    /** Ceiling for a timed monitor; `timeout_ms` may lower it, never raise it. */
+    maxRuntimeMs: number;
+    /** Ceiling for a `persistent: true` monitor. */
+    persistentMaxRuntimeMs: number;
+    /** Stdout lines produced within this window are delivered as one batch. */
+    coalesceMs: 200;
+    maxWakeIntervalMs: 300000;
+    maxBatchLines: 200;
+    maxBatchBytes: number;
+    maxLineBytes: number;
+    maxChainDepth: 4;
+    rateLimit: Readonly<{
+        windowMs: 1000;
+        maxLinesPerWindow: 200;
+        sustainedWindows: 5;
+    }>;
+}>;
+export declare const MONITORS_CAPS: Readonly<{
+    maxActive: 32;
+    maxActivePerConversation: 8;
+    maxRuntimeMs: number;
+    persistentMaxRuntimeMs: number;
+    coalesceMs: 5000;
+    maxWakeIntervalMs: 300000;
+    maxBatchLines: 2000;
+    maxBatchBytes: number;
+    maxLineBytes: number;
+    maxChainDepth: 64;
+    rateLimit: Readonly<{
+        windowMs: 60000;
+        maxLinesPerWindow: 20000;
+        sustainedWindows: 60;
+    }>;
+}>;
+/** Terminal monitors retained only until their single final wake settles. */
+export declare const MONITORS_MAX_TERMINAL_RECORDS = 32;
+export interface MonitorsRateLimitSettings {
+    readonly windowMs: number;
+    readonly maxLinesPerWindow: number;
+    readonly sustainedWindows: number;
+}
+export interface MonitorsSettings {
+    readonly configured: boolean;
+    readonly enabled: boolean;
+    readonly maxActive: number;
+    readonly maxActivePerConversation: number;
+    readonly maxRuntimeMs: number;
+    readonly persistentMaxRuntimeMs: number;
+    readonly coalesceMs: number;
+    readonly maxWakeIntervalMs: number;
+    readonly maxBatchLines: number;
+    readonly maxBatchBytes: number;
+    readonly maxLineBytes: number;
+    readonly maxChainDepth: number;
+    readonly rateLimit: MonitorsRateLimitSettings;
+}
+/** Load the host-only monitor block, failing closed on every unknown key. */
+export declare function loadMonitorsSettings(input: {
+    readonly configPath: string;
+}): Promise<MonitorsSettings>;
+/** Parse one already-loaded config object; unknown keys fail closed. */
+export declare function parseMonitorsSettings(raw: unknown): MonitorsSettings;
+//# sourceMappingURL=monitors-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"monitors-config.d.ts","sourceRoot":"","sources":["../src/monitors-config.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB;;;;IAI5B,8EAA8E;;IAE9E,gDAAgD;;IAEhD,2EAA2E;;;;;;;;;;;;EAY3E,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;EAgBxB,CAAC;AAEH,6EAA6E;AAC7E,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;CAC/C;AAmBD,6EAA6E;AAC7E,wBAAsB,oBAAoB,CAAC,KAAK,EAAE;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAS5B;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAOpE"}

package/dist/monitors-config.js

@@ -0,0 +1,150 @@
+import { readFile } from "node:fs/promises";
+/**
+ * Host-only `monitors` configuration.
+ *
+ * Monitors are a STREAMING class of the background process-job substrate: they
+ * reuse its protected private-state root, its registration proof, its sandbox
+ * protection, and its origin binding, and therefore require
+ * `processJobs.enabled`. What they do not share is capacity — a persistent watch
+ * that held an ordinary background slot would starve real background work — so
+ * every limit below is counted independently of `processJobs.*`.
+ */
+export const MONITORS_DEFAULTS = Object.freeze({
+    enabled: false,
+    maxActive: 8,
+    maxActivePerConversation: 2,
+    /** Ceiling for a timed monitor; `timeout_ms` may lower it, never raise it. */
+    maxRuntimeMs: 60 * 60 * 1_000,
+    /** Ceiling for a `persistent: true` monitor. */
+    persistentMaxRuntimeMs: 24 * 60 * 60 * 1_000,
+    /** Stdout lines produced within this window are delivered as one batch. */
+    coalesceMs: 200,
+    maxWakeIntervalMs: 300_000,
+    maxBatchLines: 200,
+    maxBatchBytes: 64 * 1024,
+    maxLineBytes: 4 * 1024,
+    maxChainDepth: 4,
+    rateLimit: Object.freeze({
+        windowMs: 1_000,
+        maxLinesPerWindow: 200,
+        sustainedWindows: 5,
+    }),
+});
+export const MONITORS_CAPS = Object.freeze({
+    maxActive: 32,
+    maxActivePerConversation: 8,
+    maxRuntimeMs: 60 * 60 * 1_000,
+    persistentMaxRuntimeMs: 24 * 60 * 60 * 1_000,
+    coalesceMs: 5_000,
+    maxWakeIntervalMs: 300_000,
+    maxBatchLines: 2_000,
+    maxBatchBytes: 1024 * 1024,
+    maxLineBytes: 64 * 1024,
+    maxChainDepth: 64,
+    rateLimit: Object.freeze({
+        windowMs: 60_000,
+        maxLinesPerWindow: 20_000,
+        sustainedWindows: 60,
+    }),
+});
+/** Terminal monitors retained only until their single final wake settles. */
+export const MONITORS_MAX_TERMINAL_RECORDS = 32;
+const MONITORS_KEYS = [
+    "enabled",
+    "maxActive",
+    "maxActivePerConversation",
+    "maxRuntimeMs",
+    "persistentMaxRuntimeMs",
+    "coalesceMs",
+    "maxWakeIntervalMs",
+    "maxBatchLines",
+    "maxBatchBytes",
+    "maxLineBytes",
+    "maxChainDepth",
+    "rateLimit",
+];
+const RATE_LIMIT_KEYS = ["windowMs", "maxLinesPerWindow", "sustainedWindows"];
+/** Load the host-only monitor block, failing closed on every unknown key. */
+export async function loadMonitorsSettings(input) {
+    let raw = {};
+    try {
+        raw = JSON.parse(await readFile(input.configPath, "utf8"));
+    }
+    catch {
+        // The core loader owns malformed/missing config reporting. This optional
+        // host block stays disabled until that loader accepts the file.
+    }
+    return parseMonitorsSettings(raw);
+}
+/** Parse one already-loaded config object; unknown keys fail closed. */
+export function parseMonitorsSettings(raw) {
+    const root = objectOf(raw);
+    const value = root.monitors;
+    if (value === undefined)
+        return resolved(false, {});
+    const block = requireObject(value, "monitors");
+    rejectUnknownKeys(block, "monitors", MONITORS_KEYS);
+    return resolved(true, block);
+}
+function resolved(configured, block) {
+    const rateLimitValue = block.rateLimit;
+    const rateLimit = rateLimitValue === undefined
+        ? {}
+        : requireObject(rateLimitValue, "monitors.rateLimit");
+    rejectUnknownKeys(rateLimit, "monitors.rateLimit", RATE_LIMIT_KEYS);
+    return {
+        configured,
+        enabled: optionalBoolean(block.enabled, "monitors.enabled") ?? MONITORS_DEFAULTS.enabled,
+        maxActive: bounded(block.maxActive, "monitors.maxActive", MONITORS_DEFAULTS.maxActive, MONITORS_CAPS.maxActive),
+        maxActivePerConversation: bounded(block.maxActivePerConversation, "monitors.maxActivePerConversation", MONITORS_DEFAULTS.maxActivePerConversation, MONITORS_CAPS.maxActivePerConversation),
+        maxRuntimeMs: bounded(block.maxRuntimeMs, "monitors.maxRuntimeMs", MONITORS_DEFAULTS.maxRuntimeMs, MONITORS_CAPS.maxRuntimeMs),
+        persistentMaxRuntimeMs: bounded(block.persistentMaxRuntimeMs, "monitors.persistentMaxRuntimeMs", MONITORS_DEFAULTS.persistentMaxRuntimeMs, MONITORS_CAPS.persistentMaxRuntimeMs),
+        coalesceMs: bounded(block.coalesceMs, "monitors.coalesceMs", MONITORS_DEFAULTS.coalesceMs, MONITORS_CAPS.coalesceMs),
+        maxWakeIntervalMs: bounded(block.maxWakeIntervalMs, "monitors.maxWakeIntervalMs", MONITORS_DEFAULTS.maxWakeIntervalMs, MONITORS_CAPS.maxWakeIntervalMs),
+        maxBatchLines: bounded(block.maxBatchLines, "monitors.maxBatchLines", MONITORS_DEFAULTS.maxBatchLines, MONITORS_CAPS.maxBatchLines),
+        maxBatchBytes: bounded(block.maxBatchBytes, "monitors.maxBatchBytes", MONITORS_DEFAULTS.maxBatchBytes, MONITORS_CAPS.maxBatchBytes),
+        maxLineBytes: bounded(block.maxLineBytes, "monitors.maxLineBytes", MONITORS_DEFAULTS.maxLineBytes, MONITORS_CAPS.maxLineBytes),
+        maxChainDepth: bounded(block.maxChainDepth, "monitors.maxChainDepth", MONITORS_DEFAULTS.maxChainDepth, MONITORS_CAPS.maxChainDepth),
+        rateLimit: {
+            windowMs: bounded(rateLimit.windowMs, "monitors.rateLimit.windowMs", MONITORS_DEFAULTS.rateLimit.windowMs, MONITORS_CAPS.rateLimit.windowMs),
+            maxLinesPerWindow: bounded(rateLimit.maxLinesPerWindow, "monitors.rateLimit.maxLinesPerWindow", MONITORS_DEFAULTS.rateLimit.maxLinesPerWindow, MONITORS_CAPS.rateLimit.maxLinesPerWindow),
+            sustainedWindows: bounded(rateLimit.sustainedWindows, "monitors.rateLimit.sustainedWindows", MONITORS_DEFAULTS.rateLimit.sustainedWindows, MONITORS_CAPS.rateLimit.sustainedWindows),
+        },
+    };
+}
+function bounded(value, path, fallback, cap) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isSafeInteger(value) || Number(value) <= 0) {
+        throw new Error(`${path} must be a positive safe integer.`);
+    }
+    if (Number(value) > cap)
+        throw new Error(`${path} cannot exceed ${String(cap)}.`);
+    return Number(value);
+}
+function objectOf(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function requireObject(value, path) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`${path} must be an object.`);
+    }
+    return value;
+}
+function optionalBoolean(value, path) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new Error(`${path} must be a boolean.`);
+    return value;
+}
+function rejectUnknownKeys(value, path, allowed) {
+    const allowedSet = new Set(allowed);
+    const unknown = Object.keys(value).filter((key) => !allowedSet.has(key));
+    if (unknown.length > 0) {
+        throw new Error(`${path} has unknown ${unknown.length === 1 ? "key" : "keys"}: ${unknown.join(", ")}.`);
+    }
+}
+//# sourceMappingURL=monitors-config.js.map

package/dist/monitors-config.js.map

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

package/dist/monitors-context.d.ts

@@ -0,0 +1,58 @@
+import { type AgentRequestBase, type AgentResponder, type AgentResponse } from "@mono-agent/agent-contracts";
+import type { MonoAgentAppLogger } from "./channels.js";
+export interface MonitorWakeContext {
+    readonly monitorId: string;
+    readonly chainDepth: number;
+}
+export type MonitorWakeContextResolution = {
+    readonly kind: "none";
+} | {
+    readonly kind: "resolved";
+    readonly context: MonitorWakeContext;
+} | {
+    readonly kind: "missed";
+};
+/**
+ * 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 declare function runWithMonitorWakeContext<T>(context: MonitorWakeContext, operation: () => Promise<T>, deliveryKey: string): Promise<T>;
+/**
+ * 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 declare function bindMonitorWakeContextToResponder(responder: AgentResponder, options?: {
+    readonly logger?: MonoAgentAppLogger;
+}): AgentResponder;
+/**
+ * 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 declare function suppressSilentMonitorReply(response: AgentResponse, context: MonitorWakeContext & {
+    readonly deliveryKey?: string;
+}, logger?: MonoAgentAppLogger): AgentResponse;
+/**
+ * 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 declare function consumeSilentMonitorWake(deliveryKey: string): boolean;
+/** Resolve only an association previously issued by this app-owned seam. */
+export declare function monitorWakeContextForRequest(request: Pick<AgentRequestBase, "metadata">): MonitorWakeContextResolution;
+//# sourceMappingURL=monitors-context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"monitors-context.d.ts","sourceRoot":"","sources":["../src/monitors-context.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAGxD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAOD,MAAM,MAAM,4BAA4B,GACpC;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AA0BhC;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,OAAO,EAAE,kBAAkB,EAC3B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iCAAiC,CAC/C,SAAS,EAAE,cAAc,EACzB,OAAO,GAAE;IAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAAO,GACrD,cAAc,CA2DhB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,aAAa,EACvB,OAAO,EAAE,kBAAkB,GAAG;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAC/D,MAAM,CAAC,EAAE,kBAAkB,GAC1B,aAAa,CAYf;AAaD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,4EAA4E;AAC5E,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,UAAU,CAAC,GAC1C,4BAA4B,CAW9B"}