@oh-hai/cli 0.1.0-beta.0

package/dist/commands/messaging/http.js

@@ -0,0 +1,270 @@
+// Shared Hub HTTP for the messaging commands (notify / ask / task) — submit an envelope and
+// poll a message, over the INJECTABLE `ctx.runtime.fetchImpl` so command tests stay hermetic
+// (never a live Hub). The one thing worth centralizing is the HTTP-status → §7 exit-code
+// mapping, so every messaging command surfaces the same codes/messages (cli spec §7/§8).
+//
+// The tiny defensive body readers + terminal sanitizer mirror the private copies in
+// `commands/login.ts`; they are duplicated (not imported) so this stays a self-contained layer
+// with FULL status coverage (409 conflict / 422 validation_error), which the device-code flow
+// in login.ts never needs. A future shared CLI-core package could unify them (distinct from
+// `@oh-hai/ma2h-core`, the protocol crypto/lifecycle/validation core, not these HTTP readers).
+import { CliError } from "../../envelope.js";
+import { exitCodeForError, isErrorCode } from "../../exit-codes.js";
+import { throwTransportError } from "../http.js";
+import { MAX_TIMER_MS, sanitizeForTerminal } from "./shared.js";
+/** Default per-request bound when no `--timeout`/`MA2H_TIMEOUT_MS` is set — mirrors the scripts
+ *  layer's DEFAULT_TIMEOUT_MS so an unresponsive Hub can't hang a command indefinitely. */
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** The per-request bound for a single Hub call: `config.timeoutMs` (from `--timeout` /
+ *  `MA2H_TIMEOUT_MS`, §6), defaulted and clamped to the timer ceiling so an oversized/negative value
+ *  can't overflow `AbortSignal.timeout` and fail the request spuriously. */
+function requestTimeoutMs(ctx) {
+    const t = ctx.config.timeoutMs;
+    return Math.min(t !== undefined && t > 0 ? t : DEFAULT_TIMEOUT_MS, MAX_TIMER_MS);
+}
+/** Redact any occurrence of the bearer from a Hub-supplied string before it can reach
+ *  stdout/stderr/logs/the `--json` envelope (§5.4) — a hostile/buggy Hub could echo the
+ *  Authorization value back in an error message, an ack field, or (inbox watch) a directive. */
+export function redactToken(message, token) {
+    if (message === undefined || token === "")
+        return message;
+    return message.split(token).join("[redacted]");
+}
+/** POST an envelope to the Hub's ingest endpoint (agent bearer). `202` → the SubmitAck; every
+ *  other status maps to the right §7 exit code (via the Hub's error envelope when present). */
+export async function submitEnvelope(ctx, token, envelope) {
+    const url = `${ctx.config.baseUrl}/v1/messages`;
+    const init = {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify(envelope),
+        signal: AbortSignal.timeout(requestTimeoutMs(ctx)),
+    };
+    let res;
+    try {
+        res = await ctx.runtime.fetchImpl(url, init);
+    }
+    catch (error) {
+        throwTransportError(error, ctx.config.baseUrl);
+    }
+    if (res.status !== 202) {
+        const { code, message } = await readErrorEnvelope(res);
+        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+    }
+    const body = await readJson(res);
+    // A conformant Hub returns `{ id, status, poll_url, review_url? }` for every message type.
+    // Validate the fields the submit paths consume — `id` + `status` (printSubmitAck echoes status,
+    // which would throw on `undefined`) + `poll_url` (the ack contract + ask `--json`'s promised
+    // resume URL), and a present `review_url` must be a string too (else printSubmitAck /--json break)
+    // — rather than casting a malformed 202 body through and crashing / emitting an incomplete payload
+    // AFTER the message was accepted.
+    if (typeof body.id !== "string" || body.id === "" ||
+        typeof body.status !== "string" || body.status === "" ||
+        typeof body.poll_url !== "string" || body.poll_url === "" ||
+        (body.review_url !== undefined && typeof body.review_url !== "string")) {
+        throw new CliError("server", "the Hub accepted the message but returned an incomplete or malformed ack.");
+    }
+    // Redact the bearer from every ack field before returning — a hostile/buggy Hub could echo the
+    // Authorization value into id/status/poll_url/review_url, which the submit handlers print to
+    // stdout / the --json envelope (§5.4). Build a clean ack (drops any extra Hub fields too).
+    const ack = {
+        id: redactToken(body.id, token),
+        status: redactToken(body.status, token),
+        poll_url: redactToken(body.poll_url, token),
+        ...(typeof body.review_url === "string" ? { review_url: redactToken(body.review_url, token) } : {}),
+    };
+    return ack;
+}
+/** GET one message (the submitter-bound pull, agent bearer). Embeds the terminal Response.
+ *  A `2xx` returns the parsed body; every other status maps to a §7 exit code. */
+export async function pollMessage(ctx, token, id, timeoutMs) {
+    const url = `${ctx.config.baseUrl}/v1/messages/${encodeURIComponent(id)}`;
+    const init = {
+        method: "GET",
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(timeoutMs),
+    };
+    let res;
+    try {
+        res = await ctx.runtime.fetchImpl(url, init);
+    }
+    catch (error) {
+        throwTransportError(error, ctx.config.baseUrl);
+    }
+    if (res.status < 200 || res.status >= 300) {
+        const { code, message } = await readErrorEnvelope(res);
+        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+    }
+    const body = await readJson(res);
+    // Validate the body shape before the await loop keys terminality on it: the `id` must be present
+    // AND match the requested id (a proxy returning a different message would otherwise report the
+    // wrong outcome under the requested id), and a `status` valid globally but IMPOSSIBLE for the
+    // message's `type` (e.g. an ask-only `cancelled` on a task) would be reported as a real outcome.
+    // A malformed / mismatched poll body is a server error, not a completed await.
+    if (typeof body.id !== "string" || body.id !== id || !isValidTypeStatus(body.type, body.status)) {
+        throw new CliError("server", "the Hub returned a malformed or mismatched message (bad/other id, or a status invalid for its type).");
+    }
+    // A TERMINAL ask/task body must embed its Response (the pull contract) — else `await` would exit
+    // "successfully" with no resolution value/actor. `open`/`delivered` are pre-terminal (no Response).
+    if (body.status !== "open" && body.status !== "delivered" && (typeof body.response !== "object" || body.response === null)) {
+        throw new CliError("server", "the Hub returned a resolved message with no embedded Response.");
+    }
+    return body;
+}
+/** GET the agent's mailbox — the human→agent drain (spec §13, agent bearer). A `2xx` returns the
+ *  signed deliveries; every other status maps to a §7 exit code. `max`, when set, caps the batch via
+ *  `?max=`. The drain also touches `agent_seen` server-side, so an authenticated poll is itself the
+ *  presence heartbeat (§15) — nothing extra to send. */
+export async function drainInbox(ctx, token, max) {
+    const query = max !== undefined ? `?max=${max}` : "";
+    const url = `${ctx.config.baseUrl}/v1/inbox${query}`;
+    const init = {
+        method: "GET",
+        headers: { Authorization: `Bearer ${token}` },
+        signal: AbortSignal.timeout(requestTimeoutMs(ctx)),
+    };
+    let res;
+    try {
+        res = await ctx.runtime.fetchImpl(url, init);
+    }
+    catch (error) {
+        throwTransportError(error, ctx.config.baseUrl);
+    }
+    if (res.status < 200 || res.status >= 300) {
+        const { code, message } = await readErrorEnvelope(res);
+        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+    }
+    const body = await readJson(res);
+    // Validate the drain shape before the loop trusts it: `directives` MUST be an array, and every
+    // element MUST carry an object `directive` with a string `id` (the dedup + ack key) and a string
+    // `signature` (forwarded to the runtime). A malformed body is a server error, not an empty drain —
+    // silently treating garbage as "no directives" would strand real mail. Mirrors submitEnvelope's
+    // defensive 202 validation.
+    const directives = body.directives;
+    if (!Array.isArray(directives) || !directives.every(isInboundDelivery)) {
+        throw new CliError("server", "the Hub returned a malformed inbox drain (expected { directives: [{ directive: { id }, signature }] }).");
+    }
+    return { directives: directives };
+}
+/** POST a single batched consume-ack for the drained ids — the §14 directive receipt (agent bearer).
+ *  A `2xx` returns the consumed count; every other status maps to a §7 exit code. */
+export async function ackInbox(ctx, token, ids) {
+    const url = `${ctx.config.baseUrl}/v1/inbox/ack`;
+    const init = {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+        body: JSON.stringify({ ids }),
+        signal: AbortSignal.timeout(requestTimeoutMs(ctx)),
+    };
+    let res;
+    try {
+        res = await ctx.runtime.fetchImpl(url, init);
+    }
+    catch (error) {
+        throwTransportError(error, ctx.config.baseUrl);
+    }
+    if (res.status < 200 || res.status >= 300) {
+        const { code, message } = await readErrorEnvelope(res);
+        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+    }
+    const body = await readJson(res);
+    // The Hub returns the ids it actually consumed (spec §14; server `ackDirectives` → string[]), not a
+    // count — validate that shape so a contract drift surfaces as a clean server error, not a silent cast.
+    const acked = body.acked;
+    if (!Array.isArray(acked) || !acked.every((id) => typeof id === "string")) {
+        throw new CliError("server", "the Hub consumed the directives but returned a malformed ack result.");
+    }
+    return { acked: acked };
+}
+/** Structural guard for one drained delivery: an object `directive` carrying string `id` / `from` /
+ *  `title` (and, when present, a string `priority`), plus a string `signature`. `id` is the dedup +
+ *  ack key; `from`/`title`/`priority` are dereferenced on the human emit path (`sanitizeForTerminal`
+ *  would throw on a non-string), so a directive whose value for any of them isn't a string must be
+ *  rejected here as a `server` error at drain — never handed to the loop to crash mid-stream. */
+function isInboundDelivery(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const { directive, signature } = value;
+    if (typeof signature !== "string")
+        return false;
+    if (directive === null || typeof directive !== "object")
+        return false;
+    const d = directive;
+    if (typeof d.id !== "string" || typeof d.from !== "string" || typeof d.title !== "string")
+        return false;
+    return d.priority === undefined || typeof d.priority === "string";
+}
+/** Valid lifecycle statuses per message type (spec §7). A status valid for one type but not the
+ *  message's actual type is a malformed body. `delivered` is terminal-on-acceptance for `notify`
+ *  ONLY — ask/task go from `open` straight to a resolution, so a `{type:"ask", status:"delivered"}`
+ *  must be rejected (else the await loop would treat it as non-terminal and hang to timeout). */
+const STATUSES_BY_TYPE = {
+    notify: new Set(["open", "delivered"]),
+    ask: new Set(["open", "answered", "declined", "cancelled", "expired"]),
+    task: new Set(["open", "completed", "dismissed", "expired"]),
+};
+function isValidTypeStatus(type, status) {
+    if (typeof type !== "string" || typeof status !== "string")
+        return false;
+    const allowed = STATUSES_BY_TYPE[type];
+    return allowed !== undefined && allowed.has(status);
+}
+/** Map a Hub error response to a CliError. The exit code comes from the HTTP status; the stable
+ *  `error.code` string (§8) prefers the Hub's own `error.code` when it maps to the SAME exit tier
+ *  — so a documented code like `version_not_supported` survives instead of being flattened to
+ *  `bad_request` (both exit 9), without letting a Hub-supplied code change the exit semantics. The
+ *  server message is stripped of terminal control chars (the top-level catch prints it). */
+function hubStatusToCliError(status, message, hubCode) {
+    const detail = message !== undefined ? sanitizeForTerminal(message) : `Hub returned ${status}.`;
+    const base = statusToErrorCode(status);
+    // Preserve the Hub's code ONLY when it is a documented §8 code AND maps to the same exit tier —
+    // an unrecognized code (e.g. `rate_limited` on a 429) must not leak into the CLI envelope, and a
+    // recognized code from a different tier must not change the exit semantics.
+    if (hubCode !== undefined && isErrorCode(hubCode) && exitCodeForError(hubCode) === exitCodeForError(base)) {
+        return new CliError(hubCode, detail);
+    }
+    return new CliError(base, detail);
+}
+/** The stable `error.code` implied by an HTTP status (§7/§8). */
+function statusToErrorCode(status) {
+    if (status === 401 || status === 403)
+        return "auth";
+    if (status === 404)
+        return "not_found";
+    if (status === 409)
+        return "conflict";
+    if (status === 413)
+        return "payload_too_large";
+    if (status === 422)
+        return "validation_error";
+    if (status === 400)
+        return "bad_request";
+    if (status >= 500)
+        return "server";
+    return "error";
+}
+/** Parse a response body as a JSON object, defensively — a fake without `json()`, a non-JSON
+ *  body, or a non-object all collapse to `{}`, so callers read fields off a plain record. */
+async function readJson(res) {
+    if (typeof res.json !== "function")
+        return {};
+    try {
+        const parsed = await res.json();
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Read the A2H error envelope `{ error: { code, message } }` from a non-2xx response. */
+async function readErrorEnvelope(res) {
+    const body = await readJson(res);
+    const error = body.error;
+    const record = error !== null && typeof error === "object" ? error : {};
+    const message = typeof record.message === "string" && record.message.trim() !== "" ? record.message.trim() : undefined;
+    const code = typeof record.code === "string" && record.code.trim() !== "" ? record.code.trim() : undefined;
+    return { code, message };
+}
+//# sourceMappingURL=http.js.map

package/dist/commands/messaging/http.js.map

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

package/dist/commands/messaging/identity.d.ts

@@ -0,0 +1,29 @@
+import type { CommandContext } from "../context.js";
+/** Resolve the effective bearer, opening the local store only when the CI env token is absent
+ *  (matches `whoami` — skip probing the OS keychain when `MA2H_AGENT_TOKEN` already resolves it).
+ *  `accountOverride`, when given, is the AUTHORITATIVE store lookup key and wins over
+ *  `ctx.config.account` — used by `--envelope` replay: a verbatim replay authenticates as the
+ *  captured envelope's `agent.id` (the Hub 403s if the bearer's agent ≠ the envelope's), so the
+ *  token must be looked up by that id, not by a configured `default_account`. The env token (CI)
+ *  still wins over both. */
+export declare function resolveBearer(ctx: CommandContext, accountOverride?: string): Promise<string | undefined>;
+/** The bearer + submitting agent id required for a REAL (non-dry-run) submit. Uses the same
+ *  `resolveIdentity` helper `whoami`/`agents` use — so besides an explicit `--account`/`MA2H_AGENT_ID`
+ *  it also DISCOVERS the sole stored identity for the Hub (the zero-config path after a device-code
+ *  `oh-hai login`), letting `notify`/`ask`/`task` work without redundantly naming the account. A
+ *  missing/ambiguous account is a usage error (exit 2, "pass --account") — actionable, and it beats
+ *  an auth error that would wrongly send the caller to re-login; a known account with no token is
+ *  the auth error (exit 3). The submitting `agent.id` MUST equal the bound bearer or the Hub 403s. */
+export declare function resolveSubmitIdentity(ctx: CommandContext): Promise<{
+    token: string;
+    agentId: string;
+}>;
+/** The bearer required when no resolved account is needed — an `await` (poll keyed by message id
+ *  + the submitter-bound bearer). Uses `resolveIdentity` so a zero-config single stored identity is
+ *  discovered for the token lookup. A missing token is an auth error (exit 3). */
+export declare function requireToken(ctx: CommandContext): Promise<string>;
+/** The bearer for an `--envelope` replay. The captured envelope already carries the submitting
+ *  `agent.id`, so fall back to it for the store lookup when no explicit `--account` was given —
+ *  otherwise a user with a stored login but no `default_account` following the replay example
+ *  would hit a spurious auth error. A missing token is an auth error (exit 3). */
+export declare function requireReplayToken(ctx: CommandContext, envelopeAgentId: string): Promise<string>;

package/dist/commands/messaging/identity.js

@@ -0,0 +1,63 @@
+// Account-aware credential resolution for the messaging commands (spec §5/§6). This is the
+// productization delta over `scripts/*`: instead of reading `MA2H_AGENT_TOKEN`/`MA2H_AGENT_ID`
+// straight from env, the bearer is resolved through the same layered store `whoami` uses —
+// `MA2H_AGENT_TOKEN` (CI path) wins, else the keychain, else the 0600 file — and the submitting
+// agent id comes from resolved config (`--account`/`--agent`/`MA2H_AGENT_ID`/`default_account`).
+import { resolveIdentity, resolveToken } from "../../auth/resolve-token.js";
+import { CliError } from "../../envelope.js";
+/** The "no token" auth error (exit 3), shared by the submit and await/replay resolvers. */
+const NOT_AUTHENTICATED = "not authenticated — no stored token (run `oh-hai login`, or set MA2H_AGENT_TOKEN).";
+/** Resolve the effective bearer, opening the local store only when the CI env token is absent
+ *  (matches `whoami` — skip probing the OS keychain when `MA2H_AGENT_TOKEN` already resolves it).
+ *  `accountOverride`, when given, is the AUTHORITATIVE store lookup key and wins over
+ *  `ctx.config.account` — used by `--envelope` replay: a verbatim replay authenticates as the
+ *  captured envelope's `agent.id` (the Hub 403s if the bearer's agent ≠ the envelope's), so the
+ *  token must be looked up by that id, not by a configured `default_account`. The env token (CI)
+ *  still wins over both. */
+export async function resolveBearer(ctx, accountOverride) {
+    const store = ctx.config.tokenSource === "env" ? undefined : await ctx.runtime.openStore();
+    const config = accountOverride !== undefined ? { ...ctx.config, account: accountOverride } : ctx.config;
+    const { token } = await resolveToken(config, store);
+    return token;
+}
+/** The bearer + submitting agent id required for a REAL (non-dry-run) submit. Uses the same
+ *  `resolveIdentity` helper `whoami`/`agents` use — so besides an explicit `--account`/`MA2H_AGENT_ID`
+ *  it also DISCOVERS the sole stored identity for the Hub (the zero-config path after a device-code
+ *  `oh-hai login`), letting `notify`/`ask`/`task` work without redundantly naming the account. A
+ *  missing/ambiguous account is a usage error (exit 2, "pass --account") — actionable, and it beats
+ *  an auth error that would wrongly send the caller to re-login; a known account with no token is
+ *  the auth error (exit 3). The submitting `agent.id` MUST equal the bound bearer or the Hub 403s. */
+export async function resolveSubmitIdentity(ctx) {
+    const store = ctx.config.tokenSource === "env" ? undefined : await ctx.runtime.openStore();
+    const { account, token } = await resolveIdentity(ctx.config, store);
+    if (account === undefined) {
+        throw new CliError("usage", "an agent id is required — pass --account/--agent, set MA2H_AGENT_ID, or log in so a single stored identity is discovered.");
+    }
+    if (token === undefined) {
+        throw new CliError("auth", NOT_AUTHENTICATED);
+    }
+    return { token, agentId: account };
+}
+/** The bearer required when no resolved account is needed — an `await` (poll keyed by message id
+ *  + the submitter-bound bearer). Uses `resolveIdentity` so a zero-config single stored identity is
+ *  discovered for the token lookup. A missing token is an auth error (exit 3). */
+export async function requireToken(ctx) {
+    const store = ctx.config.tokenSource === "env" ? undefined : await ctx.runtime.openStore();
+    const { token } = await resolveIdentity(ctx.config, store);
+    if (token === undefined) {
+        throw new CliError("auth", NOT_AUTHENTICATED);
+    }
+    return token;
+}
+/** The bearer for an `--envelope` replay. The captured envelope already carries the submitting
+ *  `agent.id`, so fall back to it for the store lookup when no explicit `--account` was given —
+ *  otherwise a user with a stored login but no `default_account` following the replay example
+ *  would hit a spurious auth error. A missing token is an auth error (exit 3). */
+export async function requireReplayToken(ctx, envelopeAgentId) {
+    const token = await resolveBearer(ctx, envelopeAgentId);
+    if (token === undefined) {
+        throw new CliError("auth", NOT_AUTHENTICATED);
+    }
+    return token;
+}
+//# sourceMappingURL=identity.js.map

package/dist/commands/messaging/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../../../src/commands/messaging/identity.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,+FAA+F;AAC/F,2FAA2F;AAC3F,gGAAgG;AAChG,iGAAiG;AAEjG,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7C,2FAA2F;AAC3F,MAAM,iBAAiB,GAAG,oFAAoF,CAAC;AAE/G;;;;;;4BAM4B;AAC5B,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAmB,EAAE,eAAwB;IAC/E,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IAC3F,MAAM,MAAM,GAAG,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IACxG,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;sGAMsG;AACtG,MAAM,CAAC,KAAK,UAAU,qBAAqB,CAAC,GAAmB;IAC7D,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IAC3F,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACpE,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,QAAQ,CAChB,OAAO,EACP,2HAA2H,CAC5H,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AACrC,CAAC;AAED;;kFAEkF;AAClF,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAmB;IACpD,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC;IAC3F,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;kFAGkF;AAClF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAmB,EAAE,eAAuB;IACnF,MAAM,KAAK,GAAG,MAAM,aAAa,CAAC,GAAG,EAAE,eAAe,CAAC,CAAC;IACxD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/commands/messaging/shared.d.ts

@@ -0,0 +1,53 @@
+import type { CommandContext } from "../context.js";
+import type { SubmitAck } from "./wire.js";
+/** The connection flags to append to a printed `await` resume hint so it is copy-paste-runnable
+ *  regardless of how the submit resolved them: a non-default `--base-url` and a set `--account`.
+ *  Without these, a hint after a CLI-routed submit (`--base-url … --account …`, no env/config) would
+ *  poll the default Hub / have no account for the token lookup. These are LOCAL config (not
+ *  Hub-supplied), so no terminal-sanitization is needed. */
+export declare function resumeRoutingSuffix(ctx: CommandContext): string;
+/** Strip terminal control characters (C0/C1 + DEL) from a Hub-supplied string before echoing it
+ *  to the terminal on a HUMAN output path — a malicious/compromised Hub could otherwise inject
+ *  ANSI/escape sequences via an ack field or a resolution's value/comment/actor. The `--json`
+ *  path is unaffected (JSON.stringify escapes control chars). Mirrors login.ts / http.ts; built by
+ *  code point to avoid a control-char regex literal. */
+export declare function sanitizeForTerminal(value: string): string;
+/** Node's setTimeout / AbortSignal.timeout ceiling (max 32-bit signed int) — a larger delay
+ *  overflows to ~immediate. Shared by every ms-flag validator so the ceiling lives in one place. */
+export declare const MAX_TIMER_MS = 2147483647;
+/** Parse a strictly-positive INTEGER flag; a NaN / fractional / 0 / negative / over-`ceiling` value is
+ *  a usage error (exit 2). `ceiling` defaults to the timer range (correct for delay flags like
+ *  `--interval` that would overflow setTimeout if huge); pass a smaller cap for count flags like
+ *  `--max`. `detail` tailors the message to the flag's unit (e.g. "a positive integer number of
+ *  milliseconds"). */
+export declare function positiveInt(raw: string | undefined, flag: string, detail?: string, ceiling?: number): number;
+/** Coerce a `parseArgs` value (string | boolean | string[] | undefined under strict:false) to a
+ *  plain string, or undefined. A repeated single-value flag arrives as an array — take the last. */
+export declare function stringFlag(value: unknown): string | undefined;
+/** Strictly parse a boolean switch. Unlike the lenient `flagOn`, an unrecognized explicit value
+ *  (`--flag=treu`) is a USAGE error rather than silently `false` — otherwise a typo on a
+ *  behavior-changing switch falls through to the wrong mode (a LIVE submit, or an infinite loop
+ *  instead of a one-shot). Absent → false; bare or a recognized on/off token → the boolean;
+ *  anything else → exit 2. */
+export declare function strictBoolFlag(value: unknown, flag: string): boolean;
+/** The `--dry-run` safety switch — a `strictBoolFlag` so a typo (`--dry-run=treu`) is a usage error,
+ *  not a silent fall-through to a LIVE submit. */
+export declare function dryRunFlag(value: unknown): boolean;
+/** A value flag that, when present, must be non-empty. An explicit `--flag=` would otherwise ship
+ *  a blank `idempotency_key`/`created_at`; the Hub dedupes on the key, so a blank collides (and a
+ *  blank timestamp is invalid). Returns undefined when the flag is absent. Shared by ask + task. */
+export declare function requireNonEmpty(flags: Record<string, unknown>, name: string): string | undefined;
+/** Reject flags that belong to a DIFFERENT subcommand (e.g. `ask await --resolver`, `ask submit
+ *  --interval`) rather than silently ignoring them (spec's loud-fail discipline). `values` is the
+ *  parsed flag map; `keys` are the foreign flag names to reject for this subcommand. */
+export declare function assertNoForeignFlags(values: Record<string, unknown>, keys: readonly string[], context: string): void;
+/** The run id stamped on the envelope — `MA2H_AGENT_RUN_ID` (env-only, kept stable across an
+ *  idempotent retry, §6) or a fresh `run_<uuid>`. Matches the scripts layer. */
+export declare function resolveRunId(): string;
+/** Print the common human-readable submit acknowledgement (headline + id + status, plus the
+ *  poll URL when relevant and a review URL when the Hub returned one). Commands append their own
+ *  next-step hint after calling this. Never prints the token (§5.4). */
+export declare function printSubmitAck(ctx: CommandContext, headline: string, ack: SubmitAck, includePoll?: boolean): void;
+/** Print a composed envelope under `--dry-run`: human → pretty JSON; `--json` → the uniform
+ *  envelope wrapping it (`{ dry_run: true, envelope }`). Posts nothing. */
+export declare function printDryRunEnvelope(ctx: CommandContext, command: string, envelope: unknown): void;

package/dist/commands/messaging/shared.js

@@ -0,0 +1,135 @@
+// Small helpers shared by the notify / ask / task command handlers: flag coercion, the
+// deferred-`--state` rejection, the submitting run id, and the human-readable submit
+// acknowledgement. Kept here so the three commands stay consistent (cli spec §4.4 / §8).
+import { randomUUID } from "node:crypto";
+import { DEFAULT_BASE_URL } from "../../config.js";
+import { CliError, buildOk, serializeEnvelope } from "../../envelope.js";
+/** The connection flags to append to a printed `await` resume hint so it is copy-paste-runnable
+ *  regardless of how the submit resolved them: a non-default `--base-url` and a set `--account`.
+ *  Without these, a hint after a CLI-routed submit (`--base-url … --account …`, no env/config) would
+ *  poll the default Hub / have no account for the token lookup. These are LOCAL config (not
+ *  Hub-supplied), so no terminal-sanitization is needed. */
+export function resumeRoutingSuffix(ctx) {
+    const parts = [];
+    if (ctx.config.baseUrl !== DEFAULT_BASE_URL)
+        parts.push(`--base-url ${ctx.config.baseUrl}`);
+    if (ctx.config.account !== undefined)
+        parts.push(`--account ${ctx.config.account}`);
+    return parts.length > 0 ? ` ${parts.join(" ")}` : "";
+}
+/** Strip terminal control characters (C0/C1 + DEL) from a Hub-supplied string before echoing it
+ *  to the terminal on a HUMAN output path — a malicious/compromised Hub could otherwise inject
+ *  ANSI/escape sequences via an ack field or a resolution's value/comment/actor. The `--json`
+ *  path is unaffected (JSON.stringify escapes control chars). Mirrors login.ts / http.ts; built by
+ *  code point to avoid a control-char regex literal. */
+export function sanitizeForTerminal(value) {
+    let out = "";
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (code > 0x1f && code !== 0x7f && !(code >= 0x80 && code <= 0x9f))
+            out += ch;
+    }
+    return out;
+}
+/** Node's setTimeout / AbortSignal.timeout ceiling (max 32-bit signed int) — a larger delay
+ *  overflows to ~immediate. Shared by every ms-flag validator so the ceiling lives in one place. */
+export const MAX_TIMER_MS = 2_147_483_647;
+/** Parse a strictly-positive INTEGER flag; a NaN / fractional / 0 / negative / over-`ceiling` value is
+ *  a usage error (exit 2). `ceiling` defaults to the timer range (correct for delay flags like
+ *  `--interval` that would overflow setTimeout if huge); pass a smaller cap for count flags like
+ *  `--max`. `detail` tailors the message to the flag's unit (e.g. "a positive integer number of
+ *  milliseconds"). */
+export function positiveInt(raw, flag, detail = "a positive integer", ceiling = MAX_TIMER_MS) {
+    const n = raw !== undefined ? Number(raw) : NaN;
+    if (!Number.isInteger(n) || n <= 0 || n > ceiling) {
+        throw new CliError("usage", `${flag} must be ${detail} (at most ${ceiling}).`);
+    }
+    return n;
+}
+/** Coerce a `parseArgs` value (string | boolean | string[] | undefined under strict:false) to a
+ *  plain string, or undefined. A repeated single-value flag arrives as an array — take the last. */
+export function stringFlag(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value)) {
+        const last = value[value.length - 1];
+        return typeof last === "string" ? last : undefined;
+    }
+    return undefined;
+}
+/** Strictly parse a boolean switch. Unlike the lenient `flagOn`, an unrecognized explicit value
+ *  (`--flag=treu`) is a USAGE error rather than silently `false` — otherwise a typo on a
+ *  behavior-changing switch falls through to the wrong mode (a LIVE submit, or an infinite loop
+ *  instead of a one-shot). Absent → false; bare or a recognized on/off token → the boolean;
+ *  anything else → exit 2. */
+export function strictBoolFlag(value, flag) {
+    if (value === undefined)
+        return false;
+    if (value === true)
+        return true;
+    if (Array.isArray(value))
+        return value.length > 0 ? strictBoolFlag(value[value.length - 1], flag) : false;
+    if (typeof value === "string") {
+        const v = value.trim().toLowerCase();
+        if (v === "" || v === "true" || v === "1" || v === "yes" || v === "on")
+            return true;
+        if (v === "false" || v === "0" || v === "no" || v === "off")
+            return false;
+    }
+    throw new CliError("usage", `${flag} does not accept the value ${JSON.stringify(value)}; use ${flag} or ${flag}=true|false.`);
+}
+/** The `--dry-run` safety switch — a `strictBoolFlag` so a typo (`--dry-run=treu`) is a usage error,
+ *  not a silent fall-through to a LIVE submit. */
+export function dryRunFlag(value) {
+    return strictBoolFlag(value, "--dry-run");
+}
+/** A value flag that, when present, must be non-empty. An explicit `--flag=` would otherwise ship
+ *  a blank `idempotency_key`/`created_at`; the Hub dedupes on the key, so a blank collides (and a
+ *  blank timestamp is invalid). Returns undefined when the flag is absent. Shared by ask + task. */
+export function requireNonEmpty(flags, name) {
+    const v = stringFlag(flags[name]);
+    if (v !== undefined && v.trim() === "") {
+        throw new CliError("usage", `--${name} was given an empty value — omit the flag for a fresh key, or pass a concrete value.`);
+    }
+    return v;
+}
+/** Reject flags that belong to a DIFFERENT subcommand (e.g. `ask await --resolver`, `ask submit
+ *  --interval`) rather than silently ignoring them (spec's loud-fail discipline). `values` is the
+ *  parsed flag map; `keys` are the foreign flag names to reject for this subcommand. */
+export function assertNoForeignFlags(values, keys, context) {
+    const present = keys.filter((k) => values[k] !== undefined);
+    if (present.length > 0) {
+        const list = present.map((k) => `--${k}`).join(", ");
+        throw new CliError("usage", `${list} ${present.length > 1 ? "are" : "is"} not valid for '${context}'.`);
+    }
+}
+/** The run id stamped on the envelope — `MA2H_AGENT_RUN_ID` (env-only, kept stable across an
+ *  idempotent retry, §6) or a fresh `run_<uuid>`. Matches the scripts layer. */
+export function resolveRunId() {
+    const raw = process.env.MA2H_AGENT_RUN_ID?.trim();
+    return raw !== undefined && raw !== "" ? raw : `run_${randomUUID()}`;
+}
+/** Print the common human-readable submit acknowledgement (headline + id + status, plus the
+ *  poll URL when relevant and a review URL when the Hub returned one). Commands append their own
+ *  next-step hint after calling this. Never prints the token (§5.4). */
+export function printSubmitAck(ctx, headline, ack, includePoll = false) {
+    // ack fields are Hub-supplied — sanitize before echoing to the terminal (§5.4 posture).
+    ctx.io.log(`✅ ${headline}`);
+    ctx.io.log(`   id:         ${sanitizeForTerminal(ack.id)}`);
+    ctx.io.log(`   status:     ${sanitizeForTerminal(ack.status)}`);
+    if (includePoll && ack.poll_url)
+        ctx.io.log(`   poll_url:   ${sanitizeForTerminal(ack.poll_url)}`);
+    if (ack.review_url)
+        ctx.io.log(`   review_url: ${sanitizeForTerminal(ack.review_url)}`);
+}
+/** Print a composed envelope under `--dry-run`: human → pretty JSON; `--json` → the uniform
+ *  envelope wrapping it (`{ dry_run: true, envelope }`). Posts nothing. */
+export function printDryRunEnvelope(ctx, command, envelope) {
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk(command, { dry_run: true, envelope: envelope })));
+    }
+    else {
+        ctx.io.log(JSON.stringify(envelope, null, 2));
+    }
+}
+//# sourceMappingURL=shared.js.map

