@oh-hai/cli 0.2.3 → 0.3.1

package/dist/commands/messaging/capability.js

@@ -0,0 +1,164 @@
+// The Hub capability document, and the §8.0 FEATURE-DETECTION GATE an addressed send must pass
+// before anything is posted (issue #657).
+//
+// WHY THIS IS A PRE-FLIGHT AND NOT A POST-HOC CHECK. §10 robustness says a Hub ignores fields it does
+// not understand — so a pre-v0.5 Hub handed an envelope carrying `to` does not refuse it. It drops
+// the address and files the message in the HUMAN inbox. The §8.1 destination-snapshot check catches
+// that, but only from the ACK: by then the content an agent addressed to another agent has already
+// been disclosed to a person, and no error code un-sends it. A round-trip is a cheap price for not
+// leaking; "the Hub's refusals are precise" was only ever true of Hubs that understand the field.
+//
+// WHAT IS REQUIRED, AND WHAT DELIBERATELY IS NOT. The gate demands a declared minor >= 0.5 — that is
+// exactly the property that makes the Hub *refuse* rather than silently misroute, since v0.5 is where
+// `to` is defined and constrained. It does NOT demand an advertised `inter_agent`: this Hub routes
+// addressed messages today while deliberately withholding that object until the response (#652) and
+// receipt (#653) producers land, so requiring it would make `--to` unusable against the very Hub that
+// implements it. An explicitly DISABLED `inter_agent` is a different matter and is refused here,
+// because that is the Hub stating the leg is off.
+//
+// FAIL CLOSED. An unreachable or unreadable capability document refuses the send. We cannot prove the
+// Hub understands `to`, and the cost of being wrong is disclosure, not inconvenience.
+import { CliError } from "../../envelope.js";
+/** The minor at which `to` / `agent.session` exist and are constrained (spec §4/§4.1). */
+const ADDRESSING_MINOR = 5;
+/** Per-process capability cache, keyed by Hub base URL. The document is effectively static for a
+ *  process lifetime, and an addressed send would otherwise pay a round-trip every call. `null` marks
+ *  a fetch that FAILED, cached so a down/unreachable discovery endpoint is not re-probed per send —
+ *  it still fails closed either way. */
+const CACHE = new Map();
+/** Test seam — a real process wants the cache to live exactly as long as it does. */
+export function resetCapabilityCache() {
+    CACHE.clear();
+}
+/** The declared minor of an `0.<minor>` version string, or null when it is absent/malformed. */
+function minorOf(version) {
+    if (typeof version !== "string")
+        return null;
+    const m = /^0\.(\d+)$/.exec(version.trim());
+    return m ? Number(m[1]) : null;
+}
+/**
+ * GET /v1/capability — the public capability document (no auth), memoized per process.
+ *
+ * Best-effort by return type: an unreachable / non-2xx / unparseable document resolves to
+ * `undefined`. Callers decide what that means — `fleet ls` degrades its caption to "unknown", while
+ * `assertHubSpeaksAddressing` below refuses the send.
+ */
+export async function fetchCapability(ctx) {
+    const key = ctx.config.baseUrl;
+    const cached = CACHE.get(key);
+    if (cached !== undefined)
+        return cached ?? undefined;
+    const timeout = ctx.config.timeoutMs !== undefined && ctx.config.timeoutMs > 0 ? Math.min(ctx.config.timeoutMs, 2_147_483_647) : 10_000;
+    let res;
+    try {
+        res = await ctx.runtime.fetchImpl(`${key}/v1/capability`, { method: "GET", headers: {}, signal: AbortSignal.timeout(timeout) });
+    }
+    catch {
+        CACHE.set(key, null);
+        return undefined;
+    }
+    if (res.status < 200 || res.status >= 300 || typeof res.json !== "function") {
+        CACHE.set(key, null);
+        return undefined;
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        CACHE.set(key, null);
+        return undefined;
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        CACHE.set(key, null);
+        return undefined;
+    }
+    const doc = body;
+    // `agent_list_visibility` is a GRANT and the only field a caller ACTS on — `fleet ls` turns it into
+    // the scope caption and into `data.scope` for scripts. A blind cast would read the STRING "false"
+    // as truthy and report the whole fleet for a list the Hub never said was account-wide. Anything
+    // that is not a real boolean is dropped, so it reads `unknown`: the honest answer for a document
+    // that did not say.
+    const sessions = doc.sessions;
+    if (sessions !== null && typeof sessions === "object" && !Array.isArray(sessions)) {
+        const visibility = sessions.agent_list_visibility;
+        if (visibility !== undefined && typeof visibility !== "boolean") {
+            delete sessions.agent_list_visibility;
+        }
+    }
+    else if (sessions !== undefined) {
+        delete doc.sessions;
+    }
+    const capability = doc;
+    CACHE.set(key, capability);
+    return capability;
+}
+/**
+ * The §8.0 gate: refuse an addressed send unless this Hub demonstrably understands `to`.
+ *
+ * Throws a `usage` CliError (exit 2 — the caller's invocation cannot work against this Hub, and no
+ * retry will change that) BEFORE any envelope is posted. See the file header for why the check is
+ * a pre-flight, why `inter_agent` is not required, and why an unreadable document fails closed.
+ */
+export async function assertHubSpeaksAddressing(ctx, to) {
+    const capability = await fetchCapability(ctx);
+    if (capability === undefined) {
+        throw new CliError("usage", `refusing to send to ${to}: this Hub's capability document (${ctx.config.baseUrl}/v1/capability) could not be read, ` +
+            "so it cannot be confirmed to understand v0.5 addressing. A Hub that does not would IGNORE the address and file " +
+            "this message in a human inbox (§10), which no error code can undo — so the send fails closed (§8.0).");
+    }
+    const minor = minorOf(capability.ma2h_version);
+    if (minor === null || minor < ADDRESSING_MINOR) {
+        throw new CliError("usage", `refusing to send to ${to}: this Hub declares MA2H ${capability.ma2h_version ?? "(no version)"}, which predates ` +
+            "the v0.5 addressing vocabulary. It would ignore `to` and file this message in a human inbox rather than refusing it (§8.0/§10).");
+    }
+    // Absent `inter_agent` is NOT read as disabled (see the file header) — but an explicit `false` is
+    // the Hub stating the leg is off, which is worth catching before a round-trip that can only 403.
+    if (capability.inter_agent?.enabled === false) {
+        throw new CliError("usage", `refusing to send to ${to}: this Hub advertises the inter-agent leg as disabled (§8.0 inter_agent.enabled=false).`);
+    }
+}
+/**
+ * The §8.0 gate for the RECEIVE half — `oh-hai bridge`'s session-presenting drain (#658).
+ *
+ * The same disclosure logic as the send gate, pointed the other way, and the failure it prevents is
+ * worse than a wasted round-trip. A pre-v0.5 Hub does not refuse `?session=`; per §10 it IGNORES the
+ * unknown query parameter and answers with the v0.4 body — which means the bridge would issue a
+ * **destructive PRINCIPAL-scoped drain**, claiming (and, on ack, consuming) every directive queued
+ * for the whole agent, while believing it had drained only its own session's mail. Concurrent runs
+ * of the same principal would then eat each other's directives: exactly the race the watch-lock
+ * exists to prevent, reintroduced by a silently-dropped parameter.
+ *
+ * So the gate runs BEFORE the first drain or stream connect, and it fails CLOSED on an unreadable
+ * capability document for the same reason the send gate does — we cannot prove the Hub understands
+ * `session`, and the cost of being wrong is consuming someone else's mail.
+ *
+ * What is deliberately NOT required: a present `inbound.session_param`. An ABSENT capability field
+ * must never be read as "disabled" (the lesson `assertHubSpeaksAddressing` records in this file's
+ * header) — a declared minor >= 0.5 is what makes the Hub *refuse* rather than silently misroute,
+ * and that is the property being tested. An EXPLICIT `false` is a different matter: that is the Hub
+ * stating the parameter is not honoured, and it is refused.
+ */
+export async function assertHubSpeaksSessionDrain(ctx) {
+    const capability = await fetchCapability(ctx);
+    if (capability === undefined) {
+        throw new CliError("usage", `refusing to bridge: this Hub's capability document (${ctx.config.baseUrl}/v1/capability) could not be read, so it ` +
+            "cannot be confirmed to understand the v0.5 session-scoped drain. A Hub that does not would IGNORE `?session=` and " +
+            "answer with the v0.4 principal-wide mailbox (§10) — consuming directives meant for every other run of this agent. " +
+            "The bridge fails closed (§8.0).");
+    }
+    const minor = minorOf(capability.ma2h_version);
+    if (minor === null || minor < ADDRESSING_MINOR) {
+        throw new CliError("usage", `refusing to bridge: this Hub declares MA2H ${capability.ma2h_version ?? "(no version)"}, which predates the v0.5 ` +
+            "session-scoped drain (§8.7.1). It would ignore `?session=` and drain this agent's WHOLE mailbox destructively " +
+            "instead of refusing. Use `oh-hai inbox watch` against a pre-0.5 Hub.");
+    }
+    if (capability.sessions?.enabled === false) {
+        throw new CliError("usage", "refusing to bridge: this Hub advertises the v0.5 session primitive as disabled (§8.0 sessions.enabled=false).");
+    }
+    if (capability.inbound?.session_param === false) {
+        throw new CliError("usage", "refusing to bridge: this Hub advertises `inbound.session_param: false` — it does not honour the session-scoped drain (§8.7.1).");
+    }
+}
+//# sourceMappingURL=capability.js.map

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

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

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

