@oh-hai/cli 0.2.3 → 0.3.1

package/dist/commands/fleet.d.ts

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

package/dist/commands/fleet.js

@@ -0,0 +1,164 @@
+// `oh-hai fleet ls` (docs/specs/cli.md §4.13) — the sessions visible to this credential, which is
+// how an agent discovers the addresses it can send to (issue #657).
+//
+// THE SCOPE OF THIS LIST IS NOT A PARAMETER — it is a property of the caller and the Hub's policy
+// (§16.4), and the command's main job is to say which one it printed:
+//
+//   * An agent ALWAYS sees its own sessions. Unconditional by §16.4, and deliberately so: a
+//     restarted or crash-looping agent must be able to find and clear its stale leases before it
+//     hits the live-session cap, and gating that read would wedge exactly that agent.
+//   * It sees the whole ACCOUNT only where the Hub's `sessions.agent_list_visibility` policy is on.
+//     §16.4 makes same-account-agent listing an explicit MAY — "an optimization for fleet
+//     dashboards, not the required discovery path" — so it is fail-closed by default.
+//
+// A list that silently narrowed from "the fleet" to "just me" would be actively misleading: the
+// user would conclude the other agents are gone. So the capability document is read (public, no
+// auth) purely to caption the result honestly. That read is best-effort — when it is unavailable
+// the caption falls back to what can be proven from the rows themselves.
+import { buildOk, serializeEnvelope } from "../envelope.js";
+import { sanitizeForTerminal } from "../terminal.js";
+import { parseSubcommandArgs } from "./flags.js";
+import { resolveSubmitIdentity } from "./messaging/identity.js";
+import { fetchCapability } from "./messaging/capability.js";
+import { listSessions } from "./messaging/sessions-http.js";
+import { nonNegativeInt, positiveInt, strictBoolFlag, stringFlag } from "./messaging/shared.js";
+const SUBCOMMANDS = ["ls"];
+const FLEET_LS_OPTIONS = {
+    limit: { type: "string" },
+    offset: { type: "string" },
+    all: { type: "boolean" },
+};
+/** The Hub's own `SESSION_LIST_MAX` / `SESSION_OFFSET_MAX`, mirrored so the "(more …)" hint is
+ *  computed against the window the Hub ACTUALLY served — a raw request above the ceiling is
+ *  clamped server-side, and comparing a full clamped page against the raw ask would wrongly report
+ *  "no more" and stop a scripted pager early. Same convention as `messages list`. */
+const SESSION_LIST_MAX = 200;
+const SESSION_OFFSET_MAX = 10_000;
+const MAX_LIST_INT = 1_000_000;
+export async function fleetCommand(ctx) {
+    const { values } = parseSubcommandArgs(ctx.argv, SUBCOMMANDS, FLEET_LS_OPTIONS);
+    const flags = values;
+    const requestedLimit = flags.limit !== undefined ? positiveInt(stringFlag(flags.limit), "--limit", "a positive integer", MAX_LIST_INT) : SESSION_LIST_MAX;
+    const requestedOffset = flags.offset !== undefined ? nonNegativeInt(stringFlag(flags.offset), "--offset", "a non-negative integer", MAX_LIST_INT) : undefined;
+    const limit = Math.min(requestedLimit, SESSION_LIST_MAX);
+    const offset = requestedOffset !== undefined ? Math.min(requestedOffset, SESSION_OFFSET_MAX) : undefined;
+    // Terminal sessions stay readable for the Hub's retention window, which is useful for a post-mortem
+    // and noise for "who can I address right now" — so LIVE-only is the default and `--all` opts in.
+    // `strictBoolFlag`, not a lenient truthiness check: `--all=treu` must be a usage error rather than
+    // silently showing the narrower list, which reads as "those sessions are gone".
+    const includeTerminal = strictBoolFlag(flags.all, "--all");
+    const identity = await resolveSubmitIdentity(ctx);
+    const rows = await listSessions(ctx, identity.token, { limit, ...(offset !== undefined ? { offset } : {}) });
+    const sessions = includeTerminal ? rows : rows.filter((s) => s.state === "active");
+    // Best-effort caption input (see the file header). `undefined` anywhere below means "the Hub did
+    // not say", which is reported as uncertainty rather than guessed either way.
+    const capability = await fetchCapability(ctx);
+    const accountWide = capability?.sessions?.agent_list_visibility;
+    const scope = describeScope(accountWide, rows, identity.agentId);
+    const effectiveOffset = offset ?? 0;
+    const nextOffset = Math.min(effectiveOffset + rows.length, SESSION_OFFSET_MAX);
+    const hasMore = rows.length === limit && effectiveOffset < SESSION_OFFSET_MAX;
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk("fleet.ls", {
+            sessions,
+            count: sessions.length,
+            // The SCOPE belongs in the machine envelope too, not just the human caption: a script that
+            // cannot tell "no other agents are live" from "this Hub won't tell me about them" will
+            // reach the wrong conclusion just as readily as a person would.
+            scope: accountWide === undefined ? "unknown" : accountWide ? "account" : "own",
+            has_more: hasMore,
+            next_offset: nextOffset,
+        })));
+        return;
+    }
+    // The pager hint is printed from ONE place, after either branch, because the live-only filter is
+    // applied client-side: a full raw page whose rows are all terminal filters to empty while
+    // `hasMore` is true. Returning early there — the original shape — printed "No live sessions" and
+    // swallowed the hint, so a live session one window further back looked like it did not exist.
+    // That is precisely the "those sessions are gone" conclusion this command exists to prevent.
+    const more = () => {
+        if (hasMore)
+            ctx.io.err(`(more — re-run with --offset ${nextOffset})`);
+    };
+    if (sessions.length === 0) {
+        ctx.io.log(includeTerminal
+            ? "No sessions."
+            : hasMore
+                ? "No live sessions in this window — every row here is closed or expired. Keep paging (below), or --all to include them."
+                : "No live sessions. (Add --all to include closed/expired ones.)");
+        ctx.io.err(scope);
+        more();
+        return;
+    }
+    const rowsOut = sessions.map((s) => toRow(s, identity.agentId));
+    const display = [
+        { address: "ADDRESS", who: "WHO", state: "STATE", age: "AGE", label: "LABEL", kind: "KIND", project: "PROJECT" },
+        ...rowsOut,
+    ];
+    const w = (key) => Math.max(...display.map((r) => r[key].length));
+    const [addressW, whoW, stateW, ageW, labelW, kindW] = [w("address"), w("who"), w("state"), w("age"), w("label"), w("kind")];
+    for (const r of display) {
+        ctx.io.log(`${r.address.padEnd(addressW)}  ${r.who.padEnd(whoW)}  ${r.state.padEnd(stateW)}  ${r.age.padEnd(ageW)}  ${r.label.padEnd(labelW)}  ${r.kind.padEnd(kindW)}  ${r.project}`);
+    }
+    // The caption and the pager hint go to stderr so piping the table into a script stays clean.
+    ctx.io.err(scope);
+    more();
+}
+/** Say what this list covers, without overclaiming. When the capability read failed we can still
+ *  prove ONE direction from the rows: a session belonging to another agent could only have come
+ *  from an account-wide read. The reverse is not provable — seeing only your own sessions is
+ *  equally consistent with "the policy is off" and "you are the only agent running." */
+function describeScope(accountWide, rows, selfAgentId) {
+    if (accountWide === true)
+        return "scope: every session in this account (this Hub permits same-account agent listing).";
+    if (accountWide === false) {
+        return ("scope: THIS AGENT's sessions only — this Hub does not permit same-account agent listing (§16.4 makes it " +
+            "an explicit MAY, off by default). Other agents may well be live; ask an account human, who always sees the whole account.");
+    }
+    if (rows.some((s) => s.agent_id !== selfAgentId)) {
+        return "scope: the account (inferred — sessions from other agents are present; the Hub's capability document was unreadable).";
+    }
+    return "scope: could not read this Hub's capability document, so whether other agents' sessions are listed here is unknown.";
+}
+/** Project one session to terminal-safe, single-line columns.
+ *
+ *  The ADDRESS cell holds the `--to` argument and NOTHING else — no "(you)" suffix, no annotation —
+ *  because the whole point of the column is that it can be copied verbatim into `--to`. A marker
+ *  glued onto it turns a copy-paste into an invalid extra argument, which is a worse failure than
+ *  the marker is a convenience. The self marker gets its own WHO column instead. */
+function toRow(session, selfAgentId) {
+    const clean = (value) => (typeof value === "string" && value.trim() !== "" ? sanitizeForTerminal(value) : "—");
+    return {
+        address: `agent:${clean(session.agent_id)}#${clean(session.id)}`,
+        who: session.agent_id === selfAgentId ? "you" : "—",
+        state: clean(session.state),
+        age: describeAge(session),
+        label: clean(session.label),
+        kind: clean(session.kind),
+        project: clean(session.project),
+    };
+}
+/** How long ago the session was last heard from — `last_seen` (client-originated renewal, §15.1)
+ *  when the Hub reports one, else its creation time, marked so the two are never confused. A
+ *  malformed timestamp renders as an em dash rather than `NaN`. */
+function describeAge(session) {
+    const seen = session.last_seen ?? session.created_at;
+    const ms = Date.parse(seen);
+    if (Number.isNaN(ms))
+        return "—";
+    const suffix = session.last_seen === undefined ? " (since start)" : "";
+    return `${humanizeAge(Date.now() - ms)}${suffix}`;
+}
+function humanizeAge(deltaMs) {
+    const seconds = Math.max(0, Math.round(deltaMs / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return `${hours}h`;
+    return `${Math.round(hours / 24)}d`;
+}
+//# sourceMappingURL=fleet.js.map

package/dist/commands/fleet.js.map

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

package/dist/commands/handlers.js

@@ -5,11 +5,15 @@
 // `notImplemented()` as a defensive fallback for any future entry added without a handler.
 import { agentsCommand } from "./agents.js";
 import { askCommand } from "./ask.js";
+import { bridgeCommand } from "./bridge.js";
 import { doctorCommand } from "./doctor.js";
+import { fleetCommand } from "./fleet.js";
 import { inboxCommand } from "./inbox.js";
 import { loginCommand } from "./login.js";
 import { logoutCommand } from "./logout.js";
+import { messagesCommand } from "./messages.js";
 import { notifyCommand } from "./notify.js";
+import { sessionCommand } from "./session.js";
 import { setupCommand } from "./setup.js";
 import { taskCommand } from "./task.js";
 import { teachCommand } from "./teach.js";
@@ -27,6 +31,10 @@ export const COMMAND_HANDLERS = {
     task: taskCommand,
     agents: agentsCommand,
     inbox: inboxCommand,
+    bridge: bridgeCommand,
+    session: sessionCommand,
+    fleet: fleetCommand,
+    messages: messagesCommand,
     doctor: doctorCommand,
     teach: teachCommand,
     upgrade: upgradeCommand,

package/dist/commands/handlers.js.map

@@ -1 +1 @@
-{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/commands/handlers.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,4FAA4F;AAC5F,2FAA2F;AAC3F,uFAAuF;AACvF,2FAA2F;AAE3F,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAEtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,CAAC,MAAM,gBAAgB,GAAmC;IAC9D,KAAK,EAAE,YAAY;IACnB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,GAAG,EAAE,UAAU;IACf,MAAM,EAAE,aAAa;IACrB,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,cAAc;CACxB,CAAC"}
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/commands/handlers.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,4FAA4F;AAC5F,2FAA2F;AAC3F,uFAAuF;AACvF,2FAA2F;AAE3F,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,CAAC,MAAM,gBAAgB,GAAmC;IAC9D,KAAK,EAAE,YAAY;IACnB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;IACrB,MAAM,EAAE,aAAa;IACrB,GAAG,EAAE,UAAU;IACf,MAAM,EAAE,aAAa;IACrB,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,WAAW;IACjB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,aAAa;IACrB,OAAO,EAAE,cAAc;IACvB,KAAK,EAAE,YAAY;IACnB,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,aAAa;IACrB,KAAK,EAAE,YAAY;IACnB,OAAO,EAAE,cAAc;CACxB,CAAC"}

package/dist/commands/messages.d.ts

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

package/dist/commands/messages.js

@@ -0,0 +1,131 @@
+// `oh-hai messages` (docs/specs/cli.md §4.11) — read the agent's OWN submitted messages. The
+// productized CLI wrapper for the submitter-bound self-list (`GET /v1/messages` with an agent
+// bearer — the #400 primitive, paginated by #527; issue #572). Subcommand `list`:
+//   - Sends the resolved AGENT bearer (`requireToken`, like `ask await`), so the Hub scopes the
+//     result to this agent's own submissions — never the account-wide human inbox.
+//   - Returns a pure INDEX: each row carries the message's `status` but NOT the resolved answer
+//     body (the list strips `response`/`delivery`). To read a specific answer, pull that message
+//     by id — the list is for history review / dedupe before resubmitting.
+//   - Pages one window per call: `--limit`/`--offset` (default limit 50; the Hub clamps to 200),
+//     optionally filtered by `--status`/`--type`. `has_more` (a full page) + `next_offset` tell a
+//     scripted pager where to resume.
+//
+// Output posture mirrors `inbox watch` (the sibling "list of server-supplied envelopes" surface),
+// NOT `agents list`: under `--json` the rows are emitted VERBATIM (already bearer-redacted by
+// http.listMessages; JSON.stringify escapes the C0 control range incl. ESC, so no ANSI injection)
+// so a legitimately multi-line message body survives intact — deep-sanitizing would strip its
+// newlines. The HUMAN table renders only single-line index fields (id/type/status/title/created/
+// priority), each `sanitizeForTerminal`'d so a hostile Hub can't inject escape sequences (§5.4).
+import { CliError, buildOk, serializeEnvelope } from "../envelope.js";
+import { sanitizeForTerminal } from "../terminal.js";
+import { parseSubcommandArgs } from "./flags.js";
+import { listMessages } from "./messaging/http.js";
+import { resolveSubmitIdentity } from "./messaging/identity.js";
+import { nonNegativeInt, positiveInt, stringFlag } from "./messaging/shared.js";
+import { isMessageType, isStatus, MESSAGE_TYPES, STATUSES } from "./messaging/validate.js";
+const SUBCOMMANDS = ["list"];
+const MESSAGES_LIST_OPTIONS = {
+    limit: { type: "string" },
+    offset: { type: "string" },
+    status: { type: "string" },
+    type: { type: "string" },
+};
+/** Default page size when `--limit` is omitted — bounded so the command doesn't drag the whole
+ *  history back by default (the Hub treats an absent `?limit` as unbounded for back-compat). */
+const DEFAULT_LIMIT = 50;
+/** The Hub's server-side clamps on `GET /v1/messages` (server `LIST_LIMIT_MAX` / `LIST_OFFSET_MAX`).
+ *  Mirrored so `has_more` / `next_offset` are computed against the limit/offset the Hub ACTUALLY
+ *  applied: a request above these is clamped server-side, so a full clamped page compared against
+ *  the raw request would wrongly report "no more" (the `(more …)` hint disappears / a scripted pager
+ *  stops early). A local mirror is the codebase's convention (see web `pagination.ts`). */
+const LIST_LIMIT_MAX = 200;
+const LIST_OFFSET_MAX = 10_000;
+/** A sane ceiling for `--limit`/`--offset` PARSING — rejects an absurd value (exit 2) before the
+ *  call. The effective value is then clamped to the Hub ceilings above for the request + paging math. */
+const MAX_LIST_INT = 1_000_000;
+export async function messagesCommand(ctx) {
+    // `list` is the only subcommand; the parse validates the operand (an unknown/absent subcommand is
+    // a usage error) before dispatch.
+    const { values } = parseSubcommandArgs(ctx.argv, SUBCOMMANDS, MESSAGES_LIST_OPTIONS);
+    await messagesList(ctx, values);
+}
+async function messagesList(ctx, flags) {
+    // Parse + validate every flag FIRST (a bad invocation is exit 2, before we touch credentials or
+    // the Hub), matching notify/agents. Then clamp to the Hub's ceilings so the paging math below
+    // matches what the Hub actually serves (a raw value above the ceiling would desync has_more).
+    const requestedLimit = flags.limit !== undefined ? positiveInt(stringFlag(flags.limit), "--limit", "a positive integer", MAX_LIST_INT) : DEFAULT_LIMIT;
+    const requestedOffset = flags.offset !== undefined ? nonNegativeInt(stringFlag(flags.offset), "--offset", "a non-negative integer", MAX_LIST_INT) : undefined;
+    const limit = Math.min(requestedLimit, LIST_LIMIT_MAX);
+    const offset = requestedOffset !== undefined ? Math.min(requestedOffset, LIST_OFFSET_MAX) : undefined;
+    const status = stringFlag(flags.status);
+    if (status !== undefined && !isStatus(status)) {
+        throw new CliError("usage", `invalid --status "${status}" (expected one of: ${STATUSES.join(", ")}).`);
+    }
+    const type = stringFlag(flags.type);
+    if (type !== undefined && !isMessageType(type)) {
+        throw new CliError("usage", `invalid --type "${type}" (expected one of: ${MESSAGE_TYPES.join(", ")}).`);
+    }
+    // Resolve BOTH the bearer and this agent's own id (like notify/ask/task): the id is needed to
+    // fail closed on a dual-audience `GET /v1/messages` response (see listMessages' ownership guard) —
+    // to safely self-list you must know which agent you are. An unresolvable/ambiguous id is a usage
+    // error, exactly as for the submit commands.
+    const { token, agentId } = await resolveSubmitIdentity(ctx);
+    const messages = await listMessages(ctx, token, {
+        limit,
+        ...(offset !== undefined ? { offset } : {}),
+        ...(status !== undefined ? { status } : {}),
+        ...(type !== undefined ? { type } : {}),
+    }, agentId);
+    // has_more follows the route's convention (no `total` field): a FULL page might have more. The Hub
+    // clamps offset to LIST_OFFSET_MAX, so the deepest fetchable window starts there — keep paging
+    // until offset IS the clamp, then stop. next_offset is clamped to the ceiling so the printed
+    // resume hint lands on that final window (de-duping the overlap) instead of a clamped-back repeat.
+    const effectiveOffset = offset ?? 0;
+    const nextOffset = Math.min(effectiveOffset + messages.length, LIST_OFFSET_MAX);
+    const hasMore = messages.length === limit && effectiveOffset < LIST_OFFSET_MAX;
+    if (ctx.json) {
+        // Rows are emitted verbatim (already bearer-redacted); see the file header on why this surface
+        // does NOT deep-sanitize under --json (multi-line bodies must survive).
+        ctx.io.log(serializeEnvelope(buildOk("messages.list", { messages, count: messages.length, has_more: hasMore, next_offset: nextOffset })));
+        return;
+    }
+    if (messages.length === 0) {
+        ctx.io.log("No messages.");
+        return;
+    }
+    // Human table — project each row to sanitized, single-line index fields (mirrors agents list's
+    // toAgentView). Absent fields render as an em dash.
+    const rows = messages.map(toRow);
+    const display = [{ id: "ID", type: "TYPE", status: "STATUS", title: "TITLE", created: "CREATED", priority: "PRIORITY" }, ...rows];
+    const idW = colWidth(display, "id");
+    const typeW = colWidth(display, "type");
+    const statusW = colWidth(display, "status");
+    const titleW = colWidth(display, "title");
+    const createdW = colWidth(display, "created");
+    for (const r of display) {
+        ctx.io.log(`${r.id.padEnd(idW)}  ${r.type.padEnd(typeW)}  ${r.status.padEnd(statusW)}  ${r.title.padEnd(titleW)}  ${r.created.padEnd(createdW)}  ${r.priority}`);
+    }
+    if (hasMore) {
+        ctx.io.err(`(more — re-run with --offset ${nextOffset})`);
+    }
+}
+/** Project one self-list row to terminal-safe, single-line columns. Every server string is
+ *  sanitized HERE (the table prints straight to the terminal and a hostile Hub could otherwise inject
+ *  escape sequences via any field — §5.4). Defensive about field presence/type so a malformed-but-
+ *  guard-passing row (the http guard only pins id/type/status) can't crash the render. */
+function toRow(m) {
+    const raw = m;
+    const clean = (value) => (typeof value === "string" && value.trim() !== "" ? sanitizeForTerminal(value) : "—");
+    return {
+        id: clean(raw.id),
+        type: clean(raw.type),
+        status: clean(raw.status),
+        title: clean(raw.title),
+        created: clean(raw.created_at),
+        priority: clean(raw.priority),
+    };
+}
+function colWidth(rows, key) {
+    return Math.max(...rows.map((r) => r[key].length));
+}
+//# sourceMappingURL=messages.js.map

package/dist/commands/messages.js.map

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

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

@@ -1,4 +1,4 @@
-import type { AskMessage, AskRequest, JsonObject, NotifyMessage, Priority, Runtime, TaskAction, TaskMessage } from "./wire.js";
+import type { AgentAddress, AskMessage, AskRequest, JsonObject, NotifyMessage, Priority, Runtime, TaskAction, TaskMessage } from "./wire.js";
 /** The submitting agent's identity. `id` MUST equal the bound bearer credential or the Hub 403s. */
 export interface AgentIdentity {
     id: string;
@@ -6,10 +6,15 @@ export interface AgentIdentity {
     /** Defaults to "cli". */
     runtime?: Runtime;
     project?: string;
+    /** v0.5 §4.1: the submitter's own live session (`--session` / `MA2H_SESSION_ID` / auto-minted).
+     *  Its presence forces the envelope to declare 0.5 — see `wireVersion`. */
+    session?: string;
 }
 export interface BuildNotifyInput {
     agent: AgentIdentity;
     title: string;
+    /** v0.5 §4 destination (`--to`). Absent = the human inbox. */
+    to?: AgentAddress;
     body?: string;
     priority?: Priority;
     tags?: string[];
@@ -24,6 +29,8 @@ export interface BuildAskInput {
     agent: AgentIdentity;
     title: string;
     request: AskRequest;
+    /** v0.5 §4 destination (`--to`). Absent = the human inbox. */
+    to?: AgentAddress;
     body?: string;
     /** Defaults to a fresh `idem_<uuid>`. */
     idempotency_key?: string;
@@ -36,6 +43,8 @@ export interface BuildTaskInput {
     agent: AgentIdentity;
     title: string;
     action: TaskAction;
+    /** v0.5 §4 destination (`--to`). Absent = the human inbox. */
+    to?: AgentAddress;
     body?: string;
     /** Defaults to a fresh `idem_<uuid>`. */
     idempotency_key?: string;

package/dist/commands/messaging/build.js

@@ -1,7 +1,7 @@
 // Pure MA2H envelope builders for the productized messaging commands (spec §4.4).
 //
 // These mirror `scripts/agent-client.ts`'s buildNotify / buildAsk / buildTask in shape —
-// stamp `ma2h_version: "0.3"`, the `type`, a `created_at` (defaulting to now), the agent
+// stamp the declared `ma2h_version` (see `wireVersion`), the `type`, a `created_at` (defaulting to now), the agent
 // descriptor (runtime defaults to "cli"), and — for ask/task — a REQUIRED idempotency key
 // (a fresh `idem_<uuid>` unless the caller pins one). No crypto and no I/O: envelope
 // construction is plain object assembly, so this is not the "no hand-rolled crypto" surface
@@ -14,8 +14,23 @@ function descriptor(agent) {
         run_id: agent.run_id,
         runtime: agent.runtime ?? "cli",
         ...(agent.project !== undefined ? { project: agent.project } : {}),
+        ...(agent.session !== undefined ? { session: agent.session } : {}),
     };
 }
+/**
+ * The version an envelope DECLARES: 0.5 when it carries v0.5 addressing vocabulary (`to` or
+ * `agent.session`), 0.3 otherwise.
+ *
+ * This is not cosmetic. The Hub routes schema validation by declared minor and REFUSES either field
+ * on a pre-0.5 envelope (`422 invalid_field` — "…is a v0.5 field; ma2h_version "0.3" predates it"),
+ * because honoring v0.5 semantics on an envelope that never claimed them would be acting on a
+ * version mismatch. Bumping per-envelope rather than wholesale is the honest statement in the other
+ * direction too: an ordinary human-inbox notify speaks no v0.5 vocabulary, so it keeps saying 0.3
+ * and its bytes on the wire are unchanged.
+ */
+function wireVersion(input) {
+    return input.to !== undefined || input.agent.session !== undefined ? "0.5" : "0.3";
+}
 function nowIso() {
     return new Date().toISOString();
 }
@@ -26,7 +41,7 @@ function freshIdempotencyKey() {
  *  would post a duplicate). An empty `tags` is omitted (the Hub treats absent and `[]` alike). */
 export function buildNotify(input) {
     return {
-        ma2h_version: "0.3",
+        ma2h_version: wireVersion(input),
         type: "notify",
         created_at: input.created_at ?? nowIso(),
         agent: descriptor(input.agent),
@@ -35,11 +50,12 @@ export function buildNotify(input) {
         ...(input.priority !== undefined ? { priority: input.priority } : {}),
         ...(input.tags !== undefined && input.tags.length > 0 ? { tags: input.tags } : {}),
         ...(input.state !== undefined ? { state: input.state } : {}),
+        ...(input.to !== undefined ? { to: input.to } : {}),
     };
 }
 export function buildAsk(input) {
     return {
-        ma2h_version: "0.3",
+        ma2h_version: wireVersion(input),
         type: "ask",
         created_at: input.created_at ?? nowIso(),
         agent: descriptor(input.agent),
@@ -48,11 +64,12 @@ export function buildAsk(input) {
         request: input.request,
         ...(input.body !== undefined ? { body: input.body } : {}),
         ...(input.state !== undefined ? { state: input.state } : {}),
+        ...(input.to !== undefined ? { to: input.to } : {}),
     };
 }
 export function buildTask(input) {
     return {
-        ma2h_version: "0.3",
+        ma2h_version: wireVersion(input),
         type: "task",
         created_at: input.created_at ?? nowIso(),
         agent: descriptor(input.agent),
@@ -61,6 +78,7 @@ export function buildTask(input) {
         action: input.action,
         ...(input.body !== undefined ? { body: input.body } : {}),
         ...(input.state !== undefined ? { state: input.state } : {}),
+        ...(input.to !== undefined ? { to: input.to } : {}),
     };
 }
 //# sourceMappingURL=build.js.map

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

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

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

@@ -0,0 +1,42 @@
+import type { CommandContext } from "../context.js";
+import type { HubCapability } from "./wire.js";
+/** Test seam — a real process wants the cache to live exactly as long as it does. */
+export declare function resetCapabilityCache(): void;
+/**
+ * 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 declare function fetchCapability(ctx: CommandContext): Promise<HubCapability | undefined>;
+/**
+ * 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 declare function assertHubSpeaksAddressing(ctx: CommandContext, to: string): Promise<void>;
+/**
+ * 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 declare function assertHubSpeaksSessionDrain(ctx: CommandContext): Promise<void>;