@skrr-ai/cli 0.1.8

package/dist/commands/agent/message/send.js

@@ -0,0 +1,1055 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXIT_DELIVERY_FAILED = exports.EXIT_DELIVERY_RETRYABLE = exports.OWNER_DM_SEGMENTATION_SOFT_LIMIT = void 0;
+exports.messageSegmentationAdvisory = messageSegmentationAdvisory;
+exports.buildSequencedRequests = buildSequencedRequests;
+exports.deliveryExitCode = deliveryExitCode;
+exports.sequenceHalt = sequenceHalt;
+exports.rejectPrincipalOverrides = rejectPrincipalOverrides;
+exports.normalizeIntentPayload = normalizeIntentPayload;
+exports.generateIdempotencyKey = generateIdempotencyKey;
+exports.buildEnvelope = buildEnvelope;
+exports.formatEnvelope = formatEnvelope;
+const crypto = __importStar(require("node:crypto"));
+const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
+const base_command_1 = require("../../../base-command");
+const agent_resolver_1 = require("../../../lib/agent-resolver");
+const cli_runtime_1 = require("../../../lib/cli-runtime");
+const message_intent_1 = require("../../../lib/message-intent");
+const entity_embeds_1 = require("../../../lib/entity-embeds");
+const prompt_1 = require("../../../lib/prompt");
+const MAX_TEXT_CHARS = 20000;
+const MAX_IDEMPOTENCY_KEY_CHARS = 240;
+const MAX_SEQUENCE_PARTS = data_provider_1.MAX_AGENT_MESSAGE_SEQUENCE_PARTS;
+/**
+ * A reading-comfort prompt, not a protocol limit. The Gateway deliberately
+ * permits much larger payloads; the sender remains responsible for choosing
+ * meaningful conversational boundaries.
+ */
+exports.OWNER_DM_SEGMENTATION_SOFT_LIMIT = 320;
+const PROTOCOL_VERSION = 1;
+/**
+ * Canonical CLI entry for agent-authored messages.
+ *
+ * The command's principal kind is derived exclusively from the caller's
+ * credential — a session credential (`OVERSKY_SESSION_TOKEN`) selects the
+ * autonomous session Gateway path; every other resolved credential is a
+ * human. There is deliberately no flag that can force one path over the
+ * other; a `principalKind` field in the JSON payload is rejected so that
+ * a compromised producer cannot elevate itself into a session principal.
+ */
+class AgentMessageSend extends base_command_1.BaseCommand {
+    static description = 'Submit a channel-neutral agent message intent through the ProactiveMessageGateway';
+    static examples = [
+        '<%= config.bin %> agent message send --from-json payload.json --json',
+        '<%= config.bin %> agent message send --from-json - --json',
+        '<%= config.bin %> agent message send --agent <agent-id> --text "Done" --json',
+        // The key carries the task id because dedup is scoped (owner, agent, key)
+        // for all time — a bare `checkpoint:verify` collides on the next run.
+        '<%= config.bin %> agent message send --agent <agent-id> --kind milestone --idempotency-key <task-id>:verify --text "Implementation is complete." --part "Verification is in progress." --json',
+        '<%= config.bin %> agent message send --agent <agent-id> --destination slack_channel --channel C123 --text "Update" --json',
+    ];
+    static args = {
+        agent: core_1.Args.string({
+            description: 'Agent ID. Optional when OVERSKY_SESSION_AGENT_ID/OVERSKY_AGENT_ID is set or exactly one agent exists.',
+            ignoreStdin: true,
+            required: false,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({
+            description: 'Emit the stable machine envelope on stdout',
+        }),
+        agent: core_1.Flags.string({
+            description: 'Agent ID. Prefer this over the positional argument in scripts',
+        }),
+        text: core_1.Flags.string({
+            char: 'm',
+            description: 'Message text; overrides content.text from --from-json',
+        }),
+        part: core_1.Flags.string({
+            description: 'A following short message in the same human-scale update; repeatable and requires --idempotency-key. Stops if an earlier part does not reach the user',
+            multiple: true,
+        }),
+        'message-lint': core_1.Flags.boolean({
+            description: 'Show a stderr advisory when a long owner DM may read better as a short --part sequence',
+            allowNo: true,
+            default: true,
+        }),
+        destination: core_1.Flags.string({
+            description: 'Destination kind for the canonical intent',
+            options: [...message_intent_1.CANONICAL_DESTINATION_KINDS],
+        }),
+        channel: core_1.Flags.string({
+            description: 'Slack channel ID (only meaningful with --destination slack_channel)',
+        }),
+        'thread-ts': core_1.Flags.string({
+            description: 'Slack thread timestamp for slack_channel destinations',
+        }),
+        'thread-root': core_1.Flags.string({
+            description: 'Agent Chat Thread root message ID for app_owner_dm. Do not use this for Slack; use --thread-ts.',
+        }),
+        'from-json': core_1.Flags.string({
+            description: 'Path to a canonical intent JSON payload, or "-" for stdin',
+        }),
+        'idempotency-key': core_1.Flags.string({
+            description: 'Stable retry key for this intent; auto-derived when omitted',
+        }),
+        kind: core_1.Flags.string({
+            description: 'Semantic kind; prefer milestone, status, decision, blocker, or result (legacy progress/question accepted)',
+            options: [...message_intent_1.COMMUNICATION_KIND_INPUTS],
+        }),
+        phase: core_1.Flags.string({ description: 'Optional execution phase label' }),
+        title: core_1.Flags.string({ description: 'Optional concise card title' }),
+        importance: core_1.Flags.string({
+            description: 'Legacy app-DM attention alias; prefer --attention',
+            options: ['ambient', 'normal', 'urgent'],
+        }),
+        attention: core_1.Flags.string({
+            description: 'Requested app-DM attention: ambient, notify, or interrupt; user policy chooses reach and device presentation',
+            options: ['ambient', 'notify', 'interrupt'],
+        }),
+        'requires-response': core_1.Flags.boolean({
+            description: 'Mark the communication as requiring a user response',
+            allowNo: true,
+        }),
+        'notification-policy': core_1.Flags.string({
+            description: 'Legacy app-DM reach ceiling; silent limits delivery to in-app and normal is neutral',
+            options: ['normal', 'silent'],
+        }),
+        'attach-task-card': core_1.Flags.boolean({
+            description: 'Render the trusted task context as a live card in an app-owner DM',
+            allowNo: true,
+        }),
+        task: core_1.Flags.string({
+            description: 'Manual-tool task context; managed sessions derive this server-side',
+        }),
+        space: core_1.Flags.string({ description: 'Optional space context for manual tools' }),
+        goal: core_1.Flags.string({ description: 'Optional goal context for manual tools' }),
+        embed: core_1.Flags.string({
+            description: (0, data_provider_1.describeEmbedGrammar)(),
+            multiple: true,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(AgentMessageSend);
+        const sessionContext = (0, message_intent_1.resolveMessageCommandSessionContext)({
+            requireHumanAuth: () => this.requireAuth(),
+        });
+        const jsonBody = await this.readPayload(flags['from-json']);
+        rejectPrincipalOverrides(jsonBody, {
+            failWithCliError: (opts) => this.failWithCliError(opts),
+        });
+        const merged = (0, prompt_1.mergeDefined)(jsonBody, {
+            agentId: flags.agent,
+            text: flags.text,
+            destinationKind: flags.destination,
+            channelId: flags.channel,
+            threadTs: flags['thread-ts'],
+            threadRootMessageId: flags['thread-root'],
+            idempotencyKey: flags['idempotency-key'],
+            communicationKind: flags.kind,
+            phase: flags.phase,
+            title: flags.title,
+            attention: flags.attention,
+            importance: flags.importance,
+            requiresResponse: booleanFlagInput(this.argv, 'requires-response', flags['requires-response']),
+            notificationPolicy: flags['notification-policy'],
+            attachTaskCard: booleanFlagInput(this.argv, 'attach-task-card', flags['attach-task-card']),
+            taskId: flags.task,
+            spaceId: flags.space,
+            goalId: flags.goal,
+        });
+        let agentIdentity;
+        try {
+            const explicitAgentId = resolveAgentInput(args.agent, flags.agent, merged, jsonBody);
+            agentIdentity = sessionContext
+                ? (0, agent_resolver_1.resolveSessionAgentIdentity)(explicitAgentId)
+                : await (0, agent_resolver_1.resolveAgentIdentity)(explicitAgentId);
+        }
+        catch (err) {
+            const failure = (0, agent_resolver_1.agentResolutionFailure)(err);
+            this.failWithCliError({
+                message: failure.message,
+                code: failure.code,
+                exit: 2,
+                retryable: false,
+                details: {
+                    suggestion: failure.suggestion,
+                    ...(failure.details ? failure.details : {}),
+                },
+            });
+        }
+        const agentId = agentIdentity.id;
+        let payload;
+        try {
+            payload = normalizeIntentPayload({ agentId, jsonBody, merged });
+        }
+        catch (err) {
+            this.failWithCliError({
+                message: err.message,
+                code: err.code || 'INVALID_MESSAGE_INTENT',
+                exit: 1,
+                retryable: false,
+            });
+        }
+        const segmentationAdvisory = messageSegmentationAdvisory({
+            destination: payload.destination,
+            text: payload.content.text,
+            followingParts: flags.part || [],
+        });
+        if (flags['message-lint'] && segmentationAdvisory)
+            this.warn(segmentationAdvisory);
+        // Resolve BEFORE the first send. A sequence that fails on part 2 because of
+        // a typo'd embed would have already delivered part 1, and a delivered
+        // message cannot be taken back.
+        let embeds = [];
+        try {
+            embeds = await (0, entity_embeds_1.resolveEmbedFlag)(flags.embed, {
+                resolveSpace: (ref) => this.resolveSpaceReference(ref),
+                resolveTask: (ref) => this.resolveTaskReference(ref),
+                // `--space` is already resolved to an id by BaseCommand.parse.
+                fallbackSpaceId: flags.space ||
+                    process.env.OVERSKY_SESSION_SPACE_ID?.trim() ||
+                    process.env.OVERSKY_SPACE_ID?.trim(),
+            });
+        }
+        catch (error) {
+            if (error instanceof entity_embeds_1.EmbedResolutionError) {
+                this.failWithCliError({
+                    message: error.message,
+                    code: error.code,
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            throw error;
+        }
+        const idempotencyKey = payload.idempotencyKey || generateIdempotencyKey(agentId, payload);
+        const request_ = canonicalIntentFromDestination({
+            agentId,
+            idempotencyKey,
+            destination: payload.destination,
+            text: payload.content.text,
+            presentation: payload.presentation,
+            notificationPolicy: payload.notificationPolicy,
+            context: payload.context,
+            threadRootMessageId: payload.threadRootMessageId,
+            embeds,
+        });
+        let requests;
+        try {
+            requests = buildSequencedRequests(request_, flags.part || [], Boolean(payload.idempotencyKey));
+        }
+        catch (error) {
+            this.failWithCliError({
+                message: error.message,
+                code: 'INVALID_MESSAGE_SEQUENCE',
+                exit: 1,
+                retryable: false,
+            });
+        }
+        const principalSource = sessionContext
+            ? 'OVERSKY_SESSION_TOKEN'
+            : this.resolvedCredential.source;
+        // `--workspace` sets the X-Workspace-Id header, which an Agent session
+        // ignores: its workspace comes from the server-side session claim, which the
+        // caller cannot influence (deliberately — it is a tenancy claim). Passing the
+        // flag here therefore changes nothing, and silence makes it look like a fix
+        // that was tried and did not work rather than one that never applied.
+        if (sessionContext && flags.workspace) {
+            this.warn('--workspace is ignored inside an Agent session: the workspace comes from the ' +
+                'session claim, not the request. To change it, run the task from a space in ' +
+                'the intended workspace.');
+        }
+        const envelopes = [];
+        let halt;
+        for (const [index, requestPart] of requests.entries()) {
+            const envelope = sessionContext
+                ? await this.submitAsSession({
+                    sessionContext,
+                    request: requestPart,
+                    agentIdentity: agentIdentity,
+                    principalSource,
+                })
+                : await this.submitAsHuman({
+                    request: requestPart,
+                    agentIdentity: agentIdentity,
+                    principalSource,
+                });
+            envelopes.push(envelope);
+            // A part that did not reach the user must stop the sequence. Continuing
+            // would deliver thought 3 while thought 2 sits held for approval, and the
+            // user would read the update out of order — worse than not receiving the
+            // tail at all.
+            halt = sequenceHalt({ envelope, sentCount: index + 1, totalParts: requests.length });
+            if (halt)
+                break;
+        }
+        if (flags.json) {
+            // Branch on the REQUESTED part count, not the sent count: a sequence that
+            // halted on its first part still has to report the parts it skipped.
+            this.log(JSON.stringify(requests.length === 1
+                ? envelopes[0]
+                : {
+                    ok: envelopes.every((envelope) => envelope.ok) && !halt,
+                    sequenceId: idempotencyKey,
+                    parts: envelopes,
+                    ...(halt ? { halt } : {}),
+                }, null, 2));
+            this.exitForDelivery(envelopes);
+            return;
+        }
+        for (const envelope of envelopes)
+            this.log(formatEnvelope(envelope));
+        // Always printed, never swallowed: a dropped embed is the difference
+        // between "the card did not render" and "the card was never sent", and
+        // only the author can act on it.
+        const rejectionReport = (0, entity_embeds_1.formatEmbedRejections)(envelopes.flatMap((envelope) => envelope.embedRejections ?? []));
+        if (rejectionReport)
+            this.warn(rejectionReport);
+        if (halt)
+            this.log(formatHalt(halt));
+        this.exitForDelivery(envelopes);
+    }
+    /**
+     * Set the process exit code from the delivery outcome, AFTER the envelope has
+     * been written. The envelope is the diagnostic and must reach stdout whether
+     * or not the send succeeded; the exit code is the signal a script branches on.
+     *
+     * No-ops on success so the normal path still returns cleanly.
+     */
+    exitForDelivery(envelopes) {
+        const code = deliveryExitCode(envelopes);
+        if (code !== 0)
+            this.exit(code);
+    }
+    async readPayload(source) {
+        if (!source)
+            return {};
+        try {
+            return await (0, prompt_1.readJsonBody)(source);
+        }
+        catch (err) {
+            this.failWithCliError({
+                message: err.message,
+                code: 'INVALID_JSON_INPUT',
+                exit: 1,
+                retryable: false,
+            });
+        }
+    }
+    async submitAsSession({ sessionContext, request, agentIdentity, principalSource, }) {
+        let result;
+        try {
+            result = await (0, message_intent_1.submitSessionMessageIntent)({ context: sessionContext, request });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'MessageIntentCliError') {
+                this.failWithCliError({
+                    message: err.message,
+                    code: err.code || 'MESSAGE_INTENT_ERROR',
+                    exit: 2,
+                    retryable: false,
+                });
+            }
+            this.handleApiError(err);
+        }
+        return buildEnvelope({
+            ok: result.ok !== false,
+            principalKind: 'session',
+            principalSource,
+            transport: 'gateway',
+            server: this.cliConfig?.baseURL ?? null,
+            agent: agentIdentity,
+            destination: request.destination,
+            content: request.content,
+            idempotencyKey: request.idempotencyKey,
+            threadRootMessageId: request.threadRootMessageId,
+            presentation: request.presentation,
+            notificationPolicy: request.notificationPolicy,
+            embeds: request.embeds,
+            embedRejections: result.embedRejections,
+            intent: {
+                id: result.intentId ?? null,
+                status: result.status || 'submitted',
+                reason: result.reason,
+                retryAfter: result.retryAfter,
+                retryable: result.retryable,
+                initiativeId: result.initiativeId,
+                ownerInterjected: result.ownerInterjected,
+            },
+        });
+    }
+    async submitAsHuman({ request, agentIdentity, principalSource, }) {
+        const server = this.cliConfig?.baseURL ?? null;
+        const commandSource = (0, cli_runtime_1.buildCliSourceMetadata)({
+            commandId: this.id,
+            rootDir: this.config.root,
+        });
+        if (request.destination.kind === 'app_owner_dm') {
+            let result;
+            try {
+                result = await data_provider_1.dataService.sendAgentDmMessage(request.agentId, {
+                    text: request.content.text,
+                    idempotencyKey: request.idempotencyKey,
+                    source: commandSource,
+                    presentation: request.presentation,
+                    notificationPolicy: request.notificationPolicy,
+                    ...(request.sequence ? { sequence: request.sequence } : {}),
+                    ...(request.threadRootMessageId
+                        ? { threadRootMessageId: request.threadRootMessageId }
+                        : {}),
+                    ...(request.embeds && request.embeds.length > 0 ? { embeds: request.embeds } : {}),
+                    ...(request.context || {}),
+                });
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            return buildEnvelope({
+                ok: result.success !== false,
+                principalKind: 'human',
+                principalSource,
+                transport: 'legacy_dm',
+                server,
+                agent: agentIdentity,
+                destination: request.destination,
+                content: request.content,
+                idempotencyKey: request.idempotencyKey,
+                threadRootMessageId: request.threadRootMessageId,
+                presentation: request.presentation,
+                notificationPolicy: request.notificationPolicy,
+                embeds: request.embeds,
+                embedRejections: result.embedRejections,
+                intent: {
+                    id: result.messageId ?? null,
+                    status: statusFromLegacyDm(result),
+                    reason: result.reason,
+                },
+            });
+        }
+        if (request.destination.kind === 'slack_channel') {
+            let result;
+            try {
+                result = (await request_post(`/api/slack/agents/${encodeURIComponent(request.agentId)}/messages`, {
+                    targetType: 'channel',
+                    targetId: request.destination.channelId,
+                    text: request.content.text,
+                    ...(request.destination.threadTs ? { threadTs: request.destination.threadTs } : {}),
+                    idempotencyKey: request.idempotencyKey,
+                    source: commandSource,
+                }));
+            }
+            catch (err) {
+                this.handleApiError(err);
+            }
+            return buildEnvelope({
+                ok: result.ok !== false,
+                principalKind: 'human',
+                principalSource,
+                transport: 'legacy_slack',
+                server,
+                agent: agentIdentity,
+                destination: request.destination,
+                content: request.content,
+                idempotencyKey: request.idempotencyKey,
+                presentation: request.presentation,
+                notificationPolicy: request.notificationPolicy,
+                embeds: request.embeds,
+                intent: {
+                    id: result.deliveryId ?? null,
+                    status: result.duplicate ? 'duplicate' : 'delivered',
+                },
+            });
+        }
+        // slack_owner_dm is a Gateway-only destination: it applies workspace-scoped
+        // owner routing that no legacy human transport can enact.
+        this.failWithCliError({
+            message: 'Destination "slack_owner_dm" is only available inside an Agent session (OVERSKY_SESSION_TOKEN). ' +
+                'Run the command from a daemon session, or pick "app_owner_dm" / "slack_channel" for human calls.',
+            code: 'HUMAN_DESTINATION_UNSUPPORTED',
+            exit: 2,
+            retryable: false,
+        });
+    }
+}
+exports.default = AgentMessageSend;
+// Re-export the module-scope `request.post` under a local name so the transport
+// helper stays testable without pulling the whole data-provider surface into
+// scope inside every helper file.
+function request_post(path, body) {
+    return data_provider_1.request.post(path, body);
+}
+/**
+ * Keep segmentation a sender decision: this advisory must never rewrite,
+ * reject, or automatically split the text. It only covers private owner DMs,
+ * where a chat-like reading cadence is normally expected.
+ */
+function messageSegmentationAdvisory({ destination, text, followingParts, }) {
+    if (followingParts.length > 0)
+        return undefined;
+    if (destination.kind !== 'app_owner_dm' && destination.kind !== 'slack_owner_dm')
+        return undefined;
+    if (text.length <= exports.OWNER_DM_SEGMENTATION_SOFT_LIMIT)
+        return undefined;
+    return (`[sky] Owner-DM message is ${text.length} characters. It may read better as 2–4 short thoughts: ` +
+        'use --part with one explicit --idempotency-key. This is only an advisory; ' +
+        'use --no-message-lint to suppress it.');
+}
+/**
+ * Preserve the caller's semantic boundary while allowing them to send a few
+ * naturally separate short messages. A sequence is never automatic: the model
+ * chooses its boundaries, and retries remain safe because every part is derived
+ * from one explicit semantic idempotency key.
+ */
+function buildSequencedRequests(request, followingParts, hasExplicitIdempotencyKey) {
+    const parts = [request.content.text, ...followingParts].map((part) => requireText(part, 'part'));
+    if (parts.length === 1)
+        return [request];
+    if (parts.length > MAX_SEQUENCE_PARTS) {
+        throw new Error(`A multi-message update may contain at most ${MAX_SEQUENCE_PARTS} parts.`);
+    }
+    if (!hasExplicitIdempotencyKey) {
+        throw new Error('A multi-message update requires an explicit --idempotency-key for safe retries.');
+    }
+    return parts.map((text, index) => ({
+        ...request,
+        content: { text },
+        idempotencyKey: sequencePartKey(request.idempotencyKey, index),
+        sequence: sequenceMetadata(request.idempotencyKey, index, parts.length),
+    }));
+}
+function sequenceMetadata(id, index, count) {
+    return { id, index: index + 1, count };
+}
+/**
+ * Statuses under which this thought either reached the user or is committed to,
+ * in order. Anything else means the user has not read part N, so parts N+1…
+ * must not be sent ahead of it.
+ *
+ * `duplicate` continues: the part was already accepted under this same key by
+ * an earlier attempt, so the ordering it established still holds.
+ */
+const SEQUENCE_CONTINUING_STATUSES = new Set([
+    'submitted',
+    'authorized',
+    'dispatching',
+    'delivered',
+    'duplicate',
+    'queued_offline',
+]);
+/**
+ * Statuses that mean the message will never reach the user without a new send.
+ *
+ * Deliberately narrower than "not in SEQUENCE_CONTINUING_STATUSES": `held` and
+ * `approval_required` are the approval workflow behaving correctly, not
+ * failures, so they keep exit 0 and report themselves in the envelope. These
+ * four are terminal non-delivery.
+ */
+const DELIVERY_FAILURE_STATUSES = new Set([
+    'failed',
+    'dropped',
+    'expired',
+    'cancelled',
+]);
+/**
+ * Exit codes for a submitted-but-undelivered message.
+ *
+ * The command used to exit 0 whenever the transport ACCEPTED the request, even
+ * when the enclosed intent reported `status: "failed"`. The exit code is the
+ * only failure signal a shell script or a non-JSON-parsing agent has, so
+ * `sky ... || handle_failure` never fired and callers reported "sent" for
+ * messages that were never delivered.
+ *
+ * Two codes rather than one because the correct response differs: a retryable
+ * failure is worth re-attempting, a terminal one can only be fixed by changing
+ * the request. CLI-level rejections keep their existing 1 / 2.
+ */
+exports.EXIT_DELIVERY_RETRYABLE = 3;
+exports.EXIT_DELIVERY_FAILED = 4;
+/**
+ * Decide the process exit code from the envelopes actually produced.
+ *
+ * @returns 0 when every part is delivered or safely in flight; otherwise the
+ *   exit code for the FIRST failing part, since that is the one that halted the
+ *   sequence and the one whose reason explains the outcome.
+ */
+function deliveryExitCode(envelopes) {
+    for (const envelope of envelopes) {
+        const failed = !envelope.ok || DELIVERY_FAILURE_STATUSES.has(envelope.intent.status);
+        if (!failed)
+            continue;
+        // `retryable` is only meaningful when the server said so. An absent flag is
+        // treated as terminal: telling a caller to retry something that cannot
+        // succeed is worse than making it look at the reason.
+        return envelope.intent.retryable === true ? exports.EXIT_DELIVERY_RETRYABLE : exports.EXIT_DELIVERY_FAILED;
+    }
+    return 0;
+}
+/**
+ * Decide whether a sequence stops after this part. Returns `undefined` when the
+ * sequence may continue — including for the final part, where there is nothing
+ * left to withhold and reporting a halt would be noise.
+ */
+function sequenceHalt({ envelope, sentCount, totalParts, }) {
+    if (totalParts < 2 || sentCount >= totalParts)
+        return undefined;
+    // The owner replying mid-update is a halt for the same reason a failed
+    // delivery is: the remaining parts would land after their turn, so the
+    // thought arrives split around something the agent has not read yet.
+    // Delivery of the part that reported it still SUCCEEDED.
+    if (envelope.intent.ownerInterjected) {
+        return {
+            sentParts: sentCount,
+            unsentParts: totalParts - sentCount,
+            status: envelope.intent.status,
+            reason: 'owner_replied',
+        };
+    }
+    if (envelope.ok && SEQUENCE_CONTINUING_STATUSES.has(envelope.intent.status))
+        return undefined;
+    return {
+        sentParts: sentCount,
+        unsentParts: totalParts - sentCount,
+        status: envelope.intent.status,
+        ...(envelope.intent.reason ? { reason: envelope.intent.reason } : {}),
+    };
+}
+function formatHalt(halt) {
+    if (halt.reason === 'owner_replied') {
+        return (`Stopped after part ${halt.sentParts}: the user replied while you were still sending. ` +
+            `${halt.unsentParts} later part(s) were not sent. Read what they said before continuing — ` +
+            'the rest of your update may no longer be the right thing to say.');
+    }
+    const because = halt.reason ? `${halt.status} (${halt.reason})` : halt.status;
+    return (`Stopped after part ${halt.sentParts}: ${because}. ` +
+        `${halt.unsentParts} later part(s) were not sent, so the user does not read this update out of order. ` +
+        'Resolve that outcome before continuing the thought.');
+}
+function sequencePartKey(base, index) {
+    const suffix = `:part:${index + 1}`;
+    if (base.length + suffix.length <= MAX_IDEMPOTENCY_KEY_CHARS) {
+        return `${base}${suffix}`;
+    }
+    // Keep the full semantic key represented when fitting the part suffix into
+    // the protocol limit. Simple truncation turns distinct long keys with a
+    // shared prefix into the same retry identity.
+    const digest = crypto.createHash('sha256').update(base).digest('hex').slice(0, 16);
+    const trailer = `:${digest}${suffix}`;
+    return `${base.slice(0, MAX_IDEMPOTENCY_KEY_CHARS - trailer.length)}${trailer}`;
+}
+/**
+ * A caller MUST NOT be able to move themselves between principal kinds by
+ * shoving `principalKind` (or the related principal metadata) into the JSON
+ * payload. The credential resolves the kind; the payload is just data.
+ */
+function rejectPrincipalOverrides(jsonBody, reporter) {
+    for (const field of [
+        'principalKind',
+        'principal',
+        'principalSource',
+        'principalToken',
+    ]) {
+        if (jsonBody[field] !== undefined) {
+            reporter.failWithCliError({
+                message: `--from-json payload must not set "${field}"; principal identity is derived from the caller credential.`,
+                code: 'PRINCIPAL_OVERRIDE_FORBIDDEN',
+                exit: 1,
+                retryable: false,
+            });
+        }
+    }
+}
+function normalizeIntentPayload({ agentId, jsonBody, merged, }) {
+    const presentationInput = jsonBody.presentation &&
+        typeof jsonBody.presentation === 'object' &&
+        !Array.isArray(jsonBody.presentation)
+        ? jsonBody.presentation
+        : {};
+    for (const field of [
+        'deliveryModality',
+        'interruptionLevel',
+        'androidChannelId',
+        'channelId',
+        'sound',
+        'criticalAlert',
+    ]) {
+        if (jsonBody[field] !== undefined || presentationInput[field] !== undefined) {
+            throw invalidIntent(`${field} is user-owned notification policy; send semantic attention instead.`);
+        }
+    }
+    const bodyDestination = readJsonDestination(jsonBody);
+    const overlayKind = optionalString(merged.destinationKind);
+    const overlayChannel = optionalString(merged.channelId);
+    const overlayThreadTs = optionalString(merged.threadTs);
+    const destinationKind = pickDestinationKind({ bodyDestination, overlayKind });
+    const destination = buildDestination({
+        kind: destinationKind,
+        bodyDestination,
+        overlayChannel,
+        overlayThreadTs,
+    });
+    const text = requireText(readTextField(jsonBody, merged), 'content.text');
+    const idempotencyKey = optionalIdempotencyKey(merged.idempotencyKey ??
+        jsonBody.idempotencyKey ??
+        jsonBody['idempotency_key'] ??
+        jsonBody['idempotency-key']);
+    const presentation = normalizePresentation(jsonBody, merged);
+    const notificationPolicy = optionalNotificationPolicy(merged.notificationPolicy ?? jsonBody.notificationPolicy ?? jsonBody.notification_policy);
+    if (destination.kind !== 'app_owner_dm' &&
+        (presentation?.attention || presentation?.importance || notificationPolicy)) {
+        throw invalidIntent('attention, legacy importance, and notificationPolicy only apply to app_owner_dm; Slack delivery does not use the user notification policy.');
+    }
+    const threadRootMessageId = optionalBoundedString(merged.threadRootMessageId ?? jsonBody.threadRootMessageId, 'threadRootMessageId', 240);
+    if (threadRootMessageId && destination.kind !== 'app_owner_dm') {
+        throw invalidIntent('threadRootMessageId only applies to app_owner_dm; use --thread-ts for Slack.');
+    }
+    const jsonContext = jsonBody.context && typeof jsonBody.context === 'object' && !Array.isArray(jsonBody.context)
+        ? jsonBody.context
+        : {};
+    const context = {
+        ...(optionalBoundedString(merged.taskId ?? jsonContext.taskId, 'context.taskId', 240)
+            ? {
+                taskId: optionalBoundedString(merged.taskId ?? jsonContext.taskId, 'context.taskId', 240),
+            }
+            : {}),
+        ...(optionalBoundedString(merged.spaceId ?? jsonContext.spaceId, 'context.spaceId', 240)
+            ? {
+                spaceId: optionalBoundedString(merged.spaceId ?? jsonContext.spaceId, 'context.spaceId', 240),
+            }
+            : {}),
+        ...(optionalBoundedString(merged.goalId ?? jsonContext.goalId, 'context.goalId', 240)
+            ? {
+                goalId: optionalBoundedString(merged.goalId ?? jsonContext.goalId, 'context.goalId', 240),
+            }
+            : {}),
+    };
+    void agentId; // agentId is already resolved before this function fires
+    return {
+        destination,
+        content: { text },
+        idempotencyKey,
+        presentation,
+        notificationPolicy,
+        ...(threadRootMessageId ? { threadRootMessageId } : {}),
+        ...(Object.keys(context).length > 0 ? { context } : {}),
+    };
+}
+function pickDestinationKind({ bodyDestination, overlayKind, }) {
+    const raw = overlayKind || bodyDestination?.kind || 'app_owner_dm';
+    const normalized = String(raw).trim();
+    if (message_intent_1.CANONICAL_DESTINATION_KINDS.includes(normalized)) {
+        return normalized;
+    }
+    throw invalidIntent(`destination.kind must be one of ${message_intent_1.CANONICAL_DESTINATION_KINDS.join(', ')} (got "${normalized}").`);
+}
+function buildDestination({ kind, bodyDestination, overlayChannel, overlayThreadTs, }) {
+    if (kind === 'app_owner_dm' || kind === 'slack_owner_dm') {
+        return { kind };
+    }
+    const channelId = optionalString(overlayChannel ?? bodyDestination?.channelId);
+    if (!channelId) {
+        throw invalidIntent('slack_channel destinations require destination.channelId.');
+    }
+    const threadTs = optionalString(overlayThreadTs ?? bodyDestination?.threadTs);
+    return {
+        kind: 'slack_channel',
+        channelId,
+        ...(threadTs ? { threadTs } : {}),
+    };
+}
+function readJsonDestination(jsonBody) {
+    const raw = jsonBody.destination;
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === 'string')
+        return { kind: raw };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        throw invalidIntent('destination must be an object or a string kind.');
+    }
+    return raw;
+}
+function readTextField(jsonBody, merged) {
+    if (merged.text !== undefined)
+        return merged.text;
+    const contentValue = jsonBody.content;
+    if (typeof contentValue === 'string')
+        return contentValue;
+    if (contentValue && typeof contentValue === 'object' && !Array.isArray(contentValue)) {
+        const record = contentValue;
+        if (typeof record.text === 'string')
+            return record.text;
+    }
+    if (typeof jsonBody.text === 'string')
+        return jsonBody.text;
+    if (typeof jsonBody.message === 'string')
+        return jsonBody.message;
+    return undefined;
+}
+/**
+ * Build the presentation the caller actually declared, or `undefined`.
+ *
+ * Undefined is meaningful downstream: the server derives the default
+ * notification policy from whether a kind was DECLARED, so filling in
+ * `kind: 'status'` here would silence every caller that never opted into
+ * the taxonomy.
+ */
+function normalizePresentation(jsonBody, merged) {
+    const source = jsonBody.presentation &&
+        typeof jsonBody.presentation === 'object' &&
+        !Array.isArray(jsonBody.presentation)
+        ? jsonBody.presentation
+        : {};
+    const declaredKind = optionalString(merged.communicationKind ?? source.kind ?? jsonBody.kind);
+    const rawTaskCard = merged.attachTaskCard ?? source.taskCard;
+    if (rawTaskCard !== undefined && typeof rawTaskCard !== 'boolean') {
+        throw invalidIntent('presentation.taskCard must be a boolean.');
+    }
+    const declaredPresentation = declaredKind ||
+        Object.keys(source).length > 0 ||
+        typeof rawTaskCard === 'boolean' ||
+        [merged.attention, merged.importance, merged.phase, merged.title, merged.requiresResponse].some((value) => value !== undefined);
+    if (!declaredPresentation) {
+        return undefined;
+    }
+    const kind = (0, message_intent_1.normalizeCommunicationKindInput)(declaredKind || 'status');
+    if (!kind) {
+        throw invalidIntent(`presentation.kind must be one of ${message_intent_1.COMMUNICATION_KINDS.join(', ')}.`);
+    }
+    const attention = optionalString(merged.attention ?? source.attention);
+    if (attention && !['ambient', 'notify', 'interrupt'].includes(attention)) {
+        throw invalidIntent('presentation.attention must be ambient, notify, or interrupt.');
+    }
+    const importance = optionalString(merged.importance ?? source.importance);
+    if (attention && importance) {
+        throw invalidIntent('presentation must not set both attention and legacy importance.');
+    }
+    if (importance && !['ambient', 'normal', 'urgent'].includes(importance)) {
+        throw invalidIntent('presentation.importance must be ambient, normal, or urgent.');
+    }
+    const rawRequiresResponse = merged.requiresResponse ?? source.requiresResponse;
+    if (rawRequiresResponse !== undefined && typeof rawRequiresResponse !== 'boolean') {
+        throw invalidIntent('presentation.requiresResponse must be a boolean.');
+    }
+    const phase = optionalBoundedString(merged.phase ?? source.phase, 'presentation.phase', 120);
+    const title = optionalBoundedString(merged.title ?? source.title, 'presentation.title', 240);
+    return {
+        kind,
+        ...(phase ? { phase } : {}),
+        ...(title ? { title } : {}),
+        ...(attention ? { attention: attention } : {}),
+        ...(importance ? { importance: importance } : {}),
+        ...(typeof rawRequiresResponse === 'boolean' ? { requiresResponse: rawRequiresResponse } : {}),
+        ...(typeof rawTaskCard === 'boolean' ? { taskCard: rawTaskCard } : {}),
+    };
+}
+function optionalNotificationPolicy(value) {
+    const normalized = optionalString(value);
+    if (!normalized)
+        return undefined;
+    if (normalized !== 'normal' && normalized !== 'silent') {
+        throw invalidIntent('notificationPolicy must be normal or silent.');
+    }
+    return normalized;
+}
+function optionalBoundedString(value, field, max) {
+    const normalized = optionalString(value);
+    if (!normalized)
+        return undefined;
+    if (normalized.length > max)
+        throw invalidIntent(`${field} must be ${max} characters or less.`);
+    return normalized;
+}
+function booleanFlagInput(argv, name, parsedValue) {
+    if (argv.includes(`--${name}`))
+        return true;
+    if (argv.includes(`--no-${name}`))
+        return false;
+    void parsedValue;
+    return undefined;
+}
+function canonicalIntentFromDestination({ agentId, idempotencyKey, destination, text, presentation, notificationPolicy, context, threadRootMessageId, embeds, }) {
+    switch (destination.kind) {
+        case 'app_owner_dm':
+            return (0, message_intent_1.canonicalAppOwnerDmRequest)({
+                agentId,
+                text,
+                idempotencyKey,
+                presentation,
+                notificationPolicy,
+                threadRootMessageId,
+                embeds,
+                ...context,
+            });
+        case 'slack_owner_dm':
+            return (0, message_intent_1.canonicalSlackOwnerDmRequest)({
+                agentId,
+                text,
+                idempotencyKey,
+                presentation,
+                notificationPolicy,
+                embeds,
+            });
+        case 'slack_channel':
+            return (0, message_intent_1.canonicalSlackChannelRequest)({
+                agentId,
+                text,
+                idempotencyKey,
+                channelId: destination.channelId,
+                threadTs: destination.threadTs,
+                presentation,
+                notificationPolicy,
+                embeds,
+            });
+    }
+}
+function resolveAgentInput(argValue, flagValue, merged, jsonBody) {
+    const fromBody = optionalString(jsonBody.agentId ?? jsonBody.agent);
+    const fromMerged = optionalString(merged.agentId);
+    return (0, agent_resolver_1.mergeExplicitAgentInputs)([
+        { label: 'agent argument', value: argValue },
+        { label: '--agent', value: flagValue },
+        { label: 'agentId in JSON input', value: fromBody ?? fromMerged },
+    ]);
+}
+function requireText(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw invalidIntent(`${field} is required.`);
+    }
+    const normalized = value.trim();
+    if (normalized.length > MAX_TEXT_CHARS) {
+        throw invalidIntent(`${field} must be ${MAX_TEXT_CHARS} characters or less.`);
+    }
+    return normalized;
+}
+function optionalString(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    const normalized = String(value).trim();
+    return normalized || undefined;
+}
+function optionalIdempotencyKey(value) {
+    const normalized = optionalString(value);
+    if (!normalized)
+        return undefined;
+    if (normalized.length > MAX_IDEMPOTENCY_KEY_CHARS) {
+        throw invalidIntent(`idempotencyKey must be ${MAX_IDEMPOTENCY_KEY_CHARS} characters or less.`);
+    }
+    return normalized;
+}
+function generateIdempotencyKey(agentId, payload) {
+    const requestId = optionalString(process.env.OVERSKY_SESSION_REQUEST_ID) ||
+        optionalString(process.env.OVERSKY_REQUEST_ID);
+    const digest = crypto
+        .createHash('sha256')
+        .update(JSON.stringify({
+        agentId,
+        destination: payload.destination,
+        text: payload.content.text,
+        presentation: payload.presentation,
+        context: payload.context,
+        threadRootMessageId: payload.threadRootMessageId,
+    }))
+        .digest('hex')
+        .slice(0, 32);
+    if (requestId) {
+        return `cli:agent-message:${compactKeyPart(requestId)}:${digest}`;
+    }
+    return `cli:${crypto.randomUUID()}:agent-message:${digest}`;
+}
+function compactKeyPart(value) {
+    const cleaned = value.replace(/[^A-Za-z0-9_.:-]/g, '_');
+    if (cleaned.length <= 80)
+        return cleaned;
+    const digest = crypto.createHash('sha256').update(value).digest('hex').slice(0, 16);
+    return `${cleaned.slice(0, 63)}:${digest}`;
+}
+function statusFromLegacyDm(result) {
+    if (result.duplicate)
+        return 'duplicate';
+    if (result.skipped)
+        return 'dropped';
+    if (result.delivered === false)
+        return 'failed';
+    return 'delivered';
+}
+function buildEnvelope(input) {
+    return {
+        ok: input.ok,
+        protocolVersion: PROTOCOL_VERSION,
+        command: 'agent message send',
+        server: input.server,
+        principalKind: input.principalKind,
+        principalSource: input.principalSource,
+        transport: input.transport,
+        agent: { id: input.agent.id, source: input.agent.source },
+        destination: input.destination,
+        content: input.content,
+        idempotencyKey: input.idempotencyKey,
+        ...(input.threadRootMessageId ? { threadRootMessageId: input.threadRootMessageId } : {}),
+        ...(input.presentation ? { presentation: input.presentation } : {}),
+        ...(input.notificationPolicy ? { notificationPolicy: input.notificationPolicy } : {}),
+        ...(input.embeds && input.embeds.length > 0 ? { embeds: input.embeds } : {}),
+        ...(input.embedRejections && input.embedRejections.length > 0
+            ? { embedRejections: input.embedRejections }
+            : {}),
+        intent: input.intent,
+    };
+}
+function formatEnvelope(envelope) {
+    const status = envelope.intent.status;
+    const suffix = envelope.intent.reason ? ` (${envelope.intent.reason})` : '';
+    const destination = describeDestination(envelope.destination);
+    const presentation = envelope.presentation
+        ? ` [kind=${envelope.presentation.kind}${envelope.presentation.attention ? `, attention=${envelope.presentation.attention}` : ''}${envelope.destination.kind === 'app_owner_dm'
+            ? '; reach=user-controlled; presentation=user-controlled'
+            : ''}]`
+        : '';
+    return `Agent message intent for ${envelope.agent.id} → ${destination}: ${status}${suffix}.${presentation}`;
+}
+function describeDestination(destination) {
+    if (destination.kind === 'slack_channel') {
+        return `slack_channel:${destination.channelId}${destination.threadTs ? `:${destination.threadTs}` : ''}`;
+    }
+    return destination.kind;
+}
+function invalidIntent(message) {
+    const err = new Error(message);
+    err.code = 'INVALID_MESSAGE_INTENT';
+    return err;
+}