@astrosheep/square 0.3.12 → 0.3.13

package/dist/views.js

@@ -0,0 +1,81 @@
+import { extractMentions, formatActivityId, parseActivityId, perceive } from './square-core.js';
+import { deliveryDelta, peerPublicActs, peerRoomChanges } from './activity-feed.js';
+import { coreActivities, coreParticipants, coreStatus, resolveKnownName } from './decisions.js';
+import { deriveDeliveryModel, isDeliveryDelivered, planActNotifications } from './delivery.js';
+import { SquareError, nameKey } from './model.js';
+import { countSays, currentHold, foldedState, freshWatchLease, inSquareCount, isCurrentlyJoined, readCursor, resolveRosterName, rosterNames, watchTerminalStatus } from './runtime.js';
+function expose(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 exposePerceived(stored, viewer) {
+    const perception = perceive(stored, viewer);
+    const activity = expose(stored);
+    if (perception === 'full' || activity.body === undefined)
+        return { ...activity, perception };
+    const { body: _body, ...withoutBody } = activity;
+    return { ...withoutBody, perception };
+}
+function parseRequiredActivityId(id) {
+    const index = parseActivityId(id);
+    if (index === undefined)
+        throw new SquareError('invalid_args', `Invalid activity id: ${id}`);
+    return index;
+}
+function historyOptions(query, viewer) {
+    return { ...(query.from === undefined ? {} : { participants: [...query.from] }), ...(query.grep === undefined ? {} : { grep: query.grep }), ...(query.mention === true && viewer !== undefined ? { mention: viewer } : {}), order: 'asc' };
+}
+function selectHistory(stored, query) {
+    let selected = stored.filter((activity) => activity.kind !== 'read');
+    if (query.all !== true && query.limit !== undefined) {
+        if (!Number.isSafeInteger(query.limit) || query.limit < 1)
+            throw new SquareError('invalid_args', 'History limit must be a positive integer');
+        selected = selected.slice(-query.limit);
+    }
+    return query.order === 'desc' ? selected.reverse() : selected;
+}
+function statuses(square, state) {
+    return coreStatus(state, square.clock()).participants.filter((participant) => participant.state !== 'not joined').map((participant) => ({ name: participant.name, state: participant.state === 'done' ? 'done' : 'joined', consumedThrough: readCursor(state, participant.name) < 0 ? null : formatActivityId(readCursor(state, participant.name)), watching: participant.presence === 'watching' }));
+}
+function anchors(state) {
+    const result = {};
+    for (const name of rosterNames(state)) {
+        const activity = state.acts.findLast((candidate) => candidate.index <= readCursor(state, name) && (candidate.kind === 'say' || candidate.kind === 'done'));
+        if (activity !== undefined)
+            result[activity.index] = [...(result[activity.index] ?? []), name];
+    }
+    return result;
+}
+function sayNumbers(state) {
+    const counts = new Map();
+    const result = {};
+    for (const activity of state.acts)
+        if (activity.kind === 'say') {
+            const next = (counts.get(nameKey(activity.actor)) ?? 0) + 1;
+            counts.set(nameKey(activity.actor), next);
+            result[activity.index] = next;
+        }
+    return result;
+}
+export async function history(square, query = {}) { const { state } = await square.cell.read(); return selectHistory(coreActivities(state, historyOptions(query)), query).map(expose); }
+export async function participantHistory(square, name, query = {}) { const { state } = await square.cell.read(); const viewer = resolveKnownName(state, name); const effective = query.all === true || query.limit !== undefined ? query : { ...query, limit: 10 }; return selectHistory(coreActivities(state, historyOptions(effective, viewer)), effective).map((activity) => exposePerceived(activity, viewer)); }
+export async function resolveParticipant(square, name) { const { state } = await square.cell.read(); return { name: resolveKnownName(state, name), roster: rosterNames(state) }; }
+export async function participants(square) { const { state } = await square.cell.read(); return statuses(square, state); }
+export async function snapshot(square) { const { state } = await square.cell.read(); const folded = foldedState(state); return { context: [...state.preamble, ...state.warmup].join('\n'), actCount: state.acts.filter((activity) => activity.kind !== 'read').length, hardCap: state.hardCap, ...(state.throttlePerMinute === undefined ? {} : { throttlePerMinute: state.throttlePerMinute }), held: folded.hold.active && folded.hold.actor !== undefined ? { by: folded.hold.actor, ...(folded.hold.reason === undefined ? {} : { reason: folded.hold.reason }) } : null, participants: statuses(square, state), delivered(name, id) { return isDeliveryDelivered(state, name, parseRequiredActivityId(id)); } }; }
+export async function activityPresentation(square, name) { const { state } = await square.cell.read(); const known = resolveKnownName(state, name); const delta = deliveryDelta(state, known); const hold = currentHold(state.acts); return { name: known, roster: rosterNames(state), pendingPublic: peerPublicActs(delta, known), pendingRoomChanges: peerRoomChanges(delta, known), activities: state.acts, participantCount: inSquareCount(state), held: hold.active, ...(hold.reason === undefined ? {} : { holdReason: hold.reason }), ownActivityCount: countSays(state.acts, known), hardCap: state.hardCap }; }
+export async function entryPresentation(square, name, lastN = 10) { const { state } = await square.cell.read(); const known = resolveRosterName(state, name) ?? name; const publicActivities = state.acts.filter((activity) => activity.kind === 'say' || activity.kind === 'done'); return { joined: isCurrentlyJoined(state.acts, known), scene: state.warmup.join('\n').trim(), context: state.preamble.join('\n').trim(), joinContext: (state.preamble.at(-1) === '---' ? state.preamble.slice(0, -1) : state.preamble).join('\n').trim(), recentActivities: lastN === null ? publicActivities : publicActivities.slice(-lastN), sayNumbers: sayNumbers(state), participantCount: inSquareCount(state) }; }
+export async function historyPresentation(square, options) { const { state } = await square.cell.read(); return { activities: coreActivities(state, options).map((activity) => ({ ...activity, perception: options.viewer === undefined ? 'full' : perceive(activity, options.viewer) })), sayNumbers: sayNumbers(state), presenceAnchors: anchors(state), participantCount: inSquareCount(state) }; }
+export async function participantsPresentation(square) { const { state } = await square.cell.read(); return coreParticipants(state, square.clock()); }
+export async function listPresentation(square) { const { state } = await square.cell.read(); return { context: state.preamble, participants: foldedState(state).participants.filter((participant) => participant.joined).sort((left, right) => (right.lastActiveAt ?? -Infinity) - (left.lastActiveAt ?? -Infinity) || left.name.localeCompare(right.name)).map((participant) => participant.name), activities: state.acts.filter((activity) => activity.kind === 'say').length }; }
+export async function statusPresentation(square) { const { state } = await square.cell.read(); const status = coreStatus(state, square.clock()); return { status, ...(status.latestAct?.kind === 'say' ? { latestActNumber: countSays(state.acts, status.latestAct.actor) } : {}) }; }
+export async function eventPresentation(square, id) { const { state } = await square.cell.read(); const activity = state.acts.find((candidate) => candidate.index === parseRequiredActivityId(id)); if (activity === undefined)
+    throw new SquareError('invalid_args', `Unknown activity id: ${id}`); return { activity, participantCount: inSquareCount(state), held: currentHold(state.acts).active }; }
+export async function watchPresentation(square, name) { const { state } = await square.cell.read(); const known = resolveKnownName(state, name); const now = square.clock(); const terminal = watchTerminalStatus(state, known); return { activities: state.acts, participantCount: inSquareCount(state), presence: { participants: coreParticipants(state, now), now }, ...(terminal === undefined ? {} : { terminalStatus: terminal }) }; }
+export async function inboxProjection(square, name, ownerId) { const { state } = await square.cell.read(); const known = resolveRosterName(state, name); if (known === undefined || !isCurrentlyJoined(state.acts, known))
+    return { name, joined: false, notifications: [] }; const lease = freshWatchLease(state, known, square.clock()); return { name: known, joined: true, notifications: deriveDeliveryModel(state).pendingFor(known).map(({ item, route }) => ({ actIndex: item.index, actor: item.actor, at: item.at, route, body: item.body })), ...(lease?.ownerId === ownerId ? { catchLease: lease } : {}) }; }
+export async function streamProjection(square, cursor, recipient) { const { state } = await square.cell.read(); return { activities: state.acts.filter((activity) => activity.index > cursor).flatMap((activity) => { if (recipient === undefined)
+        return [{ activity }]; const notification = planActNotifications(state, activity).find((candidate) => nameKey(candidate.recipient) === nameKey(recipient)); return notification === undefined ? [] : [{ activity, route: notification.route }]; }), cursor: Math.max(cursor, ...state.acts.map((activity) => activity.index)) }; }
+export async function notificationForAct(square, actIndex) { const { state } = await square.cell.read(); const activity = state.acts.find((candidate) => candidate.index === actIndex); return activity === undefined ? [] : planActNotifications(state, activity); }
+export async function pendingDeliveries(square) { const { state } = await square.cell.read(); return [...new Set(state.acts.filter((activity) => activity.kind === 'join').map((activity) => activity.actor))].filter((name) => isCurrentlyJoined(state.acts, name)).map((recipient) => ({ recipient, notifications: deriveDeliveryModel(state).pendingFor(recipient) })); }
+export async function notificationDelivered(square, recipient, actIndex) { const { state } = await square.cell.read(); return isDeliveryDelivered(state, recipient, actIndex); }

package/dist/wake-attempts.d.ts

@@ -0,0 +1,39 @@
+import { type NotifyLease, type WakeRoute, type WakeRouteKind } from './model.js';
+export type WakeOutcome = 'accepted' | 'unknown' | 'failed';
+export interface WakeAttention {
+    squarePath: string;
+    actIndex: number;
+    recipient: string;
+}
+export interface WakeAttempt {
+    at: number;
+    attention: WakeAttention;
+    routeKind: WakeRouteKind;
+    outcome: WakeOutcome;
+    signature?: string;
+    attemptN: number;
+    message?: string;
+    diagnostic?: unknown;
+}
+export declare function wakeAttemptsPath(env?: NodeJS.ProcessEnv): string;
+export declare function wakeAttentionKey(attention: WakeAttention): string;
+export declare function readWakeAttempts(opts?: {
+    attention?: WakeAttention;
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+}): WakeAttempt[];
+export declare function terminalWakeEvidence(attempts: readonly WakeAttempt[]): WakeAttempt | undefined;
+export declare function terminalWakeAttempt(attention: WakeAttention, opts?: {
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+}): WakeAttempt | undefined;
+export declare function isWakeRouteAttemptable(route: Pick<WakeRoute, 'kind' | 'updatedAt'>, attempts: readonly WakeAttempt[]): boolean;
+export declare function hasAttemptableWakeRoute(routes: readonly Pick<WakeRoute, 'kind' | 'updatedAt'>[], attempts: readonly WakeAttempt[]): boolean;
+export declare function nextWakeAttemptNumber(attention: WakeAttention, opts?: {
+    now?: number;
+    env?: NodeJS.ProcessEnv;
+}): number;
+export declare function recordWakeAttempt(attempt: Omit<WakeAttempt, 'at'> & {
+    at?: number;
+}, env?: NodeJS.ProcessEnv): WakeAttempt;
+export declare function recordRecoveredUnknown(attention: WakeAttention, lease: Pick<NotifyLease, 'attemptN' | 'routeKind'>, env?: NodeJS.ProcessEnv, at?: number): WakeAttempt | undefined;

package/dist/wake-evidence.d.ts

@@ -0,0 +1,12 @@
+import { type WakeRoute } from './model.js';
+import { type WakeAttempt } from './wake-attempts.js';
+export interface WakeEvidence {
+    delivered: boolean;
+    presented: boolean;
+    attempts: WakeAttempt[];
+    terminal?: WakeAttempt;
+    attemptableRoutes: WakeRoute[];
+}
+/** Project every wake decision from the same primary evidence. */
+export declare function wakeEvidence(squarePath: string, recipient: string, actIndex: number, now: number, env: NodeJS.ProcessEnv): Promise<WakeEvidence>;
+export declare function wakeIsEligible(evidence: WakeEvidence): boolean;

package/dist/wake-evidence.js

@@ -1,24 +1,21 @@
-import { loadSquare } from './artifact.js';
-import { isDeliveryDelivered } from './delivery.js';
 import { hasPresentedAttention } from './presented.js';
 import { lookupParticipant } from './registry.js';
-import { isCurrentlyJoined } from './runtime.js';
 import { readWakeRoutes } from './routes.js';
 import { isWakeRouteAttemptable, readWakeAttempts, terminalWakeEvidence, } from './wake-attempts.js';
-export function joinedRecipients(doc) {
-    return [...new Set(doc.acts.filter((act) => act.kind === 'join').map((act) => act.actor))]
-        .filter((name) => isCurrentlyJoined(doc.acts, name));
-}
+import { openSquare } from './square-file-adapter.js';
+import { closeOpenSquare } from './open-square.js';
+import { notificationDelivered } from './views.js';
 /** Project every wake decision from the same primary evidence. */
-export function wakeEvidence(squarePath, recipient, actIndex, now, env) {
-    const doc = loadSquare(squarePath);
+export async function wakeEvidence(squarePath, recipient, actIndex, now, env) {
+    const square = await openSquare(squarePath, { clock: () => now });
+    const delivered = await notificationDelivered(square, recipient, actIndex).finally(() => closeOpenSquare(square));
     const owners = new Set(lookupParticipant(squarePath, recipient, now).map((binding) => binding.ownerId));
     const attempts = readWakeAttempts({ attention: { squarePath, recipient, actIndex }, env, now });
     const terminal = terminalWakeEvidence(attempts);
     const routes = readWakeRoutes({ freshOnly: true, now, env })
         .filter((route) => owners.has(route.ownerId));
     return {
-        delivered: isDeliveryDelivered(doc, recipient, actIndex),
+        delivered,
         presented: hasPresentedAttention(squarePath, recipient, actIndex, env, now),
         attempts,
         ...(terminal === undefined ? {} : { terminal }),

package/dist/wake-port.d.ts

@@ -0,0 +1,20 @@
+import type { WakeAdapter, WakeDispatchResult } from './delivery.js';
+import type { WakeRoute } from './model.js';
+export interface WakePortHooks {
+    nextAttemptN(): number;
+    beforeSend(route: WakeRoute, attemptN: number): Promise<boolean>;
+    record(route: WakeRoute, attemptN: number, result: Exclude<WakeDispatchResult, {
+        outcome: 'cancelled';
+    }>): Promise<void>;
+}
+export type WakePortResult = {
+    outcome: 'accepted' | 'unknown' | 'cancelled';
+} | {
+    outcome: 'exhausted';
+};
+/** Select routes globally; adapters own only transport-specific live proof and dispatch. */
+export declare class WakePort {
+    private readonly adapters;
+    constructor(adapters: WakeAdapter[]);
+    dispatch(routes: readonly WakeRoute[], payload: string, hooks: WakePortHooks): Promise<WakePortResult>;
+}

package/dist/wake-sink.d.ts

@@ -0,0 +1,12 @@
+export interface PaseoWakeRequest {
+    agentId: string;
+    prompt: string;
+}
+export type PaseoWakeFailureKind = 'transient' | 'rejected' | 'unknown';
+export declare class PaseoWakeSendError extends Error {
+    readonly kind: PaseoWakeFailureKind;
+    constructor(message: string, kind: PaseoWakeFailureKind);
+}
+export declare function sendPaseoWake({ agentId, prompt }: PaseoWakeRequest, opts?: {
+    timeoutMs?: number;
+}): void;

package/dist/wakes.d.ts

@@ -0,0 +1,40 @@
+import { type NotifyLease, type WakeRouteKind, type WatchLease, type WatchOptions } from './model.js';
+import type { OpenSquare } from './open-square.js';
+export type WatchLeaseStart = {
+    readonly type: 'started';
+    readonly leaseId: string;
+    readonly replaced: boolean;
+    readonly heartbeatAt: number;
+} | {
+    readonly type: 'active';
+    readonly lease: WatchLease;
+};
+export type WatchLeasePulse = {
+    readonly type: 'replaced';
+} | {
+    readonly type: 'held';
+} | {
+    readonly type: 'terminal';
+    readonly status: 'capped' | 'quorum';
+} | {
+    readonly type: 'sleep';
+    readonly heartbeatAt?: number;
+};
+export type NotifyLeaseClaim = {
+    readonly type: 'delivered';
+} | {
+    readonly type: 'busy';
+} | {
+    readonly type: 'ambiguous';
+    readonly lease: NotifyLease;
+} | {
+    readonly type: 'acquired';
+    readonly leaseId: string;
+};
+export declare function acquireWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, ownerId?: string): Promise<WatchLeaseStart>;
+export declare function pulseWatchLease(square: OpenSquare, name: string, leaseId: string, options: WatchOptions, heartbeatDue: boolean): Promise<WatchLeasePulse>;
+export declare function releaseWatchLease(square: OpenSquare, name: string, leaseId: string | undefined): Promise<void>;
+export declare function ownsWatchLease(square: OpenSquare, name: string, leaseId: string): Promise<boolean>;
+export declare function claimNotificationLease(square: OpenSquare, recipient: string, actIndex: number, leaseId: string, leaseMs: number): Promise<NotifyLeaseClaim>;
+export declare function transitionNotificationLease(square: OpenSquare, recipient: string, actIndex: number, leaseId: string, phase: NotifyLease['phase'], leaseMs: number, routeKind?: WakeRouteKind, attemptN?: number): Promise<boolean>;
+export declare function releaseNotificationLease(square: OpenSquare, recipient: string, actIndex: number, leaseId: string): Promise<void>;

package/dist/wakes.js

@@ -0,0 +1,62 @@
+import { formatActivityId } from './square-core.js';
+import { isDeliveryDelivered } from './delivery.js';
+import { nameKey } from './model.js';
+import { resolveKnownName } from './decisions.js';
+import { WATCH_STALE_MS, currentHold, freshWatchLease, removeWatchLease, touchPresenceCursor, watchTerminalStatus, writeWatchLease } from './runtime.js';
+function filter(options) {
+    return { ...(options.participants === undefined ? {} : { participants: [...options.participants] }), ...(options.mention === undefined ? {} : { mention: options.mention }) };
+}
+function notificationKey(recipient, index) { return JSON.stringify([formatActivityId(index), nameKey(recipient)]); }
+export async function acquireWatchLease(square, name, leaseId, options, ownerId) {
+    const at = square.clock();
+    return square.cell.transact((state) => {
+        const known = resolveKnownName(state, name);
+        const existing = freshWatchLease(state, known, at);
+        if (existing !== undefined && !options.replace)
+            return { result: { type: 'active', lease: existing } };
+        writeWatchLease(state, known, { leaseId, ...(ownerId === undefined ? {} : { ownerId }), heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter(options)).length === 0 ? {} : { filter: filter(options) }) });
+        touchPresenceCursor(state, known, at);
+        return { state, result: { type: 'started', leaseId, replaced: existing !== undefined, heartbeatAt: at } };
+    });
+}
+export async function pulseWatchLease(square, name, leaseId, options, heartbeatDue) {
+    const at = square.clock();
+    return square.cell.transact((state) => {
+        const known = resolveKnownName(state, name);
+        const lease = freshWatchLease(state, known, at);
+        if (lease?.leaseId !== leaseId)
+            return { result: { type: 'replaced' } };
+        if (currentHold(state.acts).active)
+            return { result: { type: 'held' } };
+        const terminal = watchTerminalStatus(state, known);
+        if (terminal !== undefined)
+            return { result: { type: 'terminal', status: terminal } };
+        if (!heartbeatDue)
+            return { result: { type: 'sleep' } };
+        writeWatchLease(state, known, { leaseId, ...(lease.ownerId === undefined ? {} : { ownerId: lease.ownerId }), heartbeatAt: at, expiresAt: at + WATCH_STALE_MS, ...(Object.keys(filter(options)).length === 0 ? {} : { filter: filter(options) }) });
+        touchPresenceCursor(state, known, at);
+        return { state, result: { type: 'sleep', heartbeatAt: at } };
+    });
+}
+export async function releaseWatchLease(square, name, leaseId) {
+    if (leaseId === undefined)
+        return;
+    await square.cell.transact((state) => { const known = resolveKnownName(state, name); return removeWatchLease(state, known, leaseId) ? { state, result: undefined } : { result: undefined }; });
+}
+export async function ownsWatchLease(square, name, leaseId) { const { state } = await square.cell.read(); return freshWatchLease(state, resolveKnownName(state, name), square.clock())?.leaseId === leaseId; }
+export async function claimNotificationLease(square, recipient, actIndex, leaseId, leaseMs) {
+    const at = square.clock();
+    const key = notificationKey(recipient, actIndex);
+    return square.cell.transact((state) => { const known = resolveKnownName(state, recipient); if (isDeliveryDelivered(state, known, actIndex))
+        return { result: { type: 'delivered' } }; const existing = state.runtime.notifyLeases[key]; if (existing !== undefined && existing.expiresAt > at)
+        return { result: { type: 'busy' } }; if (existing?.phase === 'dispatching')
+        return { result: { type: 'ambiguous', lease: existing } }; state.runtime.notifyLeases[key] = { leaseId, expiresAt: at + leaseMs, phase: 'claimed' }; return { state, result: { type: 'acquired', leaseId } }; });
+}
+export async function transitionNotificationLease(square, recipient, actIndex, leaseId, phase, leaseMs, routeKind, attemptN) {
+    const at = square.clock();
+    const key = notificationKey(recipient, actIndex);
+    return square.cell.transact((state) => { if (state.runtime.notifyLeases[key]?.leaseId !== leaseId)
+        return { result: false }; state.runtime.notifyLeases[key] = { leaseId, expiresAt: at + leaseMs, phase, ...(routeKind === undefined ? {} : { routeKind }), ...(attemptN === undefined ? {} : { attemptN }) }; return { state, result: true }; });
+}
+export async function releaseNotificationLease(square, recipient, actIndex, leaseId) { const key = notificationKey(recipient, actIndex); await square.cell.transact((state) => { if (state.runtime.notifyLeases[key]?.leaseId !== leaseId)
+    return { result: undefined }; delete state.runtime.notifyLeases[key]; return { state, result: undefined }; }); }

package/dist/watch.d.ts

@@ -0,0 +1,2 @@
+import { type WatchOptions } from './model.js';
+export declare function cmdWatch(squarePath: string, name: string, opts: WatchOptions): Promise<void>;