@aeolus-fleet/gateway 0.29.2 → 0.31.0

package/dist/core/people/ports.d.ts

@@ -3,7 +3,7 @@
  * messaging (decisions 0054, 0057): the fleet's calls it makes as their
  * account, and the one crew every client of the person shares.
  */
-import type { DeliveryId, FleetId, MessageId, ShipId, ShipKind } from '@aeolus-fleet/common';
+import type { DeliveryId, FleetId, MeetingId, MessageId, ShipId, ShipKind } from '@aeolus-fleet/common';
 import type { FleetRefusal } from '../connection/ports.js';
 import type { DiscoveredStatement } from '../mcp-in/ports.js';
 import type { Result } from '../shared/result.js';
@@ -29,12 +29,43 @@ export interface PersonCrew {
     readonly crewToken: string;
     readonly crewedAt: Date;
 }
+/** A person ship, by its fleet and id. */
+export interface PersonShip {
+    readonly fleetId: FleetId;
+    readonly shipId: ShipId;
+}
 export interface PersonCrews {
+    /** The person ships it holds a crew for, of every fleet, by fleet and ship, after the one given (wake a person, W7). */
+    crewed(page: {
+        after: PersonShip | null;
+        limit: number;
+    }): Promise<PersonShip[]>;
     find(fleetId: FleetId, shipId: ShipId): Promise<PersonCrew | undefined>;
     save(crew: PersonCrew): Promise<void>;
     /** Forgets a crew that no longer works, as when its lease ended, so the ship is crewed again. */
     drop(fleetId: FleetId, shipId: ShipId): Promise<void>;
 }
+/**
+ * Outbound port: the lock of each person ship's waiter, held by one gateway
+ * instance at a time (wake a person, W9). An instance that loses its hold,
+ * as when its connection to the database ends, loses every lock it held.
+ */
+export interface WaiterLocks {
+    /** Takes the ship's lock unless another instance holds it: whether it holds it now. */
+    take(ship: PersonShip): Promise<boolean>;
+    give(ship: PersonShip): Promise<void>;
+    /** Hears each loss of every lock this instance held. */
+    onLost(listener: () => void): void;
+}
+/** A change to a person ship's inbox: its pages read it again (wake a person, #1014). */
+export interface InboxChange {
+    readonly fleetId: FleetId;
+    readonly shipId: ShipId;
+}
+/** Outbound port: tells every gateway instance that a person ship's inbox changed, carrying nothing of it. */
+export interface InboxChanges {
+    tell(change: InboxChange): Promise<void>;
+}
 /** A delivery to the person ship, as the fleet's push receive hands it. */
 export interface PersonDelivery {
     readonly deliveryId: DeliveryId;
@@ -47,6 +78,12 @@ export interface PersonDelivery {
     readonly questionTitle: string | null;
     readonly sentAt: Date;
     readonly inReplyTo: MessageId | null;
+    /** The meeting its message was contributed to or tells of; none outside a meeting (decision 0061). */
+    readonly meetingId: MeetingId | null;
+}
+/** A delivery as the person ship's push receive hands it: with the last number it was handed with under this lease, null while never handed (decision 0040). */
+export interface PushedPersonDelivery extends PersonDelivery {
+    readonly handOverNumber: number | null;
 }
 /** What a person ship may send to now, as the fleet's discover answers it: each ship by name, with what it offers, and each type. */
 export interface PersonDiscovery {
@@ -61,24 +98,35 @@ export interface PersonDiscovery {
         readonly reachable: number;
     }[];
 }
-/** Who a person's message is for: one ship by its name, or any ship of a type. */
+/** Who a person's message is for: one ship by its name, any ship of a type, or every other participant of a meeting, a contribution (decision 0061). */
 export type PersonSelector = {
     readonly kind: 'ship';
     readonly name: string;
 } | {
     readonly kind: 'type';
     readonly type: string;
+} | {
+    readonly kind: 'meeting';
+    readonly meetingId: MeetingId;
 };
 /** Outbound port: the fleet's calls the gateway makes as the crew of a person ship. */
 export interface PersonShipDoor {
-    /** How many deliveries wait for the ship, without waiting. */
-    inbox(crewToken: string): Promise<Result<{
+    /**
+     * How many deliveries wait for the ship: at once, or with a wait while the
+     * count is still the one the crew knows, up to the fleet's longest wait
+     * (wake a person, W5), or less when told. Stopping the signal ends the wait.
+     */
+    inbox(crewToken: string, wait?: {
+        knownWaiting: number;
+        signal: AbortSignal;
+        atMostMs?: number;
+    }): Promise<Result<{
         waiting: number;
     }, FleetRefusal>>;
     /** The ship's deliveries, up to max, its own held ones again first. */
     pushReceive(crewToken: string, take: {
         max: number;
-    }): Promise<Result<PersonDelivery[], FleetRefusal>>;
+    }): Promise<Result<PushedPersonDelivery[], FleetRefusal>>;
     /** Acknowledges a delivery the person opened: their own act confirms it (interop 5.1). */
     ack(crewToken: string, deliveryId: DeliveryId): Promise<Result<undefined, FleetRefusal>>;
     /** Reads a delivery the ship acknowledged again, whole, while it is not handled, recording nothing (decision 0040). */
@@ -93,6 +141,12 @@ export interface PersonShipDoor {
     }): Promise<Result<undefined, FleetRefusal>>;
     /** Reports the person dealt with the delivery. */
     handled(crewToken: string, deliveryId: DeliveryId): Promise<Result<undefined, FleetRefusal>>;
