@astrosheep/square 0.3.93 → 0.3.95

package/dist/square-stdio.js

@@ -1,235 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { validateMetadataMatch, validateDeferralDuration, validateDeferralId } from './delivery-deferral.js';
-import { spawn } from 'node:child_process';
-import path from 'node:path';
-import { createInterface } from 'node:readline';
-import { SquareError } from './model.js';
-import { harnessSessionSources } from './participant-identity.js';
-import { requireJoinName } from './seats.js';
-export const STDIO_PROTOCOL_VERSION = 2;
-export const STDIO_MAX_FRAME_BYTES = 8 * 1024 * 1024;
-export const identityVariables = [...harnessSessionSources.flatMap(source => [source.variable, ...(source.childVariable ? [source.childVariable] : [])])];
-export function wireIdentity(env) {
-    return Object.fromEntries(identityVariables.map(key => [key, env[key] ?? '']));
-}
-export function encodeError(error) {
-    const e = error;
-    return { code: -32000, message: e.message ?? 'Backend request failed', data: { code: e.code, facts: e.facts, operation: e.operation } };
-}
-function decodeError(error) {
-    return Object.assign(error.data?.code ? new SquareError(error.data.code, error.message, error.data.facts) : new Error(error.message), error.data?.operation ? { operation: error.data.operation } : {});
-}
-export function unsupported(feature) {
-    throw new SquareError('invalid_args', `The stdio backend does not support ${feature}; use explicit catch/history or a local resource`);
-}
-/** One process per opened Square. No replay, pooling, or operation policy. */
-class Connection {
-    nextId = 0;
-    closed = false;
-    closing;
-    pending = new Map();
-    child;
-    exited;
-    constructor(command, args, cwd, env) {
-        this.child = spawn(command, [...args], { cwd, env, shell: false, stdio: 'pipe' });
-        this.exited = new Promise(resolve => this.child.once('close', () => resolve()));
-        // Diagnostic bytes are deliberately not included in errors (they can contain credentials).
-        this.child.stderr.resume();
-        const lines = createInterface({ input: this.child.stdout, crlfDelay: Infinity });
-        let frameBytes = 0;
-        this.child.stdout.on('data', chunk => {
-            for (const byte of chunk) {
-                if (byte === 10)
-                    frameBytes = 0;
-                else if (++frameBytes > STDIO_MAX_FRAME_BYTES) {
-                    this.fail('Backend frame exceeds the protocol limit');
-                    break;
-                }
-            }
-        });
-        lines.on('line', line => {
-            try {
-                const message = JSON.parse(line);
-                if (message.jsonrpc !== '2.0')
-                    throw new Error();
-                if (message.method === 'square/progress') {
-                    const pending = this.pending.get(message.params?.id);
-                    if (pending && message.params?.progress) {
-                        try {
-                            pending.control?.onProgress?.(message.params.progress);
-                        }
-                        catch { /* progress observers cannot corrupt framing */ }
-                    }
-                    return;
-                }
-                if (!Number.isSafeInteger(message.id) || (Object.hasOwn(message, 'result') === Object.hasOwn(message, 'error')))
-                    throw new Error();
-                const pending = this.pending.get(message.id);
-                if (!pending)
-                    throw new Error();
-                this.pending.delete(message.id);
-                pending.dispose();
-                if (message.error)
-                    pending.reject(decodeError(message.error));
-                else
-                    pending.resolve(message.result);
-            }
-            catch {
-                this.fail('Malformed backend protocol response');
-            }
-        });
-        lines.once('close', () => this.fail('Backend stdout ended'));
-        this.child.once('error', () => this.fail('Cannot start configured backend; check command and cwd'));
-        this.child.once('exit', () => this.fail('Backend process exited'));
-        this.child.stdin.on('error', () => this.fail('Backend stdin closed'));
-    }
-    fail(message) {
-        if (this.closed)
-            return;
-        this.closed = true;
-        for (const pending of this.pending.values()) {
-            pending.dispose();
-            const error = new SquareError('unavailable', message);
-            if (pending.method === 'express')
-                Object.assign(error, { operation: { operation: 'express', expressEffect: 'unknown' } });
-            pending.reject(error);
-        }
-        this.pending.clear();
-        this.child.stdin.destroy();
-        this.child.kill();
-        const timer = setTimeout(() => this.child.kill('SIGKILL'), 500);
-        timer.unref();
-        void this.exited.then(() => clearTimeout(timer));
-    }
-    request(method, params, control) {
-        if (control?.signal?.aborted)
-            return Promise.reject(control.signal.reason ?? new Error('Operation cancelled'));
-        if (this.closed)
-            return Promise.reject(new SquareError('unavailable', 'Backend connection is closed'));
-        const id = ++this.nextId;
-        let frame;
-        try {
-            frame = JSON.stringify({ jsonrpc: '2.0', id, method, params }, (_key, value) => {
-                if (typeof value === 'number' && !Number.isFinite(value))
-                    throw new Error('Non-finite number');
-                return value;
-            }) + '\n';
-            if (Buffer.byteLength(frame) > STDIO_MAX_FRAME_BYTES)
-                throw new Error('Frame too large');
-        }
-        catch {
-            const error = new SquareError('invalid_args', 'Backend request must be JSON-serializable with finite numbers and fit the protocol frame limit');
-            if (method === 'express')
-                Object.assign(error, { operation: { operation: 'express', expressEffect: 'unsent' } });
-            return Promise.reject(error);
-        }
-        return new Promise((resolve, reject) => {
-            const abort = () => {
-                // Wait for the response: server cleanup (including catch lease release) must finish first.
-                if (!this.closed)
-                    this.child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: '$/cancelRequest', params: { id } }) + '\n');
-            };
-            this.pending.set(id, { resolve, reject, method, control, dispose: () => control?.signal?.removeEventListener('abort', abort) });
-            control?.signal?.addEventListener('abort', abort, { once: true });
-            this.child.stdin.write(frame);
-        });
-    }
-    close() {
-        return this.closing ??= (async () => {
-            const timer = setTimeout(() => this.fail('Backend close timed out'), 1000);
-            try {
-                if (!this.closed)
-                    await this.request('square/close', {});
-            }
-            catch { /* disconnect already rejects outstanding work */ }
-            finally {
-                clearTimeout(timer);
-                this.fail('Backend connection closed');
-                await this.exited;
-            }
-        })();
-    }
-}
-class StdioSquare {
-    location;
-    connection;
-    handle;
-    constructor(location, connection, handle) {
-        this.location = location;
-        this.connection = connection;
-        this.handle = handle;
-    }
-    call(method, args, control, participant, participantHandle) {
-        return this.connection.request(method, { handle: this.handle, args, ...(participant === undefined ? {} : { participant, participantHandle }) }, control);
-    }
-    participantHandle(name, reference) {
-        const call = (method, args, control) => this.call(method, args, control, name, reference);
-        return {
-            name,
-            express: ((bodyOrInput, optionsOrControl, control) => {
-                if (typeof bodyOrInput === 'object' && bodyOrInput !== null)
-                    return call('express', [bodyOrInput, undefined], optionsOrControl);
-                return call('express', [bodyOrInput, optionsOrControl], control);
-            }),
-            catch: (options, control) => call('catch', [options], control),
-            listen: (target, options, control) => call('listen', [target, options], control),
-            ignore: (target, options, control) => call('ignore', [target, options], control),
-            unlisten: (target, options, control) => call('unlisten', [target, options], control),
-            listening: (options, control) => call('listening', [options], control),
-            hold: (reason, options, control) => call('hold', [reason, options], control),
-            resume: (options, control) => call('resume', [options], control),
-            done: (body, options, control) => call('done', [body, options], control),
-            deferDelivery: async (input, control) => {
-                const match = validateMetadataMatch(input?.match), durationMs = validateDeferralDuration(input?.durationMs);
-                return call('deferDelivery', [{ match, durationMs }], control);
-            },
-            renewDeliveryDeferral: async (id, durationMs, control) => call('renewDeliveryDeferral', [validateDeferralId(id), validateDeferralDuration(durationMs)], control),
-            releaseDeliveryDeferral: async (id, control) => call('releaseDeliveryDeferral', [validateDeferralId(id)], control),
-            history: (query, control) => this.history(query, control),
-        };
-    }
-    async participant(name) {
-        const reference = randomUUID();
-        return this.participantHandle(await this.call('participant', [name, reference]), reference);
-    }
-    async join(...[name, options, control]) {
-        requireJoinName(name);
-        const reference = randomUUID();
-        const result = await this.call('join', [name, options, reference], control);
-        return { ...result, participant: this.participantHandle(result.participant, reference) };
-    }
-    history(...[query, control]) { return this.call('history', [query], control); }
-    status(...[options, control]) { return this.call('status', [options], control); }
-    participants(...[options, control]) { return this.call('participants', [options], control); }
-    recovery(...[name, control]) { return this.call('recovery', [name], control); }
-    snapshot() { return Promise.reject(new SquareError('invalid_args', 'stdio does not support function-valued snapshot; use status/participants/history')); }
-    stream() { unsupported('stream'); }
-    recognize() { return Promise.reject(new SquareError('invalid_args', 'stdio does not support host recognition; select a participant explicitly')); }
-    implicitJoin() { unsupported('host implicit join'); }
-    endOwnedSession() { unsupported('host session cleanup'); }
-    cancelDeliveries() { unsupported('host delivery cancellation'); }
-    close() { return this.connection.close(); }
-}
-export async function openStdioSquare(location, selected, input, backends, build, control) {
-    if (input.clock || input.wakeTransport)
-        unsupported('client clock or wakeTransport injection');
-    if (control?.signal?.aborted)
-        throw control.signal.reason ?? new Error('Operation cancelled');
-    const backend = Object.hasOwn(backends, selected.backend) ? backends[selected.backend] : undefined;
-    if (!backend)
-        throw new SquareError('invalid_args', `Backend ${selected.backend} is not configured; set backends or SQUARE_BACKENDS_CONFIG`);
-    const cwd = input.cwd ?? process.cwd();
-    const command = backend.command.includes('/') || backend.command.includes('\\') ? path.resolve(cwd, backend.command) : backend.command;
-    const connection = new Connection(command, backend.args ?? [], path.resolve(cwd, backend.cwd ?? '.'), { ...(input.env ?? process.env), ...backend.env });
-    try {
-        const result = await connection.request('square/open', { version: STDIO_PROTOCOL_VERSION, key: selected.key, location,
-            identity: wireIdentity(input.env ?? process.env), body: input.body, participant: input.participant, build }, control);
-        if (result.version !== STDIO_PROTOCOL_VERSION || typeof result.handle !== 'string')
-            throw new SquareError('unavailable', 'Backend protocol version mismatch');
-        return new StdioSquare(location, connection, result.handle);
-    }
-    catch (error) {
-        await connection.close();
-        throw error;
-    }
-}

