@astrosheep/square 0.3.84 → 0.3.86

package/dist/square-stdio.d.ts

@@ -0,0 +1,22 @@
+import { type SquareErrorCode, type SquareErrorFacts } from './model.js';
+import type { SquareBackends, SquareBackend } from './square-backend.js';
+import type { ParsedSquareLocation } from './square-location.js';
+import type { OperationControl, OperationFailureDetail, SquareAtInput, SquareBuildInput } from './square-facade.js';
+export declare const STDIO_PROTOCOL_VERSION = 1;
+export declare const STDIO_MAX_FRAME_BYTES: number;
+export declare const identityVariables: string[];
+export declare function wireIdentity(env: NodeJS.ProcessEnv): Record<string, string>;
+export interface WireError {
+    readonly code: number;
+    readonly message: string;
+    readonly data?: {
+        readonly code?: SquareErrorCode;
+        readonly facts?: SquareErrorFacts;
+        readonly operation?: OperationFailureDetail;
+    };
+}
+export declare function encodeError(error: unknown): WireError;
+export declare function unsupported(feature: string): never;
+export declare function openStdioSquare(location: string, selected: Extract<ParsedSquareLocation, {
+    kind: 'stdio';
+}>, input: SquareAtInput, backends: SquareBackends, build?: Pick<SquareBuildInput, 'markdown' | 'hardCap' | 'throttlePerMinute' | 'template' | 'force'>, control?: OperationControl): Promise<SquareBackend>;

package/dist/square-stdio.js