+    /** Hands the delivery over to the person with its number, naming the channel the wake went through (interop 5.1). */
+    handed(crewToken: string, handOver: {
+        deliveryId: DeliveryId;
+        handOverNumber: number;
+        channel: HandOverChannel;
+    }): Promise<Result<'handed' | 'acknowledged' | 'undeliverable', FleetRefusal>>;
     /** The ships and types the ship may send to now: the fleet checks its scopes and the network rules. */
     discover(crewToken: string): Promise<Result<PersonDiscovery, FleetRefusal>>;
     /** Sends the person's own message, once under its key. */
@@ -139,3 +193,102 @@ export interface OpenedDeliveries {
         deliveryId: string;
     }): Promise<void>;
 }
+/** The channels a person may turn on to be woken (wake a person, W1), as a hand-over names them. */
+export type WakeChannelName = 'email' | 'web-push';
+/** What a delivery is handed to the person through: a wake's channel, or a page of theirs in focus, which shows it (W6). */
+export type HandOverChannel = WakeChannelName | 'page';
+/**
+ * Outbound port: one way to wake a person (wake a person, W1, W4): it says
+ * only that something waits in the fleet, with the overview's link, and
+ * goes out at most once per its window (W3, W10).
+ */
+export interface WakeChannel {
+    readonly name: WakeChannelName;
+    /** The least time between two wakes it sends one person ship, from the gateway's configuration (W10). */
+    readonly windowMs: number;
+    /** Whether the person turned it on (W8): nothing is on by default. */
+    isOn(ship: PersonShip): Promise<boolean>;
+    /** Sends the wake: whether it went out. */
+    wake(ship: PersonShip): Promise<Result<undefined, {
+        reason: string;
+    }>>;
+}
+/** Outbound port: when each channel last woke each person ship, so the window holds across restarts and instances (W3). */
+export interface WakesSent {
+    lastSentAt(ship: PersonShip, channel: WakeChannelName): Promise<Date | undefined>;
+    record(wake: {
+        ship: PersonShip;
+        channel: WakeChannelName;
+        sentAt: Date;
+    }): Promise<void>;
+}
+/** Outbound port: whether each person turned email on to be woken for their person ship (W8), by fleet and person ship. */
+export interface EmailChannels {
+    isOn(ship: PersonShip): Promise<boolean>;
+    turn(ship: PersonShip, switched: {
+        isOn: boolean;
+        at: Date;
+    }): Promise<void>;
+}
+/** A page of a person in focus (wake a person, W6): by its own id, with when it was last seen in focus. */
+export interface FocusedPage {
+    readonly fleetId: FleetId;
+    readonly shipId: ShipId;
+    readonly pageId: string;
+    readonly seenAt: Date;
+}
+/** Outbound port: the pages in focus of every gateway instance, so the waiter of a ship sees them wherever it runs. */
+export interface FocusedPages {
+    /** Keeps it, or keeps when it was seen anew. */
+    save(page: FocusedPage): Promise<void>;
+    remove(fleetId: FleetId, pageId: string): Promise<void>;
+    /** Whether any page of the person ship's person was seen in focus since then. */
+    isAnyInFocus(ship: PersonShip, since: Date): Promise<boolean>;
+}
+/**
+ * A browser a person turned web push on in (wake a person, W8): its push
+ * service's endpoint and keys, and the fleet's name its wakes say, as the
+ * person's sign-in named it when they turned it on. A subscription its push
+ * service said is gone takes no wake again, and the overview says so.
+ */
+export interface WebPushSubscription {
+    readonly fleetId: FleetId;
+    readonly shipId: ShipId;
+    readonly endpoint: string;
+    readonly keys: {
+        readonly p256dh: string;
+        readonly auth: string;
+    };
+    /** The browser, as its person sees it named, such as Firefox on Linux. */
+    readonly browser: string;
+    readonly fleetName: string;
+    readonly addedAt: Date;
+    readonly goneAt: Date | null;
+}
+/** Outbound port: the browsers each person turned web push on in, by fleet, person ship and endpoint. */
+export interface WebPushSubscriptions {
+    /** The person ship's, oldest added first. */
+    list(fleetId: FleetId, shipId: ShipId): Promise<WebPushSubscription[]>;
+    /** Keeps it, or keeps it anew when its endpoint was kept before. */
+    save(subscription: WebPushSubscription): Promise<void>;
+    markGone(fleetId: FleetId, gone: {
+        shipId: ShipId;
+        endpoint: string;
+        goneAt: Date;
+    }): Promise<void>;
+    remove(fleetId: FleetId, removed: {
+        shipId: ShipId;
+        endpoint: string;
+    }): Promise<void>;
+}
+/** What a wake says (W4): something waits in the fleet, by its name, and the link to the gateway's overview. Nothing else. */
+export interface Wake {
+    readonly fleetName: string;
+    readonly overviewUrl: string;
+}
+/** How a push service took a wake: sent, gone (it answered 404 or 410: the subscription ended), or failed otherwise. */
+export type WebPushSent = 'sent' | 'gone' | 'failed';
+/** Outbound port: sends a wake to one browser through its push service. */
+export interface WebPush {
+    send(subscription: WebPushSubscription, wake: Wake): Promise<WebPushSent>;
+}

