@astrosheep/square 0.3.12 → 0.3.13

package/dist/inbox.js

@@ -1,34 +1,30 @@
-import { loadSquare } from './artifact.js';
-import { deriveDeliveryModel } from './delivery.js';
 import { lookupSessionBindings } from './registry.js';
-import { freshWatchLease, isCurrentlyJoined, resolveRosterName } from './runtime.js';
-export function sessionInbox(sessionId) {
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { inboxProjection } from './views.js';
+export async function sessionInbox(sessionId) {
     const inbox = [];
     for (const binding of lookupSessionBindings(sessionId)) {
+        let square;
         try {
-            const doc = loadSquare(binding.squarePath);
-            const name = resolveRosterName(doc, binding.name);
-            if (!name || !isCurrentlyJoined(doc.acts, name))
+            square = await openSquare(binding.squarePath);
+            const projection = await inboxProjection(square, binding.name, binding.ownerId);
+            if (!projection.joined)
                 continue;
-            const notifications = deriveDeliveryModel(doc).pendingFor(name).map(({ item, route }) => ({
-                actIndex: item.index,
-                actor: item.actor,
-                at: item.at,
-                route,
-                body: item.body,
-            }));
-            const lease = freshWatchLease(doc, name);
-            const catchLease = lease?.ownerId === binding.ownerId ? lease : undefined;
             inbox.push({
-                name,
+                name: projection.name,
                 squarePath: binding.squarePath,
-                notifications,
-                ...(catchLease !== undefined ? { catchLease } : {}),
+                notifications: [...projection.notifications],
+                ...(projection.catchLease !== undefined ? { catchLease: projection.catchLease } : {}),
             });
         }
         catch {
             // A stale discovery-cache row only disables delivery for that membership.
         }
+        finally {
+            if (square !== undefined)
+                await closeOpenSquare(square);
+        }
     }
     return inbox;
 }

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { type SquareRoute } from './delivery.js';
+import type { ExpressResult } from './square-facade.js';
+export { Square } from './square-wiring.js';
+export { SquareError } from './model.js';
+export { captureRoute } from './delivery.js';
+export type { SquareRoute } from './delivery.js';
+export type { ActivityId } from './square-core.js';
+export type { Activity, CatchOptions, CatchResult, ExpressOptions, ExpressResult, HistoryQuery, OpenOptions, Participant, ParticipantStatus, PerceivedActivity, SquareAtInput, SquareBuildInput, SquareSnapshot, SquareSource, WakeNotifier, } from './square-facade.js';
+export interface RouteExpressOptions {
+    readonly as: string;
+    readonly body: string;
+}
+export declare function express(route: SquareRoute, options: RouteExpressOptions): Promise<ExpressResult>;

package/dist/index.js

@@ -1,71 +1,33 @@
+import { extractMentions } from './square-core.js';
+import { parseSquareRoute } from './delivery.js';
+import { sameName, SquareError } from './model.js';
+import { Square } from './square-wiring.js';
+export { Square } from './square-wiring.js';
 export { SquareError } from './model.js';
-export { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
-export { loadSquare } from './artifact.js';
-export { countSays, joinedNames, doneNames, isCurrentlyJoined, publicActs, readCursor, } from './runtime.js';
-import { loadSquare } from './artifact.js';
-import { dispatchActNotifications, hasDeliveredNotification as hasDeliveredNotificationImpl, sweepPendingNotifications, waitForDeliveredNotification as waitForDeliveredNotificationImpl, } from './notifications.js';
-import { WATCH_STALE_MS, freshWatchLease, getReadState as getDocReadState, } from './runtime.js';
-import { resolveKnownName } from './decisions.js';
-import { execute } from './square-application.js';
-import { parseActivityId } from './square-core.js';
-export { WATCH_STALE_MS };
-function actRefIndex(ref) {
-    if (typeof ref === 'number')
-        return ref;
-    const index = parseActivityId(ref);
-    if (index === undefined)
-        throw new Error(`Invalid act ref: ${ref}`);
-    return index;
-}
-export function getReadState(squarePath, name) {
-    const doc = loadSquare(squarePath);
-    return getDocReadState(doc, resolveKnownName(doc, name));
-}
-export function hasConsumedAct(squarePath, name, ref) {
-    const state = getReadState(squarePath, name);
-    return (state?.consumedThroughIndex ?? -1) >= actRefIndex(ref);
-}
-export function hasDeliveredNotification(squarePath, name, ref) {
-    return hasDeliveredNotificationImpl(squarePath, name, actRefIndex(ref));
-}
-export async function waitForDeliveredNotification(squarePath, name, ref, opts = {}) {
-    return waitForDeliveredNotificationImpl(squarePath, name, actRefIndex(ref), opts);
-}
-export function getParticipantPresence(squarePath, name, now = Date.now()) {
-    const doc = loadSquare(squarePath);
-    const known = resolveKnownName(doc, name);
-    const lease = freshWatchLease(doc, known, now);
-    return lease === undefined ? { watching: false } : { watching: true, lease };
-}
-export function isWatching(squarePath, name, now = Date.now()) {
-    return getParticipantPresence(squarePath, name, now).watching;
-}
-/** Typed participant intents share the same commit/effect pipeline as the CLI. */
-export async function join(squarePath, name) {
-    await execute(squarePath, { type: 'join', name, now: Date.now() });
-}
-export async function done(squarePath, name, body = '') {
-    await execute(squarePath, { type: 'done', name, body, now: Date.now() });
-}
-export async function hold(squarePath, actor, body = '') {
-    await execute(squarePath, { type: 'hold', actor, body, now: Date.now() });
-}
-export async function resume(squarePath, actor) {
-    await execute(squarePath, { type: 'resume', actor, now: Date.now() });
-}
-export async function express(squarePath, name, body, opts = {}) {
-    await sweepPendingNotifications(squarePath);
-    const committed = await execute(squarePath, {
-        type: 'say',
-        name,
-        body,
-        force: opts.force ?? false,
-        now: Date.now(),
-        ...(opts.reply === undefined ? {} : { reply: actRefIndex(opts.reply) }),
-    });
-    const sayAct = committed.acts.find((act) => act.kind === 'say');
-    if (sayAct !== undefined)
-        await dispatchActNotifications(squarePath, sayAct);
-    if (committed.result.type !== 'sent')
-        throw new Error(`Activity rejected: ${committed.result.type}`);
+export { captureRoute } from './delivery.js';
+function directedBody(body, recipient) {
+    if (body.trim() === '')
+        throw new SquareError('invalid_args', 'express body cannot be empty');
+    if (extractMentions(body).some((mention) => sameName(mention, recipient)))
+        return body;
+    return `${body}${/\s$/u.test(body) ? '' : ' '}@${recipient}`;
+}
+export async function express(route, options) {
+    const parsed = parseSquareRoute(route);
+    if (options === null || typeof options !== 'object' ||
+        typeof options.as !== 'string' || options.as.trim() === '' ||
+        typeof options.body !== 'string') {
+        throw new SquareError('invalid_args', 'Route express requires { as, body }');
+    }
+    const square = await Square.at({ path: parsed.squarePath });
+    try {
+        const recipient = (await square.participants()).find((participant) => participant.state === 'joined' && sameName(participant.name, parsed.name));
+        if (recipient === undefined)
+            throw new SquareError('invalid_args', `Unknown participant "${parsed.name}"`);
+        const sender = await square.join(options.as);
+        return sender.express(directedBody(options.body, recipient.name));
+    }
+    finally {
+        await square.close();
+    }
 }

package/dist/landing.d.ts

@@ -0,0 +1,10 @@
+import type { OpenSquare } from './open-square.js';
+import type { Activity, ExpressOptions, ExpressResult } from './square-facade.js';
+export declare function join(square: OpenSquare, name: string): Promise<{
+    readonly name: string;
+    readonly activity: Activity | null;
+}>;
+export declare function express(square: OpenSquare, name: string, body: string, options?: ExpressOptions): Promise<ExpressResult>;
+export declare function done(square: OpenSquare, name: string, body?: string): Promise<ExpressResult>;
+export declare function hold(square: OpenSquare, name: string, reason?: string): Promise<ExpressResult>;
+export declare function resume(square: OpenSquare, name: string): Promise<ExpressResult>;

package/dist/landing.js

@@ -0,0 +1,95 @@
+import { extractMentions, formatActivityId, parseActivityId } from './square-core.js';
+import { coreDone, coreHold, coreResume, decideAct, decideJoin } from './decisions.js';
+import { deriveDeliveryModel } from './delivery.js';
+import { SquareError } from './model.js';
+import { participantIdentity } from './participant-identity.js';
+import { touchPresenceCursor } from './runtime.js';
+function storeActs(state, acts) {
+    const stored = [];
+    for (const act of acts) {
+        const item = { ...act, index: state.runtime.nextActIndex };
+        state.runtime.nextActIndex += 1;
+        state.acts.push(item);
+        if (item.actor !== undefined)
+            touchPresenceCursor(state, item.actor, item.at, item.index);
+        stored.push(item);
+    }
+    return stored;
+}
+function committedActivity(stored, verb) {
+    const activity = stored[0];
+    if (activity === undefined)
+        throw new Error(`${verb} activity did not commit`);
+    return activity;
+}
+function exposeActivity(stored) {
+    if (stored.kind === 'read' || stored.actor === undefined)
+        throw new Error(`Cannot expose stored activity ${formatActivityId(stored.index)}`);
+    return {
+        id: formatActivityId(stored.index), at: stored.at, kind: stored.kind, actor: stored.actor,
+        ...('body' in stored && stored.body !== undefined ? { body: stored.body } : {}),
+        mentions: stored.kind === 'say' ? extractMentions(stored.body) : [],
+        ...(stored.kind === 'say' && stored.reply !== undefined ? { reply: formatActivityId(stored.reply) } : {}),
+    };
+}
+function parseRequiredActivityId(id) {
+    const index = parseActivityId(id);
+    if (index === undefined)
+        throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
+    return index;
+}
+async function wakeAfterCommit(square, recipients, activity) {
+    if (recipients.length === 0)
+        return;
+    try {
+        square.notifier?.wake(recipients, activity);
+    }
+    catch { /* post-commit effects cannot undo activities */ }
+}
+export async function join(square, name) {
+    const now = square.clock();
+    const committed = await square.cell.transact((state) => {
+        const decision = decideJoin(state, name, now);
+        if (decision.joinAct === undefined)
+            return { result: { name: decision.joinedName, stored: null } };
+        return { state, result: { name: decision.joinedName, stored: committedActivity(storeActs(state, [decision.joinAct]), 'join') } };
+    });
+    return { name: committed.name, activity: committed.stored === null ? null : exposeActivity(committed.stored) };
+}
+export async function express(square, name, body, options = {}) {
+    const now = square.clock();
+    const reply = options.reply === undefined ? undefined : parseRequiredActivityId(options.reply);
+    const committed = await square.cell.transact((state) => {
+        const decision = decideAct(state, { name, body, force: options.force ?? false, now, ...(options.reach === undefined ? {} : { reach: options.reach }), ...(reply === undefined ? {} : { reply }) });
+        if (decision.type === 'blocked') {
+            const pending = decision.activitySummaries.reduce((count, summary) => count + summary.count, 0) + decision.unreadRoomChanges.length;
+            throw new SquareError('behind', `${participantIdentity(name)} has pending activity`, { pending });
+        }
+        if (decision.type === 'held') {
+            const holder = state.acts.filter((activity) => activity.kind === 'hold').at(-1)?.actor;
+            throw new SquareError('held', 'The square is held', holder === undefined ? undefined : { holder });
+        }
+        if (decision.type === 'capped')
+            throw new SquareError('capped', `${participantIdentity(name)} reached the activity cap`);
+        if (decision.type === 'throttled')
+            throw new SquareError('throttled', `${name} is throttled`, { retryAfterMs: decision.delayMs });
+        if (decision.type === 'bell_quota')
+            throw new SquareError('bell_quota', `${participantIdentity(name)} cannot ring the bell yet`, { retryAfterMs: Math.max(1, decision.nextAt - now) });
+        const stored = committedActivity(storeActs(state, [decision.act]), 'express');
+        return { state, result: { stored, recipients: deriveDeliveryModel(state).plan(stored).map((notification) => notification.recipient) } };
+    });
+    const activity = exposeActivity(committed.stored);
+    await wakeAfterCommit(square, committed.recipients, activity);
+    return { activity };
+}
+async function landCore(square, verb, actor, body = '') {
+    const now = square.clock();
+    const stored = await square.cell.transact((state) => {
+        const act = verb === 'done' ? coreDone(state, actor, body, now) : verb === 'hold' ? coreHold(state, actor, body, now) : coreResume(state, actor, now);
+        return { state, result: committedActivity(storeActs(state, [act]), verb) };
+    });
+    return { activity: exposeActivity(stored) };
+}
+export function done(square, name, body = '') { return landCore(square, 'done', name, body); }
+export function hold(square, name, reason = '') { return landCore(square, 'hold', name, reason); }
+export function resume(square, name) { return landCore(square, 'resume', name); }

package/dist/list.d.ts

@@ -0,0 +1 @@
+export declare function cmdListSquares(args: string[], usage: () => void): Promise<void>;

package/dist/list.js

@@ -1,11 +1,18 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { probeSquare } from './artifact.js';
-import { inSquareCount, publicActs } from './runtime.js';
+import { probeSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { listPresentation } from './views.js';
 import { formatRelativeTime } from './time.js';
+import { participantIdentity } from './presentation.js';
 const DEFAULT_LIST_DEPTH = 4;
+const CONTEXT_PREVIEW_LINES = 2;
+const PARTICIPANT_PREVIEW_COUNT = 3;
 const LIST_SKIP_DIRS = new Set(['.git', 'node_modules', 'dist']);
-function readSquareListItem(filePath, root) {
+function contextLines(lines) {
+    return lines.map((line) => line.trim()).filter(Boolean);
+}
+async function readSquareListItem(filePath, root) {
     let stat;
     try {
         stat = fs.statSync(filePath);
@@ -13,20 +20,22 @@ function readSquareListItem(filePath, root) {
     catch {
         return null;
     }
-    const doc = probeSquare(filePath);
-    if (doc === undefined)
+    const square = probeSquare(filePath);
+    if (square === undefined)
         return null;
+    const projection = await listPresentation(square).finally(() => closeOpenSquare(square));
     const relative = path.relative(root, filePath) || path.basename(filePath);
     return {
         path: relative,
         lastActiveAt: stat.mtimeMs,
-        participants: inSquareCount(doc),
-        activities: publicActs(doc.acts).filter((act) => act.kind === 'say').length,
+        context: contextLines([...projection.context]),
+        participants: [...projection.participants],
+        activities: projection.activities,
     };
 }
-function collectSquareList(root, maxDepth) {
+async function collectSquareList(root, maxDepth) {
     const items = [];
-    function walk(dir, depth) {
+    async function walk(dir, depth) {
         let entries;
         try {
             entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -39,27 +48,40 @@ function collectSquareList(root, maxDepth) {
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
                 if (depth < maxDepth && !LIST_SKIP_DIRS.has(entry.name))
-                    walk(fullPath, depth + 1);
+                    await walk(fullPath, depth + 1);
                 continue;
             }
             if (!entry.isFile())
                 continue;
-            const item = readSquareListItem(fullPath, root);
+            const item = await readSquareListItem(fullPath, root);
             if (item)
                 items.push(item);
         }
     }
-    walk(root, 0);
+    await walk(root, 0);
     return items.sort((a, b) => a.path.localeCompare(b.path));
 }
 function renderSquareList(items) {
     if (items.length === 0)
         return '(no squares found)\n';
     const now = Date.now();
-    const lines = [
-        'squares',
-        ...items.map((item) => `${item.activities > 0 ? '●' : '○'} ${item.path} · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants} in square · ${item.activities} activities`),
-    ];
+    const lines = ['squares'];
+    for (const item of items) {
+        lines.push(`${item.activities > 0 ? '●' : '○'} ${item.path} · ${formatRelativeTime(item.lastActiveAt, now)} · ${item.participants.length} in square · ${item.activities} activities`);
+        const shownContext = item.context.slice(0, CONTEXT_PREVIEW_LINES);
+        if (shownContext.length === 0) {
+            lines.push('  context · (none)');
+        }
+        else {
+            shownContext.forEach((line, index) => lines.push(`  ${index === 0 ? 'context' : '       '} · ${line}`));
+            const hiddenContext = item.context.length - shownContext.length;
+            if (hiddenContext > 0)
+                lines.push(`          · … ${hiddenContext} more ${hiddenContext === 1 ? 'line' : 'lines'}`);
+        }
+        const shownParticipants = item.participants.slice(0, PARTICIPANT_PREVIEW_COUNT);
+        const hiddenParticipants = item.participants.length - shownParticipants.length;
+        lines.push(`  participants · ${shownParticipants.length === 0 ? 'nobody' : shownParticipants.map(participantIdentity).join(' · ')}${hiddenParticipants > 0 ? ` · … ${hiddenParticipants} more` : ''}`);
+    }
     return lines.join('\n') + '\n';
 }
 function parseMaxDepth(args, usage) {
@@ -76,7 +98,7 @@ function parseMaxDepth(args, usage) {
     }
     return depth;
 }
-export function cmdListSquares(args, usage) {
+export async function cmdListSquares(args, usage) {
     const maxDepth = parseMaxDepth(args, usage);
-    process.stdout.write(renderSquareList(collectSquareList(process.cwd(), maxDepth)));
+    process.stdout.write(renderSquareList(await collectSquareList(process.cwd(), maxDepth)));
 }

package/dist/model.d.ts

@@ -0,0 +1,147 @@
+import type { Act } from './square-core.js';
+export { formatActivityId, parseActivityId } from './square-core.js';
+export type { Act, ActivityId, Audience, Reach } from './square-core.js';
+export declare const WAKE_ROUTE_KINDS: readonly ["opencode-server", "codex-app-server", "claude-native", "pi-extension", "paseo"];
+export type WakeRouteKind = typeof WAKE_ROUTE_KINDS[number];
+export declare function isWakeRouteKind(value: unknown): value is WakeRouteKind;
+export interface WakeRoute {
+    ownerId: string;
+    sessionId: string;
+    kind: WakeRouteKind;
+    address: Record<string, string>;
+    updatedAt: number;
+}
+export type SquareErrorCode = 'invalid_name' | 'invalid_args' | 'unknown_participant' | 'not_joined' | 'already_joined' | 'already_done' | 'held' | 'capped' | 'throttled' | 'bell_quota' | 'behind' | 'io' | 'unavailable';
+export type InternalSquareErrorCode = SquareErrorCode | 'not_found' | 'cap_reached' | 'conflict' | 'pending_peer';
+export interface SquareErrorFacts {
+    pending?: number;
+    holder?: string;
+    retryAfterMs?: number;
+}
+declare class SquareErrorBase<Code extends string> extends Error {
+    code: Code;
+    facts?: SquareErrorFacts | undefined;
+    constructor(code: Code, message: string, facts?: SquareErrorFacts | undefined);
+}
+export declare class SquareError extends SquareErrorBase<SquareErrorCode> {
+}
+export declare class InternalSquareError extends SquareErrorBase<InternalSquareErrorCode> {
+}
+export declare function isSquareError(error: unknown): error is SquareError | InternalSquareError;
+export type HardCap = number | null;
+export interface BuildOptions {
+    force: boolean;
+    hardCap?: HardCap;
+    template?: string;
+    throttlePerMinute?: number;
+}
+export type StoredAct = Act & {
+    index: number;
+    at: number;
+};
+export type StoredActHead = StoredAct extends infer T ? T extends StoredAct ? Omit<T, 'body' | 'through' | 'index'> : never : never;
+export interface ReadCursor {
+    consumedThroughIndex: number;
+    updatedAt: number;
+}
+export interface DeliveryReceipt {
+    /** Inject presentation lives only in the machine-local presented ledger. */
+    status: 'delivered';
+    at: number;
+}
+export interface WatchLeaseFilter {
+    participants?: string[];
+    mention?: string;
+}
+export interface WatchLease {
+    leaseId: string;
+    /** Machine-local owner that may claim automatic delivery for this lease. */
+    ownerId?: string;
+    heartbeatAt: number;
+    expiresAt: number;
+    filter?: WatchLeaseFilter;
+}
+export type DirectedNotificationRoute = 'mention' | 'bell';
+export interface InboxNotification {
+    actIndex: number;
+    actor: string;
+    at: number;
+    route: DirectedNotificationRoute;
+    body: string;
+}
+export interface InboxMembership {
+    name: string;
+    squarePath: string;
+    notifications: InboxNotification[];
+    catchLease?: WatchLease;
+}
+export interface NotifyLease {
+    leaseId: string;
+    expiresAt: number;
+    phase: 'claimed' | 'dispatching';
+    attemptN?: number;
+    routeKind?: WakeRouteKind;
+}
+export interface SquareRuntimeState {
+    nextActIndex: number;
+    cursors: Record<string, ReadCursor>;
+    deliveryReceipts: Record<string, Record<string, DeliveryReceipt>>;
+    leases: Record<string, WatchLease>;
+    notifyLeases: Record<string, NotifyLease>;
+}
+export interface SquareState {
+    hardCap: HardCap;
+    throttlePerMinute?: number;
+    preamble: string[];
+    warmup: string[];
+    acts: StoredAct[];
+    runtime: SquareRuntimeState;
+}
+export interface ActivitiesOptions {
+    lastN?: number | null;
+    participants?: string[];
+    /** Exclusive upper bound on act.at (ms). */
+    before?: number;
+    /** Exclusive lower bound on act.at (ms). Alias of --since. */
+    after?: number;
+    /** Exclusive lower bound on stable act index (--after act/<index>). */
+    afterIndex?: number;
+    /** Center act indexes for context windows (--at). */
+    atIndexes?: number[];
+    beforeContext?: number;
+    afterContext?: number;
+    mention?: string;
+    /** Undelivered mention/bell items for viewer only (read-only; requires viewer). */
+    pending?: boolean;
+    viewer?: string;
+    full?: boolean;
+    grep?: string;
+    fixed?: string;
+    order?: 'asc' | 'desc';
+    format?: string[];
+    json?: boolean;
+}
+export interface WatchOptions {
+    participants?: string[];
+    mention?: string;
+    idleMs?: number;
+    replace?: boolean;
+    now?: boolean;
+}
+export type PublicAct = Extract<StoredAct, {
+    kind: 'say' | 'done';
+}>;
+export type RoomChangeAct = Extract<StoredAct, {
+    kind: 'join' | 'done' | 'hold' | 'resume';
+}>;
+export interface HoldState {
+    active: boolean;
+    at?: number;
+    reason?: string;
+}
+export declare function formatHardCap(hardCap: HardCap): string;
+export declare function parseParticipantList(value: string): string[];
+export declare function nameKey(name: string): string;
+export declare function sameName(a: string, b: string): boolean;
+export declare function findParticipantName(participants: string[], name: string): string | undefined;
+export declare function validateName(name: string): void;

package/dist/model.js

@@ -1,16 +1,26 @@
 // Shared model and constants for Square.
+export { formatActivityId, parseActivityId } from './square-core.js';
 export const WAKE_ROUTE_KINDS = ['opencode-server', 'codex-app-server', 'claude-native', 'pi-extension', 'paseo'];
 export function isWakeRouteKind(value) {
     return typeof value === 'string' && WAKE_ROUTE_KINDS.includes(value);
 }
-export class SquareError extends Error {
+class SquareErrorBase extends Error {
     code;
-    constructor(code, message) {
+    facts;
+    constructor(code, message, facts) {
         super(message);
         this.code = code;
+        this.facts = facts;
         this.name = 'SquareError';
     }
 }
+export class SquareError extends SquareErrorBase {
+}
+export class InternalSquareError extends SquareErrorBase {
+}
+export function isSquareError(error) {
+    return error instanceof SquareError || error instanceof InternalSquareError;
+}
 export function formatHardCap(hardCap) {
     return hardCap === null ? '-1' : String(hardCap);
 }

package/dist/notifications.d.ts

@@ -0,0 +1,30 @@
+import { planActNotifications, type WakeAdapter } from './delivery.js';
+import { matchesMentionTarget } from './runtime.js';
+import { type ActivityId } from './square-core.js';
+import type { WakeNotifier } from './square-facade.js';
+export type { PlannedNotification } from './delivery.js';
+export { planActNotifications, matchesMentionTarget };
+export { notificationMessageId } from './delivery.js';
+export declare function wakeGraceMs(env?: NodeJS.ProcessEnv): number;
+export declare function hasDeliveredNotification(squarePath: string, name: string, ref: number | ActivityId): Promise<boolean>;
+export declare function hasAttentionNotification(squarePath: string, name: string, ref: number | ActivityId, env?: NodeJS.ProcessEnv): Promise<boolean>;
+export declare function waitForDeliveredNotification(squarePath: string, name: string, ref: number | ActivityId, opts?: {
+    timeoutMs?: number;
+}): Promise<boolean>;
+interface ProcessNotificationOptions {
+    adapters?: WakeAdapter[];
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+}
+export declare function processActNotificationsOnce(squarePath: string, actIndex: number, opts?: ProcessNotificationOptions): Promise<void>;
+interface WorkerLaunchOptions {
+    launchWorker?: (workerPath: string, args: string[]) => void;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function wakeNotifierForSquare(squarePath: string, env?: NodeJS.ProcessEnv): WakeNotifier;
+export interface SweepPendingNotificationsOptions extends WorkerLaunchOptions {
+    now?: number;
+    limit?: number;
+}
+/** Reconsider old pending attention at a bounded action boundary using the existing worker. */
+export declare function sweepPendingNotifications(squarePath: string, opts?: SweepPendingNotificationsOptions): Promise<number[]>;