@oh-hai/cli 0.1.0-beta.0

package/dist/commands/messaging/state.js

@@ -0,0 +1,82 @@
+// Agent-owned sealed `--state` resume for the productized messaging commands (cli spec §4.4).
+//
+// The AES-256-GCM state seal is VENDORED crypto (AGENTS.md — do not reimplement): this module
+// only reads the agent-owned key and wraps `@oh-hai/ma2h-core/state-seal`'s sealState/openState.
+// Consuming the shared core at runtime is why #219 makes `@oh-hai/ma2h-core` publishable — the
+// compiled `dist/cli.js` bin resolves the core's compiled dist. Mirrors the scripts layer
+// (scripts/ask.ts readSealKey + scripts/agent-client.ts sealResume/openSealedState).
+import { openState, sealState } from "@oh-hai/ma2h-core/state-seal";
+import { CliError } from "../../envelope.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 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 function readSealKey() {
+    const raw = process.env[STATE_SEAL_KEY_ENV]?.trim();
+    if (raw === undefined || raw === "")
+        return undefined;
+    const key = Buffer.from(raw, "base64url");
+    if (key.length !== 32) {
+        throw new CliError("usage", `${STATE_SEAL_KEY_ENV} must decode to 32 bytes (base64url); got ${key.length}.`);
+    }
+    return key;
+}
+/** Wrap an agent-owned resume object as a sealed envelope `state` value (`{ sealed: "MA2HSEALv1.…" }`).
+ *  The seal key is Hub-invisible (spec §9.3). */
+export function sealResumeState(resume, key) {
+    return { sealed: sealState(resume, key) };
+}
+/** 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 function openSealedState(response, key) {
+    const sealed = response.state?.["sealed"];
+    if (typeof sealed !== "string")
+        return undefined;
+    return openState(sealed, key);
+}
+/** 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 function openResumeState(body) {
+    const sealed = body.response?.state?.["sealed"];
+    if (typeof sealed !== "string")
+        return undefined;
+    const key = readSealKey();
+    if (key === undefined)
+        return undefined;
+    try {
+        return openState(sealed, key);
+    }
+    catch (err) {
+        throw new CliError("error", `failed to open sealed state: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** 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 function resolveState(raw) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new CliError("usage", `--state is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new CliError("usage", "--state must be a JSON object.");
+    }
+    const key = readSealKey();
+    if (key === undefined) {
+        throw new CliError("usage", `--state requires ${STATE_SEAL_KEY_ENV} (base64url 32-byte key) so resume state can be sealed.`);
+    }
+    return sealResumeState(parsed, key);
+}
+//# sourceMappingURL=state.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/commands/messaging/state.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,EAAE;AACF,8FAA8F;AAC9F,iGAAiG;AACjG,+FAA+F;AAC/F,0FAA0F;AAC1F,qFAAqF;AAErF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEpE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAG7C;0FAC0F;AAC1F,MAAM,CAAC,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAExD;8DAC8D;AAC9D,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAAE,IAAI,EAAE,CAAC;IACpD,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IACtD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;IAC1C,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,GAAG,kBAAkB,6CAA6C,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;iDACiD;AACjD,MAAM,UAAU,eAAe,CAAC,MAAkB,EAAE,GAAW;IAC7D,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,CAAC;AAC5C,CAAC;AAED;iGACiG;AACjG,MAAM,UAAU,eAAe,CAAC,QAAqB,EAAE,GAAW;IAChE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACjD,OAAO,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;qGAOqG;AACrG,MAAM,UAAU,eAAe,CAAC,IAAoB;IAClD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACjD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,CAAC;QACH,OAAO,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,gCAAgC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClH,CAAC;AACH,CAAC;AAED;;4FAE4F;AAC5F,MAAM,UAAU,YAAY,CAAC,GAAuB;IAClD,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACxC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,8BAA8B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAChH,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,gCAAgC,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,GAAG,GAAG,WAAW,EAAE,CAAC;IAC1B,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,QAAQ,CAAC,OAAO,EAAE,oBAAoB,kBAAkB,yDAAyD,CAAC,CAAC;IAC/H,CAAC;IACD,OAAO,eAAe,CAAC,MAAoB,EAAE,GAAG,CAAC,CAAC;AACpD,CAAC"}

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

@@ -0,0 +1,40 @@
+import type { Actor, AskMessage, Priority, RequestMode, ResponseOption, TaskMessage } from "./wire.js";
+export declare const PRIORITIES: readonly Priority[];
+export declare const REQUEST_MODES: readonly RequestMode[];
+export declare const CALLBACK_MODES: readonly ["pull", "push"];
+export type CallbackMode = (typeof CALLBACK_MODES)[number];
+export declare function isPriority(value: string): value is Priority;
+export declare function isRequestMode(value: string): value is RequestMode;
+export declare function isCallbackMode(value: string): value is CallbackMode;
+/** Hub-attested resolver identity `<type>:<id>` with type ∈ {human,agent,system} (spec §9.1).
+ *  Anchored end-to-end (no embedded whitespace) so a malformed `--resolver` fails loudly here. */
+export declare function isActor(value: string): value is Actor;
+/** Normalize a push `--callback-url` to the canonical WHATWG href the Hub signs and `fetch` POSTs
+ *  to (so the signed callback_url can't desync from the delivery URL), and enforce http(s) — the
+ *  Hub's SSRF delivery guard rejects every other scheme, so a mailto:/file: url would pass
+ *  `new URL()` but silently lose the push. A bad URL / scheme is a usage error (exit 2). */
+export declare function normalizePushUrl(raw: string): string;
+/** Parse `value:label` (label may itself contain ':'). Throws a usage CliError on a bad shape. */
+export declare function parseOption(raw: string): ResponseOption;
+/** A task/ask is resolvable only when allowed_resolvers names ≥1 concrete `human:<id>` — the
+ *  resolve route is human-only and fail-closed (spec §5.4), so a message with none (or only
+ *  agent:/system: resolvers) can never be marked done and sits open until expiry. */
+export declare function hasHumanResolver(resolvers: readonly unknown[] | undefined): boolean;
+/** Stricter than `hasHumanResolver`: requires ≥1 `human:<id>` with a CONCRETE (non-wildcard,
+ *  non-empty) id. The Hub matches allowed_resolvers literally (`allowed.includes(actor)`), so a
+ *  captured `human:*` can never match any real actor — the replay guard must reject it exactly as
+ *  the compose path does, or the replayed ask/task is submitted unresolvable. */
+export declare function hasConcreteHumanResolver(resolvers: readonly unknown[] | undefined): boolean;
+/** Read the `--envelope` source: inline JSON, `@<path>` (local file), or `@-` (stdin, via the
+ *  injected reader so tests never touch fd 0). */
+export declare function readEnvelopeArg(raw: string, readStdin: () => Promise<string>): Promise<string>;
+/** Validate a parsed value is a well-formed ask envelope before replaying it (spec §4.8) — enough
+ *  to fail loudly on a wrong paste (a notify/task envelope, truncated JSON, missing idempotency
+ *  key) without re-doing the Hub's full schema validation. */
+export declare function assertAskEnvelope(value: unknown): AskMessage;
+/** Validate a parsed value is a well-formed task envelope before replaying it (spec §4.8),
+ *  including an opt-in callback's shape (push needs a valid http(s) url; else pull). */
+export declare function assertTaskEnvelope(value: unknown): TaskMessage;
+/** Extract `allowed_resolvers` from a replayed ask/task envelope (they live at `request.` for
+ *  ask, `action.` for task) — used by the human-resolver replay guard. */
+export declare function replayResolvers(envelope: AskMessage | TaskMessage): readonly unknown[] | undefined;