package/dist/core/people/read-wake-channels.d.ts

@@ -0,0 +1,42 @@
+import { type Result } from '../shared/result.js';
+import type { CrewPersonShip } from './crew-person-ship.js';
+import { type PersonCaller, type PersonCrewError } from './person-crew.js';
+import type { EmailChannels, WebPushSubscriptions } from './ports.js';
+/** A browser a person turned web push on in, as the overview lists it: gone once its push service ended the subscription. */
+export interface WebPushBrowser {
+    readonly endpoint: string;
+    readonly browser: string;
+    readonly addedAt: Date;
+    readonly isGone: boolean;
+}
+/**
+ * The channels that wake a person, as their overview shows them: email
+ * offered or not, and on or not; web push with the gateway's public push
+ * key a browser subscribes with, none where it is not offered, and the
+ * browsers they turned it on in.
+ */
+export interface WakeChannels {
+    readonly email: {
+        readonly isOffered: boolean;
+        readonly isOn: boolean;
+    };
+    readonly webPush: {
+        readonly publicKey: string | null;
+        readonly browsers: readonly WebPushBrowser[];
+    };
+}
+export type ReadWakeChannels = (caller: PersonCaller) => Promise<Result<WakeChannels, PersonCrewError>>;
+/**
+ * Use case: the channels that wake a person when something waits for their
+ * person ship (wake a person, W8). Email is offered only where the gateway
+ * can ask pagasae to send it, web push only where it holds push keys;
+ * nothing is on by default. A browser's keys are never shown.
+ */
+export declare function createReadWakeChannels(deps: {
+    crewPersonShip: CrewPersonShip;
+    emailChannels: EmailChannels;
+    isEmailOffered: boolean;
+    subscriptions: WebPushSubscriptions;
+    /** The gateway's public push key; none where it holds no push keys. */
+    webPushKey: string | null;
+}): ReadWakeChannels;

package/dist/core/people/read-wake-channels.js

