@mono-agent/operator-adapter 0.19.0 → 0.20.0

package/dist/tui/server.js

@@ -1,22 +1,30 @@
 import { randomUUID } from "node:crypto";
 import { createServer } from "node:http";
 import { isAbsolute } from "node:path";
-import { AGENT_LIVE_INPUT_MAX_CHARACTERS, DEFAULT_AGENT_ATTACHMENT_MAX_BYTES, DEFAULT_AGENT_ATTACHMENT_MIME_ALLOWLIST, BoundedHttpResponseWriter, agentAttachmentKindFromMimeType, closeServerBounded, createChannelUserCancelReason, decodeAgentAttachmentText, isAgentResponseCancelledError, serializeAgentStreamFrame, } from "@mono-agent/agent-contracts";
-import { assertSafeBind, bearerTokensEqual, hostForUrl, isLoopbackHost, listen, normalizeOptionalString, readAuthorizationBearer, } from "@mono-agent/agent-contracts";
+import { AGENT_LIVE_INPUT_MAX_CHARACTERS, DEFAULT_AGENT_ATTACHMENT_MAX_BYTES, DEFAULT_AGENT_ATTACHMENT_MIME_ALLOWLIST, MCP_APP_RESOURCE_MIME_TYPE, MCP_APP_SUPPORTED_VERSIONS, MAX_AGENT_REPLY_PARTS, BoundedHttpResponseWriter, agentAttachmentKindFromMimeType, closeServerBounded, createChannelUserCancelReason, decodeAgentAttachmentText, isAgentResponseCancelledError, parseProcessJobProjection, parseProcessJobProjections, serializeAgentStreamFrame, } from "@mono-agent/agent-contracts";
+import { assertSafeBind, bearerTokensEqual, hostForUrl, isLoopbackHost, listen, normalizeOptionalString, parseCronOperatorOverview, parseCronOperatorRunDetail, parseCronOperatorRunPage, readAuthorizationBearer, } from "@mono-agent/agent-contracts";
 import express, {} from "express";
 import { DEFAULT_BASE_PATH, DEFAULT_HOST, DEFAULT_PORT, MAX_FRAME_BYTES, TUI_WIRE_SCHEMA } from "./constants.js";
+import { CronOperatorError, MAX_CRON_OPERATOR_RESPONSE_BYTES, MAX_CRON_OPERATOR_RUN_PAGE, } from "./cron.js";
 import { TuiAdapterError } from "./errors.js";
 const MAX_TURN_BODY_BYTES = 96 * 1024 * 1024;
 const MAX_VERBATIM_BODY_BYTES = 2 * 1024 * 1024;
 const MAX_VERBATIM_TEXT_CHARACTERS = 200_000;
 const MAX_VERBATIM_TEXT_BYTES = 1024 * 1024;
 const MAX_LIVE_INPUT_BODY_BYTES = 32 * 1024;
+const MAX_PROCESS_JOBS_RESPONSE_BYTES = 16 * 1024 * 1024;
 const MAX_WEB_ATTACHMENTS = 10;
 const MAX_WEB_ATTACHMENT_BYTES = 64 * 1024 * 1024;
 const MAX_REQUEST_TOOL_ENVIRONMENT_KEYS = 32;
 const MAX_REQUEST_TOOL_ENVIRONMENT_VALUE_BYTES = 16 * 1024;
 const MAX_REQUEST_TOOL_ENVIRONMENT_TOTAL_BYTES = 64 * 1024;
 const MAX_REQUEST_TOOL_ENVIRONMENT_PATHS = 4;
