@astrosheep/square 0.3.94 → 0.3.96

package/dist/artifact.js

@@ -117,7 +117,7 @@ function synchronous(value) {
     }
 }
 const readMethods = [
-    'header', 'participant', 'roster', 'attention', 'incomingAttention', 'hold',
+    'header', 'participant', 'roster', 'attention', 'incomingAttention',
     'activity', 'activityHeads', 'activities', 'activityCount', 'contextIndexes', 'sayOrdinals', 'recentSayTimes',
     'audience', 'directed', 'directedAt', 'directedCount', 'pendingAudience',
     'receipt', 'receiptFacts', 'receiptAssignments', 'lease', 'participantCounts', 'seat', 'seatsForOwner',

package/dist/attention-presentation.d.ts

@@ -1,4 +1,4 @@
-import type { DirectedNotificationRoute } from './model.js';
+import type { ActivityDelivery, DirectedNotificationRoute } from './model.js';
 export declare const ATTENTION_BODY_MAX = 200;
 export interface AttentionPreview {
     squarePath: string;
@@ -7,13 +7,14 @@ export interface AttentionPreview {
     actor: string;
     route: DirectedNotificationRoute;
     body: string;
+    delivery?: ActivityDelivery;
 }
-export declare function previewAttentionBody(body: string): string;
-export declare function attentionBodyIsClipped(body: string): boolean;
+export declare function previewAttentionBody(body: string, delivery?: ActivityDelivery): string;
+export declare function attentionBodyIsClipped(body: string, delivery?: ActivityDelivery): boolean;
 export declare function displayAttentionPath(squarePath: string): string;
 export declare function renderAttentionDescription({ actor, route }: Pick<AttentionPreview, 'actor' | 'route'>): string;
 /** Full notification text for human-facing expansion, never the bounded model preview. */
 export declare function renderAttentionFull(attention: AttentionPreview): string;
 /** Shared model-facing envelope; transport correlation and human cards stay outside it. */
-export declare function renderSquareReminder(previews: readonly string[]): string;
+export declare function renderSquareReminder(previews: readonly string[], deliveries?: readonly (ActivityDelivery | undefined)[]): string;
 export declare function renderAttentionPreview(attention: AttentionPreview): string;

package/dist/attention-presentation.js

@@ -1,14 +1,16 @@
 import { homedir } from 'node:os';
 import { formatActivityId } from './square-core.js';
 export const ATTENTION_BODY_MAX = 200;
-export function previewAttentionBody(body) {
-    const compact = body.replace(/\r\n/g, '\n');
-    if (compact.length <= ATTENTION_BODY_MAX)
+export function previewAttentionBody(body, delivery) {
+    const compact = (delivery?.mode === 'direct' ? delivery.preview ?? body : body).replace(/\r\n/g, '\n');
+    if (delivery?.mode === 'direct' || compact.length <= ATTENTION_BODY_MAX)
         return compact;
     return `${compact.slice(0, ATTENTION_BODY_MAX).trimEnd()}…`;
 }
-export function attentionBodyIsClipped(body) {
-    return body.replace(/\r\n/g, '\n').length > ATTENTION_BODY_MAX;
+export function attentionBodyIsClipped(body, delivery) {
+    return delivery?.mode === 'direct'
+        ? delivery.preview !== undefined
+        : body.replace(/\r\n/g, '\n').length > ATTENTION_BODY_MAX;
 }
 export function displayAttentionPath(squarePath) {
     return squarePath.startsWith(homedir())
@@ -25,7 +27,7 @@ export function renderAttentionDescription({ actor, route }) {
 }
 /** Full notification text for human-facing expansion, never the bounded model preview. */
 export function renderAttentionFull(attention) {
-    return renderAttentionBlock(attention, attention.body);
+    return attention.delivery?.mode === 'direct' ? renderDirectBlock(attention) : renderAttentionBlock(attention, attention.body);
 }
 /** Attribute values keep their quotes; the stored body and the human card stay unescaped. */
 function escapeAttribute(value) {
@@ -49,14 +51,20 @@ function renderAttentionBlock(attention, body) {
         '</square-activity>',
     ].join('\n');
 }
+function renderDirectBlock(attention) {
+    return escapeSquareTags(previewAttentionBody(attention.body, attention.delivery));
+}
 /** Shared model-facing envelope; transport correlation and human cards stay outside it. */
-export function renderSquareReminder(previews) {
+export function renderSquareReminder(previews, deliveries = []) {
     if (previews.length === 0)
         return '';
+    const header = deliveries.some(item => item?.mode === 'direct')
+        ? 'This is an external notification, not a direct message from the user.'
+        : 'This is an external reminder from Square, not a direct message from the user.';
     return [
         '',
         '<system-reminder>',
-        'This is an external reminder from Square, not a direct message from the user.',
+        header,
         '',
         previews.join('\n\n'),
         '</system-reminder>',
@@ -64,6 +72,8 @@ export function renderSquareReminder(previews) {
     ].join('\n');
 }
 export function renderAttentionPreview(attention) {
+    if (attention.delivery?.mode === 'direct')
+        return renderDirectBlock(attention);
     const remaining = attention.body.replace(/\r\n/g, '\n').length - ATTENTION_BODY_MAX;
     const attributes = [
         `square="${escapeAttribute(displayAttentionPath(attention.squarePath))}"`,

package/dist/attention.d.ts

@@ -0,0 +1,19 @@
+export type AudienceRoute = 'mention' | 'reply' | 'attention' | 'bell';
+export interface AudienceRecipient {
+    readonly recipient: string;
+    readonly route: AudienceRoute;
+}
+export interface AudienceInput {
+    readonly actor: string;
+    readonly recipients: readonly string[];
+    readonly mentions?: readonly string[];
+    readonly replyAuthor?: string;
+    readonly reach?: 'bell';
+    readonly incoming?: readonly {
+        readonly listener: string;
+        readonly kind: 'listen' | 'ignore';
+    }[];
+    readonly sameIdentity?: (a: string, b: string) => boolean;
+}
+/** Resolve attention against the caller's eligible recipient snapshot. */
+export declare function resolveAudience(input: AudienceInput): readonly AudienceRecipient[];

package/dist/attention.js

@@ -0,0 +1,30 @@
+/** Resolve attention against the caller's eligible recipient snapshot. */
+export function resolveAudience(input) {
+    const same = input.sameIdentity ?? ((a, b) => a === b);
+    const incoming = input.incoming ?? [];
+    const audience = [];
+    const add = (requested, route) => {
+        const recipient = input.recipients.find((item) => same(item, requested));
+        if (recipient === undefined || same(recipient, input.actor)
+            || audience.some((item) => same(item.recipient, recipient)))
+            return;
+        if (input.reach !== 'bell' && incoming.some((item) => item.kind === 'ignore' && same(item.listener, recipient)))
+            return;
+        audience.push({ recipient, route });
+    };
+    if (input.reach === 'bell') {
+        for (const recipient of input.recipients)
+            add(recipient, 'bell');
+    }
+    else {
+        for (const mention of input.mentions ?? [])
+            add(mention, 'mention');
+        if (input.replyAuthor !== undefined)
+            add(input.replyAuthor, 'reply');
+        for (const recipient of input.recipients) {
+            if (incoming.some((item) => item.kind === 'listen' && same(item.listener, recipient)))
+                add(recipient, 'attention');
+        }
+    }
+    return audience;
+}

package/dist/boundary-presentation.js

@@ -3,6 +3,7 @@ import { createHash } from 'node:crypto';
 import { withFileLock } from './file-lock.js';
 import { createArtifactPort } from './artifact.js';
 import { preparePendingPresentation } from './presentation-operations.js';
+import { presentPreparedBatch } from './delivery-effects.js';
 import { sessionInbox, projectBoundaryEligibility, pendingAtBoundary, pendingKey } from './inbox.js';
 import { attentionBodyIsClipped, renderAttentionPreview, renderSquareReminder } from './attention-presentation.js';
 export { pendingAtBoundary };
@@ -13,10 +14,13 @@ export function renderPendingAtBoundary(inbox) {
 function renderBoundary(inbox) {
     const queued = inbox.flatMap((membership) => membership.notifications.map((notification) => ({ membership, notification })));
     const blocks = [];
+    const agoraBlocks = [];
+    const deliveries = [];
+    let remainingAgora = queued.filter(({ notification }) => notification.delivery?.mode !== 'direct').length;
     const complete = [];
     let omitted = 0;
     const omission = (count) => `${count} more ${count === 1 ? 'activity' : 'activities'} not shown.`;
-    for (const [index, entry] of queued.entries()) {
+    for (const entry of queued) {
         const { membership, notification } = entry;
         const block = [
             renderAttentionPreview({
@@ -26,23 +30,29 @@ function renderBoundary(inbox) {
                 actor: notification.actor,
                 route: notification.route,
                 body: notification.body,
+                delivery: notification.delivery,
             }),
         ].join('\n');
-        const omittedAfter = omitted + queued.length - index - 1;
-        const prospective = renderSquareReminder([...blocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
-        if (prospective.length > CONTEXT_MAX) {
-            omitted += 1;
-            continue;
+        if (notification.delivery?.mode !== 'direct') {
+            remainingAgora -= 1;
+            const omittedAfter = omitted + remainingAgora;
+            const prospective = renderSquareReminder([...agoraBlocks, block, ...(omittedAfter > 0 ? [omission(omittedAfter)] : [])]);
+            if (prospective.length > CONTEXT_MAX) {
+                omitted += 1;
+                continue;
+            }
+            agoraBlocks.push(block);
         }
         blocks.push(block);
+        deliveries.push(notification.delivery);
         complete.push({
             membership,
             actIndexes: [notification.actIndex],
-            markSeen: !attentionBodyIsClipped(notification.body),
+            markSeen: !attentionBodyIsClipped(notification.body, notification.delivery),
         });
     }
     return {
-        context: renderSquareReminder([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])]),
+        context: renderSquareReminder([...blocks, ...(omitted > 0 ? [omission(omitted)] : [])], deliveries),
         complete,
     };
 }
@@ -56,53 +66,45 @@ async function presentPendingAtBoundaryUnlocked(identity, present, lookup = sess
     const artifacts = new Map();
     const claims = [];
     try {
-        // Claim the entire candidate batch before its one external effect. No later item needs
-        // a new claim (and new eligibility decision) after its bytes have already been rendered.
-        for (const entry of renderBoundary(pending).complete) {
-            const { location, seat } = entry.membership;
-            let artifact = artifacts.get(location);
-            if (artifact === undefined) {
-                // This boundary owns the connection until all effect evidence/cleanup has settled.
-                // Request cancellation travels with pre-effect operations, not that lifetime.
-                artifact = createArtifactPort(location);
-                artifacts.set(location, artifact);
-            }
-            for (const index of entry.actIndexes) {
-                const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
-                    activity: index, seat, markSeen: entry.markSeen, signal });
-                if (claim !== undefined)
-                    claims.push({ key: pendingKey(entry.membership, index), claim });
-            }
-        }
-        const eligible = new Set();
-        for (const { key, claim } of claims)
-            if (await claim.eligible())
-                eligible.add(key);
-        const fresh = renderBoundary(pending.map(membership => ({ ...membership,
-            notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.actIndex))),
-        })));
-        const included = new Set(fresh.complete.flatMap(entry => entry.actIndexes.map(index => pendingKey(entry.membership, index))));
-        if (included.size === 0 || signal?.aborted)
-            return undefined;
-        const rendered = claims.filter(({ key }) => included.has(key));
-        let result;
         try {
-            result = await present(fresh.context);
+            // Enumeration owns discovery/connections only; returned handles belong to the common runner.
+            for (const entry of renderBoundary(pending).complete) {
+                const { location, seat } = entry.membership;
+                let artifact = artifacts.get(location);
+                if (artifact === undefined) {
+                    // Keep connections alive through all signal-independent settlement/cleanup.
+                    artifact = createArtifactPort(location);
+                    artifacts.set(location, artifact);
+                }
+                for (const index of entry.actIndexes) {
+                    const claim = await preparePendingPresentation({ artifact, location, participant: seat.participant,
+                        activity: index, seat, markSeen: entry.markSeen, signal });
+                    if (claim !== undefined)
+                        claims.push({ key: pendingKey(entry.membership, index), claim });
+                }
+            }
         }
         catch (error) {
-            await Promise.all(rendered.map(({ claim }) => claim.release('failed', error instanceof Error ? error.message : String(error))));
+            // Transfer has not happened: enumeration must abandon any custody already acquired.
+            await Promise.all(claims.map(({ claim }) => claim.release()));
             throw error;
         }
-        // These are successful sink effects, not fresh delivery attempts. Settle the entire
-        // rendered set before closing any connection, even if one member's settlement fails.
-        const settlements = await Promise.allSettled(rendered.map(({ claim }) => claim.recordPresented()));
-        for (const settlement of settlements)
-            if (settlement.status === 'rejected')
-                throw settlement.reason;
-        return result;
+        const report = await presentPreparedBatch(claims.map(({ claim }) => claim), eligibleClaims => {
+            const eligible = new Set(claims.filter(({ claim }) => eligibleClaims.includes(claim)).map(({ key }) => key));
+            const fresh = renderBoundary(pending.map(membership => ({ ...membership,
+                notifications: membership.notifications.filter(note => eligible.has(pendingKey(membership, note.actIndex))),
+            })));
+            const included = new Set(fresh.complete.flatMap(entry => entry.actIndexes.map(index => pendingKey(entry.membership, index))));
+            return { payload: fresh.context, included: claims.filter(({ key }) => included.has(key)).map(({ claim }) => claim) };
+        }, present, { signal, classifyError: () => 'failed' });
+        if (report.observation.kind === 'threw')
+            throw report.observation.error;
+        for (const { result } of report.settlements)
+            if (result.persistence.status === 'error')
+                throw result.persistence.error;
+        return report.observation.kind === 'returned' ? report.observation.value : undefined;
     }
     finally {
-        await Promise.all(claims.map(({ claim }) => claim.release()));
         await Promise.all([...artifacts.values()].map(artifact => artifact.close()));
     }
 }

package/dist/catch-decisions.d.ts

@@ -6,7 +6,6 @@ export interface CatchSelection {
     readonly activities: readonly PerceivedActivity[];
     readonly remaining: number;
     readonly standingCount: number;
-    readonly held: boolean;
     readonly deliveryAvailable: boolean;
     readonly now: number;
     readonly ownActivityCount: number;
@@ -15,7 +14,7 @@ export interface CatchSelection {
     readonly hint?: string;
 }
 /** Capture a selected page (or an empty completion) without opening another resource. */
-export declare function observeCatchSelection(facts: SquareRead, participant: string, activities: readonly StoredAct[], filter: DirectedFilter, at: number): CatchSelection;
+export declare function observeCatchSelection(facts: SquareRead, participant: string, activities: readonly StoredAct[], filter: DirectedFilter, at: number, remaining?: number): CatchSelection;
 export declare const CATCH_DEFAULT_LIMIT = 10;
 export declare const CATCH_MAX_LIMIT = 100;
 export declare function catchLimit(value: number | undefined): number;

package/dist/catch-decisions.js

@@ -4,15 +4,17 @@ import { SquareError } from './model.js';
 import { resolveKnownName } from './decisions.js';
 import { toPerceivedActivity } from './views.js';
 import { catchHint } from './hints.js';
+import { consumeReceived, ReceiveError, selectReceivedHeads } from './receive.js';
+import { squareReceiveRead } from './square-receive.js';
 /** Capture a selected page (or an empty completion) without opening another resource. */
-export function observeCatchSelection(facts, participant, activities, filter, at) {
+export function observeCatchSelection(facts, participant, activities, filter, at, remaining) {
     if (typeof at !== 'number' || !Number.isFinite(at))
         throw new SquareError('invalid_args', 'Catch time must be a finite number.');
     const counts = facts.participantCounts(), header = facts.header(), current = facts.participant(participant);
     return {
         participant, activities: activities.map(activity => toPerceivedActivity(facts, activity, participant)),
-        remaining: facts.directedCount(participant, filter),
-        standingCount: counts.joined, held: facts.hold().active, now: at,
+        remaining: remaining ?? facts.directedCount(participant, filter),
+        standingCount: counts.joined, now: at,
         deliveryAvailable: facts.seat(participant)?.wakeAddress !== undefined,
         ownActivityCount: current.sayCount, hardCap: header.hardCap,
         terminalStatus: terminalStatusFor(current, header.hardCap, counts),
@@ -27,19 +29,23 @@ export function catchLimit(value) {
     }
     return limit;
 }
-/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
-export function selectCatchPage(facts, requestedName, options) {
+function catchPageSelection(facts, requestedName, options) {
     const participant = resolveKnownName(facts, requestedName);
     const limit = catchLimit(options.limit);
-    const senders = options.from?.map((name) => resolveKnownName(facts, name));
+    const senders = options.from?.map(name => resolveKnownName(facts, name));
     const filter = { unseenOnly: true, ...(senders === undefined ? {} : { senders }), ...(options.mention === true ? { attentionOnly: true } : {}) };
-    return { participant, indexes: facts.directed(participant, filter, { edge: 'oldest', limit }).items.map((item) => item.index), filter };
+    return { participant, filter, selection: { kind: 'page', query: filter, limit } };
+}
+/** Select non-ID catch coordinates without hydrating bodies or recording receipts. */
+export function selectCatchPage(facts, requestedName, options) {
+    const { participant, filter, selection } = catchPageSelection(facts, requestedName, options);
+    return { participant, indexes: selectReceivedHeads(squareReceiveRead(facts), participant, selection).map(item => item.key), filter };
 }
 /** Selection, receipts and resulting cursor belong to one artifact write transaction. */
 export function decideCatch(facts, requestedName, options, at) {
     let viewer;
-    let delivered;
     let filter = { unseenOnly: true };
+    let selection;
     if (options.id !== undefined) {
         viewer = resolveKnownName(facts, requestedName);
         catchLimit(options.limit);
@@ -48,25 +54,39 @@ export function decideCatch(facts, requestedName, options, at) {
         const index = parseActivityId(options.id);
         if (index === undefined)
             throw new SquareError('invalid_args', 'Invalid catch id: expected an activity id like act/12.');
-        const activity = facts.activity(index);
-        if (activity === undefined || activity.kind !== 'say' || facts.directedAt(viewer, index) === undefined) {
-            throw new SquareError('invalid_args', `✕ ${formatActivityId(index)} isn't addressed to you`, {
-                reason: 'not_addressed', activityId: formatActivityId(index), activityExists: activity !== undefined,
-            });
-        }
-        delivered = [activity];
+        selection = { kind: 'exact', key: index, remainingQuery: filter };
     }
     else {
-        const page = selectCatchPage(facts, requestedName, options);
+        const page = catchPageSelection(facts, requestedName, options);
         viewer = page.participant;
         filter = page.filter;
-        delivered = facts.activities(page.indexes);
+        selection = page.selection;
+    }
+    let consumed;
+    try {
+        consumed = consumeReceived({
+            ...squareReceiveRead(facts),
+            insertReceipt: (ref, time) => facts.markSeen(ref.recipient, [ref.item], time) > 0,
+        }, viewer, selection, at);
+    }
+    catch (error) {
+        if ((error instanceof TypeError || error instanceof RangeError) && (typeof at !== 'number' || !Number.isFinite(at))) {
+            throw new SquareError('invalid_args', 'Invalid square artifact: row is malformed.');
+        }
+        if (!(error instanceof ReceiveError))
+            throw error;
+        if (error.code === 'missing_item')
+            throw new SquareError('invalid_args', 'Invalid square artifact: addressed activity is missing.');
+        const index = error.key;
+        throw new SquareError('invalid_args', `✕ ${formatActivityId(index)} isn't addressed to you`, {
+            reason: 'not_addressed', activityId: formatActivityId(index), activityExists: facts.activity(index) !== undefined,
+        });
     }
-    const marked = facts.markSeen(viewer, delivered.map((item) => item.index), at);
-    const selection = observeCatchSelection(facts, viewer, delivered, filter, at);
+    const delivered = consumed.items.map(item => item.data);
+    const observed = observeCatchSelection(facts, viewer, delivered, filter, at, consumed.remaining);
     // Receipts are the durable catch count: everything directed here minus what is still unseen.
     const caught = facts.directedCount(viewer, {}) - facts.directedCount(viewer, { unseenOnly: true });
     // An exact id catch is a targeted fetch and stays repeatable, so it carries no nudge.
-    const hint = options.id === undefined ? catchHint(caught - marked, caught) : undefined;
-    return hint === undefined ? selection : { ...selection, hint };
+    const hint = options.id === undefined ? catchHint(caught - consumed.newlyConsumed, caught) : undefined;
+    return hint === undefined ? observed : { ...observed, hint };
 }

package/dist/channel.d.ts

@@ -0,0 +1,72 @@
+import { type HarnessSessionChannel } from './participant-identity.js';
+import type { SquareResourceOwner, WakeTransportPort } from './ports.js';
+import type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, Participant, WakeAddress } from './square-facade.js';
+export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
+export type { ActivityDelivery, ActivityMetadata, ChannelTruncate } from './square-facade.js';
+export type { ActivityId, ChannelSendInput, ChannelSendResult, DeliveryDeferral, HeldSeat, MetadataMatch, OperationControl, Owner, WakeAddress, SquareResourceOwner, WakeTransportPort, HarnessSessionChannel };
+export interface ResolvedHarnessSession {
+    readonly channel: HarnessSessionChannel;
+    readonly sessionId: string;
+    readonly agentId?: string;
+    readonly owner: Owner;
+    readonly wakeAddress?: WakeAddress;
+}
+export declare function resolveHarnessSession(env?: NodeJS.ProcessEnv): ResolvedHarnessSession | undefined;
+export interface ChannelOpenInput {
+    readonly path: string;
+    readonly cwd?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly clock?: () => number;
+    readonly wakeTransport?: WakeTransportPort | false;
+    readonly resources?: SquareResourceOwner;
+}
+export interface ChannelCreateInput extends ChannelOpenInput {
+    readonly force?: boolean;
+    readonly description?: string;
+}
+type EndpointOptions = {
+    readonly owner: Owner;
+    readonly wakeAddress?: WakeAddress;
+};
+type EndpointIdentity = {
+    readonly owner: Owner;
+    readonly generation: ActivityId;
+};
+/** A scoped direct-messaging vocabulary over the shared Square resource. */
+export declare class Channel {
+    private readonly square;
+    private constructor();
+    get location(): string;
+    static open(input: ChannelOpenInput, control?: OperationControl): Promise<Channel>;
+    static create(input: ChannelCreateInput, control?: OperationControl): Promise<Channel>;
+    static inMemory(input?: Omit<ChannelCreateInput, 'path' | 'resources' | 'force'>): Channel;
+    attach(name: string, options: EndpointOptions & {
+        readonly takeover?: boolean;
+    }, control?: OperationControl): Promise<ChannelEndpoint>;
+    reattach(name: string, options: EndpointOptions, control?: OperationControl): Promise<ChannelEndpoint | null>;
+    endpoint(name: string, options: {
+        readonly owner: Owner;
+    }): Promise<ChannelEndpoint>;
+    endpointsOf(owner: Owner): Promise<readonly HeldSeat[]>;
+    detach(name: string, identity: EndpointIdentity): Promise<true | null>;
+    remove(name: string, identity: EndpointIdentity): Promise<boolean>;
+    cancelDeliveries(name: string, identity: EndpointIdentity): Promise<boolean>;
+    send(input: ChannelSendInput, control?: OperationControl): Promise<ChannelSendResult>;
+    close(): Promise<void>;
+}
+/** Captures one recipient generation through its existing Participant handle. */
+export declare class ChannelEndpoint {
+    private readonly channel;
+    private readonly participant;
+    constructor(channel: Channel, participant: Participant);
+    get name(): string;
+    get generation(): ActivityId;
+    leave(control?: OperationControl): Promise<void>;
+    deferDelivery(input: Readonly<{
+        match: MetadataMatch;
+        durationMs: number;
+    }>, control?: OperationControl): Promise<DeliveryDeferral>;
+    renewDeliveryDeferral(id: string, durationMs: number, control?: OperationControl): Promise<DeliveryDeferral | null>;
+    releaseDeliveryDeferral(id: string, control?: OperationControl): Promise<boolean>;
+    send(input: Omit<ChannelSendInput, 'from'>, control?: OperationControl): Promise<ChannelSendResult>;
+}

package/dist/channel.js

@@ -0,0 +1,86 @@
+import { codexWakeAddress } from './codex-address.js';
+import { SquareError } from './model.js';
+import { harnessOwner } from './owner.js';
+import { harnessSessionSources } from './participant-identity.js';
+import { Square } from './square-api.js';
+import { squareLocation } from './square-location.js';
+export { harnessOwner, decodeHarnessOwner, localUserOwner } from './owner.js';
+export function resolveHarnessSession(env = process.env) {
+    for (const { variable, channel } of harnessSessionSources) {
+        const sessionId = env[variable]?.trim();
+        if (!sessionId)
+            continue;
+        const agentId = channel === 'claude-code' && env.CLAUDE_CODE_CHILD_SESSION?.trim() === '1'
+            ? env.CLAUDE_CODE_AGENT_ID?.trim() || undefined : undefined;
+        const wakeAddress = channel === 'codex' ? codexWakeAddress(sessionId, env)
+            : channel === 'paseo' ? { kind: 'paseo', address: { agentId: sessionId } } : undefined;
+        return { channel, sessionId, ...(agentId === undefined ? {} : { agentId }),
+            owner: harnessOwner({ channel, session: sessionId, ...(agentId === undefined ? {} : { agent: agentId }) }),
+            ...(wakeAddress === undefined ? {} : { wakeAddress }) };
+    }
+    return undefined;
+}
+function explicitLocation(input) {
+    if (typeof input?.path !== 'string' || input.path.trim() === '')
+        throw new SquareError('invalid_args', 'Channel path is required.');
+    return squareLocation(input);
+}
+/** A scoped direct-messaging vocabulary over the shared Square resource. */
+export class Channel {
+    square;
+    constructor(square) {
+        this.square = square;
+    }
+    get location() { return this.square.location; }
+    static async open(input, control) {
+        const path = explicitLocation(input);
+        return new Channel(await Square.at({ ...input, path }, control));
+    }
+    static async create(input, control) {
+        const path = explicitLocation(input);
+        return new Channel(await Square.build({ ...input, path, hardCap: null, markdown: input.description ?? '# Channel\n' }, control));
+    }
+    static inMemory(input = {}) {
+        return new Channel(Square.inMemory({ ...input, hardCap: null, markdown: input.description ?? '# Channel\n' }));
+    }
+    async attach(name, options, control) {
+        return new ChannelEndpoint(this, (await this.square.join(name, options, control)).participant);
+    }
+    async reattach(name, options, control) {
+        const participant = await this.square.reattach(name, options, control);
+        return participant === null ? null : new ChannelEndpoint(this, participant);
+    }
+    async endpoint(name, options) {
+        return new ChannelEndpoint(this, await this.square.participant(name, options));
+    }
+    endpointsOf(owner) { return this.square.seatsOf(owner); }
+    detach(name, identity) { return this.square.detach(name, identity); }
+    async remove(name, identity) { return await this.square.endHeld(name, identity) !== null; }
+    cancelDeliveries(name, identity) { return this.square.cancelDeliveries(name, identity); }
+    send(input, control) { return this.square.send(input, control); }
+    close() { return this.square.close(); }
+}
+/** Captures one recipient generation through its existing Participant handle. */
+export class ChannelEndpoint {
+    channel;
+    participant;
+    constructor(channel, participant) {
+        this.channel = channel;
+        this.participant = participant;
+    }
+    get name() { return this.participant.name; }
+    get generation() { return this.participant.generation; }
+    async leave(control) { await this.participant.done(undefined, {}, control); }
+    deferDelivery(input, control) {
+        return this.participant.deferDelivery(input, control);
+    }
+    renewDeliveryDeferral(id, durationMs, control) {
+        return this.participant.renewDeliveryDeferral(id, durationMs, control);
+    }
+    releaseDeliveryDeferral(id, control) {
+        return this.participant.releaseDeliveryDeferral(id, control);
+    }
+    send(input, control) {
+        return this.channel.send({ ...input, from: this.name }, control);
+    }
+}

package/dist/claude-delivery.js

@@ -150,7 +150,8 @@ export async function observeClaudeDelivery(sessionId, text, operation, env = pr
                 return { recognized, current: false };
             if (operation === 'stored')
                 await presentPending({ artifact: row.artifact, location: request.location,
-                    participant: request.participant, activity: request.activity, seat: request.seat, sink: { present() { } },
+                    // Claude's stored event consumes even Agora previews; retain that contract for both modes.
+                    participant: request.participant, activity: request.activity, seat: request.seat, markSeen: true, sink: { present() { } },
                     current: facts => currentPayload(facts, request) === payload });
         }
         return { recognized, current: true };

package/dist/cli/context.js

@@ -99,8 +99,6 @@ const LOCATION_REQUIRED_COMMANDS = new Set([
     'unlisten',
     'listening',
     'done',
-    'hold',
-    'resume',
     'history',
     'status',
     'participants',

package/dist/cli/express-presentation.js

@@ -88,7 +88,7 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
         const selected = square === undefined ? undefined : await selectOwnSeat(square, owner, name).catch(() => undefined);
         const fresh = await square?.recovery(selected?.name ?? name).catch(() => undefined);
         name = fresh?.participant ?? name;
-        const output = { squarePath, name, owner: opts.recoveryOwner, draftPath, participantCount: fresh?.standingCount, held: fresh?.held };
+        const output = { squarePath, name, owner: opts.recoveryOwner, draftPath, participantCount: fresh?.standingCount };
         const confirmedUnsent = landedId === undefined && detail?.landedId === undefined
             && detail?.expressEffect !== 'landed' && detail?.expressEffect !== 'unknown'
             && (!attempted || detail?.expressEffect === 'unsent' || (isSquareError(error) && error.facts?.activityUnsent === true));
@@ -116,9 +116,9 @@ export async function executeExpression(open, squarePath, requestedName, rawInpu
                 exitCode(1);
                 return;
             }
-            if (error.code === 'held' || error.code === 'throttled') {
+            if (error.code === 'throttled') {
                 process.stdout.write(renderExpressNoWait({ ...output, reason: error.code, retryCommand: retryInput,
-                    delayMs: error.facts?.retryAfterMs ?? 1, holder: error.facts?.holder, holdReason: error.facts?.holdReason,
+                    delayMs: error.facts?.retryAfterMs ?? 1,
                 }));
                 exitCode(1);
                 return;

package/dist/cli/json.js

@@ -1,6 +1,6 @@
 export const JSON_COMMANDS = new Set([
     'join', 'express', 'catch', 'history', 'listen', 'ignore', 'unlisten', 'listening',
-    'hold', 'resume', 'done', 'status', 'participants', 'inbox',
+    'done', 'status', 'participants', 'inbox',
 ]);
 /** Serialize the SDK receipt, not its optional presentation or live participant handle. */
 export function jsonResult(result) {

package/dist/cli/program.js

@@ -17,7 +17,7 @@ async function handleSquareError(error, context) {
         process.stderr.write(`${lines.join('\n')}\n`);
     else
         process.stderr.write(formatRefusal(squarePath, lines, {
-            participantCount: recovery?.standingCount, held: recovery?.held,
+            participantCount: recovery?.standingCount,
         }));
     process.exit(error.code === 'not_found' ? 1 : 2);
 }