package/dist/commands/messaging/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/commands/messaging/shared.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,qFAAqF;AACrF,yFAAyF;AAEzF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAIzE;;;;4DAI4D;AAC5D,MAAM,UAAU,mBAAmB,CAAC,GAAmB;IACrD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,gBAAgB;QAAE,KAAK,CAAC,IAAI,CAAC,cAAc,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5F,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;IACpF,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACvD,CAAC;AAED;;;;wDAIwD;AACxD,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,EAAE,IAAI,KAAK,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,IAAI,CAAC;YAAE,GAAG,IAAI,EAAE,CAAC;IACjF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;oGACoG;AACpG,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C;;;;sBAIsB;AACtB,MAAM,UAAU,WAAW,CAAC,GAAuB,EAAE,IAAY,EAAE,MAAM,GAAG,oBAAoB,EAAE,OAAO,GAAG,YAAY;IACtH,MAAM,CAAC,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC;QAClD,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,YAAY,MAAM,aAAa,OAAO,IAAI,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;oGACoG;AACpG,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACrC,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACrD,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;8BAI8B;AAC9B,MAAM,UAAU,cAAc,CAAC,KAAc,EAAE,IAAY;IACzD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IAC1G,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,MAAM,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC;QACpF,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;IAC5E,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,8BAA8B,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,IAAI,OAAO,IAAI,cAAc,CAAC,CAAC;AAChI,CAAC;AAED;kDACkD;AAClD,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,cAAc,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;AAC5C,CAAC;AAED;;oGAEoG;AACpG,MAAM,UAAU,eAAe,CAAC,KAA8B,EAAE,IAAY;IAC1E,MAAM,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACvC,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,KAAK,IAAI,sFAAsF,CAAC,CAAC;IAC/H,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC;AAED;;wFAEwF;AACxF,MAAM,UAAU,oBAAoB,CAClC,MAA+B,EAC/B,IAAuB,EACvB,OAAe;IAEf,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;IAC5D,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,mBAAmB,OAAO,IAAI,CAAC,CAAC;IAC1G,CAAC;AACH,CAAC;AAED;gFACgF;AAChF,MAAM,UAAU,YAAY;IAC1B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAClD,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,UAAU,EAAE,EAAE,CAAC;AACvE,CAAC;AAED;;wEAEwE;AACxE,MAAM,UAAU,cAAc,CAC5B,GAAmB,EACnB,QAAgB,EAChB,GAAc,EACd,WAAW,GAAG,KAAK;IAEnB,wFAAwF;IACxF,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;IAC5B,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,kBAAkB,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IAC5D,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,kBAAkB,mBAAmB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAChE,IAAI,WAAW,IAAI,GAAG,CAAC,QAAQ;QAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,kBAAkB,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACnG,IAAI,GAAG,CAAC,UAAU;QAAE,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,kBAAkB,mBAAmB,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED;2EAC2E;AAC3E,MAAM,UAAU,mBAAmB,CAAC,GAAmB,EAAE,OAAe,EAAE,QAAiB;IACzF,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QACb,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,iBAAiB,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAmC,EAAE,CAAC,CAAC,CAAC,CAAC;IACpH,CAAC;SAAM,CAAC;QACN,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAChD,CAAC;AACH,CAAC"}