@@ -0,0 +1,21 @@
+import { ok } from '../shared/result.js';
+import { personCrewOf } from './person-crew.js';
+/**
+ * Use case: the channels that wake a person when something waits for their
+ * person ship (wake a person, W8). Email is offered only where the gateway
+ * can ask pagasae to send it, web push only where it holds push keys;
+ * nothing is on by default. A browser's keys are never shown.
+ */
+export function createReadWakeChannels(deps) {
+    return async (caller) => {
+        const crew = await personCrewOf(deps.crewPersonShip, caller);
+        if (!crew.isOk) {
+            return crew;
+        }
+        const ship = { fleetId: caller.fleetId, shipId: crew.value.shipId };
+        const isOn = deps.isEmailOffered && (await deps.emailChannels.isOn(ship));
+        const browsers = deps.webPushKey === null ? [] : (await deps.subscriptions.list(ship.fleetId, ship.shipId)).map(({ endpoint, browser, addedAt, goneAt }) => ({ endpoint, browser, addedAt, isGone: goneAt !== null }));
+        return ok({ email: { isOffered: deps.isEmailOffered, isOn }, webPush: { publicKey: deps.webPushKey, browsers } });
+    };
+}
+//# sourceMappingURL=read-wake-channels.js.map

package/dist/core/people/read-wake-channels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-wake-channels.js","sourceRoot":"","sources":["../../../src/core/people/read-wake-channels.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAA2C,MAAM,kBAAkB,CAAC;AAwBzF;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAOtC;IACC,OAAO,KAAK,EAAE,MAAM,EAAE,EAAE;QACtB,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,GAAG,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;QACpE,MAAM,IAAI,GAAG,IAAI,CAAC,cAAc,IAAI,CAAC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC1E,MAAM,QAAQ,GACZ,IAAI,CAAC,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;QACxM,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAC;IACpH,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/people/turn-email-channel.d.ts

@@ -0,0 +1,21 @@
+import type { Clock } from '../shared/clock.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import type { CrewPersonShip } from './crew-person-ship.js';
+import { type PersonCaller, type PersonCrewError } from './person-crew.js';
+import type { EmailChannels } from './ports.js';
+export type TurnEmailChannel = (turn: {
+    caller: PersonCaller;
+    isOn: boolean;
+}) => Promise<Result<undefined, PersonCrewError | DomainError<'CHANNEL_NOT_OFFERED'>>>;
+/**
+ * Use case: a person turns email on or off, to be woken when something
+ * waits for their person ship (wake a person, W8), kept by fleet and person
+ * ship. Turning it on is refused where the gateway cannot send email.
+ */
+export declare function createTurnEmailChannel(deps: {
+    crewPersonShip: CrewPersonShip;
+    emailChannels: EmailChannels;
+    isEmailOffered: boolean;
+    clock: Clock;
+}): TurnEmailChannel;

package/dist/core/people/turn-email-channel.js

@@ -0,0 +1,22 @@
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+import { personCrewOf } from './person-crew.js';
+/**
+ * Use case: a person turns email on or off, to be woken when something
+ * waits for their person ship (wake a person, W8), kept by fleet and person
+ * ship. Turning it on is refused where the gateway cannot send email.
+ */
+export function createTurnEmailChannel(deps) {
+    return async ({ caller, isOn }) => {
+        if (isOn && !deps.isEmailOffered) {
+            return refuse('CHANNEL_NOT_OFFERED', 'This gateway sends no email');
+        }
+        const crew = await personCrewOf(deps.crewPersonShip, caller);
+        if (!crew.isOk) {
+            return crew;
+        }
+        await deps.emailChannels.turn({ fleetId: caller.fleetId, shipId: crew.value.shipId }, { isOn, at: deps.clock.now() });
+        return ok(undefined);
+    };
+}
+//# sourceMappingURL=turn-email-channel.js.map

package/dist/core/people/turn-email-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-email-channel.js","sourceRoot":"","sources":["../../../src/core/people/turn-email-channel.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAA2C,MAAM,kBAAkB,CAAC;AAKzF;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAA6G;IAClJ,OAAO,KAAK,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE;QAChC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC;YACjC,OAAO,MAAM,CAAC,qBAAqB,EAAE,6BAA6B,CAAC,CAAC;QACtE,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACtH,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/people/turn-off-web-push.d.ts