@@ -0,0 +1,217 @@
+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';
+export const STDIO_PROTOCOL_VERSION = 1;
+export const STDIO_MAX_FRAME_BYTES = 8 * 1024 * 1024;
+export const identityVariables = [...harnessSessionSources.flatMap(source => [source.variable, ...(source.childVariable ? [source.childVariable] : [])]), 'SQUARE_PARTICIPANT_NAME'];
+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) {
+        return this.connection.request(method, { handle: this.handle, args, ...(participant === undefined ? {} : { participant }) }, control);
+    }
+    participantHandle(name) {
+        return {
+            name,
+            express: (body, options, control) => this.call('express', [body, options], control, name),
+            catch: (options, control) => this.call('catch', [options], control, name),
+            listen: (target, options, control) => this.call('listen', [target, options], control, name),
+            ignore: (target, options, control) => this.call('ignore', [target, options], control, name),
+            unlisten: (target, options, control) => this.call('unlisten', [target, options], control, name),
+            listening: (options, control) => this.call('listening', [options], control, name),
+            hold: (reason, options, control) => this.call('hold', [reason, options], control, name),
+            resume: (options, control) => this.call('resume', [options], control, name),
+            done: (body, options, control) => this.call('done', [body, options], control, name),
+            history: (query, control) => this.history(query, control),
+        };
+    }
+    async participant(name) { return this.participantHandle(await this.call('participant', [name])); }
+    async join(...[name, options, control]) {
+        const result = await this.call('join', [name, options], control);
+        return { ...result, participant: this.participantHandle(result.participant) };
+    }
+    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'); }
+    doneOwnedSession() { unsupported('host session cleanup'); }
+    endOwnedSession() { unsupported('host session cleanup'); }
+    retireEndedSessionRoutes() { unsupported('host wake routes'); }
+    close() { return this.connection.close(); }
+}
+export async function openStdioSquare(location, selected, input, backends, build, control) {
+    if (input.clock || input.hostLedger || input.wakeTransport)
+        unsupported('client clock, hostLedger 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), 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/square-tools.js

@@ -2,7 +2,7 @@ import { z } from 'zod/v4';
 import { isSquareError } from './model.js';
 import { CATCH_DEFAULT_LIMIT } from './square-api.js';
 import { renderCatchOutcome, renderExpression, renderFailureLines, renderHistoryResult, renderJoinResult, renderLifecycleResult, renderListenerChange, renderListeningResult, renderParticipantsResult, renderStatusResult, } from './operation-presentation.js';
-const location = z.string().optional().describe('Path to the .square artifact, relative to the current working directory. Defaults to the configured square.');
+const location = z.string().optional().describe('Local .square artifact path or configured backend URI (stdio://name/key). Relative paths use the current working directory. Defaults to the configured square.');
 const participant = z.string().optional().describe('Participant name. Defaults to the configured participant or the current session’s unambiguous participant.');
 const activityId = z.string().regex(/^act\/(0|[1-9][0-9]*)$/);
 const stringArray = z.array(z.string());

package/dist/stdio-server.d.ts

@@ -0,0 +1,3 @@
+#!/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

@@ -0,0 +1,190 @@
+#!/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 } 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 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, participant: params.participant };
+                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 (await square.participant(args[0])).name;
+            case 'join': {
+                const joined = await square.join(args[0], args[1], control);
+                result = { ...joined, participant: joined.participant.name };
+                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 = await square.participant(params.participant);
+                switch (method) {
+                    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

@@ -0,0 +1,180 @@
+# 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' });
+try {
+  const bob = (await square.join()).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 1
+
+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":1,"key":"design","location":"stdio://local/design","identity":{"PI_SESSION_ID":"session-id"},"participant":"Bob"}}
+{"jsonrpc":"2.0","id":1,"result":{"version":1,"handle":"square"}}
+{"jsonrpc":"2.0","id":2,"method":"join","params":{"handle":"square","args":["Bob",{"observe":true}]}}
+```
+
+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, methods take `{handle, args, participant?}`. `args` is the public operation's positional
+arguments excluding `OperationControl`; trailing JSON nulls represent omitted optional arguments.
+Nested nulls such as `history({limit:null})` retain their public meaning.
+
+| Methods | args | participant field |
+| --- | --- | --- |
+| `participant` | `[name?]` | no; selection only, not joining |
+| `join` | `[name?, options?]` | 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 |
+
+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. Observation locations are canonical remote URIs and automatic delivery is false.
+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. `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.

package/guides/claude-native.md

@@ -37,19 +37,20 @@ changes `crossSessionInbound`. After bytes may have been sent, `unknown` remains
 attention-wide and prevents another send through Paseo, even if routes later change.
 
 Each native send persists a message ID before writing; the wire `uuid` and
-`msg_id` carry that ID. On a matching Paseo build, the Square server plugin records
-`held`, `released` and `dropped` observations from `agent.delivery_status` on the
-original host-ledger wake attempt. The event ID is deduplicated and the native
-reason and observation time remain diagnostic only. Neither a release nor a drop
-is a queue receipt, proof of consumption or retry authorization. Unknown IDs do
-not create evidence; older attempts without message IDs cannot be backfilled.
+`msg_id` carry that ID. Square records no native custody telemetry from Paseo:
+official Paseo exposes no delivery-status lifecycle event, so a held message stays
+`unknown` with `native_admission_unconfirmed`. Recording a `held`, `released` or
+`dropped` observation would require a Paseo-provided event; Square does not patch
+Paseo to invent one. Even when such an observation exists, the event ID is
+deduplicated and the native reason and observation time remain diagnostic only.
+Neither a release nor a drop is a queue receipt, proof of consumption or retry
+authorization.
 
 `square harness doctor delivery` shows native custody separately from pending
 attention, including after the activity is seen or the participant leaves. Paseo
-also presents the native state in its timeline. This integration requires the
-matching local Paseo 0.12.1-square.1 lifecycle API and plugin SDK; see
-[the Paseo plugin](../plugins/paseo/README.md). Acceptance means normal delivery
-when policy allows it, or a visible reason without bypass/replay when policy holds it.
+presents the `peer_message_hold` state in its own timeline. Acceptance means normal
+delivery when the receiver allows it, or a visible reason without bypass/replay when
+policy holds it.
 
 ## MCP tools and call identity