@@ -1,12 +1,19 @@
+import { CliError } from "../../envelope.js";
 import type { CommandContext } from "../context.js";
 import type { GetMessageBody, InboundDelivery, InboxAckResult, SubmitAck } from "./wire.js";
+/** 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. */
+export declare function requestTimeoutMs(ctx: CommandContext): number;
 /** 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 declare function redactToken(message: string | undefined, token: string): string | undefined;
 /** 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 declare function submitEnvelope(ctx: CommandContext, token: string, envelope: unknown): Promise<SubmitAck>;
+export declare function submitEnvelope(ctx: CommandContext, token: string, envelope: unknown, opts?: {
+    addressedTo?: string;
+}): Promise<SubmitAck>;
 /** 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 declare function pollMessage(ctx: CommandContext, token: string, id: string, timeoutMs: number): Promise<GetMessageBody>;
@@ -17,6 +24,26 @@ export declare function pollMessage(ctx: CommandContext, token: string, id: stri
 export declare function drainInbox(ctx: CommandContext, token: string, max?: number): Promise<{
     directives: InboundDelivery[];
 }>;
+/** GET the agent's OWN submitted messages — the submitter-bound self-list (spec §9.1, agent bearer,
+ *  the #400 primitive paginated by #527). The Hub scopes the result to (accountId, agentId) and
+ *  returns a pure INDEX: each row is the stored envelope MINUS the embedded terminal `response` and
+ *  derived `delivery` (the agent pulls a specific answer with `pollMessage`). `opts` carries the
+ *  optional `limit`/`offset` pagination and `status`/`type` filters as query params;
+ *  `expectedAgentId` is the caller's own agent id — every returned row MUST be its own submission
+ *  (see the ownership guard). A `2xx` returns the validated message array; every other status maps
+ *  to a §7 exit code. Every returned string is bearer-redacted before the caller renders it (§5.4). */
+export declare function listMessages(ctx: CommandContext, token: string, opts: {
+    limit?: number;
+    offset?: number;
+    status?: string;
+    type?: string;
+}, expectedAgentId: string): Promise<GetMessageBody[]>;
 /** 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 declare function ackInbox(ctx: CommandContext, token: string, ids: string[]): Promise<InboxAckResult>;
+/** 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). */
+export declare function statusToCliError(status: number, message: string | undefined, hubCode?: string, hint?: string): CliError;