package/dist/commands/messaging/state.d.ts

@@ -0,0 +1,26 @@
+import type { A2hResponse, GetMessageBody, JsonObject } from "./wire.js";
+/** The env var carrying the agent's 32-byte state-seal key (base64url). Agent-runtime-provisioned,
+ *  Hub-invisible, distinct from the bearer, and never embedded in `state` (spec §9.3). */
+export declare const STATE_SEAL_KEY_ENV = "MA2H_STATE_SEAL_KEY";
+/** Read + validate the agent state-seal key from the env. Returns undefined when unset; throws a
+ *  usage error (exit 2) when set but not exactly 32 bytes. */
+export declare function readSealKey(): Buffer | undefined;
+/** Wrap an agent-owned resume object as a sealed envelope `state` value (`{ sealed: "MA2HSEALv1.…" }`).
+ *  The seal key is Hub-invisible (spec §9.3). */
+export declare function sealResumeState(resume: JsonObject, key: Buffer): JsonObject;
+/** Open the agent-owned sealed `state` round-tripped in a Response (`{ sealed: "MA2HSEALv1.…" }`).
+ *  Returns undefined when the Response carries no sealed state. Throws on tamper / wrong key. */
+export declare function openSealedState(response: A2hResponse, key: Buffer): JsonObject | undefined;
+/** Await-side opener shared by `ask await` / `task await`: when the resolved message carries a
+ *  sealed `state` AND `MA2H_STATE_SEAL_KEY` is set, open it. Returns undefined when there is no
+ *  sealed blob or the key is unset (opening is opt-in — a missing key is not an error). Only the
+ *  presence of a sealed blob makes the key relevant, so the key is read *after* confirming there is
+ *  something to open: a set-but-malformed key then fails only the awaits that actually need to open
+ *  state (a usage error, exit 2) instead of breaking every await. An open failure on a present
+ *  blob (tamper / wrong key) is a generic error (non-zero) rather than a silent drop of the resume
+ *  context. (This defers the key check the scripts layer does eagerly — a deliberate CLI nicety.) */
+export declare function openResumeState(body: GetMessageBody): JsonObject | undefined;
+/** Submit-side resolver shared by notify / ask / task: parse the `--state` flag (must be a JSON
+ *  object), require the seal key, and return the sealed envelope `state`. Returns undefined when
+ *  `--state` is absent. A non-object payload or a missing key is a usage error (exit 2). */
+export declare function resolveState(raw: string | undefined): JsonObject | undefined;