@staix/agent-hub 0.32.0 → 0.34.0

package/src/hub/bus.ts

@@ -266,6 +266,8 @@ export class Bus {
   private condensing = 0;
   private closed = false;
   storageError?: string;
+  /** Verified durable-write recovery edge; observation never changes settlement. */
+  onStorageRecovered?: () => void;
 
   constructor(opts: Partial<BusOptions> = {}) {
     this.opts = { ...DEFAULT_BUS, ...opts };
@@ -423,6 +425,7 @@ export class Bus {
   private persist(): void {
     if (!this.journal) return;
     const tracking = this.trackingQueuePressure();
+    const wasUnavailable = this.storageError !== undefined;
     try {
       this.journal.transaction(() => {
         for (const outcome of this.pendingOutcomes) this.journal!.createDelivery(outcome);
@@ -430,6 +433,10 @@ export class Bus {
       });
       this.pendingOutcomes.length = 0;
       this.storageError = undefined;
+      if (wasUnavailable) queueMicrotask(() => {
+        if (this.closed || this.storageError) return;
+        try { this.onStorageRecovered?.(); } catch { /* Recovery observers cannot undo the durable write. */ }
+      });
     }
     catch { this.storageError = "delivery journal unavailable"; throw new Error("delivery journal unavailable"); }
   }

package/src/hub/daemon.ts

@@ -5693,7 +5693,7 @@ export async function startDaemon(opts: DaemonOptions) {
     screen: opts.piiScreen ?? (text => screenPii(text, { ...(config.mlx.enabled === false ? {} : { device: () => ensureMlx(config.mlx) }), onCampus, omni, fixedModel: () => activeRouting().local.fixed_model })),
     policyVersion: () => configRevision,
     limits: () => config.limits,
-    notice: value => notify(value.code === "application_capacity" ? `room ${value.room}: application capacity reached (${value.count}); resolve incoming uncertainty with ahub room resolve` : `room ${value.room}: signed frame sequence gap ${value.count} from ${value.sender}`),
+    notice: value => notify(`room ${value.room}: application capacity reached (${value.count}); resolve incoming uncertainty with ahub room resolve`),
     invocationAuthorization: (env, identity) => roomInvocations.authorization(env, identity), invocation: input => roomInvocations.receive(input),
     roster: ids => { remoteRoster.clear(); for (const id of ids) remoteRoster.add(id); },
     changed: () => { if (ready && !stopping) writeStatus(); },
@@ -5702,9 +5702,14 @@ export async function startDaemon(opts: DaemonOptions) {
   remoteQueueChanged = () => roomChat.queueChanged();
   const roomCommands = new RoomCommands({ stateDir: opts.stateDir, cwd: opts.cwd,
     presence: () => [...bus.peers].filter(([id]) => !id.includes("@") && membershipAllowed(id)).map(([id, peer]) => ({ id, state: peer.state })), chat: roomChat,
+    changed: () => { if (ready && !stopping) writeStatus(); },
   });
   // Room crypto/state failure disables only this optional outbound service, never local work.
-  void roomCommands.start().catch(() => log("rooms unavailable"));
+  bus.onStorageRecovered = () => { if (!stopping) void roomChat.retryPending().catch(() => undefined); };
+  void roomCommands.start().catch(() => {
+    const failure = roomCommands.unavailable();
+    log(`rooms unavailable (${failure?.code ?? "unavailable"}); ${failure?.nextStep ?? "check room storage and restart the hub"}`);
+  });
   let roomInboxExpiryFailed = false;
   const roomInboxExpiry = setInterval(() => {
     if (stopping || recoveryActive() || bus.isRecoveryHeld) return;
@@ -6021,7 +6026,7 @@ export async function startDaemon(opts: DaemonOptions) {
     ...(crashLines.length ? { crash: crashLines } : {}),
     projectId,
     instanceId,
-    rooms: roomCommands.statusView(),
+    ...roomCommands.statusSnapshot(),
     version: VERSION,
     pluginBundle: SERVER_JS,
     pendingRestart: allPendingRestart(),
@@ -10794,7 +10799,11 @@ export async function startDaemon(opts: DaemonOptions) {
         if (msg.op === "list" || msg.op === "status") {
           if (msg.input !== undefined && (!msg.input || typeof msg.input !== "object" || Array.isArray(msg.input)
             || Object.keys(msg.input).some(key => key !== "name") || (msg.input.name !== undefined && typeof msg.input.name !== "string"))) return roomFailure();
-          void roomCommands.rows(msg.input?.name, msg.op === "status").then(rooms => reply({ ok: true, rooms }), roomFailure);
+          void roomCommands.rows(msg.input?.name, msg.op === "status").then(rooms => reply({ ok: true, rooms }), error => {
+            const roomsUnavailable = roomCommands.unavailable();
+            if (roomsUnavailable) reply({ ok: false, code: "rooms_unavailable", roomsUnavailable });
+            else roomFailure(error);
+          });
           return;
         }
         if (["inbox_list", "inbox_show", "inbox_done", "inbox_discard"].includes(msg.op)) {

package/src/hub/handoff.ts

@@ -130,7 +130,7 @@ export function resolveTarget(name: string, projects: readonly RegisteredProject
 export function handoffConnectFailure(error: unknown, target: { id: string; root: string }): { code: HandoffRefusalCode; reach: "unreachable"; cause: string; message: string } {
   const code = typeof (error as { code?: unknown })?.code === "number" || typeof (error as { code?: unknown })?.code === "string" ? (error as { code: number | string }).code : undefined;
   if (code === 4426) return { code: "older_target", reach: "unreachable", cause: "wire version differs",
-    message: `the hub of ${target.id} speaks another wire version than this one: upgrade whichever is older (\`ahub upgrade\` in ${target.root}, and the global CLI with \`bun add -g @staix/agent-hub\`), then hand the task off again` };
+    message: `the hub of ${target.id} speaks another wire version than this one: upgrade whichever is older (\`ahub upgrade\` in ${target.root}, and the global CLI the way it was installed; \`ahub doctor\` names the exact step), then hand the task off again` };
   if (code === 4404) return { code: "mismatch", reach: "unreachable", cause: "another hub or instance answered",
     message: `the hub answering for ${target.root} is not the instance this project's registry names (it was restarted, or another project took its port): run \`ahub projects\` to see what is registered, and \`ahub up\` in ${target.root} if it is not running` };
   if (code === "AHUB_CONNECT_TIMEOUT") return { code: "not_running", reach: "unreachable", cause: "no answer in time",

package/src/rooms/application.ts

@@ -4,6 +4,21 @@ import { decodeBase64url } from "./crypto.ts";
 import { canonicalBytes, ROOM_WIRE_LIMITS } from "./wire.ts";
 
 export const ROOM_APPLICATION_MAX_BYTES = ROOM_WIRE_LIMITS.plaintext;
+/** Compatibility evidence only: never a permission, privacy or capability grant. */
+export const ROOM_CODEC_FEATURES = ["chat_v1", "person_inbox_v1", "read_invocation_v1"] as const;
+export type RoomCodecFeature = typeof ROOM_CODEC_FEATURES[number];
+export const ROOM_CODEC_FEATURE_LIMIT = 16, ROOM_CODEC_FEATURE_NAME_LIMIT = 64;
+export function roomCodecFeatures(value: unknown): readonly string[] {
+  if (!Array.isArray(value) || value.length > ROOM_CODEC_FEATURE_LIMIT
+    || value.some((item, index) => typeof item !== "string" || item.length > ROOM_CODEC_FEATURE_NAME_LIMIT
+      || !/^[a-z][a-z0-9_]*$/.test(item) || index > 0 && value[index - 1] >= item)) fail();
+  return [...value] as string[];
+}
+export function roomRequiredCodecFeature(message: RoomMessage): RoomCodecFeature | undefined {
+  if (message.type !== "chat") return undefined;
+  if (message.envelope.kind === "invocation" || message.envelope.kind === "invocation_result") return "read_invocation_v1";
+  return message.envelope.to === "user" ? "person_inbox_v1" : undefined;
+}
 export interface RoomChatEnvelope {
   id: string; trace: string; hop: number; from: string; to: string;
   kind: "chat" | "status" | "invocation" | "invocation_result"; priority: Priority; body: string; ts: number;

package/src/rooms/commands.ts

@@ -7,6 +7,7 @@ import { RoomStore, type RoomState, type RoomPersonInboxMeta, type RoomPersonInb
 import { RoomLink } from "./link.ts";
 import { exposedPeers, roomName, RoomPolicy } from "./policy.ts";
 import type { RoomChat } from "./service.ts";
+import { roomHealthCause, roomHealthNextStep, type RoomHealthCause } from "./health.ts";
 import { projectRoomStatus, type RoomStatusView } from "./status.ts";
 
 export interface RoomCommandResult { kind?: string; artifact?: string; name?: string; room?: string; owner?: string; member?: string }
@@ -50,26 +51,64 @@ export class RoomCommands {
   private pending?: Promise<RoomStore>;
   private store?: RoomStore;
   private stopped = false;
+  private openFailure?: RoomHealthCause;
+  private openRetry?: ReturnType<typeof setTimeout>;
+  private openAttempts = 0;
   private stopWork?: Promise<void>;
   private readonly links = new Map<string, RoomLink>();
   private readonly policy: RoomPolicy;
-  constructor(private readonly options: { stateDir: string; cwd: string; clock?: () => number; refreshMs?: number; presence?: () => readonly {id: string; state: string}[]; chat?: RoomChat }) { this.policy = new RoomPolicy(options.cwd); }
+  constructor(private readonly options: { stateDir: string; cwd: string; clock?: () => number; refreshMs?: number; presence?: () => readonly {id: string; state: string}[]; chat?: RoomChat; openStore?: typeof RoomStore.open; retryMs?: number; changed?: () => void }) { this.policy = new RoomPolicy(options.cwd); }
+  private changedAvailability(): void {
+    try { this.options.changed?.(); } catch { /* Diagnostics cannot change store admission. */ }
+  }
+  private retryOpen(): void {
+    if (this.stopped || this.openRetry) return;
+    const delay = Math.min(30_000, (this.options.retryMs ?? 1000) * 2 ** Math.min(this.openAttempts++, 5));
+    this.openRetry = setTimeout(() => {
+      this.openRetry = undefined;
+      if (!this.stopped) void this.start().catch(() => undefined);
+    }, delay);
+    this.openRetry.unref?.();
+  }
   private async open(): Promise<RoomStore> {
     if (this.stopped) refuse("stopped");
-    this.pending ??= RoomStore.open({ stateDir: join(this.options.stateDir, "rooms"), ...(this.options.clock ? { clock: this.options.clock } : {}) }).then(store => {
+    if (this.store) return this.store;
+    if (this.openRetry) throw new Error(`rooms unavailable (${this.openFailure ?? "unavailable"}); ${roomHealthNextStep(this.openFailure ?? "unavailable")}`);
+    this.pending ??= (this.options.openStore ?? RoomStore.open)({ stateDir: join(this.options.stateDir, "rooms"), ...(this.options.clock ? { clock: this.options.clock } : {}) }).then(store => {
       if (this.stopped) { store.close(); return refuse("stopped"); }
-      this.store = store; return store;
+      this.store = store; this.openFailure = undefined; this.openAttempts = 0;
+      this.changedAvailability(); return store;
+    }).catch(error => {
+      this.pending = undefined;
+      if (!this.stopped) {
+        const cause = roomHealthCause(error), changed = this.openFailure !== cause;
+        this.openFailure = cause; this.retryOpen();
+        if (changed) this.changedAvailability();
+      }
+      throw error;
     });
     return this.pending;
   }
   async start(): Promise<void> {
-    if (!existsSync(join(this.options.stateDir, "rooms"))) return;
-    const store = await this.open();
-    if (!this.stopped) for (const state of store.list()) if (!state.left) this.link(state.name);
+    if (this.stopped || !existsSync(join(this.options.stateDir, "rooms"))) return;
+    try {
+      const store = await this.open();
+      if (!this.stopped) for (const state of store.list()) if (!state.left) this.link(state.name);
+      const recovered = this.openFailure !== undefined;
+      this.openFailure = undefined; this.openAttempts = 0;
+      if (recovered) this.changedAvailability();
+    } catch (error) {
+      if (!this.stopped && !this.openRetry) {
+        const cause = roomHealthCause(error), changed = this.openFailure !== cause;
+        this.openFailure = cause; this.retryOpen();
+        if (changed) this.changedAvailability();
+      }
+      throw error;
+    }
   }
   stop(): Promise<void> {
     if (this.stopWork) return this.stopWork;
-    this.stopped = true; clearTimeout(this.presenceTimer); this.options.chat?.stop();
+    this.stopped = true; clearTimeout(this.presenceTimer); clearTimeout(this.openRetry); this.options.chat?.stop();
     const stops = [...this.links.values()].map(link => link.stop()); this.links.clear();
     this.stopWork = Promise.allSettled([...(this.pending ? [this.pending] : []), ...stops]).then(() => { this.store?.close(); });
     return this.stopWork;
@@ -81,7 +120,7 @@ export class RoomCommands {
       const store = this.store;
       const created: RoomLink = new RoomLink({ store, name, application: this.options.chat?.application, refreshMs: this.options.refreshMs, now: this.options.clock,
         onPresence: value => this.options.chat?.presence(store, name, created, value),
-        onState: state => this.options.chat?.linkState(store, name, created, state), presence: () => {
+        onState: state => { this.options.chat?.linkState(store, name, created, state); this.changedAvailability(); }, presence: () => {
         const allowed = new Set(this.policy.get(name));
         return (this.options.presence?.() ?? []).filter(row => allowed.has(row.id));
       } });
@@ -166,21 +205,42 @@ export class RoomCommands {
   async rows(name?: string, details = name !== undefined): Promise<Record<string, unknown>[]> {
     if (!this.store && !existsSync(join(this.options.stateDir, "rooms"))) return [];
     const store = await this.open(); if (name !== undefined) roomName(name);
-    return store.list().filter(row => name === undefined || row.name === name).map(row => ({ name: row.name, room: row.current.room, owner: this.owner(row), member: store.identity.public.fingerprint, epoch: row.current.epoch, state: row.left ? "left" : this.links.get(row.name)?.status().state ?? "offline", ...(details && this.options.chat ? { deliveries: this.options.chat.rows(row.name), remotePeers: this.options.chat.peers(row.name) } : {}) }));
+    return store.list().filter(row => name === undefined || row.name === name).map(row => {
+      const link = this.links.get(row.name)?.status();
+      const result: Record<string, unknown> = { name: row.name, room: row.current.room, owner: this.owner(row), member: store.identity.public.fingerprint, epoch: row.current.epoch,
+        state: row.left ? "left" : link?.state ?? "offline" };
+      if (details) {
+        result.linkCause = null;
+        if (!row.left) result.linkCause = link?.cause ?? null;
+        result.health = store.health(row.name);
+        if (this.options.chat) {
+          result.deliveries = this.options.chat.rows(row.name);
+          result.remotePeers = this.options.chat.peers(row.name);
+        }
+      }
+      return result;
+    });
   }
-  /** Polling uses only already-loaded public metadata; it never opens room state or reads message rows. */
-  statusView(): RoomStatusView[] | null {
-    if (this.stopped) return null;
-    if (!this.store) return this.pending ? null : [];
+  /** One metadata snapshot binds unavailable diagnostics to the reads that failed. */
+  statusSnapshot(): { rooms: RoomStatusView[] | null; roomsOpening?: true; roomsUnavailable?: { code: RoomHealthCause; nextStep: string } } {
+    const unavailable = (code: RoomHealthCause) => ({ rooms: null, roomsUnavailable: { code, nextStep: roomHealthNextStep(code) } });
+    if (this.stopped) return { rooms: null };
+    if (this.openFailure) return unavailable(this.openFailure);
+    if (!this.store) return this.pending ? { rooms: null, roomsOpening: true } : { rooms: [] };
     try {
-      return projectRoomStatus(this.store.statusMetadata().map(row => ({
+      return { rooms: projectRoomStatus(this.store.statusMetadata().map(row => ({
         name: row.name, room: row.room, owner: row.owner, member: row.member, epoch: row.epoch,
         state: row.left ? "left" : this.links.get(row.name)?.connectionState ?? "offline", members: row.members,
+        linkCause: row.left ? null : this.links.get(row.name)?.connectionCause ?? null, health: this.store!.health(row.name),
         remotePeers: this.options.chat?.peersForStatus(row.name) ?? null,
         relays: this.options.chat?.metrics(row.name, row.room) ?? null,
-      })));
-    } catch { return null; }
+      }))) };
+    } catch (error) { return unavailable(roomHealthCause(error)); }
   }
+  /** Closed cause metadata only, never raw errors; unavailable is distinct from no rooms. */
+  unavailable(): { code: RoomHealthCause; nextStep: string } | undefined { return this.statusSnapshot().roomsUnavailable; }
+  /** Polling uses loaded public metadata and aggregate counts; never opens storage or loads payloads. */
+  statusView(): RoomStatusView[] | null { return this.statusSnapshot().rooms; }
   async preview(action: unknown, raw: unknown, check: () => boolean): Promise<RoomPreview> {
     if (typeof action !== "string") refuse("invalid_operation");
     await assertRoomCryptoReady(); this.current(check);

package/src/rooms/health.ts

@@ -0,0 +1,32 @@
+import { RoomStoreError } from "./store.ts";
+
+/** Closed diagnostics only; never carry a filesystem error, path or message body. */
+export const ROOM_HEALTH_CAUSES = ["invalid", "busy", "corrupt", "unsupported", "limit", "untrusted", "state_changed", "clock_rollback", "closed", "inbox_list_limit", "unavailable", "connecting", "transport_closed", "backpressure", "broker_refused", "codec_unsupported", "codec_pending"] as const;
+export type RoomHealthCause = typeof ROOM_HEALTH_CAUSES[number];
+export function roomHealthCause(error: unknown): RoomHealthCause {
+  return error instanceof RoomStoreError && ROOM_HEALTH_CAUSES.includes(error.code) ? error.code : "unavailable";
+}
+export function roomHealthNextStep(code: RoomHealthCause): string {
+  switch (code) {
+    case "clock_rollback": return "Correct the system clock to the last recorded room time; room links retry automatically.";
+    case "busy": return "Release the competing room store writer; the hub retries automatically.";
+    case "corrupt": case "invalid": case "untrusted": return "Inspect local room state and restore a trusted backup before retrying; do not delete replay records.";
+    case "unsupported": return "Upgrade agent-hub to a version supporting this room store, then restart the hub.";
+    case "limit": case "inbox_list_limit": return "Inspect ahub room status and ahub room inbox; resolve pending work before retrying.";
+    case "connecting": return "Wait for the broker connection; inspect ahub room status if it stays connecting.";
+    case "backpressure": return "Wait for the broker queue to drain; stored frames retry automatically.";
+    case "codec_pending": return "Wait for the member's signed codec advertisement; queued messages keep their original expiry. Inspect ahub room status if waiting continues.";
+    case "codec_unsupported": return "Upgrade both hubs and the broker, reconnect the room, then retry after signed codec support is available.";
+    case "broker_refused": return "Check broker availability and the signed room membership, then retry.";
+    case "transport_closed": return "Check the broker address and network connection; the link retries automatically.";
+    case "closed": return "Restart the hub to reopen room storage.";
+    case "state_changed": return "Read ahub room status again before retrying the operation.";
+    default: return "Check room storage permissions and broker availability; the hub retries store open automatically.";
+  }
+}
+export interface RoomHealth {
+  refused: Partial<Record<"invalid_presence" | "wrong_epoch" | "trust_changed" | "stale" | "invalid_frame", number>>;
+  outboxDepth: number;
+  oldestOutboxAgeMs: number | null;
+  lastReceiptAgeMs: number | null;
+}