@wrongstack/core 0.306.4 → 0.307.0

package/dist/coordination/mail-tools.d.ts

@@ -75,12 +75,12 @@ export declare function makeMailSendTool(opts?: MailToolsOptions): {
         required: string[];
     };
     execute(input: unknown, ctx: Context): Promise<{
-        summary?: never;
         ok: boolean;
         error: string;
         messageId?: never;
         from?: never;
         to?: never;
+        summary?: never;
     } | {
         error?: never;
         ok: boolean;

package/dist/coordination/mailbox-http-actor-query.d.ts

@@ -0,0 +1,16 @@
+import { type MailboxCheckInput } from './mailbox-http-validation.js';
+import type { ActorMailboxMessage, Mailbox, MailboxActorContext, MailboxCapability, MailboxMessage, MailboxMessageType } from './mailbox-types.js';
+export declare function stripAggregateReceiptState(message: MailboxMessage, actorId: string): ActorMailboxMessage;
+export declare function eligibleRecipientsForActor(actor: MailboxActorContext): string[];
+export declare function queryMessagesForActor(mailbox: Mailbox, actor: MailboxActorContext, query: Parameters<Mailbox['query']>[0]): Promise<MailboxMessage[]>;
+export declare function visibleMessageIdsForActor(mailbox: Mailbox, actor: MailboxActorContext, messageIds: readonly string[]): Promise<Set<string>>;
+export declare function unreadCountForActor(mailbox: Mailbox, actor: MailboxActorContext): Promise<number>;
+export declare function isMessageCompletedForActor(message: MailboxMessage, actorId: string): boolean;
+export declare function isMessageVisibleToActor(mailbox: Mailbox, messageId: string, actor: MailboxActorContext): Promise<boolean>;
+export declare function requiredSendCapability(type: MailboxMessageType): MailboxCapability | undefined;
+export declare function requiredCredentialCapability(method: string, path: string): MailboxCapability | undefined;
+export declare function checkMailbox(mailbox: Mailbox, input: MailboxCheckInput, minTimestampIso: string | undefined, includeReceiptState?: boolean, eligibleRecipients?: readonly string[], readerRole?: string): Promise<{
+    data: MailboxMessage[];
+    count: number;
+}>;
+//# sourceMappingURL=mailbox-http-actor-query.d.ts.map

package/dist/coordination/mailbox-http-router.d.ts

@@ -14,63 +14,15 @@ export interface MailboxHttpRouterOptions {
     mailbox: Mailbox;
     eventEmitter?: MailboxEventEmitter;
     authorize?: (request: IncomingMessage) => MailboxHttpAccessDecision | Promise<MailboxHttpAccessDecision>;
-    /** Identity-scoped credential store for principal-based auth (GM-P0.6). */
     credentialStore?: MailboxCredentialVerifier;
-    /** Project ID for credential-based auth project-scoping (GM-P0.9). */
     projectId?: string;
     rateLimiter?: MailboxHttpRateLimiter;
     maxBodyBytes?: number;
-    /**
-     * Server-default look-back window for mailbox routes that return
-     * `MailboxMessage` records (`/mailbox/query`, `/mailbox/check`,
-     * `/mailbox/events`).
-     *
-     * The filter is **opt-in**: leaving `defaultMaxAgeMs` `undefined`
-     * (the default) leaves the filter disabled and every retained
-     * message is eligible to be returned or streamed. Pass an explicit
-     * non-negative integer (e.g. `60 * 60_000` for a 1-hour look-back,
-     * or {@link MAILBOX_HTTP_DEFAULT_MAX_AGE_MS}) to activate it.
-     *
-     * Mail older than the resolved look-back is filtered out of JSON
-     * responses and from SSE delivery so polling agents are never
-     * flooded with stale mail. The library intentionally does NOT
-     * enable a default look-back; host integrators that want the
-     * 1-hour server default must opt in explicitly.
-     *
-     * Per-request override: callers may append `?sinceMs=<ms>` to the
-     * request URL (the URL is rewritten by hosts that mount the router
-     * below a prefix). `0` opts in to the full retained history (matches
-     * the disable semantics of `defaultMaxAgeMs` below) and any positive
-     * value above {@link MAILBOX_HTTP_MAX_AGE_CEILING_MS} is silently
-     * clamped to that ceiling — this is a soft cap, not a hard rejection.
-     *
-     * Disabling the filter server-wide: pass `defaultMaxAgeMs` as
-     * `undefined` (the default), any negative number (`-1` is the
-     * canonical test-suite escape hatch), any non-finite value (`NaN`,
-     * `Infinity`, `-Infinity`), or `0`. `0` here is reserved because
-     * `now - 0` would otherwise map to the current instant and hide
-     * every retained message; `resolveDefault()` therefore treats `0` as
-     * equivalent to "disabled" via the same sentinel path as
-     * `undefined` / negative / non-finite values. The per-request
-     * `?sinceMs=0` URL parameter and the server-side `defaultMaxAgeMs=0`
-     * option therefore share identical "no filter" semantics.
-     */
     defaultMaxAgeMs?: number;
 }
 export interface MailboxHttpRouter {
-    /**
-     * Handle one canonical mailbox HTTP request. `routePath` lets a host mount
-     * the protocol below another prefix while preserving the public
-     * `/mailbox/*` route contract internally.
-     */
     handle(request: IncomingMessage, response: ServerResponse, routePath?: string): Promise<void>;
-    /** Close every active SSE stream owned by this router. Idempotent. */
     close(): void;
-    /**
-     * True while at least one SSE stream is open. Hosts that cache routers
-     * (e.g. HQ's per-project mailbox gateway map) use this to skip evicting a
-     * router that still has a live stream — closing it would cut the client.
-     */
     hasActiveStreams(): boolean;
 }
 export declare function createMailboxHttpRouter(options: MailboxHttpRouterOptions): MailboxHttpRouter;

package/dist/coordination/mailbox-http-sse.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { MailboxCredentialVerifier } from './mailbox-credential-store.js';
+import type { MailboxEventEmitter } from './mailbox-events.js';
+import type { MailboxActorContext } from './mailbox-types.js';
+export declare const MAX_SSE_BUFFER_BYTES: number;
+export declare function mailboxEventRecords(event: unknown): Record<string, unknown>[];
+export declare function extractEventTimestamp(event: unknown): string | undefined;
+export declare function isEventOlderThan(event: unknown, minTimestampIso: string): boolean;
+export declare function isMailboxEventVisibleToActor(event: unknown, actor: MailboxActorContext): boolean;
+export declare function createCredentialRevalidator(request: IncomingMessage, store: MailboxCredentialVerifier, actor: MailboxActorContext): () => Promise<boolean>;
+export declare function handleSse(request: IncomingMessage, response: ServerResponse, eventEmitter: MailboxEventEmitter, minTimestampIso: string | undefined, closeSseStreams: Set<() => void>, actor?: MailboxActorContext, revalidateCredential?: () => Promise<boolean>): void;
+//# sourceMappingURL=mailbox-http-sse.d.ts.map

package/dist/coordination/mailbox-message-types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared mailbox message DTOs.
+ *
+ * Dependency leaf consumed by the mailbox helpers (mailbox-predicates,
+ * mailbox-session-sync) and re-exported through the mailbox-types facade.
+ * Splitting these out of the facade breaks the type-level module SCC the
+ * architecture gate (ARCH-CYCLE-TYPE check) reports between the helpers and
+ * the facade.
+ */
+import type { MailboxMessageType } from './mailbox-type-properties.js';
+export type MailboxAudience = 'all' | 'leaders';
+export interface ReadReceipts {
+    [agentId: string]: string;
+}
+export interface MailboxTaskContext {
+    agentRole?: string | undefined;
+    agentName?: string | undefined;
+    taskId?: string | undefined;
+    status?: 'pending' | 'in_progress' | 'completed' | 'failed' | undefined;
+}
+export interface MailboxScopedSessionAffinity {
+    sessionId: string;
+    reportId?: string | undefined;
+    kind?: string | undefined;
+}
+export interface MailboxLegacyReportSessionAffinity {
+    sessionId?: undefined;
+    reportId: string;
+    kind?: string | undefined;
+}
+export type MailboxSessionAffinity = MailboxScopedSessionAffinity | MailboxLegacyReportSessionAffinity;
+export interface MailboxMessage {
+    id: string;
+    from: string;
+    to: string;
+    type: MailboxMessageType;
+    audience?: MailboxAudience | undefined;
+    subject: string;
+    body: string;
+    priority: 'low' | 'normal' | 'high';
+    readBy: ReadReceipts;
+    completed: boolean;
+    completedBy?: string | undefined;
+    outcome?: string | undefined;
+    timestamp: string;
+    completedAt?: string | undefined;
+    deletedAt?: string | undefined;
+    deletedBy?: string | undefined;
+    replyTo?: string | undefined;
+    taskContext?: MailboxTaskContext | undefined;
+    senderSessionId?: string | undefined;
+    sessionAffinity?: MailboxSessionAffinity | undefined;
+    expiresAt?: string | undefined;
+}
+export interface MailboxReceiptRecordV2 {
+    __mailboxReceipt: 2;
+    messageId: string;
+    actorId: string;
+    timestamp: string;
+    read?: boolean | undefined;
+    completed?: boolean | undefined;
+    outcome?: string | undefined;
+}
+export interface ActorMailboxMessage extends Omit<MailboxMessage, 'readBy' | 'completed' | 'completedBy' | 'completedAt' | 'outcome'> {
+    readByMe: boolean;
+    completedByMe: boolean;
+    actionRequiredForMe: boolean;
+    myOutcome?: string | undefined;
+    legacyGlobalCompletion?: boolean | undefined;
+}
+//# sourceMappingURL=mailbox-message-types.d.ts.map

package/dist/coordination/mailbox-predicates.d.ts

@@ -0,0 +1,13 @@
+import { type MailboxMessageType } from './mailbox-type-properties.js';
+import type { ActorMailboxMessage, MailboxMessage, MailboxReceiptRecordV2 } from './mailbox-message-types.js';
+export declare function mailboxIdentityBase(agentId: string): string;
+export declare function isMailboxLeader(agentId: string, role?: string): boolean;
+export declare function isMailboxSenderInFamily(senderId: string, family: string): boolean;
+export declare function isMailboxMessageVisibleTo(message: Pick<MailboxMessage, 'audience'>, agentId: string, role?: string): boolean;
+export declare function validateSendType(type: MailboxMessageType, to: string): void;
+export declare const SESSION_RECIPIENT_PREFIX = "@session:";
+export declare function sessionRecipient(sessionId: string): string;
+export declare function normalizeRecipient(to: string, sessionId?: string): string;
+export declare function isMailboxReceiptRecordV2(value: unknown): value is MailboxReceiptRecordV2;
+export declare function isActionRequiredForActor(message: Pick<MailboxMessage, 'type' | 'deletedAt' | 'completed'>, projection: Pick<ActorMailboxMessage, 'completedByMe' | 'legacyGlobalCompletion'>): boolean;
+//# sourceMappingURL=mailbox-predicates.d.ts.map

package/dist/coordination/mailbox-project-server.js

@@ -1353,7 +1353,7 @@ var AUTO_COMPACT_TYPE_TTL_MS = {
   // 30 min
 };
 
-// src/coordination/mailbox-types.ts
+// src/coordination/mailbox-predicates.ts
 function mailboxIdentityBase(agentId) {
   return agentId.split(/[@#]/, 1)[0].trim().toLowerCase();
 }

package/dist/coordination/mailbox-session-sync.d.ts

@@ -0,0 +1,8 @@
+import type { MailboxMessage } from './mailbox-message-types.js';
+export interface MailboxSessionAffinityContext {
+    resolveChimeraReportSessionId?: ((reportId: string) => string | undefined | Promise<string | undefined>) | undefined;
+    allowUnscoped?: boolean | undefined;
+}
+export declare function acceptMailboxMessageForSession(message: Pick<MailboxMessage, 'type' | 'sessionAffinity'>, currentSessionId: string | undefined, ctx?: MailboxSessionAffinityContext): Promise<boolean>;
+export declare function acceptMailboxMessageForSessionSync(message: Pick<MailboxMessage, 'type' | 'sessionAffinity'>, currentSessionId: string | undefined, ctx?: MailboxSessionAffinityContext): boolean;
+//# sourceMappingURL=mailbox-session-sync.d.ts.map