package/dist/commands/messaging/validate.js

@@ -0,0 +1,193 @@
+// Pure validation helpers + `--envelope` replay guards for the messaging commands (spec §4.4 /
+// §4.8). Ported from `scripts/ask.ts` + `scripts/task.ts`'s loud-failure discipline: an
+// out-of-range mode/priority/actor, a malformed option, or a wrong-shaped replayed envelope
+// fails LOCALLY (exit 2) rather than slipping through to a remote 422. No I/O except the
+// `@file` read in `readEnvelopeArg` (a local file); `@-` goes through the injected stdin reader
+// so tests stay hermetic.
+import { readFileSync } from "node:fs";
+import { CliError } from "../../envelope.js";
+export const PRIORITIES = ["low", "normal", "high", "urgent"];
+export const REQUEST_MODES = ["select", "input", "confirm"];
+export const CALLBACK_MODES = ["pull", "push"];
+export function isPriority(value) {
+    return PRIORITIES.includes(value);
+}
+export function isRequestMode(value) {
+    return REQUEST_MODES.includes(value);
+}
+export function isCallbackMode(value) {
+    return CALLBACK_MODES.includes(value);
+}
+/** Hub-attested resolver identity `<type>:<id>` with type ∈ {human,agent,system} (spec §9.1).
+ *  Anchored end-to-end (no embedded whitespace) so a malformed `--resolver` fails loudly here. */
+export function isActor(value) {
+    return /^(human|agent|system):[^\s]+$/.test(value);
+}
+/** True when `raw` parses as an http(s) URL — the only schemes the Hub's SSRF delivery guard
+ *  accepts for a push callback, so a mailto:/file: url would silently lose the push. */
+function isHttpUrl(raw) {
+    try {
+        const u = new URL(raw);
+        return u.protocol === "http:" || u.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+/** Normalize a push `--callback-url` to the canonical WHATWG href the Hub signs and `fetch` POSTs
+ *  to (so the signed callback_url can't desync from the delivery URL), and enforce http(s) — the
+ *  Hub's SSRF delivery guard rejects every other scheme, so a mailto:/file: url would pass
+ *  `new URL()` but silently lose the push. A bad URL / scheme is a usage error (exit 2). */
+export function normalizePushUrl(raw) {
+    let parsed;
+    try {
+        parsed = new URL(raw.trim());
+    }
+    catch {
+        throw new CliError("usage", `--callback-url is not a valid URL: ${JSON.stringify(raw)}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new CliError("usage", `--callback-url must be http(s) (the Hub rejects other schemes), got ${JSON.stringify(parsed.protocol)}`);
+    }
+    return parsed.href;
+}
+/** Parse `value:label` (label may itself contain ':'). Throws a usage CliError on a bad shape. */
+export function parseOption(raw) {
+    const i = raw.indexOf(":");
+    if (i < 0)
+        throw new CliError("usage", `--option must be "value:label", got "${raw}"`);
+    const value = raw.slice(0, i).trim();
+    const label = raw.slice(i + 1).trim();
+    if (value === "" || label === "") {
+        throw new CliError("usage", `--option must be "value:label" with non-empty parts, got "${raw}"`);
+    }
+    return { value, label };
+}
+/** A task/ask is resolvable only when allowed_resolvers names ≥1 concrete `human:<id>` — the
+ *  resolve route is human-only and fail-closed (spec §5.4), so a message with none (or only
+ *  agent:/system: resolvers) can never be marked done and sits open until expiry. */
+export function hasHumanResolver(resolvers) {
+    return (resolvers ?? []).some((r) => typeof r === "string" && r.startsWith("human:"));
+}
+/** Stricter than `hasHumanResolver`: requires ≥1 `human:<id>` with a CONCRETE (non-wildcard,
+ *  non-empty) id. The Hub matches allowed_resolvers literally (`allowed.includes(actor)`), so a
+ *  captured `human:*` can never match any real actor — the replay guard must reject it exactly as
+ *  the compose path does, or the replayed ask/task is submitted unresolvable. */
+export function hasConcreteHumanResolver(resolvers) {
+    return (resolvers ?? []).some((r) => {
+        if (typeof r !== "string" || !r.startsWith("human:"))
+            return false;
+        const id = r.slice("human:".length);
+        return id !== "" && !id.includes("*");
+    });
+}
+/** Read the `--envelope` source: inline JSON, `@<path>` (local file), or `@-` (stdin, via the
+ *  injected reader so tests never touch fd 0). */
+export async function readEnvelopeArg(raw, readStdin) {
+    if (raw === "@-")
+        return readStdin();
+    if (raw.startsWith("@")) {
+        const path = raw.slice(1);
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch (error) {
+            // A missing/unreadable local file is a usage mistake (exit 2), not a generic error (exit 1):
+            // re-throw as a CliError so the message is actionable rather than a raw Node ENOENT.
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new CliError("usage", `--envelope: could not read ${JSON.stringify(path)}: ${reason}`);
+        }
+    }
+    return raw;
+}
+/** Validate a parsed value is a well-formed ask envelope before replaying it (spec §4.8) — enough
+ *  to fail loudly on a wrong paste (a notify/task envelope, truncated JSON, missing idempotency
+ *  key) without re-doing the Hub's full schema validation. */
+export function assertAskEnvelope(value) {
+    const env = asObject(value, "--envelope must be a JSON object (the envelope printed by 'ask submit --dry-run')");
+    if (env["type"] !== "ask") {
+        throw new CliError("usage", `--envelope must be an ask envelope (type "ask"), got type ${JSON.stringify(env["type"])}`);
+    }
+    if (typeof env["ma2h_version"] !== "string")
+        throw new CliError("usage", "--envelope is missing ma2h_version");
+    if (typeof env["idempotency_key"] !== "string" || env["idempotency_key"].trim() === "") {
+        throw new CliError("usage", "--envelope is missing the REQUIRED idempotency_key");
+    }
+    if (typeof env["agent"] !== "object" || env["agent"] === null || Array.isArray(env["agent"])) {
+        throw new CliError("usage", "--envelope agent must be an object");
+    }
+    const request = env["request"];
+    if (typeof request !== "object" || request === null || Array.isArray(request)) {
+        throw new CliError("usage", "--envelope request must be an object");
+    }
+    // Validate an ask push callback's scheme (mirrors assertTaskEnvelope): a non-http(s) push url
+    // passes new URL() but is silently dropped by the Hub's SSRF guard — fail fast locally.
+    const callback = request["callback"];
+    if (callback !== undefined) {
+        if (typeof callback !== "object" || callback === null || Array.isArray(callback)) {
+            throw new CliError("usage", "--envelope request.callback must be an object");
+        }
+        const mode = callback["mode"];
+        if (mode === "push") {
+            const url = callback["url"];
+            if (typeof url !== "string" || !isHttpUrl(url)) {
+                throw new CliError("usage", "--envelope push callback requires a valid http(s) url");
+            }
+        }
+        else if (mode !== "pull") {
+            throw new CliError("usage", `--envelope request.callback.mode must be "pull" or "push", got ${JSON.stringify(mode)}`);
+        }
+    }
+    return value;
+}
+/** Validate a parsed value is a well-formed task envelope before replaying it (spec §4.8),
+ *  including an opt-in callback's shape (push needs a valid http(s) url; else pull). */
+export function assertTaskEnvelope(value) {
+    const env = asObject(value, "--envelope must be a JSON object (the envelope printed by 'task submit --dry-run')");
+    if (env["type"] !== "task") {
+        throw new CliError("usage", `--envelope must be a task envelope (type "task"), got type ${JSON.stringify(env["type"])}`);
+    }
+    if (typeof env["ma2h_version"] !== "string")
+        throw new CliError("usage", "--envelope is missing ma2h_version");
+    if (typeof env["idempotency_key"] !== "string" || env["idempotency_key"].trim() === "") {
+        throw new CliError("usage", "--envelope is missing the REQUIRED idempotency_key (a blank value collides on the Hub's dedup key)");
+    }
+    if (typeof env["agent"] !== "object" || env["agent"] === null || Array.isArray(env["agent"])) {
+        throw new CliError("usage", "--envelope agent must be an object");
+    }
+    const action = env["action"];
+    if (typeof action !== "object" || action === null || Array.isArray(action)) {
+        throw new CliError("usage", "--envelope action must be an object");
+    }
+    const callback = action["callback"];
+    if (callback !== undefined) {
+        if (typeof callback !== "object" || callback === null || Array.isArray(callback)) {
+            throw new CliError("usage", "--envelope action.callback must be an object");
+        }
+        const mode = callback["mode"];
+        if (mode === "push") {
+            const url = callback["url"];
+            if (typeof url !== "string" || !isHttpUrl(url)) {
+                throw new CliError("usage", "--envelope push callback requires a valid http(s) url");
+            }
+        }
+        else if (mode !== "pull") {
+            throw new CliError("usage", `--envelope action.callback.mode must be "pull" or "push", got ${JSON.stringify(mode)}`);
+        }
+    }
+    return value;
+}
+/** Extract `allowed_resolvers` from a replayed ask/task envelope (they live at `request.` for
+ *  ask, `action.` for task) — used by the human-resolver replay guard. */
+export function replayResolvers(envelope) {
+    const holder = envelope.type === "ask" ? envelope.request : envelope.action;
+    const resolvers = holder.allowed_resolvers;
+    return Array.isArray(resolvers) ? resolvers : undefined;
+}
+function asObject(value, message) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new CliError("usage", message);
+    }
+    return value;
+}
+//# sourceMappingURL=validate.js.map

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

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

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

@@ -0,0 +1,133 @@
+/** Recursive JSON value — for opaque `state` and free-form input answers/schemas. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type Priority = "low" | "normal" | "high" | "urgent";
+export type Runtime = "github-actions" | "cli" | "cloud" | "desktop" | "openclaw" | "other";
+export type RequestMode = "select" | "input" | "confirm";
+/** Hub-attested resolver identity: `<type>:<id>` (spec §9.1). */
+export type Actor = `${"human" | "agent" | "system"}:${string}`;
+export interface AgentDescriptor {
+    id: string;
+    run_id: string;
+    runtime: Runtime;
+    project?: string;
+}
+export interface ResponseOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+/** Callback, discriminated by mode (push requires a url). The CLI never composes callback
+ *  `auth`, so it is omitted from the local type. */
+export type Callback = {
+    mode: "push";
+    url: string;
+} | {
+    mode: "pull";
+};
+export interface AskRequest {
+    mode: RequestMode;
+    options?: ResponseOption[];
+    schema?: JsonObject;
+    allowed_resolvers?: Actor[];
+    callback?: Callback;
+}
+export interface TaskAction {
+    instructions: string;
+    checklist?: {
+        text: string;
+    }[];
+    allowed_resolvers?: Actor[];
+    callback?: Callback;
+}
+interface BaseEnvelope {
+    ma2h_version: "0.3";
+    created_at: string;
+    agent: AgentDescriptor;
+    title: string;
+    body?: string;
+    priority?: Priority;
+    tags?: string[];
+    /** Agent-owned, agent-integrity-sealed resume blob (`{ sealed: "MA2HSEALv1.…" }`, via `--state`).
+     *  Opaque to the Hub (MUST NOT inspect/log — spec §9.3). Sealed by `state.ts` on submit. */
+    state?: JsonObject;
+}
+export interface NotifyMessage extends BaseEnvelope {
+    type: "notify";
+    idempotency_key?: string;
+}
+export interface AskMessage extends BaseEnvelope {
+    type: "ask";
+    idempotency_key: string;
+    request: AskRequest;
+}
+export interface TaskMessage extends BaseEnvelope {
+    type: "task";
+    idempotency_key: string;
+    action: TaskAction;
+}
+export type A2hMessage = NotifyMessage | AskMessage | TaskMessage;
+export type AskResolution = "answered" | "declined" | "cancelled" | "expired";
+export type TaskResolution = "completed" | "dismissed" | "expired";
+export type Resolution = AskResolution | TaskResolution;
+export type Status = "open" | "delivered" | Resolution;
+export interface ResponseDetail {
+    /** ask only: chosen option value (string) or the input object. Absent for task. */
+    value?: string | JsonObject;
+    actor: Actor;
+    resolved_at: string;
+    comment?: string;
+}
+export interface A2hResponse {
+    ma2h_version: "0.3";
+    in_reply_to: string;
+    resolution_id: string;
+    resolution: Resolution;
+    defaulted?: boolean;
+    response?: ResponseDetail;
+    state?: JsonObject;
+}
+export interface SubmitAck {
+    id: string;
+    status: "open" | "delivered";
+    poll_url: string;
+    review_url?: string;
+}
+/** GET /v1/messages/:id — the stored envelope plus its lifecycle status and terminal Response. */
+export type GetMessageBody = A2hMessage & {
+    id: string;
+    status: Status;
+    response?: A2hResponse;
+};
+/** One human→agent directive drained from the agent's mailbox (spec §13.1). */
+export interface InboundDirective {
+    ma2h_version: string;
+    type: "directive";
+    id: string;
+    from: string;
+    to: string;
+    created_at: string;
+    title: string;
+    body?: string;
+    priority?: Priority;
+    tags?: string[];
+    context?: JsonValue[];
+    expires_at?: string;
+    sensitive?: boolean;
+}
+/** One drained directive plus its detached `MA2H-Signature` (spec §8.7 / §9.7). Forwarded verbatim
+ *  so a runtime that wants defense-in-depth can verify the signature against the Hub key. */
+export interface InboundDelivery {
+    directive: InboundDirective;
+    signature: string;
+}
+/** POST /v1/inbox/ack — the ids of the directives consumed by this call (spec §14; the server's
+ *  `ackDirectives` returns the id array, not a count). */
+export interface InboxAckResult {
+    acked: string[];
+}
+export {};

package/dist/commands/messaging/wire.js

@@ -0,0 +1,16 @@
+// The MA2H wire shapes the productized messaging commands compose and read (spec/v0.3).
+//
+// These MIRROR the canonical definitions in `@oh-hai/ma2h-core` (`packages/ma2h-core/src/types.ts`,
+// and the shapes `scripts/agent-client.ts` builds), but are RE-DECLARED locally on purpose:
+// `@oh-hai/cli` ships as a standalone published bin (`bin: dist/cli.js`, `tsconfig.build.json`
+// sets `rootDir: "src"`). This matches the CLI's existing design — `config.ts` re-declares its own
+// types rather than reaching out. Only the subset the CLI composes or reads lives here (no context
+// Parts, permissions, or callback-auth refs — the CLI's push callback is a bare `{ mode, url }`).
+// The server validates every envelope at ingest, so any drift surfaces as a 422/400, never silent
+// corruption. As of #219 the CLI DOES consume the core's runtime crypto (`state-seal` — the
+// vendored AES-256-GCM seal must not be re-implemented, AGENTS.md; see `state.ts`), now that
+// `@oh-hai/ma2h-core` is npm-publishable. These wire TYPES stay locally re-declared (types are
+// compile-time only, erased from `dist/cli.js`); a full type re-export from the core is a separate
+// follow-up, out of #219 scope.
+export {};
+//# sourceMappingURL=wire.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"wire.js","sourceRoot":"","sources":["../../../src/commands/messaging/wire.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,EAAE;AACF,oGAAoG;AACpG,4FAA4F;AAC5F,+FAA+F;AAC/F,mGAAmG;AACnG,mGAAmG;AACnG,kGAAkG;AAClG,kGAAkG;AAClG,4FAA4F;AAC5F,6FAA6F;AAC7F,+FAA+F;AAC/F,mGAAmG;AACnG,gCAAgC"}

package/dist/commands/notify.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "./context.js";
+export declare function notifyCommand(ctx: CommandContext): Promise<void>;

package/dist/commands/notify.js

@@ -0,0 +1,68 @@
+// `oh-hai notify` (docs/specs/cli.md §4.4) — fire-and-forget notification (status / FYI /
+// digest). The productized sibling of `scripts/notify.ts`: the bearer is resolved account-aware
+// (keychain/file/env, not raw env), output follows the `--json` envelope, and HTTP statuses map
+// to §7 exit codes. No idempotency key — a notify must not be retried (a retry posts a duplicate).
+import { CliError, buildOk, serializeEnvelope } from "../envelope.js";
+import { parseCommandArgs } from "./flags.js";
+import { buildNotify } from "./messaging/build.js";
+import { submitEnvelope } from "./messaging/http.js";
+import { resolveSubmitIdentity } from "./messaging/identity.js";
+import { dryRunFlag, printDryRunEnvelope, printSubmitAck, resolveRunId, stringFlag } from "./messaging/shared.js";
+import { resolveState } from "./messaging/state.js";
+import { PRIORITIES, isPriority } from "./messaging/validate.js";
+export async function notifyCommand(ctx) {
+    const { values } = parseCommandArgs(ctx.argv, {
+        title: { type: "string" },
+        body: { type: "string" },
+        priority: { type: "string" },
+        tag: { type: "string", multiple: true },
+        "dry-run": { type: "boolean" },
+        state: { type: "string" },
+    });
+    // Seal an optional `--state` resume blob up front (requires MA2H_STATE_SEAL_KEY) so the
+    // preview under --dry-run shows the sealed envelope. notify has no await/open leg.
+    const state = resolveState(stringFlag(values.state));
+    const title = stringFlag(values.title);
+    if (title === undefined || title.trim() === "") {
+        throw new CliError("usage", "missing required flag: --title (must be non-empty).");
+    }
+    const priority = stringFlag(values.priority);
+    if (priority !== undefined && !isPriority(priority)) {
+        throw new CliError("usage", `invalid --priority "${priority}" (expected one of: ${PRIORITIES.join(", ")}).`);
+    }
+    const body = stringFlag(values.body);
+    const tags = Array.isArray(values.tag) ? values.tag.filter((t) => typeof t === "string") : [];
+    // Strict parse (not `=== true`): the `=`-form `--dry-run=true` still previews, and a malformed
+    // value like `--dry-run=treu` fails as usage rather than falling through to a LIVE submit.
+    const dryRun = dryRunFlag(values["dry-run"]);
+    // Under --dry-run neither a token nor a resolved account is required — the envelope is only
+    // previewed. Use a placeholder agent id so the composed envelope stays inspectable. A real
+    // submit resolves the bearer + account up front (auth/usage errors before composing).
+    let agentId = ctx.config.account ?? "oh-hai/notify-bot";
+    let token = ""; // reassigned on the real path below; dry-run returns before it's used
+    if (!dryRun) {
+        const identity = await resolveSubmitIdentity(ctx);
+        agentId = identity.agentId;
+        token = identity.token;
+    }
+    const notify = buildNotify({
+        agent: { id: agentId, run_id: resolveRunId() },
+        title,
+        ...(body !== undefined ? { body } : {}),
+        ...(priority !== undefined ? { priority } : {}),
+        ...(tags.length > 0 ? { tags } : {}),
+        ...(state !== undefined ? { state } : {}),
+    });
+    if (dryRun) {
+        printDryRunEnvelope(ctx, "notify", notify);
+        return;
+    }
+    const ack = await submitEnvelope(ctx, token, notify);
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk("notify", { id: ack.id })));
+    }
+    else {
+        printSubmitAck(ctx, "notify posted", ack);
+    }
+}
+//# sourceMappingURL=notify.js.map

package/dist/commands/notify.js.map

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

package/dist/commands/registry.d.ts

@@ -0,0 +1,14 @@
+export interface CommandSpec {
+    /** The command token, e.g. "notify" or "agents". */
+    name: string;
+    /** One-line summary for the top-level help. */
+    summary: string;
+    /** The downstream issue that implements this command's body. */
+    issue: number;
+    /** Valid subcommands, if any (e.g. ask → submit | await). */
+    subcommands: string[];
+    /** Full `--help` text for this command. */
+    help: string;
+}
+export declare const COMMANDS: readonly CommandSpec[];
+export declare function findCommand(name: string): CommandSpec | undefined;