@@ -0,0 +1,13 @@
+import { type Result } from '../shared/result.js';
+import type { CrewPersonShip } from './crew-person-ship.js';
+import { type PersonCaller, type PersonCrewError } from './person-crew.js';
+import type { WebPushSubscriptions } from './ports.js';
+export type TurnOffWebPush = (input: {
+    caller: PersonCaller;
+    endpoint: string;
+}) => Promise<Result<undefined, PersonCrewError>>;
+/** Use case: a person removes a browser they turned web push on in (wake a person, W8): it takes no wake again. */
+export declare function createTurnOffWebPush(deps: {
+    crewPersonShip: CrewPersonShip;
+    subscriptions: WebPushSubscriptions;
+}): TurnOffWebPush;

package/dist/core/people/turn-off-web-push.js

@@ -0,0 +1,14 @@
+import { ok } from '../shared/result.js';
+import { personCrewOf } from './person-crew.js';
+/** Use case: a person removes a browser they turned web push on in (wake a person, W8): it takes no wake again. */
+export function createTurnOffWebPush(deps) {
+    return async ({ caller, endpoint }) => {
+        const crew = await personCrewOf(deps.crewPersonShip, caller);
+        if (!crew.isOk) {
+            return crew;
+        }
+        await deps.subscriptions.remove(caller.fleetId, { shipId: crew.value.shipId, endpoint });
+        return ok(undefined);
+    };
+}
+//# sourceMappingURL=turn-off-web-push.js.map

package/dist/core/people/turn-off-web-push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-off-web-push.js","sourceRoot":"","sources":["../../../src/core/people/turn-off-web-push.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAA2C,MAAM,kBAAkB,CAAC;AAKzF,mHAAmH;AACnH,MAAM,UAAU,oBAAoB,CAAC,IAA6E;IAChH,OAAO,KAAK,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE;QACpC,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;QACzF,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/people/turn-on-web-push.d.ts

@@ -0,0 +1,35 @@
+import type { HostResolver } from '../a2a-in/ports.js';
+import type { Clock } from '../shared/clock.js';
+import { type DomainError } from '../shared/errors.js';
+import { type Result } from '../shared/result.js';
+import type { CrewPersonShip } from './crew-person-ship.js';
+import { type PersonCaller, type PersonCrewError } from './person-crew.js';
+import type { WebPushSubscriptions } from './ports.js';
+export interface WebPushTurnedOn {
+    readonly caller: PersonCaller;
+    /** The fleet's name its wakes say, as the person's sign-in names it. */
+    readonly fleetName: string;
+    readonly endpoint: string;
+    readonly keys: {
+        readonly p256dh: string;
+        readonly auth: string;
+    };
+    readonly browser: string;
+}
+export type TurnOnWebPush = (input: WebPushTurnedOn) => Promise<Result<undefined, PersonCrewError | DomainError<'CHANNEL_NOT_OFFERED' | 'INVALID_SUBSCRIPTION'>>>;
+/**
+ * Use case: a person turns web push on for a browser (wake a person, W8),
+ * with the subscription the browser's push service gave it: kept for their
+ * person ship, a browser turned on again kept anew. A push service is
+ * reached over https at public addresses only, as A2A webhooks are: an
+ * endpoint whose host is, or resolves to, any private, loopback or
+ * link-local address is refused. Refused where the gateway holds no push
+ * keys.
+ */
+export declare function createTurnOnWebPush(deps: {
+    crewPersonShip: CrewPersonShip;
+    subscriptions: WebPushSubscriptions;
+    resolver: HostResolver;
+    isWebPushOffered: boolean;
+    clock: Clock;
+}): TurnOnWebPush;

package/dist/core/people/turn-on-web-push.js

