@astrosheep/square 0.3.92 → 0.3.94

package/dist/harness-links.js

@@ -1,79 +1,10 @@
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { isDeepStrictEqual } from 'node:util';
 import crossSpawn from 'cross-spawn';
+import { applyEdits, createScanner, findNodeAtLocation, modify, parse, parseTree } from 'jsonc-parser';
 import { SQUARE_IDENTITY } from './identity.js';
 import { truncateExternalDiagnostic } from './presentation.js';
-function packageRoot() {
-    // Emitted modules live in dist; package assets are one level above them.
-    return fileURLToPath(new URL('../', import.meta.url));
-}
-export function installHarnessLinks(links, force = false) {
-    const prepared = links.map((link) => {
-        if (!fs.existsSync(link.source)) {
-            throw new Error(`Harness link source is missing: ${link.source}`);
-        }
-        const existing = (() => {
-            try {
-                return fs.lstatSync(link.target);
-            }
-            catch (error) {
-                if (error.code === 'ENOENT')
-                    return undefined;
-                throw error;
-            }
-        })();
-        return {
-            ...link,
-            existing,
-            sourceIsDirectory: fs.statSync(link.source).isDirectory(),
-            alreadyManaged: existing !== undefined && sameLink(link.source, link.target),
-        };
-    });
-    for (const { target, existing, alreadyManaged } of prepared) {
-        if (existing !== undefined && !alreadyManaged && !force)
-            throw new Error(`Refusing to overwrite existing link: ${target}\nPass -f to replace it.`);
-    }
-    for (const { source, target, existing, sourceIsDirectory, alreadyManaged } of prepared) {
-        if (alreadyManaged)
-            continue;
-        fs.mkdirSync(path.dirname(target), { recursive: true });
-        if (existing !== undefined)
-            fs.rmSync(target, { recursive: true, force: true });
-        const symlinkType = os.platform() === 'win32' && sourceIsDirectory ? 'junction' : 'file';
-        fs.symlinkSync(source, target, symlinkType);
-    }
-    return prepared.map(({ target }) => target);
-}
-function sameLink(source, target) {
-    try {
-        return fs.realpathSync(source) === fs.realpathSync(target);
-    }
-    catch {
-        return false;
-    }
-}
-export function uninstallHarnessLinks(links) {
-    const removed = [];
-    for (const link of links) {
-        try {
-            if (fs.lstatSync(link.target).isSymbolicLink() && sameLink(link.source, link.target)) {
-                fs.rmSync(link.target, { force: true });
-                removed.push(link.target);
-            }
-        }
-        catch {
-            // A missing or user-owned target is preserved.
-        }
-    }
-    return removed;
-}
-export function doctorHarnessLinks(links) {
-    return links.map((link) => sameLink(link.source, link.target)
-        ? `✓ Square ${link.kind ?? 'link'} ${link.target}`
-        : `○ Square ${link.kind ?? 'link'} missing ${link.target}`);
-}
 function runOpenCode(homeDir, args) {
     const prefix = (() => {
         try {
@@ -94,39 +25,150 @@ function runOpenCode(homeDir, args) {
     return { status: result.status ?? 1, stdout: result.stdout || '', stderr: result.stderr || '' };
 }
 export function installOpenCodePlugin(homeDir, force = false, run = runOpenCode) {
-    // OpenCode v2's `plugin add` is idempotent and has no --global/--force flags.
+    // Explicit `square install` replaces owned pins/duplicates with one unpinned
+    // current-field entry; updating an exact old pin otherwise succeeds unchanged.
     void force;
-    const args = ['plugin', 'add', SQUARE_IDENTITY.packageName];
+    const configs = readOpenCodeConfigs(homeDir);
+    const entries = configs.flatMap((config) => config.entries);
+    const options = entries.map((entry) => entry.options).filter((value) => value !== undefined);
+    if (options.some((value) => !isDeepStrictEqual(value, options[0]))) {
+        throw new Error('Conflicting Square plugin options in OpenCode configuration; reconcile the owned plugin/plugins entries before installing.');
+    }
+    const canonical = options.length ? { package: SQUARE_IDENTITY.packageName, options: options[0] } : SQUARE_IDENTITY.packageName;
+    const targets = configs.length ? configs : [{ target: openCodeConfigPaths(homeDir)[0], source: '{}', entries: [] }];
+    const alreadyCanonical = entries.length === 1 && configs[0]?.entries[0]?.field === 'plugins'
+        && isDeepStrictEqual(entries[0].value, canonical);
+    const changes = alreadyCanonical ? [] : targets.map(({ target, source, entries }, index) => {
+        let next = source;
+        for (const { field, index } of entries.toReversed())
+            next = removeOpenCodeEntry(next, field, index);
+        if (index === 0)
+            next = applyEdits(next, modify(next, ['plugins', -1], canonical, {}));
+        return { target, source, next };
+    }).filter(({ source, next }) => source !== next);
+    // Appending just our element avoids native add's whole-array rewrite, which
+    // drops comments belonging to unrelated plugins. Native add still owns npm.
+    for (const { target, next } of changes) {
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, next);
+    }
+    if (!entries.some(({ spec }) => spec === SQUARE_IDENTITY.packageName)) {
+        try {
+            openCodeCommand(homeDir, ['plugin', 'add', SQUARE_IDENTITY.packageName], run, 'install');
+        }
+        catch (error) {
+            // Undo only our preparation, never files the native command/user changed.
+            for (const { target, source, next } of changes) {
+                if (fs.existsSync(target) && fs.readFileSync(target, 'utf8') === next) {
+                    if (configs.length)
+                        fs.writeFileSync(target, source);
+                    else
+                        fs.rmSync(target);
+                }
+            }
+            throw error;
+        }
+    }
+    // Even add can reuse an older cached package. Always request the latest.
+    openCodeCommand(homeDir, ['plugin', 'update', SQUARE_IDENTITY.packageName], run, 'update');
+    return [SQUARE_IDENTITY.packageName];
+}
+function openCodeCommand(homeDir, args, run, operation) {
     const result = run(homeDir, args);
     if (result.status !== 0)
-        throw new Error(`OpenCode plugin install failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`}`);
-    return [SQUARE_IDENTITY.packageName];
+        throw new Error(`OpenCode ${operation} failed: ${result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`}`);
+    return result.stdout;
 }
-function configPath(homeDir) {
+function openCodeConfigPaths(homeDir) {
     const configHome = process.env.XDG_CONFIG_HOME ?? path.join(homeDir, '.config');
-    return path.join(configHome, 'opencode', 'opencode.jsonc');
+    const root = path.resolve(configHome, 'opencode');
+    return [root, path.join(root, '.opencode')].flatMap((directory) => ['opencode.json', 'opencode.jsonc'].map((name) => path.join(directory, name)));
+}
+function readOpenCodeConfigs(homeDir) {
+    return openCodeConfigPaths(homeDir).flatMap((target) => {
+        let source;
+        try {
+            source = fs.readFileSync(target, 'utf8');
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return [];
+            throw error;
+        }
+        const errors = [];
+        const config = parse(source, errors, { allowTrailingComma: true });
+        if (errors.length || typeof config !== 'object' || config === null || Array.isArray(config)) {
+            throw new Error(`Invalid OpenCode configuration: ${target}`);
+        }
+        const entries = ['plugin', 'plugins'].flatMap((field) => {
+            const plugins = config[field];
+            if (plugins === undefined)
+                return [];
+            if (!Array.isArray(plugins))
+                throw new Error(`Invalid OpenCode ${field} configuration: ${target}`);
+            return plugins.flatMap((entry, index) => {
+                const spec = openCodePluginSpec(entry);
+                const options = Array.isArray(entry) ? entry[1]
+                    : typeof entry === 'object' && entry !== null ? entry.options : undefined;
+                return spec === undefined ? [] : [{ field, index, spec, options, value: entry }];
+            });
+        });
+        return [{ target, source, entries }];
+    });
 }
-function removeConfiguredPlugin(homeDir) {
-    const target = configPath(homeDir);
-    let source;
+export function uninstallOpenCodePlugin(homeDir) {
+    // Native remove only handles `plugins` in one file. Delete our elements in
+    // both fields/files, from the end so indexes remain stable, keeping JSONC.
+    const changes = readOpenCodeConfigs(homeDir).filter(({ entries }) => entries.length).map(({ target, source, entries }) => {
+        for (const { field, index } of entries.reverse()) {
+            source = removeOpenCodeEntry(source, field, index);
+        }
+        return { target, source };
+    });
+    for (const { target, source } of changes)
+        fs.writeFileSync(target, source);
+    return changes.length ? [SQUARE_IDENTITY.packageName] : [];
+}
+// jsonc-parser's array `modify` also removes intervening comments. Use its AST
+// and scanner to remove only the owned value and one separator, not the trivia.
+function removeOpenCodeEntry(source, field, index) {
+    const array = findNodeAtLocation(parseTree(source), [field]);
+    const node = array.children[index];
+    const scanner = createScanner(source, true);
+    scanner.setPosition(node.offset + node.length);
+    let comma = scanner.scan() === 5 /* SyntaxKind.CommaToken */ ? scanner.getTokenOffset() : undefined;
+    if (comma === undefined && index > 0) {
+        const previous = array.children[index - 1];
+        scanner.setPosition(previous.offset + previous.length);
+        if (scanner.scan() === 5 /* SyntaxKind.CommaToken */)
+            comma = scanner.getTokenOffset();
+    }
+    return applyEdits(source, [
+        { offset: node.offset, length: node.length, content: '' },
+        ...(comma === undefined ? [] : [{ offset: comma, length: 1, content: '' }]),
+    ]);
+}
+function openCodePluginSpec(entry) {
+    const spec = typeof entry === 'string' ? entry : Array.isArray(entry) ? entry[0]
+        : typeof entry === 'object' && entry !== null && 'package' in entry ? entry.package : undefined;
+    return typeof spec === 'string' && (spec === SQUARE_IDENTITY.packageName || spec.startsWith(`${SQUARE_IDENTITY.packageName}@`))
+        ? spec : undefined;
+}
+function parseOpenCodeConfig(stdout) {
+    let sources;
     try {
-        source = fs.readFileSync(target, 'utf8');
+        sources = JSON.parse(stdout);
     }
     catch {
-        return false;
+        throw new Error('OpenCode debug config returned invalid JSON');
     }
-    const escaped = SQUARE_IDENTITY.packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const packageLine = new RegExp(`^\\s*"${escaped}(?:@[^"\\n]+)?"\\s*,?\\s*$`, 'm');
-    const next = source.replace(packageLine, '');
-    if (next === source)
-        return false;
-    fs.writeFileSync(target, next);
-    return true;
-}
-export function uninstallOpenCodePlugin(homeDir) {
-    return removeConfiguredPlugin(homeDir) ? [SQUARE_IDENTITY.packageName] : [];
+    if (!Array.isArray(sources) || sources.some((source) => source === null || typeof source !== 'object'
+        || !['document', 'directory'].includes(source.type))) {
+        throw new Error('OpenCode debug config returned unexpected configuration sources');
+    }
+    return sources;
 }
-/** Verify that OpenCode accepts its resolved runtime configuration after links are installed. */
+/** Config sources prove configuration, not that a running session loaded the plugin. */
 export function verifyOpenCodeRuntime(homeDir, run = runOpenCode) {
     try {
         const result = run(homeDir, ['debug', 'config']);
@@ -134,28 +176,21 @@ export function verifyOpenCodeRuntime(homeDir, run = runOpenCode) {
             const diagnostic = result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`;
             return `✕ OpenCode debug config failed: ${truncateExternalDiagnostic(diagnostic)}`;
         }
-        let config;
+        let sources;
         try {
-            config = JSON.parse(result.stdout);
+            sources = parseOpenCodeConfig(result.stdout);
         }
-        catch {
-            return '✕ OpenCode debug config returned invalid JSON';
+        catch (error) {
+            return `✕ ${error.message}`;
         }
-        const plugin = config.config?.plugin;
-        const expected = SQUARE_IDENTITY.packageName;
-        if (Array.isArray(plugin) && plugin.includes(expected))
-            return '✓ OpenCode npm plugin loaded';
-        return `○ OpenCode npm plugin not loaded: ${expected}`;
+        const configured = sources.some((source) => source.type === 'document'
+            && Array.isArray(source.info?.plugins) && source.info.plugins.some((entry) => openCodePluginSpec(entry) !== undefined));
+        return configured
+            ? '✓ OpenCode npm plugin configured (runtime loading not verified)'
+            : `○ OpenCode npm plugin not configured: ${SQUARE_IDENTITY.packageName}`;
     }
     catch (error) {
         const diagnostic = error instanceof Error ? error.message : String(error);
         return `○ OpenCode runtime unavailable (${truncateExternalDiagnostic(diagnostic)})`;
     }
 }
-export function skillLinks(homeDir = os.homedir(), parents = ['.claude', '.agents']) {
-    return parents.flatMap((parent) => ['square'].map((name) => ({
-        source: path.join(packageRoot(), 'skills', name),
-        target: path.join(homeDir, parent, 'skills', name),
-        kind: 'skill',
-    })));
-}

package/dist/harness.js

@@ -5,7 +5,7 @@ import { truncateExternalDiagnostic } from './presentation.js';
 import { doctorClaudePlugin, installClaudePlugin, uninstallClaudePlugin, } from './harness-claude.js';
 import { doctorCodexPlugin, installCodexPlugin, uninstallCodexPlugin, } from './harness-codex.js';
 import { doctorPiPackage, installPiPackage, uninstallPiPackage, } from './harness-pi.js';
-import { doctorHarnessLinks, installHarnessLinks, installOpenCodePlugin, skillLinks, uninstallOpenCodePlugin, uninstallHarnessLinks, verifyOpenCodeRuntime, } from './harness-links.js';
+import { installOpenCodePlugin, uninstallOpenCodePlugin, verifyOpenCodeRuntime, } from './harness-links.js';
 function result(lines, notes = []) {
     return { lines, notes };
 }
@@ -18,9 +18,6 @@ async function doctorHost(label, inspect) {
         return result([`○ ${label} doctor unavailable (${truncateExternalDiagnostic(diagnostic)})`]);
     }
 }
-function openCodeLinks(homeDir) {
-    return skillLinks(homeDir, ['.agents']);
-}
 function readableSquarePath(squarePath) {
     if (squarePath === undefined)
         return false;
@@ -67,15 +64,9 @@ const TARGETS = [
     {
         name: 'opencode',
         capabilities: ['install', 'uninstall', 'doctor'],
-        install: async ({ homeDir, force }) => result([
-            ...installOpenCodePlugin(homeDir, force),
-            ...installHarnessLinks(openCodeLinks(homeDir), force),
-        ]),
-        uninstall: ({ homeDir }) => result([
-            ...uninstallOpenCodePlugin(homeDir),
-            ...uninstallHarnessLinks(openCodeLinks(homeDir)),
-        ]),
-        doctor: ({ homeDir }) => result([verifyOpenCodeRuntime(homeDir), ...doctorHarnessLinks(openCodeLinks(homeDir))]),
+        install: ({ homeDir, force }) => result(installOpenCodePlugin(homeDir, force)),
+        uninstall: ({ homeDir }) => result(uninstallOpenCodePlugin(homeDir)),
+        doctor: ({ homeDir }) => result([verifyOpenCodeRuntime(homeDir)]),
     },
     {
         name: 'pi',

package/dist/help.js

@@ -1,3 +1,4 @@
+import { JSON_COMMANDS } from './cli/json.js';
 const COMMANDS = [
     { names: ['help'], usage: 'help [command]', summary: 'Show the command index or help for one command.' },
     { names: ['version'], usage: 'version', summary: 'Print the installed version.', hiddenFromIndex: true },
@@ -52,9 +53,9 @@ const COMMANDS = [
         details: ['Options:', '  --ndjson       Emit one JSON event per line.', '  --for <name>   With --ndjson, emit notifications for one participant.', '  --last <N>     Emit the last N eligible activities first (default 10, maximum 100).', '  --after <id>   Resume after a canonical activity id (act/12).'],
     },
     {
-        names: ['inbox'], usage: 'inbox --for-session <session-id> [--limit <N>] [--json]', hiddenFromIndex: true,
+        names: ['inbox'], usage: 'inbox --for-owner <owner> [--limit <N>]', hiddenFromIndex: true,
         summary: 'Inspect a bounded machine-local notification snapshot for a native session.',
-        details: ['Options:', '  --for-session <id>  Required harness session id.', '  --limit <N>         Snapshot memberships (default 20, maximum 100).', '  --json              Emit the bounded snapshot as structured JSON.'],
+        details: ['Options:', '  --for-owner <id>    Required opaque owner.', '  --limit <N>         Snapshot memberships (default 20, maximum 100).'],
     },
     { names: ['codex-hook'], usage: '{command}', summary: 'Present pending attention at one native agent boundary.', hiddenFromIndex: true },
     { names: ['claude-mod'], usage: '{command}', summary: 'Receive a structured operation from the loaded Claude mod.', hiddenFromIndex: true },
@@ -67,7 +68,7 @@ const COMMANDS = [
     {
         names: ['participants'], usage: 'participants [--limit <count>]', usesSquare: true, group: 'host',
         summary: 'Show the participant roster and current states.',
-        details: ['Options:', '  --limit <count>  Show the first count names in roster order (default 20, maximum 100).'],
+        details: ['Options:', '  --limit <count>  Show the first count names in human text (default 20, maximum 100).'],
     },
     { names: ['hold'], usage: '--as <name> hold [reason | -]', usesSquare: true, group: 'participant', summary: 'Raise a hand and pause participant activity.' },
     { names: ['resume'], usage: '--as <name> resume', usesSquare: true, group: 'participant', summary: 'Lower the raised hand and resume activity.' },
@@ -93,7 +94,7 @@ const COMMANDS = [
     {
         names: ['migrate'], usage: 'migrate', usesSquare: true, group: 'maintenance',
         summary: 'Convert a supported older square to the current format in place.',
-        details: ['For the selected .square artifact only. Stop sessions using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'Versions 2, 3 and 4 are accepted; version 1, unrelated or unsupported artifacts are refused without a write. Names whose own owner and route evidence agrees may share a body; names with missing or conflicting ownership stay standing without write or delivery authority. Migration reports recovered seats, unowned standing names, shared-body seats and skipped evidence. There is no --check, --backup or --force.'],
+        details: ['For the selected .square artifact only. Stop sessions using this artifact before conversion. Back up the stopped artifact, migrate it, then run square --location <path> doctor before starting updated clients.', 'Versions 2–6 migrate explicitly to format 7; format 6 attachment is preserved and Body coordinates become opaque owners. Versions 4/5 first gain attached seats; 4 also gains empty deferrals. Version 1, unrelated or unsupported artifacts refuse without a write. Names whose legacy owner and routes agree may share an owner; ambiguous names stay standing without custody. Rejoin with the same owner after migration to republish discovery. There is no --check, --backup or --force.'],
     },
 ];
 function definitionFor(command) {
@@ -117,10 +118,11 @@ export function renderGlobalHelp() {
         '',
     ]);
     return [
-        'Usage: square [--location <square>] [--as <name>] <command> [args...]',
-        'Environment: SQUARE_LOCATION sets the CLI location (local artifact path or stdio://name/key); square-accessing commands require it or --location. Use --as to select a participant.',
-        'Backends: SQUARE_BACKENDS_CONFIG selects {backends:{name:{command,args?,cwd?,env?}}}; default ~/.config/square/backends.json. See guides/backends.md.',
-        'CLI flags override environment values. Participants join explicitly; no square is joined automatically.',
+        'Usage: square [--location <square>] [--as <name>] [--owner <id>] <command> [args...]',
+        'Environment: SQUARE_LOCATION sets the CLI local artifact path; square-accessing commands require it or --location. Use --as to select a participant.',
+        'Identity: --owner overrides SQUARE_OWNER, then a complete harness identity, then user:<OS user>@<host>. Incomplete or ambiguous harness identities refuse. Owners without wake use catch --idle.',
+        'Output: --json on join, express, catch, history, listen, ignore, unlisten, listening, hold, resume, done, status, participants and inbox prints the SDK result without observation; a participant handle becomes {name}.',
+        'History emits one JSON document; stream --ndjson emits one SDK record per line.',
         '',
         ...commandLines,
         "Run 'square <command> --help' for command options.",
@@ -132,7 +134,7 @@ export function renderSubcommandHelp(command) {
     if (definition === undefined)
         return undefined;
     const aliases = definition.names.filter((name) => name !== command);
-    const usage = definition.usage.replace('{command}', command);
+    const usage = definition.usage.replace('{command}', command) + (JSON_COMMANDS.has(command) ? ' [--json]' : '');
     return [
         `Usage: square ${definition.usesSquare ? '[--location <square>] ' : ''}${usage}`,
         ...(aliases.length > 0 ? [`Aliases: ${aliases.join(', ')}`] : []),
@@ -151,7 +153,7 @@ export function helpRequest(rawArgs) {
     const args = [];
     for (let index = 0; index < rawArgs.length; index++) {
         const arg = rawArgs[index];
-        if (arg === '--location' || arg === '--as') {
+        if (arg === '--location' || arg === '--as' || arg === '--owner') {
             const value = rawArgs[index + 1];
             if (value === undefined || value.startsWith('--'))
                 return undefined;

package/dist/inbox.d.ts

@@ -1,4 +1,4 @@
-import { type Body, type LocatedSeat, type PendingMembership } from './model.js';
+import { type Owner, type LocatedSeat, type PendingMembership } from './model.js';
 import type { SquareRead } from './ports.js';
 export interface PendingWaitOptions {
     signal?: AbortSignal;
@@ -14,15 +14,12 @@ export declare function pendingAtBoundary(inbox: readonly PendingMembership[]):
 export declare function projectBoundaryEligibility(inbox: readonly PendingMembership[]): Promise<PendingMembership[]>;
 export interface SessionBindingCandidate {
     readonly location: string;
-    readonly body: Body;
+    readonly owner: Owner;
 }
 /** HOME is a candidate path index; current seats and delivery evidence live in the artifact. */
 export declare function projectSessionCandidates(input: SessionSeatQuery): Promise<readonly SessionBindingCandidate[]>;
 export interface SessionSeatQuery {
-    readonly body?: Body;
-    readonly sessionId?: string;
-    readonly channel?: string;
-    readonly agent?: string;
+    readonly owner?: Owner;
     readonly location?: string;
     readonly env?: NodeJS.ProcessEnv;
 }
@@ -36,31 +33,21 @@ export interface NativePendingPreview {
 }
 export type NativePendingPreviewInput = {
     readonly location: string;
-    readonly sessionId: string;
+    readonly generation: import('./model.js').ActivityId;
     readonly participant: string;
     readonly actIndex: number;
     readonly cancelledThrough?: number;
     readonly now: number;
 } & ({
     readonly routeKind: 'claude-native';
-    readonly address: {
-        readonly endpoint: string;
-    };
+    readonly address: Readonly<Record<string, string>>;
 } | {
     readonly routeKind: 'opencode-server';
-    readonly address: {
-        readonly sessionId: string;
-    };
+    readonly address: Readonly<Record<string, string>>;
 });
-/** First matching current seat, exact body/generation/address and catch ownership. */
+/** Current-generation native attention, owned by its exact wake address and catch state. */
 export declare function nativePendingPreview(facts: SquareRead, input: NativePendingPreviewInput): NativePendingPreview | undefined;
-export interface SessionIdentityQuery {
-    readonly channel: string;
-    readonly session: string;
-    readonly allAgents?: true;
-}
-export type SessionIdentity = Body | SessionIdentityQuery;
-export declare function sessionInbox(identity: SessionIdentity, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<PendingMembership[]>;
+export declare function sessionInbox(owner: Owner, env?: NodeJS.ProcessEnv, signal?: AbortSignal): Promise<PendingMembership[]>;
 export interface SessionPendingObserver {
     /** Read committed revisions before reusing content; filesystem hints are only for waiting. */
     read(options?: Pick<PendingWaitOptions, 'signal' | 'excludeKeys'>): Promise<PendingMembership[]>;
@@ -68,4 +55,4 @@ export interface SessionPendingObserver {
     close(): void;
 }
 /** Session-scoped projection over process-shared storage change detectors. */
-export declare function observeSessionPending(identity: SessionIdentity, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;
+export declare function observeSessionPending(owner: Owner, suppliedEnv?: NodeJS.ProcessEnv): Promise<SessionPendingObserver>;

package/dist/inbox.js

@@ -1,4 +1,3 @@
-import { sameBody } from './model.js';
 import { createArtifactPort, observeSquareDeliveryRevision, observeSquareRevision } from './artifact.js';
 import { indexedSquareEntries, observeSquareIndex } from './square-index.js';
 import { canonicalPath } from './canonical-path.js';
@@ -20,8 +19,8 @@ export function pendingAtBoundary(inbox) {
 }
 function eligibleNotifications(facts, membership, now = Date.now()) {
     const seat = facts.seat(membership.seat.participant);
-    if (seat === undefined || seat.generation !== membership.seat.generation
-        || !sameBody(seat.body, membership.seat.body))
+    if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== membership.seat.generation
+        || seat.owner !== membership.seat.owner)
         return { notifications: [] };
     const cancelledThrough = facts.cancelledThrough(seat.participant, seat.generation);
     let expiry = Infinity;
@@ -68,22 +67,22 @@ export async function projectBoundaryEligibility(inbox) {
 /** HOME is a candidate path index; current seats and delivery evidence live in the artifact. */
 export async function projectSessionCandidates(input) {
     const location = input.location === undefined ? undefined : await canonicalPath(input.location);
-    const entries = await indexedSquareEntries({ body: input.body, session: input.sessionId, channel: input.channel, agent: input.agent }, input.env ?? process.env);
+    const entries = await indexedSquareEntries({ owner: input.owner }, input.env ?? process.env);
     const candidates = new Map();
     for (const entry of entries) {
         if (location !== undefined && location !== entry.location)
             continue;
-        const key = JSON.stringify([entry.location, entry.body.channel, entry.body.session, entry.body.agent ?? null]);
-        candidates.set(key, { location: entry.location, body: entry.body });
+        const key = JSON.stringify([entry.location, entry.owner]);
+        candidates.set(key, { location: entry.location, owner: entry.owner });
     }
     return [...candidates.values()];
 }
 function groupCandidates(candidates) {
     const grouped = new Map();
-    for (const { location, body } of candidates) {
-        const bodies = grouped.get(location) ?? [];
-        bodies.push(body);
-        grouped.set(location, bodies);
+    for (const { location, owner } of candidates) {
+        const owners = grouped.get(location) ?? [];
+        owners.push(owner);
+        grouped.set(location, owners);
     }
     return grouped;
 }
@@ -97,11 +96,11 @@ function locatedSeats(facts, location, seats) {
 /** Lifecycle reads resolve seats and join times, never pending activity bodies. */
 export async function projectSessionSeats(input, signal) {
     const seats = [];
-    for (const [location, bodies] of groupCandidates(await projectSessionCandidates(input))) {
+    for (const [location, owners] of groupCandidates(await projectSessionCandidates(input))) {
         signal?.throwIfAborted();
         const artifact = createArtifactPort(location, undefined, signal);
         try {
-            seats.push(...(await artifact.read(facts => locatedSeats(facts, location, bodies.flatMap(body => facts.seatsForBody(body))), signal)).value);
+            seats.push(...(await artifact.read(facts => locatedSeats(facts, location, owners.flatMap(owner => facts.seatsForOwner(owner))), signal)).value);
         }
         catch (error) {
             if (signal?.aborted)
@@ -116,11 +115,11 @@ export async function projectSessionSeats(input, signal) {
 /** Public count boundary: one coherent read per artifact, without pending body hydration. */
 export async function sessionInboxCounts(input, signal) {
     const rows = [];
-    for (const [location, bodies] of groupCandidates(await projectSessionCandidates(input))) {
+    for (const [location, owners] of groupCandidates(await projectSessionCandidates(input))) {
         signal?.throwIfAborted();
         const artifact = createArtifactPort(location, undefined, signal);
         try {
-            rows.push(...(await artifact.read(facts => locatedSeats(facts, location, bodies.flatMap(body => facts.seatsForBody(body))).map(({ seat }) => ({
+            rows.push(...(await artifact.read(facts => locatedSeats(facts, location, owners.flatMap(owner => facts.seatsForOwner(owner).filter(seat => seat.attachment === 'attached'))).map(({ seat }) => ({
                 name: seat.participant, squarePath: location, pending: facts.directedCount(seat.participant, { unseenOnly: true }),
             })), signal)).value);
         }
@@ -137,13 +136,13 @@ export async function sessionInboxCounts(input, signal) {
 /** One authoritative read per canonical artifact, even when discovery names several bodies. */
 async function projectPending(candidates, cache, signal) {
     const pending = [];
-    for (const [location, bodies] of groupCandidates(candidates)) {
+    for (const [location, owners] of groupCandidates(candidates)) {
         signal?.throwIfAborted();
         const artifact = createArtifactPort(location, undefined, signal);
         try {
             const { value: current } = await artifact.read(facts => {
-                const seats = bodies.flatMap(body => facts.seatsForBody(body));
-                const coordinate = JSON.stringify([bodies, seats.map(seat => [seat.participant, seat.body, seat.generation])]);
+                const seats = owners.flatMap(owner => facts.seatsForOwner(owner).filter(seat => seat.attachment === 'attached'));
+                const coordinate = JSON.stringify([owners, seats.map(seat => [seat.participant, seat.owner, seat.generation])]);
                 const header = facts.header();
                 let cached = cache?.get(location);
                 if (cached?.coordinate !== coordinate || cached.version !== header.revision) {
@@ -177,14 +176,14 @@ async function projectPending(candidates, cache, signal) {
     return pending;
 }
 function sameWakeAddress(address, kind, requested) {
-    if (address?.kind !== kind)
+    if (address?.kind !== kind || Object.keys(address.address).length !== Object.keys(requested).length)
         return false;
     return Object.entries(requested).every(([key, value]) => address.address[key] === value);
 }
-/** First matching current seat, exact body/generation/address and catch ownership. */
+/** Current-generation native attention, owned by its exact wake address and catch state. */
 export function nativePendingPreview(facts, input) {
     const seat = facts.seat(input.participant);
-    if (seat === undefined || seat.body.session !== input.sessionId
+    if (seat === undefined || seat.attachment !== 'attached' || seat.generation !== input.generation
         || !sameWakeAddress(seat.wakeAddress, input.routeKind, input.address))
         return undefined;
     const cancelledThrough = facts.cancelledThrough(seat.participant, seat.generation);
@@ -200,10 +199,8 @@ export function nativePendingPreview(facts, input) {
     return { payload: renderSquareReminder([renderAttentionPreview({ squarePath: input.location, recipient: input.participant, actIndex: item.index,
                 actor: item.actor, route: head.route, body: item.body ?? '(structured activity)' })]), clipped: attentionBodyIsClipped(item.body ?? '(structured activity)') };
 }
-export async function sessionInbox(identity, env = process.env, signal) {
-    const query = 'allAgents' in identity ? { channel: identity.channel, sessionId: identity.session, env }
-        : { body: identity, env };
-    return projectPending(await projectSessionCandidates(query), undefined, signal);
+export async function sessionInbox(owner, env = process.env, signal) {
+    return projectPending(await projectSessionCandidates({ owner, env }), undefined, signal);
 }
 async function capture(observer, kind, signal) {
     const generation = observer.generation;
@@ -234,10 +231,9 @@ async function capture(observer, kind, signal) {
     }
 }
 /** Session-scoped projection over process-shared storage change detectors. */
-export async function observeSessionPending(identity, suppliedEnv = process.env) {
+export async function observeSessionPending(owner, suppliedEnv = process.env) {
     const env = { ...suppliedEnv };
-    const query = 'allAgents' in identity ? { channel: identity.channel, sessionId: identity.session, env }
-        : { body: identity, env };
+    const query = { owner, env };
     const index = await observeSquareIndex(env);
     const artifacts = new Map();
     const cache = new Map();

package/dist/index.d.ts

@@ -1,8 +1,6 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
+export { selectOwnSeat, requireOwner, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';
 export type { WakeTransportPort, WakeRequest, WakeOutcome } from './ports.js';
 export type { WakeTransports } from './notifications.js';
-export { createDefaultWakeTransport } from './notifications.js';
-export type { PresentationSinkPort } from './ports.js';
-export type * from './square-backend.js';
 export type * from './square-facade.js';

package/dist/index.js

@@ -1,3 +1,3 @@
 export { Square, squareLocation, squareClock, createSquareResourceOwner, discover, inbox, diagnoseSquare, migrateSquare } from './square-api.js';
 export { SquareError, ACTIVITY_METADATA_MAX_BYTES } from './model.js';
-export { createDefaultWakeTransport } from './notifications.js';
+export { selectOwnSeat, requireOwner, localUserOwner, harnessOwner, decodeHarnessOwner } from './square-api.js';

package/dist/mcp.d.ts

@@ -1,7 +1,10 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Owner } from './square-api.js';
 import type { SquareAtInput } from './square-facade.js';
 /** The server owns its artifact connection lifetime, so callers cannot lend one. */
 export interface SquareMcpOptions extends Omit<SquareAtInput, 'resources'> {
+    readonly owner?: Owner;
+    readonly wakeAddress?: import('./model.js').WakeAddress;
 }
 export type SquareMcpServer = McpServer;
 export declare function createSquareMcpServer(options: SquareMcpOptions): SquareMcpServer;