@astrosheep/square 0.4.0 → 0.4.1

package/dist/codex-queue.js

@@ -1,46 +1,46 @@
 import { connect, DeliveryError } from './packages/agent-delivery/src/index.js';
-export { sendCodexQueue, CodexQueueSendError } from './packages/agent-delivery/src/codex-queue.js';
+import { codexIdleAtStop } from './packages/agent-delivery/src/codex.js';
+import { codexQueueEndpoint } from './packages/agent-delivery/src/codex-endpoint.js';
 import { codexBoundaryStore } from './codex-boundary-state.js';
+import { renderDeliveryReminder } from './delivery-frame.js';
+/** Instantiated only by the receiver, for one captured Stop epoch. */
 export class CodexQueueTransport {
     opts;
-    constructor(opts = {}) {
+    kind = 'codex-queue';
+    constructor(opts) {
         this.opts = opts;
     }
-    async attempt(request, timeoutMs, beforeSend) {
-        const deadline = Date.now() + timeoutMs;
-        const { address } = request.route;
+    async send(card, address, context) {
         const threadId = address.threadId?.trim();
-        if (!threadId) {
-            return { outcome: 'failed', signature: 'invalid_address', message: 'Codex route has no thread id.' };
-        }
+        if (!threadId || !address.codexHome || Object.keys(address).length !== Object.keys(this.opts.address).length ||
+            !Object.entries(this.opts.address).every(([key, value]) => address[key] === value))
+            return 'not-capable';
         const env = this.opts.env ?? process.env;
-        const payload = request.presentation?.payload;
-        if (payload === undefined)
-            return { outcome: 'not-capable', diagnostic: 'No pending Square activity to preview.' };
-        if (!(await beforeSend()))
-            return { outcome: 'not-capable' };
+        const boundaries = codexBoundaryStore(env), epoch = this.opts.epoch;
         try {
-            const agent = await (this.opts.connect ?? connect)({
-                harness: 'codex', transport: 'cli', sessionId: threadId, boundaries: codexBoundaryStore(env),
-                env, bin: env.SQUARE_CODEX_BIN, codexHome: address.codexHome, endpoint: address.endpoint,
-            });
-            const remaining = deadline - Date.now();
-            if (remaining <= 0) {
-                return { outcome: 'failed', signature: 'dispatch_budget_exhausted', message: 'The wake dispatch budget elapsed before queueing.' };
-            }
-            await agent.queue(payload, { timeoutMs: remaining });
-            return { outcome: 'accepted' };
+            // Receiver delivery addresses the already-hosting endpoint explicitly;
+            // disappearing native custody must not trigger CLI service startup.
+            const endpoint = address.endpoint ?? codexQueueEndpoint({ CODEX_HOME: address.codexHome });
+            const agent = await connect({ harness: 'codex', transport: 'cli', sessionId: threadId,
+                boundaries: { queueEligible: async (id) => {
+                        if (!await boundaries.queueEligible(id, epoch))
+                            return false;
+                        // Repeat the native sample after claim, immediately before the final
+                        // epoch and ledger fences. These reads are not an atomic native enqueue.
+                        if (!await codexIdleAtStop({ harness: 'codex', sessionId: id, codexHome: address.codexHome,
+                            endpoint, timeoutMs: Math.max(1, context.deadline - Date.now()), signal: context.signal }, epoch.turnId))
+                            return false;
+                        return await boundaries.queueEligible(id, epoch) && await context.beforeSend()
+                            && !context.signal.aborted && Date.now() < context.deadline;
+                    } },
+                env, bin: env.SQUARE_CODEX_BIN, codexHome: address.codexHome, endpoint });
+            if (context.signal.aborted || Date.now() >= context.deadline)
+                return 'not-capable';
+            await agent.queue(renderDeliveryReminder([card.text], { tagged: true }), { timeoutMs: context.deadline - Date.now(), signal: context.signal });
+            return 'accepted';
         }
         catch (error) {
-            if (error instanceof DeliveryError && error.code === 'session_inactive') {
-                return { outcome: 'failed', signature: 'boundary_not_stopped',
-                    message: 'The Codex thread has no current Stop boundary for queueing.' };
-            }
-            const message = error instanceof Error ? error.message : String(error);
-            if (!(error instanceof DeliveryError) || error.maybeDelivered)
-                return { outcome: 'unknown', signature: 'queue_unknown', message };
-            return { outcome: 'failed', signature: ['unavailable', 'timeout', 'aborted'].includes(error.code)
-                    ? 'queue_pre_accept_transient' : 'queue_pre_accept_rejected', message };
+            return error instanceof DeliveryError && !error.maybeDelivered ? 'not-capable' : 'unknown';
         }
     }
 }

package/dist/codex-watch.d.ts

@@ -0,0 +1,2 @@
+/** One native async hook owns observation; the lock itself conveys no idle authority. */
+export declare function runCodexWatch(inputText: string, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<string>;

package/dist/codex-watch.js

@@ -0,0 +1,100 @@
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { DeliveryLedger, deliveryLedgerLocation } from './delivery-ledger.js';
+import { retainDeliveryLedger } from './delivery-lifetime.js';
+import { harnessOwner } from './owner.js';
+import { withFileLock } from './file-lock.js';
+import { canonicalPath } from './canonical-path.js';
+import { codexBoundaryStore } from './codex-boundary-state.js';
+import { codexWakeAddress } from './codex-address.js';
+import { parseCodexHookText } from './codex-hook.js';
+import { CodexQueueTransport } from './codex-queue.js';
+import { codexIdleAtStop } from './packages/agent-delivery/src/codex.js';
+/** One native async hook owns observation; the lock itself conveys no idle authority. */
+export async function runCodexWatch(inputText, env = process.env, signal) {
+    const input = parseCodexHookText(inputText);
+    if (input?.hook_event_name !== 'Stop' || signal?.aborted)
+        return '';
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    const timer = setTimeout(stop, 86_400_000);
+    const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+    process.on('SIGTERM', stop);
+    process.on('SIGINT', stop);
+    try {
+        const route = codexWakeAddress(input.session_id, env);
+        const home = await canonicalPath(route.address.codexHome);
+        const coordinate = [input.session_id, route.address.endpoint ?? home];
+        const root = path.join(path.dirname(deliveryLedgerLocation(env)), 'codex-watchers');
+        await fs.mkdir(root, { recursive: true, mode: 0o700 });
+        const lock = path.join(root, createHash('sha256').update(JSON.stringify(coordinate)).digest('hex') + '.lock');
+        const file = await fs.open(lock, 'a', 0o600);
+        await file.close();
+        await withFileLock(lock, { retryMs: 10, skipIfBusy: true, signal: combined }, async () => {
+            const ledger = await DeliveryLedger.open({ location: deliveryLedgerLocation(env) });
+            const lifetime = retainDeliveryLedger(ledger);
+            let observer;
+            try {
+                const owner = harnessOwner({ channel: 'codex', session: input.session_id });
+                const captured = await ledger.session(owner);
+                if (captured?.state !== 'attached')
+                    return;
+                const boundaries = codexBoundaryStore(env);
+                // Subscribe before inspecting pending work. Both ledger edges and the
+                // bounded wait below cause reconciliation; boundary-only changes matter.
+                observer = await ledger.observe(owner);
+                while (!combined.aborted) {
+                    let version = await observer.read(combined);
+                    const session = await ledger.session(owner);
+                    if (session?.state !== 'attached' || session.generation !== captured.generation)
+                        return;
+                    const registered = session.routes.find(candidate => candidate.kind === 'codex-queue');
+                    if (!registered || registered.address.threadId !== input.session_id ||
+                        registered.address.endpoint !== route.address.endpoint ||
+                        !registered.address.codexHome || await canonicalPath(registered.address.codexHome) !== home)
+                        return;
+                    const boundary = await boundaries.read(input.session_id);
+                    if (boundary?.ended)
+                        return;
+                    const pending = await ledger.pending(owner, { generation: captured.generation });
+                    const held = new Set((await ledger.handoffs(owner, { generation: captured.generation }))
+                        .filter(attempt => !['failed', 'released'].includes(attempt.outcome)).map(attempt => attempt.seq));
+                    for (const card of pending) {
+                        if (combined.aborted)
+                            break;
+                        if (held.has(card.seq))
+                            continue;
+                        // Follow the latest Stop, regardless of which Stop launched this process.
+                        const epoch = (await boundaries.read(input.session_id))?.stop;
+                        if (!epoch || !await codexIdleAtStop({ harness: 'codex', sessionId: input.session_id,
+                            codexHome: registered.address.codexHome, endpoint: registered.address.endpoint,
+                            timeoutMs: 2000, signal: combined }, epoch.turnId))
+                            break;
+                        lifetime.track(await ledger.dispatchHandoff(owner, card.key, new CodexQueueTransport({ epoch, env, address: registered.address }), { generation: captured.generation, timeoutMs: 5000, signal: combined }));
+                        // Drain our own claim/settlement edge. A known-unsent failure must
+                        // not turn file observation into an immediate retry loop. Any post
+                        // racing this read is still found by the bounded rescan below.
+                        version = await observer.read(combined);
+                    }
+                    // No claims are held while waiting, including while active or disarmed.
+                    await observer.changed(version, 1000, combined);
+                }
+            }
+            finally {
+                observer?.close();
+                await lifetime.close();
+            }
+        });
+    }
+    catch {
+        if (!combined.aborted)
+            throw new Error('Codex watcher unavailable.');
+    }
+    finally {
+        clearTimeout(timer);
+        process.off('SIGTERM', stop);
+        process.off('SIGINT', stop);
+    }
+    return '';
+}

package/dist/decisions.js

@@ -51,7 +51,7 @@ export function unreadActivitySummaries(facts, name, now) {
     let afterIndex = readCursor(facts, name);
     const summaries = new Map();
     while (true) {
-        const page = facts.directed(name, { afterIndex, kinds: ['say'] }, { edge: 'oldest', limit: FACT_PAGE_SIZE });
+        const page = facts.directed(name, { afterIndex, kinds: ['say'], unseenOnly: true }, { edge: 'oldest', limit: FACT_PAGE_SIZE });
         for (const item of page.items) {
             const summary = summaries.get(item.actor) ?? { count: 0, latestAt: -Infinity, lastIndex: item.index };
             summary.count++;
@@ -194,7 +194,7 @@ export function coreParticipants(facts, now) {
             activityCount: current.sayCount, lastActiveAt,
             presence: current.done ? 'done' : !current.joined ? 'never-joined' : facts.seat(current.name)?.attachment === 'detached' ? 'away'
                 : freshWatchLease(facts, current.name, now) !== undefined ? 'watching' : 'active',
-            unreadActivityCount: current.joined ? facts.directedCount(current.name, { kinds: ['say'], afterIndex: readCursor(facts, current.name) }) : 0,
+            unreadActivityCount: current.joined ? facts.directedCount(current.name, { kinds: ['say'], afterIndex: readCursor(facts, current.name), unseenOnly: true }) : 0,
             pendingMentionCount: current.joined ? facts.directedCount(current.name, { kinds: ['say'], afterIndex: current.lastJoinIndex ?? -1, unseenOnly: true }) : 0,
         };
     }).sort(compareParticipantActivity);

package/dist/delivery-deferral.d.ts

@@ -1,19 +1,10 @@
-import type { MessageMetadata } from './channel-values.js';
-import type { ChannelRead, EndpointRef } from './channel-ports.js';
-import type { MetadataMatch } from './channel-metadata.js';
-export type { MetadataMatch, MetadataScalar, DeliveryDeferral } from './channel-metadata.js';
-export interface DeliveryDeferralFact {
-    readonly participant: string;
-    readonly generation: string;
-    readonly id: string;
-    readonly match: MetadataMatch;
-    readonly expiresAt: number;
+import type { ActivityMetadata } from './model.js';
+export type MetadataScalar = null | boolean | number | string;
+export interface MetadataMatch {
+    readonly fields: readonly Readonly<{
+        path: readonly string[];
+        equals: MetadataScalar;
+    }>[];
 }
-export declare const MAX_DELIVERY_DEFERRAL_MS: number;
 export declare function validateMetadataMatch(value: unknown): MetadataMatch;
-export declare function validateDeferralDuration(value: unknown): number;
-export declare function validateDeferralId(value: unknown): string;
-export declare function matchesMetadata(metadata: MessageMetadata | undefined, match: MetadataMatch): boolean;
-export declare function matchingDeferrals(deferrals: readonly DeliveryDeferralFact[], metadata: MessageMetadata | undefined, now: number): readonly DeliveryDeferralFact[];
-export declare function deliveryDeferralExpiry(facts: ChannelRead, captured: EndpointRef, index: number, now: number): number | undefined;
-export declare function earliestMatchingDeferralExpiry(deferrals: readonly DeliveryDeferralFact[], metadata: MessageMetadata | undefined, now: number): number | undefined;
+export declare function matchesMetadata(metadata: ActivityMetadata | undefined, match: MetadataMatch): boolean;

package/dist/delivery-deferral.js

@@ -1,5 +1,4 @@
 import { SquareError } from './neutral.js';
-export const MAX_DELIVERY_DEFERRAL_MS = 24 * 60 * 60 * 1000;
 export function validateMetadataMatch(value) {
     const fail = () => { throw new SquareError('invalid_args', 'Invalid metadata match.'); };
     const record = (item) => {
@@ -41,16 +40,6 @@ export function validateMetadataMatch(value) {
     });
     return Object.freeze({ fields: Object.freeze(validated) });
 }
-export function validateDeferralDuration(value) {
-    if (!Number.isSafeInteger(value) || value <= 0)
-        throw new SquareError('invalid_args', 'Delivery deferral duration must be a positive safe integer.');
-    return Math.min(value, MAX_DELIVERY_DEFERRAL_MS);
-}
-export function validateDeferralId(value) {
-    if (typeof value !== 'string' || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value))
-        throw new SquareError('invalid_args', 'Invalid delivery deferral id.');
-    return value;
-}
 export function matchesMetadata(metadata, match) {
     if (metadata === undefined)
         return false;
@@ -64,20 +53,3 @@ export function matchesMetadata(metadata, match) {
         return value === equals && (value === null || typeof value !== 'object');
     });
 }
-export function matchingDeferrals(deferrals, metadata, now) {
-    return deferrals.filter((lease) => lease.expiresAt > now && matchesMetadata(metadata, lease.match));
-}
-export function deliveryDeferralExpiry(facts, captured, index, now) {
-    const seat = facts.endpoint(captured.participant);
-    if (seat === undefined || seat.generation !== captured.generation || seat.owner !== captured.owner)
-        return undefined;
-    const leases = facts.deliveryDeferrals(seat.participant, seat.generation);
-    if (!leases.some(lease => lease.expiresAt > now))
-        return undefined;
-    const message = facts.message(index);
-    return message === undefined ? undefined : earliestMatchingDeferralExpiry(leases, message.metadata, now);
-}
-export function earliestMatchingDeferralExpiry(deferrals, metadata, now) {
-    const matches = matchingDeferrals(deferrals, metadata, now);
-    return matches.length ? Math.min(...matches.map((lease) => lease.expiresAt)) : undefined;
-}

package/dist/delivery-frame.d.ts

@@ -0,0 +1,7 @@
+/** Receivers frame finished cards; card text and its whitespace stay verbatim. */
+export declare function renderDeliveryReminder(texts: readonly string[], options: {
+    tagged: boolean;
+}): string;
+export declare function deliveryFrameOverhead(options: {
+    tagged: boolean;
+}): number;

package/dist/delivery-frame.js

@@ -0,0 +1,11 @@
+const warning = 'This is an external notification, not a direct message from the user.';
+/** Receivers frame finished cards; card text and its whitespace stay verbatim. */
+export function renderDeliveryReminder(texts, options) {
+    if (!texts.length)
+        return '';
+    const text = `${warning}\n\n${texts.join('\n\n')}`;
+    return options.tagged ? `<system-reminder>\n${text}\n</system-reminder>` : text;
+}
+export function deliveryFrameOverhead(options) {
+    return renderDeliveryReminder([''], options).length;
+}

package/dist/delivery-ledger-sqlite.d.ts

@@ -0,0 +1,97 @@
+import type { DeliveryAttempt, DeliveryCard, DeliveryCorrelation, DeliveryHandoffRef, DeliveryHealth, DeliveryOutcome, DeliveryReceipt, DeliveryRoute, DeliverySession, PostResult, SuppressionResult } from './delivery-ledger.js';
+/** All ledger file access and SQL are confined here. Transactions never span external effects. */
+export declare class LedgerStore {
+    readonly location: string;
+    private readonly db;
+    private readonly clock;
+    private pending;
+    private closed;
+    private constructor();
+    static open(location: string, clock: () => number): Promise<LedgerStore>;
+    close(): Promise<void>;
+    private transaction;
+    private getSession;
+    private attached;
+    private listAttempts;
+    private awaitingEffect;
+    private getAttempt;
+    private normalize;
+    private deleteCard;
+    private gc;
+    session(owner: string): Promise<DeliverySession | undefined>;
+    sessions(): Promise<readonly DeliverySession[]>;
+    pendingCards(owner: string, generation: string): Promise<readonly DeliveryCard[]>;
+    handoffs(owner: string, generation: string): Promise<readonly DeliveryAttempt[]>;
+    attach(input: {
+        owner: string;
+        expectedGeneration: string | null;
+        routes: readonly DeliveryRoute[];
+    }): Promise<DeliverySession | false>;
+    updateRoutes(input: {
+        owner: string;
+        generation: string;
+        routes: readonly DeliveryRoute[];
+    }): Promise<boolean>;
+    lifecycle(input: {
+        owner: string;
+        generation: string;
+    }, state: 'detached' | 'deleted'): Promise<boolean>;
+    post(input: {
+        owner: string;
+        key: string;
+        text: string;
+        details: string | null;
+    }): Promise<PostResult>;
+    suppress(input: {
+        owner: string;
+        key: string;
+        scope: 'exact' | 'prefix';
+        expiresAt?: number;
+    }): Promise<SuppressionResult>;
+    renewSuppression(input: {
+        owner: string;
+        id: string;
+        expiresAt: number;
+    }): Promise<boolean>;
+    releaseSuppression(input: {
+        owner: string;
+        id: string;
+    }): Promise<boolean>;
+    cancel(input: {
+        owner: string;
+        generation: string;
+    }): Promise<boolean>;
+    private isSuppressed;
+    private eligible;
+    private insertAttempt;
+    claimPresentation(owner: string, generation: string, budgetChars: number, leaseMs: number, signal?: AbortSignal): Promise<{
+        cards: DeliveryCard[];
+        attempts: DeliveryAttempt[];
+    } | undefined>;
+    claimHandoff(owner: string, key: string, generation: string, kind: string, leaseMs: number, signal?: AbortSignal): Promise<{
+        card: DeliveryCard;
+        route: DeliveryRoute;
+        attempt: DeliveryAttempt;
+    } | undefined>;
+    current(tokens: readonly string[], signal?: AbortSignal, route?: DeliveryRoute): Promise<boolean>;
+    prepare(token: string, value: DeliveryCorrelation, signal?: AbortSignal): Promise<boolean>;
+    private receipt;
+    private confirm;
+    settle(tokens: readonly string[], outcome: Exclude<DeliveryOutcome, 'dispatching'>): Promise<boolean>;
+    private handoffFacts;
+    private matchingHandoff;
+    private currentHandoff;
+    handoff(token: string): Promise<(DeliveryHandoffRef & {
+        routeKind: string;
+    }) | undefined>;
+    guardHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
+    acceptHandoff(ref: DeliveryHandoffRef): Promise<boolean>;
+    observePresentation(handoff: string | DeliveryHandoffRef, options?: {
+        readonly requireCurrent?: boolean;
+    }): Promise<boolean>;
+    receipts(owner: string, options: {
+        keys?: readonly string[];
+        since?: number;
+    }): Promise<readonly DeliveryReceipt[]>;
+    health(owner?: string): Promise<DeliveryHealth>;
+}