@@ -0,0 +1,49 @@
+import { reachOf } from '../a2a-in/webhook-address.js';
+import { refuse } from '../shared/errors.js';
+import { ok } from '../shared/result.js';
+import { personCrewOf } from './person-crew.js';
+/** The longest push service endpoint the gateway keeps. */
+const ENDPOINT_MAX_LENGTH = 2048;
+/** The longest browser name, as the page names it. */
+const BROWSER_MAX_LENGTH = 100;
+/** A browser's P-256 public key (65 bytes) and auth secret (16 bytes), base64url as its PushSubscription states them, padded or not. */
+const P256DH = /^[A-Za-z0-9_-]{87}=?$/;
+const AUTH = /^[A-Za-z0-9_-]{22}(==)?$/;
+function isHttpsUrl(text) {
+    return URL.canParse(text) && new URL(text).protocol === 'https:';
+}
+/**
+ * Use case: a person turns web push on for a browser (wake a person, W8),
+ * with the subscription the browser's push service gave it: kept for their
+ * person ship, a browser turned on again kept anew. A push service is
+ * reached over https at public addresses only, as A2A webhooks are: an
+ * endpoint whose host is, or resolves to, any private, loopback or
+ * link-local address is refused. Refused where the gateway holds no push
+ * keys.
+ */
+export function createTurnOnWebPush(deps) {
+    return async ({ caller, fleetName, endpoint, keys, browser }) => {
+        if (!deps.isWebPushOffered) {
+            return refuse('CHANNEL_NOT_OFFERED', 'This gateway sends no web push');
+        }
+        if (endpoint.length > ENDPOINT_MAX_LENGTH || !isHttpsUrl(endpoint)) {
+            return refuse('INVALID_SUBSCRIPTION', `The push service's endpoint must be an https URL of at most ${String(ENDPOINT_MAX_LENGTH)} characters`);
+        }
+        if (!P256DH.test(keys.p256dh) || !AUTH.test(keys.auth)) {
+            return refuse('INVALID_SUBSCRIPTION', "The browser's push keys are not a P-256 public key and an auth secret of 16 bytes");
+        }
+        if (browser.length === 0 || browser.length > BROWSER_MAX_LENGTH) {
+            return refuse('INVALID_SUBSCRIPTION', `The browser's name must hold 1 to ${String(BROWSER_MAX_LENGTH)} characters`);
+        }
+        if ((await reachOf(deps.resolver, new URL(endpoint))) !== 'public') {
+            return refuse('INVALID_SUBSCRIPTION', "The push service's endpoint must resolve to public addresses only");
+        }
+        const crew = await personCrewOf(deps.crewPersonShip, caller);
+        if (!crew.isOk) {
+            return crew;
+        }
+        await deps.subscriptions.save({ fleetId: caller.fleetId, shipId: crew.value.shipId, endpoint, keys, browser, fleetName, addedAt: deps.clock.now(), goneAt: null });
+        return ok(undefined);
+    };
+}
+//# sourceMappingURL=turn-on-web-push.js.map

package/dist/core/people/turn-on-web-push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn-on-web-push.js","sourceRoot":"","sources":["../../../src/core/people/turn-on-web-push.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAEvD,OAAO,EAAE,MAAM,EAAoB,MAAM,qBAAqB,CAAC;AAC/D,OAAO,EAAE,EAAE,EAAe,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,YAAY,EAA2C,MAAM,kBAAkB,CAAC;AAGzF,2DAA2D;AAC3D,MAAM,mBAAmB,GAAG,IAAI,CAAC;AAEjC,sDAAsD;AACtD,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B,wIAAwI;AACxI,MAAM,MAAM,GAAG,uBAAuB,CAAC;AACvC,MAAM,IAAI,GAAG,0BAA0B,CAAC;AAaxC,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACnE,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAA8I;IAChL,OAAO,KAAK,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE;QAC9D,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;YAC3B,OAAO,MAAM,CAAC,qBAAqB,EAAE,gCAAgC,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,QAAQ,CAAC,MAAM,GAAG,mBAAmB,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACnE,OAAO,MAAM,CAAC,sBAAsB,EAAE,+DAA+D,MAAM,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;QACjJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACvD,OAAO,MAAM,CAAC,sBAAsB,EAAE,mFAAmF,CAAC,CAAC;QAC7H,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,GAAG,kBAAkB,EAAE,CAAC;YAChE,OAAO,MAAM,CAAC,sBAAsB,EAAE,qCAAqC,MAAM,CAAC,kBAAkB,CAAC,aAAa,CAAC,CAAC;QACtH,CAAC;QACD,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnE,OAAO,MAAM,CAAC,sBAAsB,EAAE,mEAAmE,CAAC,CAAC;QAC7G,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QAC7D,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACnK,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/core/people/wait-on-person-ship.d.ts