package/dist/commands/messaging/http.js

@@ -11,6 +11,7 @@
 import { CliError } from "../../envelope.js";
 import { exitCodeForError, isErrorCode } from "../../exit-codes.js";
 import { throwTransportError } from "../http.js";
+import { assertHubSpeaksAddressing } from "./capability.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. */
@@ -18,7 +19,7 @@ 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) {
+export function requestTimeoutMs(ctx) {
     const t = ctx.config.timeoutMs;
     return Math.min(t !== undefined && t > 0 ? t : DEFAULT_TIMEOUT_MS, MAX_TIMER_MS);
 }
@@ -32,7 +33,15 @@ export function redactToken(message, token) {
 }
 /** 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) {
+export async function submitEnvelope(ctx, token, envelope, opts = {}) {
+    // §8.0 FEATURE DETECTION, before a single byte is posted. A pre-v0.5 Hub does not refuse an
+    // envelope carrying `to` — §10 says it IGNORES the field, files the message in the human inbox,
+    // and acks success. The §8.1 snapshot check below catches that only from the ack, by which point
+    // agent-addressed content has already been disclosed to a person and cannot be recalled. Gating
+    // HERE, at the one choke point every submit path funnels through, is also why the replay paths
+    // cannot miss it — a per-caller gate already got forgotten once.
+    if (opts.addressedTo !== undefined)
+        await assertHubSpeaksAddressing(ctx, opts.addressedTo);
     const url = `${ctx.config.baseUrl}/v1/messages`;
     const init = {
         method: "POST",
@@ -49,7 +58,11 @@ export async function submitEnvelope(ctx, token, envelope) {
     }
     if (res.status !== 202) {
         const { code, message } = await readErrorEnvelope(res);
-        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+        // On an ADDRESSED submit, append the one sentence that turns each documented §8.5 refusal into
+        // a next step. Done here — where the HTTP status and the Hub's own `error.code` are still in
+        // hand — rather than by re-inspecting a flattened CliError message at the call site.
+        const hint = opts.addressedTo !== undefined ? addressedHint(res.status, code, opts.addressedTo) : undefined;
+        throw statusToCliError(res.status, redactToken(message, token), code, hint);
     }
     const body = await readJson(res);
     // A conformant Hub returns `{ id, status, poll_url, review_url? }` for every message type.
@@ -67,14 +80,94 @@ export async function submitEnvelope(ctx, token, envelope) {
     // 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 destination = destinationOf(body, token, opts.addressedTo !== undefined);
+    // §8.1 MUST: every ADDRESSED ack carries the destination snapshot, and its absence is not a
+    // cosmetic gap — it is positive proof that the Hub did not route the address. A pre-0.5 Hub cannot
+    // emit this object at all, so a 202 without it means `to` was ignored and the message was filed in
+    // the HUMAN inbox. Printing a warning while still returning a successful ack (the earlier shape)
+    // left every caller exiting 0 and `--json` saying `ok: true` for a message that reached the wrong
+    // recipient — a silent misroute is exactly what this snapshot exists to make impossible. The id is
+    // included because the submit WAS accepted: the caller needs it to find (and cancel) the message.
+    if (opts.addressedTo !== undefined && destination === undefined) {
+        throw new CliError("server", `the Hub accepted this message (id ${redactToken(String(body.id), token)}) but returned no destination snapshot, ` +
+            `which means it did not route "${opts.addressedTo}" — the message was filed in the HUMAN inbox instead. ` +
+            "This Hub predates v0.5 addressing (§8.1).");
+    }
     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) } : {}),
+        ...(destination !== undefined ? { destination } : {}),
     };
     return ack;
 }
+/** Read the v0.5 §8.1 `destination` snapshot off an ack, defensively. Absent / wrong-shaped ⇒
+ *  undefined, which the submit handlers render as "no destination snapshot" — a meaningful signal in
+ *  itself on an ADDRESSED submit, because a pre-0.5 Hub cannot emit this object at all, so its
+ *  absence is the sender's proof that `to` was IGNORED and the message filed in a human inbox.
+ *  An unrecognized `state` is passed through verbatim (sanitized at render) rather than coerced to
+ *  `unknown`: inventing a reachability claim is exactly the dishonesty §8.1 exists to prevent. */
+function destinationOf(body, token, addressed) {
+    const raw = body.destination;
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const { state, last_seen: lastSeen } = raw;
+    if (typeof state !== "string" || state === "")
+        return undefined;
+    if (addressed) {
+        // The v0.5 submit-ack schema (and conformance vector sv-034) fixes BOTH the enum and the
+        // relationship: `state` is online|offline|unknown, and `unknown` — the "no visibility" answer —
+        // MUST carry no `last_seen`, because a timestamp IS visibility. Passing an out-of-enum state
+        // through "verbatim" was the wrong kind of honesty: rendering `reachable` or an `unknown` with a
+        // last-seen invents a reachability claim the protocol cannot express, which is exactly the false
+        // belief this snapshot exists to prevent. A violation is a malformed ack, not a usable reading.
+        if (state !== "online" && state !== "offline" && state !== "unknown") {
+            throw new CliError("server", `the Hub returned an unknown destination reachability state ${JSON.stringify(sanitizeForTerminal(state))}.`);
+        }
+        // The schema pins the relationship in BOTH directions, and each direction is load-bearing:
+        // `unknown` must carry no `last_seen` (a timestamp IS visibility, so one here contradicts the
+        // claim), and `online`/`offline` MUST carry one (a known state with no timestamp is an
+        // unanchored assertion — "online" as of when?). Half-validating leaves the second case rendering
+        // a reachability reading the sender cannot date, which is the same unfalsifiable claim the
+        // snapshot exists to replace.
+        if (state === "unknown" && lastSeen !== undefined) {
+            throw new CliError("server", "the Hub returned an `unknown` destination reachability carrying a last_seen, which the v0.5 ack schema forbids.");
+        }
+        if (state !== "unknown" && !isIsoTimestamp(lastSeen)) {
+            throw new CliError("server", `the Hub reported the destination as ${state} without the last_seen timestamp the v0.5 ack schema requires to anchor it.`);
+        }
+    }
+    return {
+        state: redactToken(state, token),
+        ...(typeof lastSeen === "string" ? { last_seen: redactToken(lastSeen, token) } : {}),
+    };
+}
+/** The actionable second sentence for a refused ADDRESSED submit (spec §8.5). Keyed on the HTTP
+ *  status plus the Hub's `error.code`, both of which are documented and stable:
+ *  - `403` — the leg is ACCOUNT-OPT-IN and defaults off (§8.0). Nothing the sender can fix in argv.
+ *  - `422 unknown_destination` — no such agent (or a session that is not the addressee's) in THIS
+ *    account. Deliberately indistinguishable from "exists but not yours", so the guidance can only
+ *    point at the discovery surface.
+ *  - `410 destination_gone` — the addressed session is terminal; the PRINCIPAL may still be live.
+ *  - `422 invalid_field` — a Hub that predates v0.5 addressing vocabulary.
+ *  Anything else falls through to the Hub's own message unadorned. */
+function addressedHint(status, code, to) {
+    if (status === 403) {
+        return "the inter-agent leg is opt-in per account and off by default — an account owner enables it before agents can address each other.";
+    }
+    if (status === 410) {
+        const principal = to.split("#")[0] ?? to;
+        return `that session is terminal — re-address the principal (\`--to ${principal}\`) or pick a live session from \`oh-hai fleet ls\`.`;
+    }
+    if (status === 422 && code === "unknown_destination") {
+        return "no live agent (or session) in this account answers to that address — check it with `oh-hai fleet ls`.";
+    }
+    if (status === 422 && code === "invalid_field") {
+        return "this Hub does not speak v0.5 addressing, so `--to` cannot be routed here.";
+    }
+    return undefined;
+}
 /** 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) {
@@ -93,7 +186,7 @@ export async function pollMessage(ctx, token, id, timeoutMs) {
     }
     if (res.status < 200 || res.status >= 300) {
         const { code, message } = await readErrorEnvelope(res);
-        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+        throw statusToCliError(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
@@ -104,9 +197,12 @@ export async function pollMessage(ctx, token, id, timeoutMs) {
     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)) {
+    // A body that reached a §7 RESOLUTION must embed its Response (the pull contract) — else `await`
+    // would exit "successfully" with no resolution value/actor. Keyed on the resolution set rather
+    // than "not open and not delivered": the v0.5 §14.2 delivery-track states carry no §7 Response by
+    // design (they describe DELIVERY, not a human's answer), so the old negative form would have
+    // rejected a legitimate `queued` / `acknowledged` / `bounced` poll body as malformed.
+    if (isResolved(body.type, body.status) && (typeof body.response !== "object" || body.response === null)) {
         throw new CliError("server", "the Hub returned a resolved message with no embedded Response.");
     }
     return body;
@@ -132,7 +228,7 @@ export async function drainInbox(ctx, token, max) {
     }
     if (res.status < 200 || res.status >= 300) {
         const { code, message } = await readErrorEnvelope(res);
-        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+        throw statusToCliError(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
@@ -146,6 +242,76 @@ export async function drainInbox(ctx, token, max) {
     }
     return { directives: directives };
 }
+/** GET the agent's OWN submitted messages — the submitter-bound self-list (spec §9.1, agent bearer,
+ *  the #400 primitive paginated by #527). The Hub scopes the result to (accountId, agentId) and
+ *  returns a pure INDEX: each row is the stored envelope MINUS the embedded terminal `response` and
+ *  derived `delivery` (the agent pulls a specific answer with `pollMessage`). `opts` carries the
+ *  optional `limit`/`offset` pagination and `status`/`type` filters as query params;
+ *  `expectedAgentId` is the caller's own agent id — every returned row MUST be its own submission
+ *  (see the ownership guard). A `2xx` returns the validated message array; every other status maps
+ *  to a §7 exit code. Every returned string is bearer-redacted before the caller renders it (§5.4). */
+export async function listMessages(ctx, token, opts, expectedAgentId) {
+    const query = new URLSearchParams();
+    if (opts.limit !== undefined)
+        query.set("limit", String(opts.limit));
+    if (opts.offset !== undefined)
+        query.set("offset", String(opts.offset));
+    if (opts.status !== undefined)
+        query.set("status", opts.status);
+    if (opts.type !== undefined)
+        query.set("type", opts.type);
+    const suffix = query.toString();
+    const url = `${ctx.config.baseUrl}/v1/messages${suffix ? `?${suffix}` : ""}`;
+    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 statusToCliError(res.status, redactToken(message, token), code);
+    }
+    const body = await readJson(res);
+    // The self-list body is `{ messages: [...] }`; validate each row is an INDEX item with the string
+    // id/type/status the renderer keys on (mirrors drainInbox's shape guard) — a malformed body is a
+    // server error, not a silently-empty list that would hide a Hub/proxy regression.
+    const messages = body.messages;
+    if (!Array.isArray(messages) || !messages.every(isListItem)) {
+        throw new CliError("server", "the Hub returned a malformed message list (expected { messages: [{ id, type, status }] }).");
+    }
+    // Defense-in-depth against the dual-audience route: `GET /v1/messages` returns the submitter-bound
+    // self-list for an agent bearer but the account-wide inbox for a human/session bearer. Refuse any
+    // row not submitted by THIS agent — that catches a misconfigured non-agent bearer whenever the
+    // account has other agents' messages. (A heuristic, not a proof of the agent branch: a single-agent
+    // or empty account has no foreign row to trip on — but the index projection below then yields only
+    // this agent's own rows, so nothing extra leaks. See the polish backlog for the rigorous fix.)
+    if (messages.some((m) => m.agent?.id !== expectedAgentId)) {
+        throw new CliError("server", "the Hub returned a message this agent did not submit — refusing a non-self-list result.");
+    }
+    // Project every row to a pure INDEX (drop the answer body + bulky detail payloads); see toIndexRow.
+    const index = messages.map(toIndexRow);
+    // Redact the bearer from every field before the caller prints it to stdout / the --json envelope —
+    // a hostile/buggy Hub could echo the Authorization value into a title/id. Round-trips the array
+    // through redactToken so a match in ANY nested string is scrubbed (mirrors the MCP client's
+    // #redact). Fail CLOSED on the pathological case where the re-parse fails: never return the
+    // un-redacted array (that would leak the bearer) — surface a clean server error instead.
+    const redacted = redactToken(JSON.stringify(index), token);
+    if (redacted === undefined)
+        return index;
+    try {
+        return JSON.parse(redacted);
+    }
+    catch {
+        throw new CliError("server", "the Hub response could not be safely processed.");
+    }
+}
 /** 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) {
@@ -165,7 +331,7 @@ export async function ackInbox(ctx, token, ids) {
     }
     if (res.status < 200 || res.status >= 300) {
         const { code, message } = await readErrorEnvelope(res);
-        throw hubStatusToCliError(res.status, redactToken(message, token), code);
+        throw statusToCliError(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
@@ -194,12 +360,43 @@ function isInboundDelivery(value) {
         return false;
     return d.priority === undefined || typeof d.priority === "string";
 }
+/** Structural guard for one self-list row — an INDEX item carrying the string `id` / `type` /
+ *  `status` the renderer reads. The Hub strips `response`/`delivery`, so those are absent by design;
+ *  a row missing any of the three keyed strings is a malformed body, not a usable list item. */
+function isListItem(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const { id, type, status } = value;
+    return typeof id === "string" && typeof type === "string" && typeof status === "string";
+}
+/** Project a self-list row down to an INDEX shape (mirrors the server's `toSearchResultBody`): drop
+ *  the terminal answer payload (`response`/`delivery` — never render a resolved answer from the bulk
+ *  list) AND the bulky detail payloads (`context`/`state`/`request`/`action`, which can be large or
+ *  opaque). A history list must stay lightweight; the agent pulls a specific message's detail via
+ *  GET /:id. Keeps the index fields (id/type/title/body/status/created_at/priority/agent/…). */
+function toIndexRow(row) {
+    const rest = { ...row };
+    for (const field of ["response", "delivery", "context", "state", "request", "action"]) {
+        delete rest[field];
+    }
+    return rest;
+}
 /** 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). */
