@astrosheep/square 0.3.105 → 0.4.0

package/dist/channel-internal.js

@@ -0,0 +1,440 @@
+import crypto from 'node:crypto';
+import { openChannelArtifact, createChannelArtifactFile, createMemoryChannelArtifact, channelCourier } from './channel-artifact.js';
+import { canonicalPath } from './canonical-path.js';
+import { codexWakeAddress } from './codex-address.js';
+import { validateDeferralDuration, validateDeferralId, validateMetadataMatch } from './delivery-deferral.js';
+import { compileSearchPattern } from './search.js';
+import { InternalSquareError, SquareError } from './neutral.js';
+import { messageMetadataHasContent, sameName, validateMessageMetadata, validateName } from './channel-values.js';
+import { consumeReceived } from './receive.js';
+import { harnessOwner } from './owner.js';
+import { harnessSessionSources } from './participant-identity.js';
+import { formatMessageId, newEndpointGeneration, parseMessageId, validateEndpointGeneration } from './message.js';
+import { rememberSquarePath, squareIndexPath } from './square-index.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;
+}
+export function checkControl(control) {
+    if (control?.signal?.aborted)
+        throw control.signal.reason ?? new Error('Square operation was cancelled');
+}
+export function squareClock(env, clock) {
+    if (clock !== undefined)
+        return clock;
+    if (env.SQUARE_NOW_MS === undefined)
+        return Date.now;
+    const value = Number.parseInt(env.SQUARE_NOW_MS, 10);
+    if (!Number.isFinite(value))
+        throw new SquareError('invalid_args', 'Invalid SQUARE_NOW_MS: expected integer milliseconds.');
+    return () => value;
+}
+export function failure(error, detail) {
+    const normalized = error instanceof Error ? error : new Error(String(error), { cause: error });
+    Object.assign(normalized, { operation: detail });
+    return normalized;
+}
+function explicitLocation(input) {
+    if (typeof input?.path !== 'string' || input.path.trim() === '')
+        throw new SquareError('invalid_args', 'Channel path is required.');
+    return squareLocation(input);
+}
+function requireOwner(owner) {
+    if (typeof owner !== 'string' || !owner || Buffer.byteLength(owner, 'utf8') > 512 || /[\u0000-\u001f\u007f-\u009f]/u.test(owner))
+        throw new SquareError('invalid_args', 'A participant write requires a non-empty owner without control characters (at most 512 UTF-8 bytes).');
+    return owner;
+}
+/** A generic managed address must not displace the receiver's native registration on reconnect. */
+function canRefreshWakeAddress(current, proposed) {
+    return proposed.kind !== 'paseo' || current === undefined || current.kind === 'paseo';
+}
+/** Foundational point-to-point endpoint and messaging resource over one artifact port. */
+export class Channel {
+    location;
+    artifact;
+    clock;
+    deliverEffect;
+    indexPath;
+    closesArtifact;
+    constructor(location, artifact, clock, deliverEffect, indexPath, closesArtifact = true) {
+        this.location = location;
+        this.artifact = artifact;
+        this.clock = clock;
+        this.deliverEffect = deliverEffect;
+        this.indexPath = indexPath;
+        this.closesArtifact = closesArtifact;
+    }
+    /** Internal composition point for upper resources; no wrapping square is involved. */
+    static fromPort(init) {
+        return new Channel(init.location, init.artifact, init.clock, init.deliverEffect, init.indexPath, init.closesArtifact ?? true);
+    }
+    static async open(input, control) {
+        const path = explicitLocation(input);
+        const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env, path });
+        const clock = squareClock(env, input.clock);
+        const artifact = openChannelArtifact(location, control?.signal);
+        const transport = input.wakeTransport !== undefined
+            ? input.wakeTransport || undefined
+            : await import('./wake-transports.js').then(({ createDefaultWakeTransport }) => createDefaultWakeTransport(env)).catch(() => undefined);
+        try {
+            await artifact.read(facts => facts.header(), control?.signal);
+            const deliveryLocation = await canonicalPath(location);
+            return Channel.fromPort({ location, artifact, clock,
+                ...(transport === undefined ? {} : { deliverEffect: channelCourier(artifact, transport, deliveryLocation, clock) }),
+                indexPath: squareIndexPath(env) });
+        }
+        catch (error) {
+            await artifact.close();
+            if (error instanceof InternalSquareError && error.code === 'not_found')
+                throw new SquareError('unavailable', `Channel is unavailable at ${location}`);
+            throw error;
+        }
+    }
+    static async create(input, control) {
+        const path = explicitLocation(input);
+        const env = { ...(input.env ?? process.env) }, location = squareLocation({ ...input, env, path });
+        // Endpoints and messages carry no Agora chatroom warmup.
+        await createChannelArtifactFile(location, input.description ?? '# Channel\n', input.force ?? false, control?.signal);
+        return Channel.open({ ...input, path: location, env }, control);
+    }
+    static inMemory(input = {}) {
+        const env = { ...(input.env ?? process.env) };
+        const artifact = createMemoryChannelArtifact(input.description ?? '# Channel\n');
+        const location = `memory://${crypto.randomUUID()}`, clock = squareClock(env, input.clock);
+        const transport = input.wakeTransport || undefined;
+        return Channel.fromPort({ location, artifact, clock,
+            ...(transport === undefined ? {} : { deliverEffect: channelCourier(artifact, transport, location, clock) }) });
+    }
+    async remember(owner) {
+        if (this.indexPath !== undefined)
+            await rememberSquarePath(this.location, owner, this.indexPath).catch(() => undefined);
+    }
+    /** Establish a new opaque endpoint generation, or take over the existing one explicitly. */
+    async attach(name, options, control) {
+        checkControl(control);
+        validateName(name);
+        const owner = requireOwner(options?.owner);
+        const endpoint = (await this.artifact.transactAs({ kind: 'endpoint', participant: name, owner }, (facts) => {
+            const current = facts.endpoint(name);
+            if (current !== undefined && !options.takeover) {
+                if (current.owner !== owner)
+                    throw new SquareError('already_joined', `${name} is held by another owner; take it over explicitly.`);
+                if (current.attachment === 'detached')
+                    facts.reattachEndpoint(current, options.wakeAddress);
+                else if (options.wakeAddress !== undefined && canRefreshWakeAddress(current.wakeAddress, options.wakeAddress))
+                    facts.updateWakeAddress(current, options.wakeAddress);
+                return facts.endpoint(name);
+            }
+            const endpoint = { participant: name, owner, generation: newEndpointGeneration(), attachment: 'attached',
+                ...(options.wakeAddress === undefined ? {} : { wakeAddress: options.wakeAddress }) };
+            facts.storeEndpoint(endpoint);
+            return endpoint;
+        }, control?.signal)).value;
+        await this.remember(owner);
+        return new ChannelEndpoint(this, endpoint);
+    }
+    /** Restore an exact standing endpoint without changing its generation. */
+    async reattach(name, { owner, wakeAddress }, control) {
+        checkControl(control);
+        validateName(name);
+        requireOwner(owner);
+        const current = (await this.artifact.read(facts => facts.endpoint(name), control?.signal)).value;
+        if (current === undefined || current.owner !== owner)
+            return null;
+        return this.reattachEndpoint(current, wakeAddress, control);
+    }
+    async reattachEndpoint(current, wakeAddress, control) {
+        const endpoint = (await this.artifact.transactAs({ kind: 'endpoint', participant: current.participant, owner: current.owner }, (facts) => {
+            if (current.attachment === 'detached')
+                facts.reattachEndpoint(current, wakeAddress);
+            else if (wakeAddress !== undefined && canRefreshWakeAddress(current.wakeAddress, wakeAddress))
+                facts.updateWakeAddress(current, wakeAddress);
+            return facts.endpoint(current.participant);
+        }, control?.signal)).value;
+        return new ChannelEndpoint(this, endpoint);
+    }
+    /** Select one attached endpoint held by an exact owner. */
+    async endpoint(name, { owner }) {
+        validateName(name);
+        requireOwner(owner);
+        const endpoint = (await this.artifact.read(facts => {
+            const current = facts.endpoint(name);
+            if (current === undefined || current.owner !== owner || current.attachment !== 'attached') {
+                throw new SquareError('already_joined', current === undefined
+                    ? `${name} has no endpoint in this channel.`
+                    : current.owner !== owner ? `${name} is not held by this owner.` : `${name} is away.`, { reason: 'needs_seat' });
+            }
+            return current;
+        })).value;
+        return new ChannelEndpoint(this, endpoint);
+    }
+    async endpointsOf(owner) {
+        requireOwner(owner);
+        return (await this.artifact.read(facts => facts.endpointsForOwner(owner).map(({ participant, generation, attachment }) => ({ name: participant, generation, attachment })))).value;
+    }
+    async listEndpoints(control) {
+        checkControl(control);
+        return (await this.artifact.read(facts => facts.endpoints()
+            .map(endpoint => ({
+            name: endpoint.participant,
+            generation: endpoint.generation,
+            attachment: endpoint.attachment,
+            deliveryAvailable: endpoint.wakeAddress !== undefined,
+            unreadCount: facts.directedCount(endpoint.participant, { unseenOnly: true, currentGeneration: true }),
+        })), control?.signal)).value;
+    }
+    async detach(name, identity) {
+        const ref = { participant: name, ...identity };
+        const current = await this.held(name, ref);
+        if (current === undefined)
+            return null;
+        return (await this.artifact.transactAs({ kind: 'endpoint-cleanup', seat: ref }, facts => facts.detachEndpoint(ref) ? true : null)).value;
+    }
+    async cancelDeliveries(name, identity, control) {
+        const ref = { participant: name, ...identity };
+        const current = await this.held(name, ref);
+        if (current === undefined)
+            return false;
+        return (await this.artifact.transactAs({ kind: 'participant', seat: ref }, facts => {
+            const boundary = facts.header().lastMessageIndex;
+            return boundary < 0 ? false : facts.cancelThrough(ref, boundary);
+        }, control?.signal)).value;
+    }
+    async remove(name, identity) {
+        const ref = { participant: name, ...identity };
+        const current = await this.held(name, ref);
+        if (current === undefined)
+            return false;
+        return (await this.artifact.transactAs({ kind: 'endpoint-cleanup', seat: ref }, facts => facts.removeEndpoint(ref))).value;
+    }
+    async held(name, identity) {
+        const current = (await this.artifact.read(facts => facts.endpoint(name))).value;
+        return current?.generation === identity.generation && current.owner === identity.owner ? current : undefined;
+    }
+    /** Commit one message, then run the shared custody runner outside the transaction. */
+    async send(input, control) {
+        checkControl(control);
+        const { from } = input;
+        if (typeof from !== 'string')
+            throw new SquareError('invalid_args', 'Channel sender must be a name.');
+        validateName(from);
+        return this.sendAs({ kind: 'send', actor: from }, input, control);
+    }
+    async sendAs(authority, input, control) {
+        checkControl(control);
+        const { from, to, body, truncate = false } = input;
+        const targets = typeof to === 'string' ? [to] : to;
+        if (!Array.isArray(targets) || targets.length < 1 || targets.length > 10)
+            throw new SquareError('invalid_args', 'Channel needs between 1 and 10 recipients.');
+        const unique = [];
+        for (const target of targets) {
+            if (typeof target !== 'string')
+                throw new SquareError('invalid_args', 'Channel recipients must be names.');
+            validateName(target);
+            if (!unique.some(name => sameName(name, target)))
+                unique.push(target);
+        }
+        if (typeof body !== 'string' || body.trim() === '')
+            throw new SquareError('invalid_args', 'Channel body must be non-empty.');
+        if (truncate !== false && (!Number.isSafeInteger(truncate) || truncate < 1))
+            throw new SquareError('invalid_args', 'Channel truncate must be false or a positive integer.');
+        const fullBody = body.replace(/\r\n/g, '\n');
+        const preview = truncate !== false && fullBody.length > truncate
+            ? `${fullBody.slice(0, truncate).trimEnd()}… (truncated ${fullBody.length - truncate} chars)` : undefined;
+        const metadata = validateMessageMetadata(input.metadata);
+        const { published, addresses } = (await this.artifact.transactAs(authority, (facts) => {
+            const current = facts;
+            const resolved = unique.flatMap(target => { const endpoint = current.endpoint(target); return endpoint === undefined ? [] : [endpoint]; });
+            const missing = unique.filter(target => !resolved.some(endpoint => sameName(endpoint.participant, target)));
+            if (missing.length > 0)
+                throw new SquareError('invalid_args', `Channel recipients are not standing: ${missing.join(', ')}`, {
+                    reason: 'not_standing', targets: missing, activityUnsent: true,
+                });
+            const draft = { from, at: this.clock(), body: fullBody,
+                ...(messageMetadataHasContent(metadata) ? { metadata } : {}), ...(preview === undefined ? {} : { preview }),
+                // An ordinary Channel send captures no endpoint generation: the message survives takeover until consumed.
+                to: resolved.map(({ participant }) => ({ recipient: participant })) };
+            const published = current.publishMessage(draft);
+            return { published, addresses: current.addresses(published.index).map(address => address.recipient) };
+        }, control?.signal)).value;
+        await this.deliver(published.index);
+        return { id: formatMessageId(published.index), at: published.at, from, to: addresses, body: fullBody,
+            ...(published.metadata === undefined ? {} : { metadata: published.metadata }) };
+    }
+    /** Shared post-commit custody runner. */
+    async deliver(message) {
+        await this.deliverEffect?.(message).catch(() => undefined);
+    }
+    async history(query = {}, control) {
+        checkControl(control);
+        const limit = query.limit === undefined ? 100 : query.limit;
+        if (limit !== null && (!Number.isSafeInteger(limit) || limit < 1 || limit > 100))
+            throw new SquareError('invalid_args', 'History limit must be a positive integer no greater than 100.');
+        if (query.order !== undefined && query.order !== 'asc' && query.order !== 'desc')
+            throw new SquareError('invalid_args', 'History order must be asc or desc.');
+        const filter = {
+            ...(query.at === undefined ? {} : { indexes: query.at.map(requireMessageIndex) }),
+            ...(query.from === undefined ? {} : { senders: query.from }),
+            ...(query.match === undefined ? {} : { metadataMatch: validateMetadataMatch(query.match) }),
+            ...(query.search === undefined ? {} : { search: channelSearch(query.search) }),
+            ...(query.cursor === undefined ? {} : query.cursor.direction === 'after' ? { afterIndex: requireMessageIndex(query.cursor.id) } : { beforeIndex: requireMessageIndex(query.cursor.id) }),
+        };
+        return (await this.artifact.read(facts => {
+            const current = facts;
+            const count = current.messageCount(filter);
+            const page = current.messageHeads(filter, { edge: query.cursor?.direction === 'after' ? 'oldest' : 'newest', limit: limit ?? Math.max(1, count) });
+            const messages = page.items.map(item => channelMessage(item, current));
+            if (query.order === 'desc')
+                messages.reverse();
+            return { messages };
+        }, control?.signal)).value;
+    }
+    async close() {
+        if (this.closesArtifact)
+            await this.artifact.close();
+    }
+}
+function requireMessageIndex(id) {
+    const index = parseMessageId(id);
+    if (index === undefined)
+        throw new SquareError('invalid_args', `Invalid message id: ${id}`);
+    return index;
+}
+function channelMessage(item, facts) {
+    return { id: formatMessageId(item.index), at: item.at, from: item.from,
+        to: facts.addresses(item.index).map(address => address.recipient), body: item.body,
+        ...(item.metadata === undefined ? {} : { metadata: item.metadata }), ...(item.preview === undefined ? {} : { preview: item.preview }) };
+}
+function channelSearch(search) {
+    if (typeof search !== 'object' || search === null || typeof search.text !== 'string' || search.text === ''
+        || (search.mode !== 'literal' && search.mode !== 'regex') || Object.keys(search).some(key => key !== 'text' && key !== 'mode'))
+        throw new SquareError('invalid_args', 'Query search requires non-empty text and literal/regex mode.');
+    compileSearchPattern(search.text, search.mode === 'literal');
+    return { text: search.text, mode: search.mode };
+}
+function channelPendingSelection(options) {
+    const limit = options.limit === undefined ? 100 : options.limit;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+        throw new SquareError('invalid_args', 'Pending limit must be a positive integer no greater than 100.');
+    const filter = {
+        ...(options.at === undefined ? {} : { indexes: options.at.map(requireMessageIndex) }),
+        ...(options.from === undefined ? {} : { senders: options.from }),
+        ...(options.match === undefined ? {} : { metadataMatch: validateMetadataMatch(options.match) }),
+        ...(options.search === undefined ? {} : { search: channelSearch(options.search) }),
+        ...(options.cursor === undefined ? {} : options.cursor.direction === 'after' ? { afterIndex: requireMessageIndex(options.cursor.id) } : { beforeIndex: requireMessageIndex(options.cursor.id) }),
+        unseenOnly: true, currentGeneration: true,
+    };
+    return { limit, filter };
+}
+/** Captures one recipient endpoint through the channel's own storage, never a wrapped square. */
+export class ChannelEndpoint {
+    channel;
+    endpointFact;
+    constructor(channel, endpointFact) {
+        this.channel = channel;
+        this.endpointFact = endpointFact;
+    }
+    get name() { return this.endpointFact.participant; }
+    get generation() { return this.endpointFact.generation; }
+    get ref() { return this.endpointFact; }
+    get storage() { return this.channel.artifact; }
+    get participant() { return this.endpointFact.participant; }
+    async pending(options = {}, control) {
+        checkControl(control);
+        const { limit, filter } = channelPendingSelection(options);
+        return (await this.storage.read(facts => {
+            assertEndpoint(facts, this.endpointFact);
+            const page = facts.directed(this.participant, filter, { edge: 'oldest', limit });
+            const loaded = new Map(facts.messages(page.items.map(item => item.index)).map(item => [item.index, item]));
+            return { messages: page.items.flatMap(head => { const item = loaded.get(head.index); return item === undefined ? [] : [channelMessage(item, facts)]; }),
+                remaining: facts.directedCount(this.participant, filter) - page.items.length };
+        }, control?.signal)).value;
+    }
+    async ack(ids, control) {
+        checkControl(control);
+        if (!Array.isArray(ids))
+            throw new SquareError('invalid_args', 'Ack requires an array of message IDs.');
+        const indexes = [...new Set(Array.from(ids, requireMessageIndex))];
+        return (await this.storage.transactAs({ kind: 'participant', seat: this.endpointFact }, (facts) => {
+            for (const index of indexes) {
+                if (facts.directed(this.participant, { afterIndex: index - 1, throughIndex: index, currentGeneration: true }, { edge: 'oldest', limit: 1 }).items.length === 0)
+                    throw new SquareError('invalid_args', `${formatMessageId(index)} is not addressed to you.`, {
+                        reason: 'not_addressed', activityId: formatMessageId(index),
+                    });
+            }
+            return { consumed: facts.markSeen(this.participant, indexes, this.channel.clock()) };
+        }, control?.signal)).value;
+    }
+    /** Select and consume matching unconsumed messages in one transaction. */
+    async receive(options = {}, control) {
+        checkControl(control);
+        const { limit, filter } = channelPendingSelection(options);
+        return (await this.storage.transactAs({ kind: 'participant', seat: this.endpointFact }, (facts) => {
+            const lower = facts;
+            const consumed = consumeReceived({ heads: (recipient, query, page) => lower.directed(recipient, query, { edge: 'oldest', limit: page.limit }).items.map(item => ({ key: item.index, via: item })),
+                addressed: (recipient, index) => { const head = lower.directed(recipient, { indexes: [index] }, { edge: 'oldest', limit: 1 }).items[0]; return head === undefined ? undefined : { key: head.index, via: head }; },
+                load: (keys) => new Map(lower.messages(keys).map(item => [item.index, item])),
+                count: (recipient, query) => lower.directedCount(recipient, query), insertReceipt: (ref, at) => lower.markSeen(ref.recipient, [ref.item], at) > 0,
+            }, this.participant, { kind: 'page', query: filter, limit }, this.channel.clock());
+            return { messages: consumed.items.map(item => channelMessage(item.data, lower)),
+                consumed: consumed.newlyConsumed, remaining: consumed.remaining };
+        }, control?.signal)).value;
+    }
+    async deferDelivery(input, control) {
+        checkControl(control);
+        const match = validateMetadataMatch(input?.match), duration = validateDeferralDuration(input?.durationMs);
+        return (await this.storage.transactAs({ kind: 'participant', seat: this.endpointFact }, (facts) => {
+            const now = this.channel.clock(), expiresAt = now + duration, id = crypto.randomUUID();
+            const result = { id, expiresAt: new Date(expiresAt).toISOString() };
+            facts.putDeliveryDeferral(this.endpointFact, id, match, expiresAt, now);
+            return result;
+        }, control?.signal)).value;
+    }
+    async renewDeliveryDeferral(id, durationMs, control) {
+        checkControl(control);
+        validateDeferralId(id);
+        const duration = validateDeferralDuration(durationMs);
+        return (await this.storage.transactAs({ kind: 'participant', seat: this.endpointFact }, (facts) => {
+            const now = this.channel.clock(), expiresAt = now + duration;
+            const result = { id, expiresAt: new Date(expiresAt).toISOString() };
+            return facts.renewDeliveryDeferral(this.endpointFact, id, expiresAt, now) ? result : null;
+        }, control?.signal)).value;
+    }
+    async releaseDeliveryDeferral(id, control) {
+        checkControl(control);
+        validateDeferralId(id);
+        return (await this.storage.transactAs({ kind: 'participant', seat: this.endpointFact }, (facts) => facts.releaseDeliveryDeferral(this.endpointFact, id, this.channel.clock()), control?.signal)).value;
+    }
+    send(input, control) {
+        return this.channel.sendAs({ kind: 'participant', seat: this.endpointFact }, { ...input, from: this.participant }, control);
+    }
+    /** Standalone Channel retirement; it ends no Agora membership. */
+    async leave(control) {
+        checkControl(control);
+        const current = (await this.storage.read(facts => facts.endpoint(this.participant), control?.signal)).value;
+        if (current === undefined || current.owner !== this.endpointFact.owner || current.generation !== this.endpointFact.generation || current.attachment !== 'attached')
+            throw new SquareError('already_joined', 'This participant endpoint is not attached.');
+        await this.channel.remove(this.participant, { owner: this.endpointFact.owner, generation: this.endpointFact.generation });
+    }
+}
+function assertEndpoint(facts, expected) {
+    const current = facts.endpoint(expected.participant);
+    if (current === undefined || current.owner !== expected.owner || current.generation !== expected.generation)
+        throw new SquareError('already_joined', 'This participant endpoint has been replaced.');
+    if (current.attachment !== 'attached')
+        throw new SquareError('already_joined', 'This participant is away; attach again before writing.', { reason: 'needs_seat', activityUnsent: true });
+}
+export { validateEndpointGeneration };

package/dist/channel-metadata.d.ts

@@ -0,0 +1,11 @@
+export type MetadataScalar = null | boolean | number | string;
+export interface MetadataMatch {
+    readonly fields: readonly Readonly<{
+        path: readonly string[];
+        equals: MetadataScalar;
+    }>[];
+}
+export interface DeliveryDeferral {
+    readonly id: string;
+    readonly expiresAt: string;
+}

package/dist/channel-metadata.js

@@ -0,0 +1 @@
+export {};