@astrosheep/square 0.3.77 → 0.3.79

package/dist/notifications.js

@@ -2,7 +2,7 @@ import { hostLedgerRoot } from './host-ledger-root.js';
 import path from 'node:path';
 import fs from 'node:fs';
 import { SquareError } from './model.js';
-import { displayAttentionPath } from './attention-presentation.js';
+import { renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
 import { openSquare } from './open-square.js';
 import { closeOpenSquare } from './open-square.js';
 import { deliverPending, sweepPending } from './delivery-operations.js';
@@ -96,13 +96,29 @@ export function createWakeTransport(adapters, hostLedger, clock, nativePorts = {
             if (adapter === undefined)
                 return { outcome: 'not-capable', diagnostic: `no adapter for ${request.route.kind}` };
             try {
-                const kind = request.route.kind;
-                const payload = [
-                    `<system-reminder source="square" wake="${kind === 'paseo' ? 'paseo' : kind.startsWith('codex') ? 'codex-queue' : kind}">`,
-                    `square: ${displayAttentionPath(request.location)}`,
-                    `attention: ${request.activity} for ${request.participant} from ${request.actor}`,
-                    '</system-reminder>',
-                ].join('\n');
+                const location = await canonicalPath(request.location);
+                const square = await openSquare(location, { hostLedger }).catch(() => undefined);
+                if (square === undefined)
+                    return { outcome: 'not-capable', diagnostic: `Square is unavailable at ${location}` };
+                let payload;
+                try {
+                    const index = parseActivityId(request.activity);
+                    payload = (await square.artifact.read((facts) => {
+                        const head = index === undefined ? undefined : pendingHead(facts, request.participant, index);
+                        const item = index === undefined ? undefined : facts.activity(index);
+                        if (!head || item?.kind !== 'say')
+                            return undefined;
+                        return renderSquareReminder([renderAttentionPreview({
+                                squarePath: location, recipient: request.participant, actIndex: item.index,
+                                actor: item.actor, route: head.route, body: item.body,
+                            })]);
+                    })).value;
+                }
+                finally {
+                    await closeOpenSquare(square);
+                }
+                if (payload === undefined)
+                    return { outcome: 'not-capable', diagnostic: 'No pending Square activity to preview.' };
                 const result = await adapter.dispatch(request.route.address, payload, finalGate, timeoutMs, request);
                 if (result.outcome !== 'gate-rejected')
                     return result;

package/dist/participant-host.js

@@ -10,6 +10,8 @@ export async function identityRouteDraft(context, participant) {
     if (context.location === undefined || context.location === 'memory')
         return undefined;
     const identity = processIdentity(context.env ?? process.env);
+    if (identity.channel === 'unknown')
+        return undefined;
     const provider = identity.channel === 'claude-code' ? 'claude' : identity.channel === 'opencode' ? 'opencode' : identity.channel === 'pi' ? 'pi' : identity.channel === 'paseo' ? 'paseo' : 'codex';
     const boundary = { location: context.location, participant, sessionId: identity.session, provider };
     const env = context.env ?? process.env;
@@ -51,6 +53,9 @@ export async function ensureLocalPresence(context, participant, epoch) {
     if (context.hostLedger === undefined || context.location === undefined || context.location === 'memory')
         return;
     const identity = processIdentity(context.env ?? process.env);
+    // Sessionless library operations do not establish host presence or ownership.
+    if (identity.channel === 'unknown')
+        return;
     const now = Date.now();
     let existing;
     try {

package/dist/plugins/opencode/index.js

@@ -3,7 +3,7 @@ import { hostLedgerForEnv } from '../../registry.js';
 import { canonicalPath } from '../../canonical-path.js';
 import { openSquare } from '../../open-square.js';
 import { closeOpenSquare } from '../../open-square.js';
-import { Square } from '../../square-application.js';
+import { Square } from '../../square-api.js';
 import { connectNative } from '../../packages/agent-delivery/src/opencode-native.js';
 import { observeOpenCodeContext, publishOpenCodeRoutes, receiveOpenCodePending } from './delivery.js';
 /** Actual OpenCode 2.0.20 server plugin. Harness identity belongs to ctx, never process.env. */

package/dist/square-actions.d.ts

@@ -1,5 +1,6 @@
+import { type StoredAct } from './model.js';
 import type { WakeTransportPort } from './ports.js';
-import type { Activity, CatchOptions, ExpressOptions, ExpressResult, ExpressionObservation, ListenerChangeResult, OperationControl, OwnershipFenceOptions } from './square-facade.js';
+import type { Activity, ActivityResult, CatchOptions, ExpressOptions, ExpressResult, ExpressionObservation, OperationControl, OwnershipFenceOptions, SquareObservation } from './square-facade.js';
 import { type CatchSelection } from './catch-decisions.js';
 import { type HostContext } from './participant-host.js';
 export interface OperationContext extends HostContext {
@@ -8,6 +9,7 @@ export interface OperationContext extends HostContext {
 export type { OwnershipFenceOptions };
 export declare function catchUp(square: OperationContext, name: string, options?: CatchOptions, control?: OperationControl): Promise<CatchSelection>;
 export declare function catchUp(square: OperationContext, name: string, options: CatchOptions, control: OperationControl | undefined, leaseId: string): Promise<CatchSelection | null>;
+type LandingContext = Pick<SquareObservation, 'standingCount' | 'held' | 'now'>;
 export declare function join(square: OperationContext, name: string, control?: OperationControl, admission?: {
     readonly requireKnown?: boolean;
 }): Promise<{
@@ -15,28 +17,39 @@ export declare function join(square: OperationContext, name: string, control?: O
     readonly activity: Activity | null;
     readonly participantCount: number;
     readonly reconnected: boolean;
+    readonly observation: LandingContext;
 }>;
 /** Takeover holds the host CAS fence across the single done+join artifact transaction. */
-export declare function takeover(square: OperationContext, name: string, _oldSessionIds?: readonly string[], control?: OperationControl): Promise<{
+export declare function takeover(square: OperationContext, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly activities: readonly Activity[];
     readonly participantCount: number;
     readonly epoch?: number;
+    readonly observation: LandingContext;
 }>;
 export declare function implicitJoin(square: OperationContext, name: string, control?: OperationControl): Promise<{
     readonly name: string;
     readonly state: 'joined' | 'active' | 'done';
     readonly activity: Activity | null;
 }>;
-export interface ExpressCommittedResult extends ExpressResult {
+export interface ExpressCommittedResult extends Omit<ExpressResult, 'waited' | 'observation'> {
     readonly observation: ExpressionObservation;
 }
 export declare function express(square: OperationContext, name: string, body: string, options?: ExpressOptions, control?: OperationControl): Promise<ExpressCommittedResult>;
-export declare function listen(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerChangeResult>;
-export declare function ignore(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerChangeResult>;
+export interface ListenerCommittedResult {
+    readonly activity: Activity | null;
+    readonly observation: LandingContext;
+}
+export declare function listen(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerCommittedResult>;
+export declare function ignore(square: OperationContext, actor: string, target: string, control?: OperationControl): Promise<ListenerCommittedResult>;
 export declare function listening(square: OperationContext, actor: string, control?: OperationControl): Promise<readonly string[]>;
-export declare function done(square: OperationContext, name: string, body?: string, fence?: OwnershipFenceOptions, control?: OperationControl): Promise<ExpressResult>;
-export declare function endOwnedSession(square: OperationContext, name: string, sessionId: string, expectedEpoch?: number): Promise<ExpressResult | null>;
+export interface LifecycleCommittedResult extends ActivityResult {
+    readonly observation: LandingContext & {
+        readonly activity: StoredAct;
+    };
+}
+export declare function done(square: OperationContext, name: string, body?: string, fence?: OwnershipFenceOptions, control?: OperationControl): Promise<LifecycleCommittedResult>;
+export declare function endOwnedSession(square: OperationContext, name: string, sessionId: string, expectedEpoch?: number): Promise<ActivityResult | null>;
 export declare function retireEndedSessionRoutes(square: OperationContext, sessionId: string): Promise<void>;
-export declare function hold(square: OperationContext, name: string, reason?: string, control?: OperationControl): Promise<ExpressResult>;
-export declare function resume(square: OperationContext, name: string, control?: OperationControl): Promise<ExpressResult>;
+export declare function hold(square: OperationContext, name: string, reason?: string, control?: OperationControl): Promise<LifecycleCommittedResult>;
+export declare function resume(square: OperationContext, name: string, control?: OperationControl): Promise<LifecycleCommittedResult>;

package/dist/square-actions.js

@@ -1,4 +1,4 @@
-import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin, resolveKnownName, validateDoneBody } from './decisions.js';
+import { coreDone, coreHold, coreIgnore, coreListen, coreListening, coreResume, decideAct, decideImplicitJoin, decideJoin, expressionReach, resolveKnownName, validateDoneBody } from './decisions.js';
 import { isSquareError, nameKey, SquareError, validateName } from './model.js';
 import { participantIdentity } from './participant-identity.js';
 import { deliverPending } from './delivery-operations.js';
@@ -40,21 +40,23 @@ export async function join(square, name, control, admission = {}) {
     const preview = (await square.artifact.read((facts) => {
         // Express may reenter a known participant, but must never create a new name.
         const selected = admission.requireKnown ? resolveKnownName(facts, name) : name;
+        const now = square.clock();
         return {
-            ...decideJoin(facts, selected, square.clock()),
+            ...decideJoin(facts, selected, now),
             participantCount: facts.roster().filter((p) => p.joined || p.done).length,
+            observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now },
         };
     }, control?.signal)).value;
     name = preview.joinedName;
     if (preview.joinAct === undefined) {
         if (hostLedger === undefined)
-            return { name: preview.joinedName, activity: null, participantCount: preview.participantCount, reconnected: false };
+            return { name: preview.joinedName, activity: null, participantCount: preview.participantCount, reconnected: false, observation: preview.observation };
         const identity = processIdentity(square.env ?? process.env);
         const owner = await readParticipantOwner(square.location, preview.joinedName, hostLedger);
         if (owner?.session === identity.session)
             return {
                 name: preview.joinedName, activity: null, participantCount: preview.participantCount,
-                reconnected: identity.channel !== 'unknown',
+                reconnected: identity.channel !== 'unknown', observation: preview.observation,
             };
         // Missing or foreign owner must pass CAS, not become a silent reconnect.
     }
@@ -80,6 +82,7 @@ export async function join(square, name, control, admission = {}) {
             return {
                 name: decision.joinedName, stored,
                 participantCount: facts.roster().filter((p) => p.joined || p.done).length,
+                observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now },
             };
         }, control?.signal)).value;
     }
@@ -91,11 +94,11 @@ export async function join(square, name, control, admission = {}) {
     await publishCommittedIdentity(square, committed.name, epoch);
     return {
         name: committed.name, activity: committed.stored === null ? null : toPublicActivity(committed.stored),
-        participantCount: committed.participantCount, reconnected: false,
+        participantCount: committed.participantCount, reconnected: false, observation: committed.observation,
     };
 }
 /** Takeover holds the host CAS fence across the single done+join artifact transaction. */
-export async function takeover(square, name, _oldSessionIds = [], control) {
+export async function takeover(square, name, control) {
     throwIfAborted(control);
     validateName(name);
     const hostLedger = square.hostLedger;
@@ -113,6 +116,7 @@ export async function takeover(square, name, _oldSessionIds = [], control) {
             return {
                 name: joinedName, stored: [storedDone, storedJoin],
                 participantCount: facts.roster().filter((p) => p.joined || p.done).length,
+                observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now },
             };
         }, control?.signal)).value;
     };
@@ -131,11 +135,11 @@ export async function takeover(square, name, _oldSessionIds = [], control) {
         }, control?.signal);
         if (outcome.status === 'busy')
             throw new SquareError('already_joined', `${participantIdentity(name)} already stands here — another session holds the name`);
-        return { name: outcome.result.name, activities: outcome.result.stored.map(toPublicActivity), participantCount: outcome.result.participantCount, epoch: outcome.epoch };
+        return { name: outcome.result.name, activities: outcome.result.stored.map(toPublicActivity), participantCount: outcome.result.participantCount, epoch: outcome.epoch, observation: outcome.result.observation };
     }
     const committed = await commitLifecycle();
     await publishCommittedIdentity(square, committed.name);
-    return { name: committed.name, activities: committed.stored.map(toPublicActivity), participantCount: committed.participantCount };
+    return { name: committed.name, activities: committed.stored.map(toPublicActivity), participantCount: committed.participantCount, observation: committed.observation };
 }
 export async function implicitJoin(square, name, control) {
     throwIfAborted(control);
@@ -185,7 +189,10 @@ export async function express(square, name, body, options = {}, control) {
         }
         catch (error) {
             if (isSquareError(error))
-                error.facts = { ...error.facts, reason: 'invalid_reply', activityId: options.reply };
+                error.facts = {
+                    ...error.facts, reason: 'invalid_reply', activityId: options.reply,
+                    hasReachWithoutReply: expressionReach({ ...options, body }).hasReachWithoutReply,
+                };
             throw error;
         }
     });
@@ -216,6 +223,7 @@ export async function express(square, name, body, options = {}, control) {
                 standingCount: inSquareCount(facts), held: facts.hold().active, now,
                 ownActivityCount: facts.participant(name).sayCount, hardCap: facts.header().hardCap,
             },
+            ...(decision.unmatchedMentions === undefined ? {} : { unmatchedMentions: decision.unmatchedMentions }),
             ...(decision.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: decision.replyAuthorNotHere }),
         };
     }, control?.signal)).value;