@@ -0,0 +1,44 @@
+import type { FleetId, ShipId } from '@aeolus-fleet/common';
+import type { Sleep } from '../mcp-out/run-party.js';
+import type { Clock } from '../shared/clock.js';
+import type { InboxChanges, PersonCrews, PersonShipDoor } from './ports.js';
+import type { WakePerson } from './wake-person.js';
+/**
+ * Why a waiter ended: the ship's crew no longer works and was dropped, the
+ * gateway holds no crew for the ship, or it was stopped.
+ */
+export type WaiterEnd = {
+    readonly reason: 'crewEnded';
+} | {
+    readonly reason: 'noCrew';
+} | {
+    readonly reason: 'stopped';
+};
+export type WaitOnPersonShip = (ship: {
+    fleetId: FleetId;
+    shipId: ShipId;
+}, signal: AbortSignal) => Promise<WaiterEnd>;
+/**
+ * Use case: the waiter of a person ship the gateway crews (wake a person,
+ * W5, W7). It looks once at the ship's inbox, then asks the fleet to wait
+ * while the count is the one it knows, and tells the person's pages at its
+ * first look and each time the count changed. When something waits at its
+ * first look, and each time the count rose, it wakes the person (W3); a
+ * wake a window held back is asked for again once the window ends, and one
+ * that failed after a wait, longer each time. It reads the crew it holds anew for every call, so
+ * a ship crewed again goes on with its new crew; a crew that no longer works
+ * is dropped, so the next sign-in crews again, and the waiter ends. While
+ * the fleet does not answer, it waits longer each time.
+ */
+export declare function createWaitOnPersonShip(deps: {
+    crews: PersonCrews;
+    door: Pick<PersonShipDoor, 'inbox'>;
+    changes: InboxChanges;
+    wakePerson: WakePerson;
+    clock: Clock;
+    sleep: Sleep;
+    /** How long to wait after each refusal in a row; the last repeats. */
+    againWaitsMs: readonly number[];
+    /** How long to wait before a wake that failed is tried again, each in a row; the last repeats. */
+    wakeAgainWaitsMs: readonly number[];
+}): WaitOnPersonShip;

package/dist/core/people/wait-on-person-ship.js

@@ -0,0 +1,92 @@
+import { isEndedCrew } from './person-crew.js';
+/**
+ * Use case: the waiter of a person ship the gateway crews (wake a person,
+ * W5, W7). It looks once at the ship's inbox, then asks the fleet to wait
+ * while the count is the one it knows, and tells the person's pages at its
+ * first look and each time the count changed. When something waits at its
+ * first look, and each time the count rose, it wakes the person (W3); a
+ * wake a window held back is asked for again once the window ends, and one
+ * that failed after a wait, longer each time. It reads the crew it holds anew for every call, so
+ * a ship crewed again goes on with its new crew; a crew that no longer works
+ * is dropped, so the next sign-in crews again, and the waiter ends. While
+ * the fleet does not answer, it waits longer each time.
+ */
+export function createWaitOnPersonShip(deps) {
+    return async (ship, signal) => {
+        const { fleetId, shipId } = ship;
+        let knownWaiting;
+        let refusedInARow = 0;
+        /** When to ask for a wake again though the count did not rise: a window ended, or a failed wake waited out. */
+        let wakeAgainAt;
+        let failedWakesInARow = 0;
+        // Read as a call, as the signal aborts between awaits.
+        const isStopped = () => signal.aborted;
+        /** Drops the crew that no longer works, unless the ship was crewed again meanwhile: whether it was dropped. */
+        const isDropped = async (crewToken) => {
+            const held = await deps.crews.find(fleetId, shipId);
+            if (held?.crewToken !== crewToken) {
+                return false;
+            }
+            await deps.crews.drop(fleetId, shipId);
+            return true;
+        };
+        const waitOf = (waitsMs, inARow) => waitsMs[Math.min(inARow, waitsMs.length - 1)] ?? 0;
+        while (!isStopped()) {
+            const crew = await deps.crews.find(fleetId, shipId);
+            if (crew === undefined) {
+                return { reason: 'noCrew' };
+            }
+            // A wake held back is asked for again once due, so the wait ends by then.
+            const atMostMs = wakeAgainAt === undefined ? undefined : Math.max(0, wakeAgainAt.getTime() - deps.clock.now().getTime());
+            const answered = await deps.door.inbox(crew.crewToken, knownWaiting === undefined ? undefined : { knownWaiting, signal, ...(atMostMs === undefined ? {} : { atMostMs }) });
+            if (isStopped()) {
+                break;
+            }
+            if (!answered.isOk) {
+                if (isEndedCrew(answered.error)) {
+                    if (await isDropped(crew.crewToken)) {
+                        return { reason: 'crewEnded' };
+                    }
+                    continue;
+                }
+                await deps.sleep(waitOf(deps.againWaitsMs, refusedInARow), signal);
+                refusedInARow += 1;
+                continue;
+            }
+            refusedInARow = 0;
+            const { waiting } = answered.value;
+            // The first look tells too: a page may have read the inbox before the waiter started.
+            if (waiting !== knownWaiting) {
+                await deps.changes.tell(ship);
+            }
+            const hasRisen = waiting > (knownWaiting ?? 0);
+            knownWaiting = waiting;
+            const isWakeDue = wakeAgainAt !== undefined && wakeAgainAt.getTime() <= deps.clock.now().getTime();
+            if (!hasRisen && !isWakeDue) {
+                continue;
+            }
+            const woken = await deps.wakePerson(ship, crew.crewToken);
+            if (!woken.isOk && isEndedCrew(woken.error) && (await isDropped(crew.crewToken))) {
+                return { reason: 'crewEnded' };
+            }
+            // A wake the fleet refused counts as one that failed: tried again after a wait.
+            const outcome = woken.isOk ? woken.value : { kind: 'failed' };
+            switch (outcome.kind) {
+                case 'settled':
+                    wakeAgainAt = undefined;
+                    failedWakesInARow = 0;
+                    break;
+                case 'inWindow':
+                    wakeAgainAt = outcome.until;
+                    failedWakesInARow = 0;
+                    break;
+                case 'failed':
+                    wakeAgainAt = new Date(deps.clock.now().getTime() + waitOf(deps.wakeAgainWaitsMs, failedWakesInARow));
+                    failedWakesInARow += 1;
+                    break;
+            }
+        }
+        return { reason: 'stopped' };
+    };
+}
+//# sourceMappingURL=wait-on-person-ship.js.map