+/** The v0.5 §14.2 DELIVERY-track states belong to the NOTIFY set only.
+ *
+ *  An addressed notify's lifecycle IS the delivery track, so `status` legitimately reads
+ *  `queued`/`acknowledged`/`bounced`/`expired` there (spec §5.1). An addressed ASK/TASK keeps the §7
+ *  resolution machinery at `status` — an undeliverable track terminal auto-resolves it to
+ *  `cancelled`/`dismissed` — and surfaces the outbound track under `mailbox` instead
+ *  (v0.5 get-message.schema.json). Admitting the delivery states into the ask/task sets would let a
+ *  malformed `{type:"ask", status:"bounced"}` through, and `ask await` would then report it as a
+ *  successful terminal resolution carrying no Response — the exact "status valid globally but
+ *  impossible for this type" failure this table exists to catch. */
 const STATUSES_BY_TYPE = {
-    notify: new Set(["open", "delivered"]),
+    notify: new Set(["open", "delivered", "queued", "acknowledged", "bounced", "expired"]),
     ask: new Set(["open", "answered", "declined", "cancelled", "expired"]),
     task: new Set(["open", "completed", "dismissed", "expired"]),
 };
@@ -209,13 +406,34 @@ function isValidTypeStatus(type, status) {
     const allowed = STATUSES_BY_TYPE[type];
     return allowed !== undefined && allowed.has(status);
 }