@@ -224,19 +232,18 @@ export async function express(square, name, body, options = {}, control) {
         ? await deliverPending({ artifact: square.artifact, hostLedger: square.hostLedger, transport: square.wakeTransport, location: square.location, activity: committed.stored.index, now })
             .catch(() => ({ attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 }))
         : { attempted: 0, accepted: 0, failed: 0, unknown: 0, notCapable: 1 };
-    return {
-        activity: toPublicActivity(committed.stored), delivery, observation: committed.observation,
-        ...(committed.replyAuthorNotHere === undefined ? {} : { replyAuthorNotHere: committed.replyAuthorNotHere }),
-    };
+    const { stored, observation, ...metadata } = committed;
+    return { activity: toPublicActivity(stored), delivery, observation, ...metadata };
 }
 async function landListenerChange(square, verb, actor, target, control) {
     throwIfAborted(control);
     const now = square.clock();
-    const stored = (await square.artifact.transact((facts) => {
+    const committed = (await square.artifact.transact((facts) => {
         const act = verb === 'listen' ? coreListen(facts, actor, target, now) : coreIgnore(facts, actor, target, now);
-        return act === undefined ? null : facts.land(act);
+        const stored = act === undefined ? null : facts.land(act);
+        return { stored, observation: { standingCount: inSquareCount(facts), held: facts.hold().active, now } };
     }, control?.signal)).value;
-    return { activity: stored === null ? null : toPublicActivity(stored) };
+    return { activity: committed.stored === null ? null : toPublicActivity(committed.stored), observation: committed.observation };
 }
 export function listen(square, actor, target, control) { return landListenerChange(square, 'listen', actor, target, control); }
 export function ignore(square, actor, target, control) { return landListenerChange(square, 'ignore', actor, target, control); }
@@ -256,7 +263,9 @@ async function landCore(square, verb, actor, body = '', fence = {}, control) {
             const result = facts.land(verb === 'done' ? coreDone(facts, actor, body, now) : verb === 'hold' ? coreHold(facts, actor, body, now) : coreResume(facts, actor, now));
             if (session !== undefined)
                 dropEndedSessionWakeRoutes(facts, square.location, session, { expectedEpoch: fence.expectedEpoch, force: true, participant: actor });
-            return result;
+            return { activity: toPublicActivity(result), observation: {
+                    activity: result, standingCount: inSquareCount(facts), held: facts.hold().active, now,
+                } };
         }, control?.signal)).value;
         for (const row of owners)
             await hostLedger.removePresenceIfUnchanged(row).catch((error) => {
@@ -264,8 +273,7 @@ async function landCore(square, verb, actor, body = '', fence = {}, control) {
             });
         return stored;
     };
-    const stored = hostLedger === undefined ? await commitAndCleanup() : await hostLedger.withClaimLock(commitAndCleanup, control?.signal);
-    return { activity: toPublicActivity(stored) };
+    return hostLedger === undefined ? commitAndCleanup() : hostLedger.withClaimLock(commitAndCleanup, control?.signal);
 }
 export function done(square, name, body = '', fence = {}, control) { return landCore(square, 'done', name, body, fence, control); }
 function liveClaimedParticipants(rows, sessionId) {

package/dist/square-api.d.ts

@@ -0,0 +1,43 @@
+import type { ActivityResult, HistoryQuery, HistoryResult, JoinOptions, JoinResult, ObservationOptions, OperationControl, Participant, SquareAtInput, SquareBuildInput, SquareLocation, StatusOptions, StatusResult, ParticipantsResult, RecoveryResult, DiscoveryOptions, InboxOptions, InboxResult, StreamOptions } from './square-facade.js';
+export type * from './square-facade.js';
+export { createSquareResourceOwner } from './open-square.js';
+export { formatActivityId, parseActivityId, MAX_IDENTITY_SET_SIZE } from './square-core.js';
+export { CATCH_DEFAULT_LIMIT, CATCH_MAX_LIMIT } from './catch-decisions.js';
+export { HELD_WAIT_BUDGET_MS } from './runtime.js';
+export { HISTORY_DEFAULT_LIMIT, HISTORY_MAX_LIMIT } from './views.js';
+export { DEFAULT_LIST_DEPTH, MAX_LIST_DEPTH, DEFAULT_LIST_LIMIT, MAX_LIST_LIMIT } from './list.js';
+export declare function squareLocation(input: SquareLocation): string;
+export declare function squareClock(env: NodeJS.ProcessEnv, clock?: () => number): () => number;
+/** One concrete square resource. Request handles may borrow a server-owned connection. */
+export declare class Square {
+    readonly location: string;
+    private readonly square;
+    private readonly defaultParticipant?;
+    private readonly transport;
+    private constructor();
+    static at(input: SquareAtInput, control?: OperationControl): Promise<Square>;
+    static build(input: SquareBuildInput, control?: OperationControl): Promise<Square>;
+    static inMemory(input: Omit<SquareBuildInput, 'path' | 'resources'>): Square;
+    private handle;
+    participant(requested?: string): Promise<Participant>;
+    join(requested?: string, options?: JoinOptions, control?: OperationControl): Promise<JoinResult>;
+    doneOwnedSession(name: string, body: string, expectedEpoch: number, control?: OperationControl): Promise<ActivityResult>;
+    implicitJoin(name: string, control?: OperationControl): Promise<{
+        readonly state: 'joined' | 'active' | 'done';
+        readonly participant?: Participant;
+    }>;
+    snapshot(control?: OperationControl): Promise<import("./square-facade.js").SquareSnapshot>;
+    history(query?: HistoryQuery, control?: OperationControl): Promise<HistoryResult>;
+    status(options?: StatusOptions, control?: OperationControl): Promise<StatusResult>;
+    participants(options?: ObservationOptions, control?: OperationControl): Promise<ParticipantsResult>;
+    recovery(requested?: string, control?: OperationControl): Promise<RecoveryResult>;
+    stream(options: StreamOptions, control?: OperationControl): AsyncIterable<import("./square-facade.js").StreamRecord>;
+    recognize(env: NodeJS.ProcessEnv): Promise<Participant | null>;
+    close(): Promise<void>;
+    endOwnedSession(name: string, sessionId: string, expectedEpoch?: number): Promise<ActivityResult | null>;
+    retireEndedSessionRoutes(sessionId: string): Promise<void>;
+}
+export declare function diagnoseSquare(input: SquareLocation, control?: OperationControl): Promise<import("./artifact.js").DiagnoseResult>;
+export declare function migrateSquare(input: SquareLocation, control?: OperationControl): Promise<import("./square-migration.js").MigrationOutcome>;
+export declare function discover(input: SquareAtInput, options?: DiscoveryOptions, control?: OperationControl): Promise<import("./square-facade.js").DiscoveryResult>;
+export declare function inbox(input: SquareAtInput, sessionId: string, options?: InboxOptions, control?: OperationControl): Promise<InboxResult>;