package/dist/core/people/wait-on-person-ship.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-on-person-ship.js","sourceRoot":"","sources":["../../../src/core/people/wait-on-person-ship.ts"],"names":[],"mappings":"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"}

package/dist/core/people/wake-person.d.ts

@@ -0,0 +1,40 @@
+import type { FleetRefusal } from '../connection/ports.js';
+import type { Clock } from '../shared/clock.js';
+import { type Result } from '../shared/result.js';
+import type { FocusedPages, PersonShip, PersonShipDoor, WakeChannel, WakesSent } from './ports.js';
+/**
+ * What a wake came to: nothing left to wake (settled), a wake held back
+ * until the earliest window of a channel turned on ends (inWindow), or no
+ * channel sent it, so it is tried again (failed).
+ */
+export type WakeOutcome = {
+    readonly kind: 'settled';
+} | {
+    readonly kind: 'inWindow';
+    readonly until: Date;
+} | {
+    readonly kind: 'failed';
+};
+export type WakePerson = (ship: PersonShip, crewToken: string) => Promise<Result<WakeOutcome, FleetRefusal>>;
+/**
+ * Use case: wakes a person for what waits on their person ship (wake a
+ * person, W3, W8). It takes the ship's deliveries with the gateway as their
+ * waker; those never handed are fresh. Each channel the person turned on
+ * whose window has passed sends one wake for all of them; each fresh
+ * delivery is then handed no. 1, naming the first channel that went out, so
+ * a delivery is woken once. A wake held back by a window, or that no
+ * channel sent, hands nothing. Each channel's window is kept after the
+ * hand-overs, so a gateway that stopped in between wakes again: one wake
+ * more, nothing lost. While a page of the person is in focus, the page
+ * shows what arrives (W6): each fresh delivery is handed through it and no
+ * wake goes out.
+ */
+export declare function createWakePerson(deps: {
+    door: Pick<PersonShipDoor, 'pushReceive' | 'handed'>;
+    channels: readonly WakeChannel[];
+    wakesSent: WakesSent;
+    focused: FocusedPages;
+    /** How long a page counts in focus since it was last seen so. */
+    focusFreshMs: number;
+    clock: Clock;
+}): WakePerson;