+/** A `format: date-time` string, checked as far as is useful here: a parseable ISO timestamp. Used
+ *  for the reachability anchor, where an unparseable value is as unusable as an absent one. */
+function isIsoTimestamp(value) {
+    return typeof value === "string" && value.trim() !== "" && !Number.isNaN(Date.parse(value));
+}
+/** The §7 RESOLUTION states per type — the ones whose body MUST embed a terminal Response. A notify
+ *  has no resolution track at all (its `expired` belongs to the §14.2 delivery track and carries no
+ *  human answer), which is why this is per-type rather than one flat set: `expired` means two
+ *  different things depending on which track owns the message. */
+const RESOLUTIONS_BY_TYPE = {
+    ask: new Set(["answered", "declined", "cancelled", "expired"]),
+    task: new Set(["completed", "dismissed", "expired"]),
+};
+function isResolved(type, status) {
+    if (typeof type !== "string" || typeof status !== "string")
+        return false;
+    return RESOLUTIONS_BY_TYPE[type]?.has(status) === true;
+}
 /** 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}.`;
+export function statusToCliError(status, message, hubCode, hint) {
+    const base_ = message !== undefined ? sanitizeForTerminal(message) : `Hub returned ${status}.`;
+    // The hint is CLI-authored (never Hub-supplied), so it needs no sanitizing — but it is appended
+    // AFTER the Hub's own message so the verbatim server text stays the headline.
+    const detail = hint !== undefined ? `${base_} — ${hint}` : base_;
     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
@@ -229,7 +447,10 @@ function hubStatusToCliError(status, message, hubCode) {
 function statusToErrorCode(status) {
     if (status === 401 || status === 403)
         return "auth";
-    if (status === 404)
+    // 410 Gone joins 404: the named resource is no longer usable (a terminal destination session,
+    // §8.5 `destination_gone`). Distinguishing it from 404 at the EXIT-code level would buy a caller
+    // nothing — both mean "re-address"; the Hub's own message carries the distinction.
+    if (status === 404 || status === 410)
         return "not_found";
     if (status === 409)
         return "conflict";