+const MAX_CRON_ACTION_BODY_BYTES = 32 * 1024;
+const MAX_REPLY_ARTIFACT_ID_BYTES = 128;
+const MAX_REPLY_ARTIFACT_CONVERSATION_BYTES = 4 * 1024;
+const MAX_MCP_APP_IDENTITY_BYTES = 4 * 1024;
+const MAX_MCP_APP_REQUEST_BYTES = 64 * 1024;
+const REPLY_ARTIFACT_DRAIN_TIMEOUT_MS = 30_000;
 const ALLOWED_ATTACHMENT_MIME_TYPES = new Set(DEFAULT_AGENT_ATTACHMENT_MIME_ALLOWLIST.map((mimeType) => mimeType.toLowerCase()));
 export async function startTuiAdapter(options) {
     if (typeof options.responder?.respond !== "function") {
@@ -26,6 +34,10 @@ export async function startTuiAdapter(options) {
     const port = options.port ?? DEFAULT_PORT;
     const basePath = normalizeBasePath(options.basePath ?? DEFAULT_BASE_PATH);
     const apiKey = normalizeOptionalString(options.apiKey);
+    const processJobsBearer = normalizeOptionalString(options.processJobsBearer);
+    if ((options.processJobs === undefined) !== (processJobsBearer === undefined)) {
+        throw new TuiAdapterError("invalid_config", "processJobs and processJobsBearer must be configured together.");
+    }
     if (options.requestToolEnvironment !== undefined && !isLoopbackHost(host)) {
         throw new TuiAdapterError("unsafe_host", "Request tool environment requires a loopback-only TUI adapter bind.", { host });
     }
@@ -40,21 +52,76 @@ export async function startTuiAdapter(options) {
     const cancelPath = `${basePath}/v1/conversations/:conversationId/cancel`;
     const verbatimPath = `${basePath}/v1/conversations/:conversationId/verbatim`;
     const liveInputPath = `${basePath}/v1/conversations/:conversationId/live-input`;
+    const replyArtifactPath = `${basePath}/v1/conversations/:conversationId/reply-artifacts/:artifactId`;
+    const mcpAppPath = `${basePath}/v1/conversations/:conversationId/mcp-apps/:invocationId`;
+    const mcpAppRequestPath = `${mcpAppPath}/requests`;
     const askPath = `${basePath}/v1/conversations/:conversationId/ask`;
+    const interactionPath = `${basePath}/v1/interactions/:interactionId`;
+    const cronOverviewPath = `${basePath}/v1/cron`;
+    const cronRunsPath = `${basePath}/v1/cron/jobs/:jobId/runs`;
+    const cronRunDetailPath = `${basePath}/v1/cron/jobs/:jobId/runs/:runId`;
+    const cronConfigViewPath = `${basePath}/v1/cron/config-view`;
+    const cronRunNowPath = `${basePath}/v1/cron/jobs/:jobId/run`;
+    const cronEnabledPath = `${basePath}/v1/cron/jobs/:jobId/effective-enabled`;
+    const jobsPath = `${basePath}/v1/jobs`;
+    const jobPath = `${basePath}/v1/jobs/:jobId`;
+    const jobCancelPath = `${basePath}/v1/jobs/:jobId/cancel`;
     app.get(infoPath, (req, res) => {
         if (!authorize(req, res, apiKey)) {
             return;
         }
-        void resolveInfo(options.info)
-            .then((info) => {
+        const cronInfo = options.cron === undefined
+            ? Promise.resolve({ kind: "absent" })
+            : Promise.resolve()
+                .then(async () => await options.cron.overview())
+                .then((overview) => ({ kind: "available", overview }))
+                .catch((error) => {
+                // Cron is an additive capability, never the agent-liveness probe. A
+                // stopped registry or failed control store must not turn /v1/info into
+                // a 500 that makes the whole agent appear unreachable.
+                options.logger?.error?.("Cron operator overview failed during TUI info.", {
+                    error: errorToMessage(error),
+                });
+                return { kind: "degraded" };
+            });
+        void Promise.all([resolveInfo(options.info), cronInfo])
+            .then(([info, cronState]) => {
             res.status(200).json({
                 schema: TUI_WIRE_SCHEMA,
                 pid: process.pid,
                 capabilities: {
                     attachments: true,
+                    ...(typeof options.responder.openReplyArtifact === "function"
+                        ? { replyAttachments: { version: 1, maxBytes: DEFAULT_AGENT_ATTACHMENT_MAX_BYTES } }
+                        : {}),
+                    ...(typeof options.responder.loadMcpApp === "function"
+                        && typeof options.responder.requestMcpApp === "function"
+                        ? {
+                            mcpApps: {
+                                bridgeVersion: 1,
+                                versions: MCP_APP_SUPPORTED_VERSIONS,
+                                mimeTypes: [MCP_APP_RESOURCE_MIME_TYPE],
+                            },
+                        }
+                        : {}),
                     ...(typeof options.responder.offerLiveInput === "function" ? { liveInput: true } : {}),
                     ...(typeof options.responder.deliverVerbatim === "function" ? { historyAppend: true } : {}),
                     ...(options.interaction === undefined ? {} : { askUser: true }),
+                    ...(typeof options.interaction?.getAsk === "function" ? { askById: true } : {}),
+                    ...(cronState.kind === "absent"
+                        ? {}
+                        : cronState.kind === "degraded"
+                            ? { cron: { status: "degraded", read: false, actions: false } }
+                            : {
+                                cron: {
+                                    status: cronState.overview.degradedReason === undefined ? "ready" : "degraded",
+                                    read: true,
+                                    actions: cronState.overview.degradedReason === undefined
+                                        && apiKey !== undefined
+                                        && cronState.overview.actionsEnabled === true,
+                                },
+                            }),
+                    ...(options.processJobs === undefined || processJobsBearer === undefined ? {} : { jobs: true }),
                     ...(options.requestToolEnvironment === undefined ? {} : { toolEnvironment: true }),
                 },
                 ...(info?.label === undefined ? {} : { label: info.label }),
@@ -72,6 +139,69 @@ export async function startTuiAdapter(options) {
             sendJsonError(res, 500, error);
         });
     });
+    app.get(jobsPath, (req, res, next) => {
+        if (!authorize(req, res, processJobsBearer))
+            return;
+        if (options.processJobs === undefined || processJobsBearer === undefined) {
+            sendJsonError(res, 404, new TuiAdapterError("invalid_request", "Process jobs are unavailable."));
+            return;
+        }
+        void options.processJobs.list()
+            .then((jobs) => sendBoundedJobs(res, jobs))
+            .catch(next);
+    });
+    app.get(jobPath, (req, res, next) => {
+        if (!authorize(req, res, processJobsBearer))
+            return;
+        if (options.processJobs === undefined || processJobsBearer === undefined) {
+            sendJsonError(res, 404, new TuiAdapterError("invalid_request", "Process jobs are unavailable."));
+            return;
+        }
+        const jobId = normalizeOptionalString(typeof req.params.jobId === "string" ? req.params.jobId : undefined);
+        if (jobId === undefined || jobId.length > 256) {
+            sendJsonError(res, 400, new TuiAdapterError("invalid_request", "A bounded jobId is required."));
+            return;
+        }
+        void options.processJobs.get(jobId)
+            .then((job) => {
+            if (job === undefined) {
+                res.status(404).json({ error: { code: "process_job_not_found", message: "Process job was not found." } });
+            }
+            else {
+                sendBoundedJob(res, job);
+            }
+        })
+            .catch(next);
+    });
+    app.post(jobCancelPath, (req, res, next) => {
+        if (!authorize(req, res, processJobsBearer))
+            return;
+        if (options.processJobs === undefined || processJobsBearer === undefined) {
+            sendJsonError(res, 404, new TuiAdapterError("invalid_request", "Process jobs are unavailable."));
+            return;
+        }
+        const jobId = normalizeOptionalString(typeof req.params.jobId === "string" ? req.params.jobId : undefined);
+        if (jobId === undefined || jobId.length > 256) {
+            sendJsonError(res, 400, new TuiAdapterError("invalid_request", "A bounded jobId is required."));
+            return;
+        }
+        void options.processJobs.cancel(jobId)
+            .then((job) => sendBoundedJob(res, job))
+            .catch((error) => {
+            const code = typeof error === "object" && error !== null
+                ? error.code
+                : undefined;
+            if (code === "process_job_not_found") {
+                res.status(404).json({ error: { code, message: errorToMessage(error) } });
+            }
+            else if (code === "process_job_conflict") {
+                res.status(409).json({ error: { code, message: errorToMessage(error) } });
+            }
+            else {
+                next(error);
+            }
+        });
+    });
     // Keep the enlarged parser scoped to turn submission. 64 MiB of decoded
     // files expands to about 85.4 MiB in base64, while info/cancel stay bodyless.
     app.post(turnsPath, express.json({ limit: MAX_TURN_BODY_BYTES }), (req, res) => {
@@ -103,6 +233,101 @@ export async function startTuiAdapter(options) {
         options.interaction?.cancelAsks(conversationId);
         res.status(202).json({ cancelled: conversationId });
     });
+    app.get(replyArtifactPath, (req, res, next) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        if (typeof options.responder.openReplyArtifact !== "function") {
+            sendJsonError(res, 404, new TuiAdapterError("invalid_request", "Reply artifacts are unavailable."));
+            return;
+        }
+        const conversationId = normalizeOptionalString(typeof req.params.conversationId === "string" ? req.params.conversationId : undefined);
+        const artifactId = normalizeOptionalString(typeof req.params.artifactId === "string" ? req.params.artifactId : undefined);
+        const expectedIntegrityId = normalizeOptionalString(req.header("x-mono-agent-integrity-id"));
+        if (conversationId === undefined
+            || artifactId === undefined
+            || Buffer.byteLength(conversationId, "utf8") > MAX_REPLY_ARTIFACT_CONVERSATION_BYTES
+            || Buffer.byteLength(artifactId, "utf8") > MAX_REPLY_ARTIFACT_ID_BYTES) {
+            sendJsonError(res, 400, new TuiAdapterError("invalid_request", "A valid conversation and artifact id are required."));
+            return;
+        }
+        void options.responder.openReplyArtifact({
+            conversationId,
+            reference: { scheme: "mono-agent-artifact", id: artifactId },
+            ...(expectedIntegrityId === undefined ? {} : { expectedIntegrityId }),
+        }).then(async (opened) => {
+            setReplyArtifactHeaders(res, opened.attachment);
+            let streamed = 0;
+            for await (const chunk of opened.body) {
+                streamed += chunk.byteLength;
+                if (streamed > opened.attachment.sizeBytes) {
+                    throw new TuiAdapterError("invalid_request", "Reply artifact exceeded its declared size.");
+                }
+                await writeBinaryChunk(res, chunk);
+            }
+            if (streamed !== opened.attachment.sizeBytes) {
+                throw new TuiAdapterError("invalid_request", "Reply artifact stream ended before its declared size.");
+            }
+            res.end();
+        }).catch((error) => {
+            if (res.headersSent) {
+                res.destroy(error instanceof Error ? error : new Error(String(error)));
+                return;
+            }
+            const code = codeOf(error);
+            const status = code === "artifact_forbidden" || code === "artifact_missing" || code === "artifact_expired"
+                ? 404
+                : code === "artifact_integrity_failed" ? 409 : 500;
+            sendJsonError(res, status, error);
+        }).catch(next);
+    });
+    app.get(mcpAppPath, (req, res) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        if (typeof options.responder.loadMcpApp !== "function") {
+            sendJsonError(res, 404, new TuiAdapterError("invalid_request", "MCP Apps are unavailable."));
+            return;
+        }
+        const identity = normalizeMcpAppIdentity(req);
+        if (identity === undefined) {
+            sendJsonError(res, 400, new TuiAdapterError("invalid_request", "A valid conversation, invocation, and connection id are required."));
+            return;
+        }
+        void options.responder.loadMcpApp(identity).then((resource) => {
+            setPrivateMcpAppHeaders(res);
+            res.status(200).json(resource);
+        }).catch((error) => sendMcpAppError(res, error));
+    });
+    app.post(mcpAppRequestPath, express.json({ limit: MAX_MCP_APP_REQUEST_BYTES, strict: true }), (req, res) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        if (typeof options.responder.requestMcpApp !== "function") {
+            sendJsonError(res, 404, new TuiAdapterError("invalid_request", "MCP Apps are unavailable."));
+            return;
+        }
+        const identity = normalizeMcpAppIdentity(req);
+        const body = isRecord(req.body) ? req.body : undefined;
+        const method = body?.method;
+        const params = body?.params;
+        const confirmed = body?.confirmed;
+        if (identity === undefined
+            || (method !== "resources/read"
+                && method !== "tools/call"
+                && method !== "ui/open-link"
+                && method !== "ui/update-model-context")
+            || (confirmed !== undefined && typeof confirmed !== "boolean")) {
+            sendJsonError(res, 400, new TuiAdapterError("invalid_request", "The MCP App bridge request is invalid."));
+            return;
+        }
+        void options.responder.requestMcpApp({
+            ...identity,
+            method,
+            ...(params === undefined ? {} : { params }),
+            ...(confirmed === undefined ? {} : { confirmed }),
+        }).then((result) => {
+            setPrivateMcpAppHeaders(res);
+            res.status(200).json({ result });
+        }).catch((error) => sendMcpAppError(res, error));
+    });
     app.post(verbatimPath, express.json({ limit: MAX_VERBATIM_BODY_BYTES, strict: true }), (req, res, next) => {
         if (!authorize(req, res, apiKey)) {
             return;
@@ -200,6 +425,128 @@ export async function startTuiAdapter(options) {
             res.status(200).json(result);
         }).catch((error) => sendJsonError(res, 500, error));
     });
+    app.get(interactionPath, (req, res) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        const interactionId = normalizeOptionalString(typeof req.params.interactionId === "string" ? req.params.interactionId : undefined);
+        if (interactionId === undefined) {
+            sendJsonError(res, 400, new TuiAdapterError("invalid_request", "interactionId is required."));
+            return;
+        }
+        if (typeof options.interaction?.getAsk !== "function") {
+            sendJsonError(res, 501, new TuiAdapterError("invalid_request", "Exact interaction lookup is unsupported."));
+            return;
+        }
+        void Promise.resolve(options.interaction.getAsk(interactionId))
+            .then((ask) => res.status(200).json({ ask: ask ?? null }))
+            .catch((error) => sendJsonError(res, 500, error));
+    });
+    app.get(cronOverviewPath, (req, res, next) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        if (options.cron === undefined) {
+            sendJsonError(res, 404, new CronOperatorError("unavailable", "Cron operator capability is unavailable.", 404));
+            return;
+        }
+        void Promise.resolve(options.cron.overview())
+            .then((overview) => sendBoundedCronJson(res, 200, parseCronOperatorOverview(overview)))
+            .catch(next);
+    });
+    app.get(cronRunsPath, (req, res, next) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        if (options.cron === undefined) {
+            sendJsonError(res, 404, new CronOperatorError("unavailable", "Cron operator capability is unavailable.", 404));
+            return;
+        }
+        try {
+            const jobId = cronJobId(req.params.jobId);
+            const rawLimit = typeof req.query.limit === "string" ? Number(req.query.limit) : 50;
+            if (!Number.isSafeInteger(rawLimit) || rawLimit < 1 || rawLimit > MAX_CRON_OPERATOR_RUN_PAGE) {
+                throw new CronOperatorError("invalid_request", `limit must be 1-${String(MAX_CRON_OPERATOR_RUN_PAGE)}.`, 400);
+            }
+            const before = typeof req.query.before === "string" && req.query.before.length > 0
+                ? req.query.before
+                : undefined;
+            if (before !== undefined && Buffer.byteLength(before, "utf8") > 4_096) {
+                throw new CronOperatorError("invalid_request", "before cursor is too large.", 400);
+            }
+            void Promise.resolve(options.cron.runs({ jobId, limit: rawLimit, ...(before === undefined ? {} : { before }) }))
+                .then((page) => sendBoundedCronJson(res, 200, parseCronOperatorRunPage(page)))
+                .catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.get(cronRunDetailPath, (req, res, next) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        if (options.cron === undefined) {
+            sendJsonError(res, 404, new CronOperatorError("unavailable", "Cron operator capability is unavailable.", 404));
+            return;
+        }
+        try {
+            const jobId = cronJobId(req.params.jobId);
+            const runId = cronRunId(req.params.runId);
+            void Promise.resolve(options.cron.run({ jobId, runId }))
+                .then((run) => sendBoundedCronJson(res, 200, { run: parseCronOperatorRunDetail(run) }))
+                .catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.get(cronConfigViewPath, (req, res, next) => {
+        if (!authorize(req, res, apiKey))
+            return;
+        if (options.cron === undefined) {
+            sendJsonError(res, 404, new CronOperatorError("unavailable", "Cron operator capability is unavailable.", 404));
+            return;
+        }
+        void Promise.resolve(options.cron.configView())
+            .then((configView) => res.status(200).json({ configView }))
+            .catch(next);
+    });
+    app.post(cronRunNowPath, express.json({ limit: MAX_CRON_ACTION_BODY_BYTES, strict: true }), (req, res, next) => {
+        if (!authorize(req, res, apiKey) || !requireCronActionKey(res, apiKey))
+            return;
+        if (options.cron === undefined) {
+            sendJsonError(res, 404, new CronOperatorError("unavailable", "Cron operator capability is unavailable.", 404));
+            return;
+        }
+        try {
+            const jobId = cronJobId(req.params.jobId);
+            const action = cronActionInput(req.body);
+            void Promise.resolve(options.cron.runNow(jobId, action))
+                .then((result) => sendCronMutation(res, result))
+                .catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
+    app.post(cronEnabledPath, express.json({ limit: MAX_CRON_ACTION_BODY_BYTES, strict: true }), (req, res, next) => {
+        if (!authorize(req, res, apiKey) || !requireCronActionKey(res, apiKey))
+            return;
+        if (options.cron === undefined) {
+            sendJsonError(res, 404, new CronOperatorError("unavailable", "Cron operator capability is unavailable.", 404));
+            return;
+        }
+        try {
+            const jobId = cronJobId(req.params.jobId);
+            if (!isRecord(req.body) || typeof req.body.enabled !== "boolean") {
+                throw new CronOperatorError("invalid_request", "enabled must be a boolean.", 400);
+            }
+            const action = cronActionInput(req.body);
+            void Promise.resolve(options.cron.setEffectiveEnabled(jobId, req.body.enabled, action))
+                .then((result) => sendCronMutation(res, result))
+                .catch(next);
+        }
+        catch (error) {
+            next(error);
+        }
+    });
     app.use((error, _req, res, next) => {
         if (res.headersSent) {
             next(error);
@@ -213,6 +560,10 @@ export async function startTuiAdapter(options) {
         }
         // 400 only for client mistakes (invalid_request, body-parse SyntaxError);
         // anything else is a server-side failure and must read as one.
+        if (error instanceof CronOperatorError) {
+            sendJsonError(res, error.status, error);
+            return;
+        }
         const isClientError = codeOf(error) === "invalid_request" ||
             (error instanceof SyntaxError && error.status === 400);
         sendJsonError(res, isClientError ? 400 : 500, error);
@@ -276,6 +627,7 @@ export async function startTuiAdapter(options) {
                 kind: "finish",
                 ...(response.text === undefined ? {} : { finalText: response.text }),
                 ...(response.metadata === undefined ? {} : { metadata: response.metadata }),
+                ...(response.parts === undefined || response.parts.length === 0 ? {} : { parts: response.parts }),
             });
         }
         catch (error) {
@@ -317,7 +669,9 @@ export async function startTuiAdapter(options) {
  * the response's backpressure signal and carry a bounded pending-byte budget,
  * so a slow client cannot grow the process heap without limit. Oversized event
  * frames are reduced or replaced with a marker to meet the exported UTF-8 byte
- * cap; non-event frames retain their existing behavior.
+ * cap. Append text is split losslessly; other text fields are deterministically
+ * truncated, and terminal rich parts that cannot fit are replaced by an
+ * explicit failure marker.
  */
 class NdjsonMessageStream {
     res;
@@ -330,11 +684,30 @@ class NdjsonMessageStream {
         if (this.res.writableEnded) {
             return;
         }
-        let line = serializeAgentStreamFrame(frame);
-        if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES && frame.kind === "event") {
-            line = serializeCappedEventFrame(frame.event, line);
+        const boundedFrame = frame.kind === "finish" ? capFinishReplyParts(frame) : frame;
+        const line = serializeAgentStreamFrame(boundedFrame);
+        if (Buffer.byteLength(line, "utf8") <= MAX_FRAME_BYTES) {
+            await this.writer.write(line);
+            return;
+        }
+        if (boundedFrame.kind === "append") {
+            for (const chunk of splitTextForWireFrame("append", boundedFrame.delta)) {
+                await this.writer.write(serializeAgentStreamFrame({ kind: "append", delta: chunk }));
+            }
+            return;
         }
-        await this.writer.write(line);
+        const capped = boundedFrame.kind === "event"
+            ? serializeCappedEventFrame(boundedFrame.event, line)
+            : boundedFrame.kind === "finish"
+                ? serializeCappedFinishFrame(line)
+                : boundedFrame.kind === "status" || boundedFrame.kind === "replace" || boundedFrame.kind === "error"
+                    ? serializeCappedTextFrame(boundedFrame)
+                    : serializeAgentStreamFrame({
+                        kind: "error",
+                        code: "frame_too_large",
+                        message: "A transport frame exceeded the maximum size.",
+                    });
+        await this.writer.write(capped);
     }
     async status(text) {
         await this.writeFrame({ kind: "status", text });
@@ -353,6 +726,24 @@ class NdjsonMessageStream {
         // AgentResponse (which carries metadata); mid-stream finish() is a no-op.
     }
 }
+function capFinishReplyParts(frame) {
+    const parts = frame.parts;
+    if (parts === undefined || parts.length <= MAX_AGENT_REPLY_PARTS)
+        return frame;
+    const omitted = parts.length - (MAX_AGENT_REPLY_PARTS - 1);
+    return {
+        ...frame,
+        parts: [
+            ...parts.slice(0, MAX_AGENT_REPLY_PARTS - 1),
+            {
+                type: "failure",
+                id: "wire-rich-parts-over-limit",
+                code: "reply_part_too_large",
+                message: `${omitted} rich reply part${omitted === 1 ? " was" : "s were"} omitted because the reply exceeded the 20-part transport limit.`,
+            },
+        ],
+    };
+}
 /**
  * Prepare a stable reducer for the payload-bearing event variants whose shape
  * the operator adapter preserves under truncation. The input is the parsed
@@ -462,12 +853,217 @@ function serializeOversizedEventMarker(originalType) {
         },
     });
 }
+function serializeCappedFinishFrame(serializedFrame) {
+    const snapshot = JSON.parse(serializedFrame);
+    const safeMetadata = compactFinishMetadata(snapshot.metadata);
+    const base = {
+        kind: "finish",
+        ...(safeMetadata === undefined ? {} : { metadata: safeMetadata }),
+    };
+    const parts = snapshot.parts ?? [];
+    const allPartsFrame = {
+        ...base,
+        ...(parts.length === 0 ? {} : { parts }),
+    };
+    const allPartsWithoutText = serializeAgentStreamFrame(allPartsFrame);
+    if (Buffer.byteLength(allPartsWithoutText, "utf8") <= MAX_FRAME_BYTES) {
+        const withText = serializeFinishWithCappedText(allPartsFrame, snapshot.finalText);
+        if (Buffer.byteLength(withText, "utf8") <= MAX_FRAME_BYTES)
+            return withText;
+    }
+    const failure = {
+        type: "failure",
+        id: "wire-rich-parts-truncated",
+        code: "reply_part_too_large",
+        message: "One or more rich reply parts were omitted because the terminal frame exceeded 256 KiB.",
+    };
+    let frame = {
+        ...base,
+        ...(snapshot.finalText === undefined ? {} : { finalText: snapshot.finalText }),
+        parts: [failure],
+    };
+    let line = serializeAgentStreamFrame(frame);
+    if (Buffer.byteLength(line, "utf8") > MAX_FRAME_BYTES && snapshot.finalText !== undefined) {
+        frame = {
+            ...frame,
+            finalText: `${largestTextThatFits(snapshot.finalText, (candidate) => serializeAgentStreamFrame({ ...frame, finalText: `${candidate}… [truncated]` }))}… [truncated]`,
+        };
+    }
+    const accepted = [];
+    for (const part of parts) {
+        const candidate = serializeAgentStreamFrame({ ...frame, parts: [...accepted, part, failure] });
+        if (Buffer.byteLength(candidate, "utf8") <= MAX_FRAME_BYTES) {
+            accepted.push(part);
+        }
+    }
+    line = serializeAgentStreamFrame({
+        ...frame,
+        parts: [...accepted, failure],
+    });
+    return Buffer.byteLength(line, "utf8") <= MAX_FRAME_BYTES
+        ? line
+        : serializeAgentStreamFrame({ kind: "finish", metadata: { truncated: true } });
+}
+function serializeFinishWithCappedText(frame, finalText) {
+    if (finalText === undefined)
+        return serializeAgentStreamFrame(frame);
+    const complete = serializeAgentStreamFrame({ ...frame, finalText });
+    if (Buffer.byteLength(complete, "utf8") <= MAX_FRAME_BYTES)
+        return complete;
+    const suffix = "… [truncated]";
+    const text = largestTextThatFits(finalText, (candidate) => serializeAgentStreamFrame({
+        ...frame,
+        finalText: `${candidate}${suffix}`,
+    }));
+    return serializeAgentStreamFrame({ ...frame, finalText: `${text}${suffix}` });
+}
+function compactFinishMetadata(metadata) {
+    if (metadata === undefined)
+        return undefined;
+    const compact = { truncated: true };
+    for (const key of ["runId", "conversationId", "requestId"]) {
+        const value = metadata[key];
+        if (typeof value === "string")
+            compact[key] = value.slice(0, 512);
+    }
+    return compact;
+}
+function serializeCappedTextFrame(frame) {
+    const suffix = "… [truncated]";
+    if (frame.kind === "error") {
+        const text = largestTextThatFits(frame.message, (candidate) => serializeAgentStreamFrame({
+            ...frame,
+            message: `${candidate}${suffix}`,
+        }));
+        return serializeAgentStreamFrame({ ...frame, message: `${text}${suffix}` });
+    }
+    const text = largestTextThatFits(frame.text, (candidate) => serializeAgentStreamFrame({
+        ...frame,
+        text: `${candidate}${suffix}`,
+    }));
+    return serializeAgentStreamFrame({ ...frame, text: `${text}${suffix}` });
+}
+function splitTextForWireFrame(kind, text) {
+    if (text.length === 0)
+        return [""];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        const chunk = largestTextThatFits(remaining, (candidate) => serializeAgentStreamFrame({ kind, delta: candidate }));
+        if (chunk.length === 0)
+            break;
+        chunks.push(chunk);
+        remaining = remaining.slice(chunk.length);
+    }
+    return chunks;
+}
+function largestTextThatFits(text, serialize) {
+    let lower = 0;
+    let upper = text.length;
+    let best = "";
+    while (lower <= upper) {
+        let length = Math.floor((lower + upper) / 2);
+        if (length > 0 && isHighSurrogate(text.charCodeAt(length - 1)))
+            length -= 1;
+        const candidate = text.slice(0, length);
+        if (Buffer.byteLength(serialize(candidate), "utf8") <= MAX_FRAME_BYTES) {
+            best = candidate;
+            lower = Math.max(lower + 1, length + 1);
+        }
+        else {
+            upper = length - 1;
+        }
+    }
+    return best;
+}
+function isHighSurrogate(code) {
+    return code >= 0xd800 && code <= 0xdbff;
+}
 function serializeUnknown(value) {
     return typeof value === "string" ? value : JSON.stringify(value) ?? "";
 }
 function truncatePreparedText(text, cap) {
     return text.length > cap ? `${text.slice(0, cap)}… [truncated]` : text;
 }
+function setReplyArtifactHeaders(res, attachment) {
+    const asciiName = attachment.name
+        .replace(/[^\x20-\x7e]/gu, "_")
+        .replace(/["\\]/gu, "_")
+        .slice(0, 180) || "attachment";
+    const encodedName = encodeURIComponent(attachment.name).replace(/['()*]/gu, (character) => `%${character.codePointAt(0).toString(16).toUpperCase()}`);
+    res.status(200);
+    const risky = /^(?:text\/(?:html|javascript|xml)|application\/(?:javascript|xhtml\+xml|xml)|image\/svg\+xml)$/iu
+        .test(attachment.mediaType);
+    res.setHeader("Content-Type", risky ? "application/octet-stream" : attachment.mediaType);
+    if (risky)
+        res.setHeader("X-Original-Content-Type", attachment.mediaType);
+    res.setHeader("Content-Length", String(attachment.sizeBytes));
+    res.setHeader("Accept-Ranges", "none");
+    res.setHeader("Content-Disposition", `attachment; filename="${asciiName}"; filename*=UTF-8''${encodedName}`);
+    res.setHeader("Cache-Control", "private, no-store, max-age=0");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Content-Security-Policy", "sandbox; default-src 'none'; base-uri 'none'; form-action 'none'");
+    res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+    res.setHeader("X-Mono-Agent-Integrity-Id", attachment.integrityId);
+}
+async function writeBinaryChunk(res, chunk) {
+    if (res.destroyed || res.writableEnded)
+        throw new Error("Reply artifact client disconnected.");
+    if (res.write(Buffer.from(chunk)))
+        return;
+    await new Promise((resolveDrain, rejectDrain) => {
+        const cleanup = () => {
+            clearTimeout(timer);
+            res.off("drain", onDrain);
+            res.off("close", onClose);
+            res.off("error", onError);
+        };
+        const onDrain = () => { cleanup(); resolveDrain(); };
+        const onClose = () => { cleanup(); rejectDrain(new Error("Reply artifact client disconnected.")); };
+        const onError = (error) => { cleanup(); rejectDrain(error); };
+        const timer = setTimeout(() => {
+            cleanup();
+            rejectDrain(new Error("Reply artifact response did not drain in time."));
+        }, REPLY_ARTIFACT_DRAIN_TIMEOUT_MS);
+        res.once("drain", onDrain);
+        res.once("close", onClose);
+        res.once("error", onError);
+    });
+}
+function normalizeMcpAppIdentity(req) {
+    const conversationId = normalizeOptionalString(typeof req.params.conversationId === "string" ? req.params.conversationId : undefined);
+    const invocationId = normalizeOptionalString(typeof req.params.invocationId === "string" ? req.params.invocationId : undefined);
+    const connectionId = normalizeOptionalString(req.header("x-mono-agent-mcp-connection-id"));
+    if (conversationId === undefined
+        || invocationId === undefined
+        || connectionId === undefined
+        || Buffer.byteLength(conversationId, "utf8") > MAX_MCP_APP_IDENTITY_BYTES
+        || Buffer.byteLength(invocationId, "utf8") > MAX_MCP_APP_IDENTITY_BYTES
+        || Buffer.byteLength(connectionId, "utf8") > MAX_MCP_APP_IDENTITY_BYTES)
+        return undefined;
+    return { conversationId, invocationId, connectionId };
+}
+function setPrivateMcpAppHeaders(res) {
+    res.setHeader("Cache-Control", "private, no-store, max-age=0");
+    res.setHeader("X-Content-Type-Options", "nosniff");
+    res.setHeader("Content-Security-Policy", "default-src 'none'; base-uri 'none'; frame-ancestors 'none'");
+    res.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+}
+function sendMcpAppError(res, error) {
+    const code = codeOf(error);
+    const status = code === "app_forbidden" || code === "app_missing" || code === "app_expired"
+        ? 404
+        : code === "app_request_too_large" ? 413
+            : code === "app_tool_forbidden" || code === "app_resource_forbidden" || code === "app_open_link_forbidden" ? 403
+                : code === "app_confirmation_required" ? 409
+                    : code === "app_audit_incomplete" ? 409
+                        : code === "app_rate_limited" ? 429
+                            : code === "app_connection_closed" ? 410
+                                : code === "app_audit_failed" ? 507
+                                    : 500;
+    setPrivateMcpAppHeaders(res);
+    sendJsonError(res, status, error);
+}
 function normalizeVerbatimBody(rawConversationId, body) {
     const conversationId = normalizeOptionalString(typeof rawConversationId === "string" ? rawConversationId : undefined);
     if (conversationId === undefined) {
@@ -753,6 +1349,56 @@ async function resolveInfo(info) {
     }
     return info;
 }
+function cronJobId(value) {
+    const raw = typeof value === "string" ? value : undefined;
+    const jobId = normalizeOptionalString(raw);
+    if (jobId === undefined || Buffer.byteLength(jobId, "utf8") > 512) {
+        throw new CronOperatorError("invalid_request", "A valid cron job id is required.", 400);
+    }
+    return jobId;
+}
+function cronRunId(value) {
+    const raw = typeof value === "string" ? value : undefined;
+    const runId = normalizeOptionalString(raw);
+    if (runId === undefined || Buffer.byteLength(runId, "utf8") > 4_096) {
+        throw new CronOperatorError("invalid_request", "A valid cron run id is required.", 400);
+    }
+    return runId;
+}
+function cronActionInput(value) {
+    if (!isRecord(value)) {
+        throw new CronOperatorError("invalid_request", "A JSON action body is required.", 400);
+    }
+    const idempotencyKey = normalizeOptionalString(typeof value.idempotencyKey === "string" ? value.idempotencyKey : undefined);
+    if (idempotencyKey === undefined || Buffer.byteLength(idempotencyKey, "utf8") > 256) {
+        throw new CronOperatorError("invalid_request", "A valid idempotencyKey is required.", 400);
+    }
+    const confirmationToken = normalizeOptionalString(typeof value.confirmationToken === "string" ? value.confirmationToken : undefined);
+    if (confirmationToken !== undefined && Buffer.byteLength(confirmationToken, "utf8") > 1_024) {
+        throw new CronOperatorError("invalid_request", "confirmationToken is too large.", 400);
+    }
+    return { idempotencyKey, ...(confirmationToken === undefined ? {} : { confirmationToken }) };
+}
+function requireCronActionKey(res, apiKey) {
+    if (apiKey !== undefined)
+        return true;
+    sendJsonError(res, 403, new CronOperatorError("actions_disabled", "Cron actions require an operator API key.", 403));
+    return false;
+}
+function sendCronMutation(res, result) {
+    if (result.kind === "confirmation_required") {
+        sendBoundedCronJson(res, 428, result);
+        return;
+    }
+    sendBoundedCronJson(res, 200, result);
+}
+function sendBoundedCronJson(res, status, value) {
+    const serialized = JSON.stringify(value);
+    if (Buffer.byteLength(serialized, "utf8") > MAX_CRON_OPERATOR_RESPONSE_BYTES) {
+        throw new CronOperatorError("unavailable", "Cron operator response exceeded its bounded wire contract.", 503);
+    }
+    res.status(status).type("application/json").send(serialized);
+}
 function authorize(req, res, apiKey) {
     if (apiKey === undefined) {
         return true;
@@ -772,6 +1418,64 @@ function sendJsonError(res, status, error) {
         },
     });
 }
+function sendBoundedJobs(res, jobs) {
+    const body = serializeBoundedJobs(jobs);
+    if (body === undefined) {
+        sendJsonError(res, 413, new TuiAdapterError("process_job_response_too_large", `Process-job list exceeds the ${String(MAX_PROCESS_JOBS_RESPONSE_BYTES)}-byte operator response bound.`));
+        return;
+    }
+    res.status(200).type("application/json").send(body);
+}
+function serializeBoundedJobs(jobs) {
+    const parsed = parseProcessJobProjections(jobs);
+    const selected = new Map();
+    let selectedCount = 0;
+    let bodyBytes = Buffer.byteLength('{"jobs":[]}', "utf8");
+    const add = (index, projection) => {
+        const serialized = JSON.stringify(projection);
+        const nextBytes = bodyBytes
+            + Buffer.byteLength(serialized, "utf8")
+            + (selectedCount === 0 ? 0 : 1);
+        if (nextBytes > MAX_PROCESS_JOBS_RESPONSE_BYTES)
+            return false;
+        selected.set(index, serialized);
+        selectedCount += 1;
+        bodyBytes = nextBytes;
+        return true;
+    };
+    // The app can retain up to 32 starting/running and 64 queued records
+    // alongside its terminal ceiling. Keep that complete control-plane view
+    // even when large terminal projections require a smaller HTTP representation.
+    for (const [index, projection] of parsed.entries()) {
+        if (isActiveProcessJobProjection(projection) && !add(index, projection))
+            return undefined;
+    }
+    // Service lists are already newest-first. Select one deterministic terminal
+    // prefix so a larger byte budget can only extend, never reshuffle, history.
+    for (const [index, projection] of parsed.entries()) {
+        if (isActiveProcessJobProjection(projection))
+            continue;
+        if (!add(index, projection))
+            break;
+    }
+    const serialized = [...selected.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([, projection]) => projection);
+    return `{"jobs":[${serialized.join(",")}]}`;
+}
+function isActiveProcessJobProjection(projection) {
+    return projection.state === "queued"
+        || projection.state === "starting"
+        || projection.state === "running";
+}
+function sendBoundedJob(res, job) {
+    const body = JSON.stringify(parseProcessJobProjection(job));
+    if (Buffer.byteLength(body, "utf8") > MAX_PROCESS_JOBS_RESPONSE_BYTES) {
+        sendJsonError(res, 413, new TuiAdapterError("process_job_response_too_large", `Process-job projection exceeds the ${String(MAX_PROCESS_JOBS_RESPONSE_BYTES)}-byte operator response bound.`));
+        return;
+    }
+    res.status(200).type("application/json").send(body);
+}
 function codeOf(error) {
     const candidate = error?.code;
     return typeof candidate === "string" ? candidate : undefined;