package/dist/stdio-server.d.ts

@@ -1,3 +0,0 @@
-#!/usr/bin/env node
-/** Serve the existing resource API. This adapter contains no activity policy. */
-export declare function runSquareStdioServer(root: string): Promise<void>;

package/dist/stdio-server.js

@@ -1,212 +0,0 @@
-#!/usr/bin/env node
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { createInterface } from 'node:readline';
-import { pathToFileURL } from 'node:url';
-import { SqliteSquare } from './sqlite-square.js';
-import { SquareError, validateBody } from './model.js';
-import { canonicalPath } from './canonical-path.js';
-import { STDIO_PROTOCOL_VERSION, STDIO_MAX_FRAME_BYTES, encodeError, identityVariables } from './square-stdio.js';
-import { parseSquareLocation } from './square-location.js';
-/** Serve the existing resource API. This adapter contains no activity policy. */
-export async function runSquareStdioServer(root) {
-    await fs.mkdir(root, { recursive: true });
-    root = await canonicalPath(root);
-    const baseEnv = { ...process.env };
-    let square;
-    let location;
-    let opening = false, closing = false;
-    const participants = new Map();
-    const captureParticipant = (reference, participant) => {
-        if (typeof reference !== 'string' || reference.length === 0 || participants.has(reference))
-            throw new SquareError('invalid_args', 'Participant handle must be a fresh connection-local reference');
-        participants.set(reference, participant);
-        return participant.name;
-    };
-    const running = new Map();
-    const write = (message) => { if (!process.stdout.destroyed)
-        process.stdout.write(JSON.stringify(message) + '\n'); };
-    const response = (id, result) => write({ jsonrpc: '2.0', id, result });
-    const fail = (id, error) => write({ jsonrpc: '2.0', id, error: encodeError(error) });
-    const lines = createInterface({ input: process.stdin, crlfDelay: Infinity });
-    let shutdown;
-    const close = () => shutdown ??= (async () => {
-        closing = true;
-        for (const request of running.values())
-            request.controller.abort();
-        await Promise.allSettled([...running.values()].map(request => request.work));
-        await square?.close();
-        lines.close();
-        process.stdin.pause();
-    })();
-    const fatal = () => { void close().finally(() => { process.exitCode = 1; }); };
-    let frameBytes = 0;
-    process.stdin.on('data', chunk => {
-        for (const byte of Buffer.from(chunk)) {
-            if (byte === 10)
-                frameBytes = 0;
-            else if (++frameBytes > STDIO_MAX_FRAME_BYTES) {
-                fatal();
-                break;
-            }
-        }
-    });
-    process.stdout.on('error', fatal);
-    process.once('SIGTERM', fatal);
-    process.once('SIGINT', fatal);
-    lines.on('close', () => { if (!closing)
-        void close(); });
-    async function invoke(method, params, control) {
-        if (method === 'square/open') {
-            if (square || opening)
-                throw new SquareError('invalid_args', 'One logical open is allowed per connection');
-            opening = true;
-            try {
-                if (params.version !== STDIO_PROTOCOL_VERSION)
-                    throw new SquareError('invalid_args', 'Unsupported Square stdio protocol version');
-                const parsed = parseSquareLocation(params.location);
-                if (parsed.kind !== 'stdio' || parsed.key !== params.key)
-                    throw new SquareError('invalid_args', 'Open requires a matching stdio location and key');
-                const target = path.join(root, `${parsed.key}.square`);
-                const canonical = await canonicalPath(target);
-                if (path.dirname(canonical) !== root)
-                    throw new SquareError('invalid_args', 'Square key escapes the configured backend root');
-                const env = { ...baseEnv };
-                for (const key of identityVariables) {
-                    const value = params.identity?.[key];
-                    if (value !== undefined && typeof value !== 'string')
-                        throw new SquareError('invalid_args', 'Invalid operation identity');
-                    env[key] = value ?? '';
-                }
-                const input = { path: target, env, body: params.body, participant: params.participant };
-                if (params.body !== undefined)
-                    validateBody(params.body);
-                square = params.build === undefined ? await SqliteSquare.at(input, control, false)
-                    : await SqliteSquare.build({ ...params.build, ...input }, control, false);
-                location = parsed.uri;
-                return { version: STDIO_PROTOCOL_VERSION, handle: 'square' };
-            }
-            finally {
-                opening = false;
-            }
-        }
-        if (!square || params.handle !== 'square')
-            throw new SquareError('invalid_args', 'Open a logical square first');
-        if (!Array.isArray(params.args))
-            throw new SquareError('invalid_args', 'Operation args must be an array');
-        // JSON null represents omitted optional arguments, never the meaningful history limit:null inside an options object.
-        const args = params.args.map((arg) => arg === null ? undefined : arg);
-        let result;
-        switch (method) {
-            case 'participant': return captureParticipant(args[1], await square.participant(args[0]));
-            case 'join': {
-                if (typeof args[2] !== 'string' || args[2].length === 0 || participants.has(args[2]))
-                    throw new SquareError('invalid_args', 'Participant handle must be a fresh connection-local reference');
-                const joined = await square.join(args[0], args[1], control);
-                result = { ...joined, participant: captureParticipant(args[2], joined.participant) };
-                break;
-            }
-            case 'history':
-                result = await square.history(args[0], control);
-                break;
-            case 'status':
-                result = await square.status(args[0], control);
-                break;
-            case 'participants':
-                result = await square.participants(args[0], control);
-                break;
-            case 'recovery':
-                result = await square.recovery(args[0], control);
-                break;
-            default: {
-                if (typeof params.participant !== 'string')
-                    throw new SquareError('invalid_args', 'Participant operation requires a name');
-                const participant = participants.get(params.participantHandle);
-                if (participant === undefined || participant.name !== params.participant)
-                    throw new SquareError('invalid_args', 'Select a captured participant handle on this connection');
-                switch (method) {
-                    case 'deferDelivery':
-                        result = await participant.deferDelivery(args[0], control);
-                        break;
-                    case 'renewDeliveryDeferral':
-                        result = await participant.renewDeliveryDeferral(args[0], args[1], control);
-                        break;
-                    case 'releaseDeliveryDeferral':
-                        result = await participant.releaseDeliveryDeferral(args[0], control);
-                        break;
-                    case 'express':
-                        result = await participant.express(args[0], args[1], control);
-                        break;
-                    case 'catch':
-                        result = await participant.catch(args[0], control);
-                        break;
-                    case 'listen':
-                        result = await participant.listen(args[0], args[1], control);
-                        break;
-                    case 'ignore':
-                        result = await participant.ignore(args[0], args[1], control);
-                        break;
-                    case 'unlisten':
-                        result = await participant.unlisten(args[0], args[1], control);
-                        break;
-                    case 'listening':
-                        result = await participant.listening(args[0], control);
-                        break;
-                    case 'hold':
-                        result = await participant.hold(args[0], args[1], control);
-                        break;
-                    case 'resume':
-                        result = await participant.resume(args[0], control);
-                        break;
-                    case 'done':
-                        result = await participant.done(args[0], args[1], control);
-                        break;
-                    default: throw new SquareError('invalid_args', 'Unsupported stdio operation');
-                }
-            }
-        }
-        if (result?.observation)
-            result = { ...result, observation: { ...result.observation, location, automaticDeliveryAvailable: false } };
-        return result;
-    }
-    lines.on('line', line => {
-        if (closing)
-            return;
-        let message;
-        try {
-            message = JSON.parse(line);
-            if (message.jsonrpc !== '2.0' || typeof message.method !== 'string' || !message.params || typeof message.params !== 'object')
-                throw new Error();
-            if (message.method === '$/cancelRequest') {
-                running.get(message.params.id)?.controller.abort();
-                return;
-            }
-            if (!Number.isSafeInteger(message.id) || running.has(message.id))
-                throw new Error();
-        }
-        catch {
-            fatal();
-            return;
-        }
-        if (message.method === 'square/close') {
-            void close().then(() => { response(message.id, null); process.stdout.end(); });
-            return;
-        }
-        const controller = new AbortController();
-        // Start on a microtask so the request is tracked before progress/cleanup can run.
-        const work = Promise.resolve().then(() => invoke(message.method, message.params, {
-            signal: controller.signal,
-            onProgress: progress => write({ jsonrpc: '2.0', method: 'square/progress', params: { id: message.id, progress } }),
-        })).then(result => response(message.id, result), error => fail(message.id, error)).finally(() => { running.delete(message.id); });
-        running.set(message.id, { controller, work });
-    });
-}
-if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
-    if (process.argv.length !== 4 || process.argv[2] !== '--root') {
-        process.stderr.write('usage: node dist/stdio-server.js --root <backend-artifact-directory>\n');
-        process.exitCode = 2;
-    }
-    else {
-        await runSquareStdioServer(path.resolve(process.argv[3]));
-    }
-}

package/guides/backends.md

@@ -1,193 +0,0 @@
-# Locations and the stdio backend
-
-Square and Participant are the same public resource API for local SQLite, local in-memory,
-and stdio-backed squares. There is no separate participant policy or caller-specific dispatch.
-`Square.at` / `Square.build` choose the backend before opening storage. CLI, MCP and Pi tools use
-that same boundary. No Slack backend or external messaging integration is included.
-
-## Runnable setup
-
-From a built source checkout (`npm run build`), create a JSON configuration file, substituting
-absolute paths for this machine:
-
-```json
-{
-  "backends": {
-    "local": {
-      "command": "/absolute/path/to/node",
-      "args": ["/absolute/path/to/square/dist/stdio-server.js", "--root", "/absolute/path/to/squares"]
-    }
-  }
-}
-```
-
-The bundled backend's standalone startup command is:
-
-```sh
-node /absolute/path/to/square/dist/stdio-server.js --root /absolute/path/to/squares
-```
-
-Normally Square spawns it automatically, without a shell, using the configured command. Its
-stdin/stdout are the protocol, not an interactive terminal. Stderr is diagnostics. The client
-drains stderr without inserting it into participant output or error messages.
-
-```sh
-export SQUARE_BACKENDS_CONFIG=/absolute/path/to/backends.json
-export SQUARE_LOCATION=stdio://local/design
-printf '# Design\nA place to compare ideas.\n' | node dist/square.js build -
-node dist/square.js --as Alice join
-node dist/square.js --as Bob join
-node dist/square.js --as Alice express --force 'What do you think @Bob?'
-node dist/square.js --as Bob history
-node dist/square.js --as Bob catch --now
-```
-
-History does not consume. Catch consumes eligible directed activity once. A reply uses the usual
-`--reply act/N`; mentions, replies, listening, ownership, hold/throttle, reentry and receipt semantics
-are the existing SQLite implementation. Independent processes address the same `design.square`
-inside the backend root. They do **not** share an in-memory resource.
-
-SDK callers may provide typed configuration directly:
-
-```ts
-import { Square, type SquareBackends } from '@astrosheep/square';
-
-const backends: SquareBackends = {
-  local: { command: process.execPath, args: ['/absolute/path/to/square/dist/stdio-server.js', '--root', '/tmp/squares'] },
-};
-const square = await Square.at({ path: 'stdio://local/design', backends, participant: 'Bob',
-  body: { channel: 'example', session: 'bob-process' } });
-try {
-  const bob = (await square.join('Bob')).participant;
-  const caught = await bob.catch();
-  console.log(caught.activities);
-} finally {
-  await square.close();
-}
-```
-
-Use the same `path` and `backends` in `createSquareMcpServer` options. Tool calls can override
-`location: "stdio://local/design"`; the override owns its process rather than borrowing the
-configured local SQLite connection. Pi tools accept the identical location and read the captured
-`SQUARE_BACKENDS_CONFIG`. Native session identity is still chosen by each adapter on each call.
-
-## Locations and configuration
-
-- Plain locations are filesystem paths, resolved against captured input `cwd`. `inMemory` is always
-  local. Remote `build` creates a square through the backend; it never writes a URI-named local file.
-- Stdio URI grammar is `stdio://<alias>/<encoded-key>`. Aliases are case-sensitive ASCII letters,
-  digits, `_` and `-`. The key is one nonempty Unicode name, **not** a hierarchy: encode it with
-  `encodeURIComponent`, decoded exactly once. Encoded slashes/backslashes, controls, `.` and `..`
-  are refused. Canonical URIs re-encode the decoded key, so `hello%20world` is unambiguous.
-  Credentials, ports, query strings, fragments, extra path segments and unknown schemes are refused.
-- A key `design` maps to `design.square` in the bundled server root. The root is created if needed;
-  resolved artifact targets outside it (including existing escaping symlinks) are refused. Use a root
-  managed by the backend owner, not an attacker-writable directory. Different aliases need not refer
-  to different servers, but ownership is established by backend persistence, not by the alias.
-- An alias is explicit configuration, never an executable in a URI. An entry is
-  `{command: string, args?: string[], cwd?: string, env?: Record<string,string>}`. `command` is a
-  program name on PATH or a path. Relative command paths, entry `cwd`, and the config-file path are
-  resolved against captured input `cwd`, **not** relative to the config file. Commands spawn with
-  no shell and inherit captured caller environment plus only the entry's explicit env overrides.
-- SDK `backends` (including `{}`) wins over file configuration. Otherwise Square reads
-  `SQUARE_BACKENDS_CONFIG`, default `~/.config/square/backends.json` (`HOME` from captured env).
-  A missing default file is harmless for local resources. Explicit missing/invalid files, malformed
-  configuration and missing selected aliases refuse with `invalid_args`. Error text never dumps
-  configuration values or environment secrets.
-- Each remote open owns one child process/connection, reused across its operations. There is no
-  global pool. A supplied SQLite `resources` owner is not used for remote opens; close still closes
-  that remote process. Separate opens share state only through the backend's persistence.
-- CLI failed-expression drafts stay in local `./drafts` for backend locations; recovery commands and
-  display labels retain the URI. Local-artifact draft placement is unchanged.
-
-## Protocol version 2
-
-Newline-delimited JSON-RPC 2.0 over UTF-8 stdin/stdout, one object per line, at most 8 MiB per frame.
-Stdout is protocol only. No batch requests. The initial versioned handshake opens one logical square
-per connection and returns an opaque handle. IDs are unique positive integers on the client;
-requests may overlap and responses may arrive out of order.
-
-```json
-{"jsonrpc":"2.0","id":1,"method":"square/open","params":{"version":2,"key":"design","location":"stdio://local/design","identity":{"PI_SESSION_ID":"session-id"},"body":{"channel":"pi","session":"session-id"},"participant":"Bob"}}
-{"jsonrpc":"2.0","id":1,"result":{"version":2,"handle":"square"}}
-{"jsonrpc":"2.0","id":2,"method":"join","params":{"handle":"square","args":["Bob",{"observe":true},"fresh-participant-reference"]}}
-```
-
-Open may include `build: {markdown, hardCap?, throttlePerMinute?, template?, force?}` instead of
-opening an existing artifact. The client transmits only recognized harness session coordinates,
-the Claude child flag and configured participant name as identity facts, **not the whole environment
-in the protocol**. The backend captures its own process environment, clears **all** these startup
-coordinates (including PASEO_AGENT_ID), then overlays explicit call-local facts without mutating
-`process.env`. Participant defaults remain separate from square keys. Each new tool open therefore
-uses that call's identity, not MCP/Pi/backend startup identity.
-
-After open, square methods take `{handle, args}` and Participant methods additionally require
-`{participant, participantHandle}`. Selection/join supply a fresh opaque connection-local reference;
-the server retains the actual captured Participant under it instead of reselecting by name per
-request. Version 2 deliberately refuses older peers rather than accepting unfenced handles.
-`args` is the public operation's positional arguments excluding `OperationControl`, plus the
-selection reference noted below; trailing JSON nulls represent omitted optional arguments.
-Nested nulls such as `history({limit:null})` retain their public meaning.
-
-| Methods | args | participant field |
-| --- | --- | --- |
-| `participant` | `[name?, freshReference]` | no; selection only, not joining |
-| `join` | `[name, options?, freshReference]` | no |
-| `history`, `status`, `participants` | `[options?]` | no |
-| `recovery` | `[name?]` | no |
-| `express` | `[body, options?]` | required |
-| `catch`, `listening`, `resume` | `[options?]` | required |
-| `listen`, `ignore`, `unlisten` | `[target, options?]` | required |
-| `hold`, `done` | `[body?, options?]` | required |
-| `deferDelivery` | `[{match, durationMs}]` | required |
-| `renewDeliveryDeferral` | `[id, durationMs]` | required |
-| `releaseDeliveryDeferral` | `[id]` | required |
-
-Results are the concrete public operation results, including requested observations. Participant
-handles serialize as names for `participant` and `join.participant` and become real local handles
-on the client, using their retained connection-local references. Done/takeover/rejoin fences old
-references even when the same Body later reacquires the name. Observation locations are canonical
-remote URIs and automatic delivery is false. SDK/stdio deferrals have identical validation, independent
-lease and owner-generation semantics; create/renew return only `{id, expiresAt}`, renew returns null
-and release false for an inactive ID, and stale handles receive the normal ownership refusal.
-No CLI/MCP/Pi deferral-authoring command is included. Errors are JSON-RPC `{code:-32000,message,data:{code?,facts?,operation?}}`; Square codes, structured
-facts, history bounds and express certainty survive the boundary. The client does not infer
-`unsent` from a connection failure. There is no mutation retry or replay.
-
-Progress is a notification
-`{jsonrpc:"2.0",method:"square/progress",params:{id,progress}}` where progress is the typed public
-`OperationProgress`. Request abort sends `$/cancelRequest` with `{id}`; the server aborts only that
-request and returns its response **after** cleanup, including releasing a catch lease. Another
-request on the same handle continues normally. Cancellation never undoes an explicitly committed
-receipt or lease mutation. A committed deferral remains until release, expiry or seat retirement;
-connection close does not cancel it. `square/close` with `{}` aborts/drains outstanding requests, closes SQLite and acknowledges
-with a null result. Client close is idempotent, waits briefly for graceful cleanup, then terminates
-an unresponsive process. EOF, malformed framing, version mismatch and process exit reject pending
-requests and release the connection. A lost express response after dispatch has unknown effect;
-inspect history before deciding whether to send again.
-
-## Explicit limitations
-
-- No automatic wake, route registration, native notification delivery or cross-host inbox for stdio.
-  The server disables wake dispatch and route publication explicitly, while retaining backend-local
-  session ownership. A harness identity does not imply wake capability. Use explicit `catch`
-  (including cancellable positive-idle catch) or history.
-- `snapshot` (which contains a function), `stream`, host recognition/implicit join, owner-session
-  cleanup and route-retirement operations refuse explicitly. No partial JSON snapshot or fake stream
-  is offered. Use status/participants/history and explicit participant lifecycle methods.
-- Client clock functions, host-ledger objects and wake transport objects cannot cross the process
-  boundary and are refused. Backend process configuration owns its environment, clock and ledger.
-- File doctor, migrate and discovery are local-only and refuse a selected backend URI. Run file
-  diagnostics/migration locally on the backend host with the artifact path while clients are stopped.
-  Local harness discovery/inbox do not enumerate remote backends; remote membership is not registered
-  into the client's host ledger or notification watchers.
-- No process pooling, reconnection, automatic retries, server daemon, Slack IDs, credentials, live
-  external sends, installation or release management is introduced.
-
-## Slack is a bridge, not a backend
-
-Slack never becomes a Square location and does not change the backend grammar. To bring Slack humans
-into a square, run `packages/slack-bridge` (`square-slack-bridge`) against one channel and one local
-artifact: Slack messages land as ordinary activities from `slack/<name>` participants, and Square
-`say` activities appear in the channel. The artifact stays authoritative, so mentions, replies, catch,
-notifications and previews are the existing native behavior; no core, CLI, MCP or Pi code changes.